@elastic/distillate 0.0.0 → 0.2.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,290 @@
+# emotion
+
+## Interfaces
+
+### CreateEmotionOptions [#createemotionoptions]
+
+Defined in: [emotion.ts:30](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L30)
+
+Shared sink for Emotion compat modules on one registry.
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| $$$sink$$$ `sink?` | [`StyleSink`](index-1.md#stylesink) | Notified when a compat module registers. Shared across `createEmotion` calls on the same registry. | [emotion.ts:32](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L32) |
+
+***
+
+### Emotion [#emotion]
+
+Defined in: [emotion.ts:56](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L56)
+
+Emotion-shaped authoring API bound to one Distillery registry.
+
+#### Methods
+
+##### css() [#css]
+
+```ts
+css(strings, ...values): EmotionCss;
+```
+
+Defined in: [emotion.ts:58](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L58)
+
+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:60](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L60)
+
+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:69](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L69)
+
+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:62](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L62)
+
+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:67](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L67)
+
+Emits the full CSS for all generated emotion styles.
+
+###### Returns
+
+`string`
+
+***
+
+### EmotionCss [#emotioncss-1]
+
+Defined in: [emotion.ts:36](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L36)
+
+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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/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/d1dccb0eb5372d5984331c21603220340752a304/src/styles/types.ts#L119) |
+
+#### Methods
+
+##### \[toPrimitive\]() [#toprimitive]
+
+```ts
+toPrimitive: string;
+```
+
+Defined in: [emotion.ts:40](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L40)
+
+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/d1dccb0eb5372d5984331c21603220340752a304/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-1)
+
+##### toString() [#tostring]
+
+```ts
+toString(): string;
+```
+
+Defined in: [emotion.ts:38](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L38)
+
+Stringifies to the readable class name.
+
+###### Returns
+
+`string`
+
+## Type Aliases
+
+### ClassNameArg [#classnamearg]
+
+```ts
+type ClassNameArg = 
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | EmotionCss
+  | StyleHandle
+  | ClassNameArg[]
+  | {
+[className: string]: boolean;
+};
+```
+
+Defined in: [emotion.ts:44](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L44)
+
+One `cx(...)` argument: a class, handle, list, or truthy map.
+
+## Functions
+
+### createEmotion() [#createemotion]
+
+```ts
+function createEmotion<TTokens>(distillery, options?): Emotion;
+```
+
+Defined in: [emotion.ts:114](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/emotion.ts#L114)
+
+`@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)
+
+## References
+
+### createDomSink [#createdomsink]
+
+Re-exports [createDomSink](index-1.md#createdomsink)
+
+***
+
+### CreateDomSinkOptions [#createdomsinkoptions]
+
+Re-exports [CreateDomSinkOptions](index-1.md#createdomsinkoptions)
+
+***
+
+### DocumentLike [#documentlike]
+
+Re-exports [DocumentLike](index-1.md#documentlike)
+
+***
+
+### StyleElementLike [#styleelementlike]
+
+Re-exports [StyleElementLike](index-1.md#styleelementlike)
+
+***
+
+### StyleParentLike [#styleparentlike]
+
+Re-exports [StyleParentLike](index-1.md#styleparentlike)
+
+***
+
+### StyleSink [#stylesink]
+
+Re-exports [StyleSink](index-1.md#stylesink)