# Css

Compile ordered style data into CSS text, class names, and variable set scopes.

`Css` holds the web CSS compiler, with its types and errors. It reads data and returns strings without touching the filesystem, the DOM, or a bundler. Bundler integrations call it for each module, and custom pipelines and tests can call it directly.

The Rust compiler emits the CSS. Node.js loads its native addon, and browser bundles inline its WebAssembly build, which instantiates synchronously.

```ts title="compile.ts"
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const styles = Style.define({ card: { color: 'black', padding: '1rem' } })

// { classes: { card: 'z-text-black z-p-1rem' }, css: '.z-text-black{color:black;}…' }
const output = Css.compile({ styles })
```

## Css.compile

Compile [`Style.define`](/docs/api/core/namespaces/Style) data into a stylesheet and a class map. The result is frozen, and its keys keep the authored style and variable set names.

## Signature

```ts
// One options object, returning the stylesheet and class maps
Css.compile(options)
```

## Parameters

### options.styles

* **Type:** `Style.Definition`

The ordered, validated definitions from `Style.define`. Each style key becomes a key of the returned class map.

```ts
// Styles keep their authored order in the stylesheet
Css.compile({ styles: Style.define({ card: { padding: '1rem' } }) })
```

### options.cssOutput

* **Type:** `'atomic' | 'grouped'`
* **Default:** `'atomic'`

Atomic output emits one class per declaration and shares identical declarations across styles. Grouped output emits one class per style with all its declarations. The [CSS Output](/docs/guides/css-output) guide compares the two.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const styles = Style.define({ card: { color: 'black', padding: '1rem' } })

// { classes: { card: 'z-card' }, css: '.z-card{color:black;padding:1rem;}' }
const output = Css.compile({ cssOutput: 'grouped', styles })
```

### options.composition

* **Type:** `'independent' | 'ordered'`
* **Default:** `'ordered'`

`ordered` keeps precedence correct when class lists combine on one element. `independent` deduplicates identical styles, shares one rule per repeated atomic declaration, and factors shared grouped declarations, so its class lists must never combine with each other. A style's own `composition` takes precedence.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const styles = Style.define({
  card: { color: 'black', padding: '1rem' },
  title: { fontSize: '2rem', padding: '1rem' },
})

// card: 'z-card z-card__1', title: 'z-card z-title'
const output = Css.compile({
  composition: 'independent',
  cssOutput: 'grouped',
  styles,
})
```

### options.contributions

* **Type:** `readonly Css.Contribution[]`
* **Default:** `undefined`

Ordered stylesheet rules that belong to no style, such as layer order, global rules, and at-rules. Source compilation builds them from `global`, `layers`, and the other stylesheet helpers. Their CSS precedes the style rules.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const output = Css.compile({
  // Emits `@layer reset,base;` before the style rules
  contributions: [{ kind: 'layers', names: ['reset', 'base'] }],
  styles: Style.define({ card: { padding: '1rem' } }),
})
```

### options.development

* **Type:** `boolean`
* **Default:** `false`

Disables the application deduplication, atomic sharing, and grouped factoring of `composition: 'independent'`. Atomic output still shares identical declarations across styles. Integrations enable it in development servers.

```ts
// Replace the class map and CSS together after each edit
Css.compile({ development: true, styles })
```

### options.names

* **Type:** `Readonly<Record<string, string>>`
* **Default:** `undefined`

Fixed class names for styles, keyed by style name. A fixed name replaces the generated classes, which suits stylesheets consumed without the class map.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const styles = Style.define({ card: { padding: '1rem' } })

// { classes: { card: 'card' }, css: '.card{padding:1rem;}' }
const output = Css.compile({ names: { card: 'card' }, styles })
```

### options.schemes

* **Type:** `boolean`
* **Default:** `false`

Emits the `color-scheme` classes that `vars({ colorScheme })`, `appearance`, and `script()` apply. Source compilation enables it for modules that use those helpers.

```ts
// Adds `.z_scheme-dark{color-scheme:dark;}` and its siblings
Css.compile({ schemes: true, styles })
```

### options.scope

* **Type:** `string`
* **Default:** `undefined`

