@elastic/distillate 0.0.0 → 0.1.0

package/docs/playground.md

@@ -0,0 +1,28 @@
+---
+navigation_title: Playground
+description: Live Distillate editor with stylesheet, compact names, and a tree-shaken artifact.
+---
+
+# Playground
+
+The playground is a full-viewport workbench: source and tokens on the left, a centered live preview in the remaining canvas, and generated CSS under the preview.
+
+- **On GitHub Pages:** [elastic.github.io/distillate/playground](https://elastic.github.io/distillate/playground/)
+- **Locally:** `pnpm playground:dev` from the repo root (Vite, default <http://localhost:5173>)
+
+Two authoring modes share one demo environment (`prefix: 'dstl'`, theme vars on `:host`):
+
+- **Emotion** — tagged `css` templates, plus `cx`, `injectGlobal`, `tokens`, and `cn`
+- **Native module** — `createStyleModule`, `rule`, `media`, `container`, `variants`, `tokens`, `cn`
+
+The editor is Monaco with TypeScript IntelliSense for the injected playground scope (`css` / `createStyleModule`, `tokens`, `cn`, …). Generated CSS is a read-only Monaco view of the compile output. Imports in snippets are educational; the real bindings are injected at eval time. Each snippet ends in `return` of an HTML string.
+
+**Readable** and **Compact** are naming modes on the full stylesheet (`stylesheetCollector`). **Artifact** is the compact payload from the handles the returned markup actually named (`artifactCollector`, after collection completes). Byte counts for the full stylesheet versus that artifact stay visible above the CSS; they are the same comparison as [`docs/examples/06-payload.ts`](https://github.com/elastic/distillate/blob/main/docs/examples/06-payload.ts). Card, Buttons, Tree shake, Local vars, and Media + container ship in both modes so you can compare authoring. Switching Emotion vs Native keeps the selected example. **Tree shake** names one style in the markup; the stylesheet still contains the rest. See [`docs/playground/src/examples/snippets.ts`](https://github.com/elastic/distillate/blob/main/docs/playground/src/examples/snippets.ts).
+
+Emotion handles collect when `cx(...)`, `cn(...)`, or string interpolation (`${handle}`) runs during the returned markup. `injectGlobal` still follows engine semantics: it ships in the stylesheet and is omitted from the artifact unless you collect those modules yourself.
+
+A read-only Tokens table sits under the editor and lists every `tokens.*` path in the demo environment with its resolved CSS (`themeVars` light/dark for colors and fonts; `value` / `.cq` for scales). Color swatches follow the Preview Light/Dark toggle. Demo colors use Borealis brand values (`primary`, `accent`, `accentSecondary`, `success`, `warning`, `danger`) plus text, surface, subtle, and border — hard-coded, not imported from EUI.
+
+The chrome around the editor is itself a Distillate readable stylesheet (`prefix: 'pg'`, theme vars on `:root`), kept on a separate distillery from snippet compilation so the two registries never mix.
+
+The compile pipeline is sucrase (TypeScript → JS) then `new Function`. It is a demo, not a sandbox: do not paste untrusted source.

package/docs/reference/api/emotion.md

@@ -0,0 +1,372 @@
+# emotion
+
+## Interfaces
+
+### CreateDomSinkOptions [#createdomsinkoptions]
+
+Defined in: [dom\_sink.ts:25](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L25)
+
+Host document and optional flush scheduler for a `<style>` sink.
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| $$$document$$$ `document` | [`DocumentLike`](#documentlike) | The host document where the style element will be appended. | [dom\_sink.ts:27](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L27) |
+| $$$schedule$$$ `schedule?` | (`flush`) => `void` | Defers the flush. Defaults to `queueMicrotask`. | [dom\_sink.ts:29](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L29) |
+
+***
+
+### CreateEmotionOptions [#createemotionoptions]
+
+Defined in: [emotion.ts:33](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L33)
+
+Shared sink for Emotion compat modules on one registry.
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| $$$sink$$$ `sink?` | [`StyleSink`](#stylesink) | Notified when a compat module registers. Shared across `createEmotion` calls on the same registry. | [emotion.ts:35](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L35) |
+
+***
+
+### DocumentLike [#documentlike]
+
+Defined in: [dom\_sink.ts:17](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L17)
+
+Minimal interface for a DOM `Document` able to create and append style tags.
+
+#### Properties
+
+| Property | Modifier | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| $$$head$$$ `head` | `readonly` | `object` | Node that receives the created style element. | [dom\_sink.ts:21](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L21) |
+| `head.appendChild` | `public` | `void` | - | [dom\_sink.ts:21](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L21) |
+
+#### Methods
+
+##### createElement() [#createelement]
+
+```ts
+createElement(tagName): StyleElementLike;
+```
+
+Defined in: [dom\_sink.ts:19](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L19)
+
+Creates a `<style>` element.
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tagName` | `"style"` |
+
+###### Returns
+
+[`StyleElementLike`](#styleelementlike)
+
+***
+
+### Emotion [#emotion]
+
+Defined in: [emotion.ts:59](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L59)
+
+Emotion-shaped authoring API bound to one Distillery registry.
+
+#### Methods
+
+##### css() [#css]
+
+```ts
+css(strings, ...values): EmotionCss;
+```
+
+Defined in: [emotion.ts:61](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L61)
+
+Authors styles and returns a handle that can be used directly or passed to `cx`.
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `strings` | `TemplateStringsArray` |
+| ...`values` | readonly `unknown`[] |
+
+###### Returns
+
+[`EmotionCss`](#emotioncss-1)
+
+##### cx() [#cx]
+
+```ts
+cx(...args): string;
+```
+
+Defined in: [emotion.ts:63](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L63)
+
+Combines handles, conditional classes, and plain strings into a space-separated string.
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`args` | readonly [`ClassNameArg`](#classnamearg)[] |
+
+###### Returns
+
+`string`
+
+##### globalModules() [#globalmodules]
+
+```ts
+globalModules(): readonly StylesModule<StylesObject>[];
+```
+
+Defined in: [emotion.ts:72](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L72)
+
+Returns the underlying modules backing `injectGlobal` calls.
+
+###### Returns
+
+readonly [`StylesModule`](index-1.md#stylesmodule)\<[`StylesObject`](index-1.md#stylesobject)\>[]
+
+##### injectGlobal() [#injectglobal]
+
+```ts
+injectGlobal(strings, ...values): void;
+```
+
+Defined in: [emotion.ts:65](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L65)
+
+Defines styles that apply globally (e.g. `body`, `html`).
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `strings` | `TemplateStringsArray` |
+| ...`values` | readonly `unknown`[] |
+
+###### Returns
+
+`void`
+
+##### stylesheet() [#stylesheet]
+
+```ts
+stylesheet(): string;
+```
+
+Defined in: [emotion.ts:70](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L70)
+
+Emits the full CSS for all generated emotion styles.
+
+###### Returns
+
+`string`
+
+***
+
+### EmotionCss [#emotioncss-1]
+
+Defined in: [emotion.ts:39](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L39)
+
+Style handle that stringifies to its readable class name.
+
+#### Extends
+
+- [`StyleHandle`](index-1.md#stylehandle)
+
+#### Properties
+
+| Property | Modifier | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ | ------ |
+| $$$declarations$$$ `declarations` | `readonly` | [`Declarations`](index-1.md#declarations) | CSS properties for this handle. | [`StyleHandle`](index-1.md#stylehandle).[`declarations`](index-1.md#declarations-1) | [styles/types.ts:117](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L117) |
+| $$$key$$$ `key` | `readonly` | `string` | Full path joined by dots. | [`StyleHandle`](index-1.md#stylehandle).[`key`](index-1.md#key-1) | [styles/types.ts:113](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L113) |
+| $$$kind$$$ `kind` | `readonly` | `"handle"` | Discriminant for [StyleEntry](index-1.md#styleentry). | [`StyleHandle`](index-1.md#stylehandle).[`kind`](index-1.md#kind) | [styles/types.ts:107](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L107) |
+| $$$localname$$$ `localName` | `readonly` | `string` | Leaf key if at root, or composed path for nested handles. | [`StyleHandle`](index-1.md#stylehandle).[`localName`](index-1.md#localname) | [styles/types.ts:111](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L111) |
+| $$$modulename$$$ `moduleName` | `readonly` | `string` | The registered module name this handle belongs to. | [`StyleHandle`](index-1.md#stylehandle).[`moduleName`](index-1.md#modulename) | [styles/types.ts:109](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L109) |
+| $$$readablename$$$ `readableName` | `readonly` | `string` | Predictable name used for output CSS classes. | [`StyleHandle`](index-1.md#stylehandle).[`readableName`](index-1.md#readablename) | [styles/types.ts:115](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L115) |
+| $$$variant$$$ `variant` | `readonly` | `boolean` | `true` when produced inside `variants(...)`. Skipped by [StylesCollector.use](index-1.md#use). | [`StyleHandle`](index-1.md#stylehandle).[`variant`](index-1.md#variant) | [styles/types.ts:119](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L119) |
+
+#### Methods
+
+##### \[toPrimitive\]() [#toprimitive]
+
+```ts
+toPrimitive: string;
+```
+
+Defined in: [emotion.ts:43](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L43)
+
+Template interpolation; same as [EmotionCss.toString](#tostring).
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `hint` | `string` |
+
+###### Returns
+
+`string`
+
+##### resolveClassName() [#resolveclassname]
+
+```ts
+resolveClassName(context): string;
+```
+
+Defined in: [styles/types.ts:121](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/styles/types.ts#L121)
+
+Produces the final class name via the provided resolver context.
+
+###### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `context` | \{ `resolveClassName`: (...`handles`) => `string`; \} | - |
+| `context.resolveClassName` | (...`handles`) => `string` | Joins one or more handles into a class-name string. |
+
+###### Returns
+
+`string`
+
+###### Inherited from
+
+[`StyleHandle`](index-1.md#stylehandle).[`resolveClassName`](index-1.md#resolveclassname)
+
+##### toString() [#tostring]
+
+```ts
+toString(): string;
+```
+
+Defined in: [emotion.ts:41](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L41)
+
+Stringifies to the readable class name.
+
+###### Returns
+
+`string`
+
+***
+
+### StyleElementLike [#styleelementlike]
+
+Defined in: [dom\_sink.ts:11](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L11)
+
+Minimal interface for a DOM `<style>` element.
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| $$$textcontent$$$ `textContent` | `string` \| `null` | Current stylesheet text, or `null` before the first flush. | [dom\_sink.ts:13](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L13) |
+
+***
+
+### StyleSink [#stylesink]
+
+Defined in: [emotion.ts:27](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L27)
+
+Receives stylesheet invalidation from Emotion compat modules.
+
+#### Methods
+
+##### invalidate() [#invalidate]
+
+```ts
+invalidate(render): void;
+```
+
+Defined in: [emotion.ts:29](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L29)
+
+Marks the sink dirty. `render` produces the current stylesheet when it flushes.
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `render` | () => `string` |
+
+###### Returns
+
+`void`
+
+## Type Aliases
+
+### ClassNameArg [#classnamearg]
+
+```ts
+type ClassNameArg = 
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | EmotionCss
+  | StyleHandle
+  | ClassNameArg[]
+  | {
+[className: string]: boolean;
+};
+```
+
+Defined in: [emotion.ts:47](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L47)
+
+One `cx(...)` argument: a class, handle, list, or truthy map.
+
+## Functions
+
+### createDomSink() [#createdomsink]
+
+```ts
+function createDomSink(__namedParameters): StyleSink;
+```
+
+Defined in: [dom\_sink.ts:35](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/dom_sink.ts#L35)
+
+One managed `<style>` element, rewritten on each flush.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `__namedParameters` | [`CreateDomSinkOptions`](#createdomsinkoptions) |
+
+#### Returns
+
+[`StyleSink`](#stylesink)
+
+***
+
+### createEmotion() [#createemotion]
+
+```ts
+function createEmotion<TTokens>(distillery, options?): Emotion;
+```
+
+Defined in: [emotion.ts:117](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/emotion.ts#L117)
+
+`@emotion/css`-shaped API over a distillery.
+
+`String(css\`...\`)` is the readable class name and does not collect. Passing the wrapper through `resolveClassName` collects and compacts like a native handle.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TTokens` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `distillery` | [`Distillery`](index-1.md#distillery)\<`TTokens`\> | Bound distillery that owns the underlying registry. |
+| `options` | [`CreateEmotionOptions`](#createemotionoptions) | Optional sink for DOM injection. |
+
+#### Returns
+
+[`Emotion`](#emotion)