A namespace inserted into generated class names, which keeps stylesheets compiled and delivered separately from colliding.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const styles = Style.define({ card: { padding: '1rem' } })

// { classes: { card: 'z-card-p-1rem' }, css: '.z-card-p-1rem{padding:1rem;}' }
const output = Css.compile({ scope: 'card', styles })
```

### options.vars

* **Type:** `Readonly<Record<string, Vars.Definition>>`
* **Default:** `undefined`

Named variable sets from [`defineVars`](/docs/api/core/defineVars) and [`extendVars`](/docs/api/core/extendVars). Each set emits a scope class that assigns the variables the styles reference.

```ts
import { defineVars, Style } from 'zyzz'
import { Css } from 'zyzz/web'

const base = defineVars({ color: { ink: '#171717' } })
const styles = Style.define({ card: { color: base.color.ink } })

// output.vars.base is the scope class that assigns `--z0`
const output = Css.compile({ styles, vars: { base } })
```

## Returns

### classes

* **Type:** `Readonly<Record<name, string>>`

Space-separated classes for each style, keyed by style name. A style without declarations maps to an empty string.

```ts
// Applies the compiled classes in markup
const markup = `<article class="${output.classes.card}"></article>`
```

### css

* **Type:** `string`

The complete stylesheet, including any contributions before the style rules. Deliver it together with the class map from the same call.

```ts
// Loads the stylesheet in a page
const markup = `<style>${output.css}</style>`
```

### contributionCss

* **Type:** `string | undefined`

The contribution rules alone, present when contributions emit CSS. Hosts that hoist shared rules load it before `scopedCss` and before other stylesheets that declare layers.

```ts
// '@layer reset,base;'
const shared = output.contributionCss
```

### scopedCss

* **Type:** `string | undefined`

The variable scopes and style rules alone, present when contributions emit CSS. A consumer loads either `css`, or `contributionCss` followed by `scopedCss`, but never both.

```ts
// Falls back to the complete stylesheet without contributions
const moduleCss = output.scopedCss ?? output.css
```

### vars

* **Type:** `Readonly<Record<themeName, string>>`

The scope class for each variable set, keyed by set name. It is empty when `options.vars` is omitted.

```ts
// Applies the base set's variables to a subtree
const markup = `<section class="${output.vars.base}"></section>`
```

## Types

* **`Css.compile.ErrorType`:** The error `Css.compile` throws, `Css.CompileError`.
* **`Css.compile.Options`:** The accepted options.
* **`Css.compile.ReturnType`:** The returned stylesheet and class maps.
* **`Css.Contribution`:** One stylesheet rule, discriminated by `kind`, such as `'layers'`, `'rule'`, `'font-face'`, `'keyframes'`, or `'property'`. An optional `within` lists enclosing groups, outermost first.
* **`Css.Diagnostic`:** One compilation failure, with a `code`, a `message`, and a `path`.

```ts
import type { Css } from 'zyzz/web'

// A shared layer order for several compilations
export const order = [
  { kind: 'layers', names: ['reset', 'base'] },
] satisfies Css.Contribution[]
```

## Errors

### Css.CompileError

Thrown when styles, variable sets, or names cannot compile, with no partial output. `diagnostics` lists every failure in authored order. Each `code` is `identity_collision`, `invalid_declaration`, `invalid_name`, `invalid_output`, or `invalid_theme`.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

try {
  // Two different styles cannot share one fixed name
  Css.compile({
    names: { body: 'text', title: 'text' },
    styles: Style.define({ body: { color: 'black' }, title: { color: 'red' } }),
  })
} catch (error) {
  // [{ code: 'identity_collision', path: ['title'], … }]
  if (error instanceof Css.CompileError) console.error(error.diagnostics)
}
```

TypeScript also rejects reads of style names that the input does not define.

```ts
import { Style } from 'zyzz'
import { Css } from 'zyzz/web'

const output = Css.compile({
  styles: Style.define({ card: { padding: '1rem' } }),
})

// `title` is not a style in this compilation
output.classes.title
// error: Property 'title' does not exist on type 'Readonly<Record<"card", string>>'.
```
