@elastic/distillate 0.0.0 → 0.1.0

package/docs/concepts/single-copy.md

@@ -0,0 +1,103 @@
+---
+navigation_title: Single-copy invariant
+description: Exactly one copy of Distillate may load at runtime.
+---
+
+# Single-copy invariant
+
+The engine keeps module-scope state:
+
+- A `WeakSet` of values produced inside `variants(...)`, so `collector.use(module)` can skip them.
+- A `WeakMap` from module to dependent-entry lists, so auto-collection does not walk the whole registry per handle.
+- Per-registry emotion caches (template wrappers, sinks).
+
+Two copies of the module mean two caches. Variants from copy A look unmarked to copy B's collector, so they ship in every artifact and inflate CSS. That reads as a payload regression, not a throw.
+
+## What the package does
+
+On import, `src/instance.ts` stores a random identity token on `globalThis[Symbol.for('elastic.distillate.instance')]`. A later import with a different token logs a `console.warn`. It warns rather than throws because two copies degrade output without breaking it. A reload (HMR, a fresh vitest registry) also mints a new token, so a warning is not proof of two physical packages.
+
+The package `sideEffects` field lists `**/instance.ts` and `**/instance.js` so bundlers do not tree-shake the guard away.
+
+## What consumers must do
+
+Do not nest a second version of `@elastic/distillate` in an app's `node_modules`. When a **library** bundles, mark Distillate external so the app supplies the one copy. When an **app** bundles, force every importer to resolve the copy at the project root.
+
+### Vite
+
+`ssr.external` leaves Distillate out of the SSR bundle (Node loads the package once). `resolve.dedupe` makes client and SSR resolve the same physical directory. `build.rollupOptions.external` is for library builds; do not set it in an app that must ship Distillate to the browser.
+
+```ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    dedupe: ['@elastic/distillate'],
+  },
+  ssr: {
+    external: [
+      '@elastic/distillate',
+      '@elastic/distillate/emotion',
+      '@elastic/distillate/testing',
+    ],
+  },
+  // Library packages only — omit this block in an application:
+  build: {
+    rollupOptions: {
+      external: ['@elastic/distillate', /^@elastic\/distillate\//],
+    },
+  },
+});
+```
+
+### Rollup (library)
+
+```js
+export default {
+  external: ['@elastic/distillate', /^@elastic\/distillate\//],
+};
+```
+
+### webpack
+
+Library:
+
+```js
+module.exports = {
+  externals: {
+    '@elastic/distillate': '@elastic/distillate',
+    '@elastic/distillate/emotion': '@elastic/distillate/emotion',
+    '@elastic/distillate/testing': '@elastic/distillate/testing',
+  },
+};
+```
+
+App — pin every importer to the hoisted package:
+
+```js
+module.exports = {
+  resolve: {
+    alias: {
+      '@elastic/distillate$': require.resolve('@elastic/distillate'),
+      '@elastic/distillate/emotion$': require.resolve(
+        '@elastic/distillate/emotion'
+      ),
+      '@elastic/distillate/testing$': require.resolve(
+        '@elastic/distillate/testing'
+      ),
+    },
+  },
+};
+```
+
+## Plugin-host architectures
+
+In a platform where many independently built plugins share one runtime (Kibana-style), the platform — not any individual plugin — must own the single copy. Declare Distillate as a **platform-provided shared dependency** (similar to how `react` and `react-dom` are shared), and configure each plugin build to externalize all three entry points. A plugin that bundles its own copy will silently inflate every artifact it emits and break variant tree-shaking across the module boundary.
+
+## Dual-package hazard
+
+The package is published as ESM (`dist/`, reached through the `import` export condition) with a parallel CommonJS build (`dist/cjs/`, reached through `require`) so hosts that transpile to CommonJS — a Kibana-style server plugin, for instance — can `require('@elastic/distillate')` without hitting Node's `ERR_REQUIRE_ESM`. Both builds compile from the same `src/`, but they are two physically distinct sets of files.
+
+That reintroduces the single-copy problem one level up: if one importer in a process reaches the package through `import` and another reaches it through `require`, Node loads **both** builds, each with its own module-scope state and its own identity token. This is the same failure mode as two copies in `node_modules`, described above — a `console.warn`, not a crash, and it silently inflates artifact CSS because variants from one build look unmarked to the other build's collector.
+
+This is a real risk specifically where a host mixes module systems for the same dependency — for example, a plugin-host platform where some plugins bundle Distillate via `import` and others load it via `require`. It is not a risk merely because both `dist/` and `dist/cjs/` exist on disk; a consistent toolchain resolves to exactly one of them. Pick one export condition for a given runtime and keep every importer on it — the platform-external, dedupe, and alias configuration above pins the *physical directory*; it does not by itself prevent a second, differently-loaded copy of that directory if some other part of the same process resolves the package through the other condition.

package/docs/concepts/tokens.md

@@ -0,0 +1,99 @@
+---
+navigation_title: Tokens and vars
+description: Theme trees, lightDark, cq, contextualVar, and module-local vars groups.
+---
+
+# Tokens and vars
+
+Author a nested value tree. `createDistillery` derives `CssToken` / `ScaleToken` leaves and the `themeVars` registry. Branded values stringify through `Symbol.toPrimitive`, which is why they interpolate into tagged templates.
+
+## Theme tokens
+
+```ts
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      warning: '#FACB3D',
+    },
+  },
+});
+const { ink } = distillery.tokens.colors;
+String(ink); <1>
+ink.cssVar; <2>
+ink.path; <3>
+```
+
+1. Interpolates as `var(--eui-colors-ink)`. This is what tagged templates splice in.
+2. Custom-property name: `--eui-colors-ink`.
+3. Slash path matching `themeVars` keys: `colors/ink`.
+
+A string leaf is scheme-invariant (`light === dark`). `lightDark(light, dark)` is scheme-varying and both sides must be CSS `<color>` values. Emission uses `light-dark(light, dark)` when the two values differ. Unread theme tokens are pruned from the theme block.
+
+`zipSchemes(light, dark)` folds two per-scheme trees into this form: equal strings stay bare, differing strings become `lightDark`, and `ScaleToken` leaves must agree.
+
+Named variations go on `variations` in `createDistillery`. Declaring a variation does not emit it; name it at `renderStyles` with `{ flatten }` or `{ alternates }`. Variations extend the base only. `ScaleToken` leaves must match the base because they inline and cannot vary. See [declare and select variations](../guides/theming.md).
+
+`themeToken(path, cssVar)` remains the constructor derivation calls. Paths are slash-delimited (`colors/ink`), matching `themeVars` keys.
+
+A surface that cannot resolve `var(--x)` (a headless SVG rasterizer, for example) should call `distillery.resolveValues(scheme, variation?)` instead of walking `themeVars` by hand. That walk returns nested literal strings for one scheme, including `ScaleToken.value`. A surface that still wants the stylesheet, but has no color scheme for `light-dark()` to resolve against, passes `{ scheme }` to `renderStyles`. See [read values outside CSS](../guides/non-css-surfaces.md).
+
+The `chip` module below uses `tokens.colors.surface` from the [quick start](../getting-started/quick-start.md) token tree.
+
+## Scale tokens
+
+```ts
+const gap = cq('8px', '2cqi');
+String(gap); <1>
+gap.cq; <2>
+```
+
+1. Inlines as `8px`. No custom property, nothing to prune.
+2. Container-relative value: `2cqi`. Use this when the declaration should track container size.
+
+`cq` is an alias of `scaleToken`.
+
+## Shared contextual vars
+
+```ts
+const foreground = contextualVar(
+  'vars/app/tone/foreground',
+  '--eui-app-tone-foreground'
+);
+String(foreground); <1>
+String(foreground.name); <2>
+```
+
+1. Interpolating the var **reads** it: `var(--eui-app-tone-foreground)`.
+2. Writing `.name` **declares** the property: `--eui-app-tone-foreground`.
+
+Register the path in `sharedVars` so two modules can share the name without either owning it.
+
+## Module-local `vars`
+
+```ts
+const chip = distillery.createStyleModule('chip', ({ css, tokens, vars }) => {
+  const look = vars('look', {
+    bg: tokens.colors.surface,
+    unusedBorder: tokens.colors.accent, <1>
+  });
+  return {
+    root: css`
+      ${look} <2>
+      background: ${look.bg}; <3>
+    `,
+    loud: css`
+      ${look.set({ bg: tokens.colors.accent })} <4>
+    `,
+  };
+});
+```
+
+1. Never referenced, so this key is pruned — and so is the `colors.accent` default it would have pulled in.
+2. Emits default declarations (`--eui-chip-look-bg: var(--eui-colors-surface)`).
+3. Reads the var.
+4. Override on this handle. Override entries emit after defaults, so stacking `root` and the modifier class wins.
+
+Local-var names are `cssVarName(prefix, path)` (`--${prefix}-${module}-${group}-${key}`). A collision with a theme or shared var throws at module construction. See [name collisions](../guides/name-collisions.md).

package/docs/docset.yml

@@ -0,0 +1,53 @@
+# Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+# or more contributor license agreements. Licensed under the Elastic License
+# 2.0; you may not use this file except in compliance with the Elastic License
+# 2.0.
+
+project: 'Distillate'
+# Internal Codex publication needs a `registry:` environment name and a
+# `codex.group` from the docs team. Those values are not public; leave them
+# unset until onboarding. Isolated GitHub Pages builds do not need them.
+# Vite playground, its description page, and executable fixtures live under `docs/` but are not pages.
+exclude:
+  - playground/**
+  - playground.md
+  - examples/**
+toc:
+  - file: index.md
+  - folder: getting-started
+    children:
+      - file: index.md
+      - file: installation.md
+      - file: quick-start.md
+      - file: your-first-stylesheet.md
+  - folder: concepts
+    children:
+      - file: index.md
+      - file: distillery.md
+      - file: tokens.md
+      - file: authoring.md
+      - file: collection.md
+      - file: naming-and-output.md
+      - file: ordering.md
+      - file: single-copy.md
+  - folder: guides
+    children:
+      - file: index.md
+      - file: vs-emotion.md
+      - file: theming.md
+      - file: non-css-surfaces.md
+      - file: compact-artifacts.md
+      - file: react-renderer.md
+      - file: emotion-migration.md
+      - file: var-invariant.md
+      - file: name-collisions.md
+  - folder: reference
+    children:
+      - file: index.md
+      - file: entry-points.md
+      - file: environment.md
+      - file: api.md
+      - folder: api
+      - file: okf-map.md
+subs:
+  pkg: '@elastic/distillate'

package/docs/examples/01-stylesheet.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { createExampleDistillery } from './fixture';
+
+/** Emits the full readable stylesheet for every registered module. */
+export const run = (): string => {
+  const distillery = createExampleDistillery();
+  distillery.createStyleModule('demo', ({ css, tokens }) => ({
+    root: css`
+      color: ${tokens.colors.ink};
+      padding: ${tokens.gap};
+    `,
+  }));
+  return distillery.renderStyles(distillery.stylesheetCollector());
+};

package/docs/examples/02-artifact.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { createExampleDistillery } from './fixture';
+
+/** Collects one handle and emits a compact, self-contained payload. */
+export const run = (): string => {
+  const distillery = createExampleDistillery();
+  const demo = distillery.createStyleModule('demo', ({ css, tokens }) => ({
+    root: css`
+      color: ${tokens.colors.ink};
+      padding: ${tokens.gap};
+    `,
+    unused: css`
+      color: ${tokens.colors.accent};
+    `,
+  }));
+
+  const collector = distillery.artifactCollector('compact');
+  collector.use(demo.handles.root);
+  return distillery.renderStyles(collector);
+};

package/docs/examples/03-variants.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { variants } from '../../src/index';
+
+import { createExampleDistillery } from './fixture';
+
+export interface VariantExample {
+  readonly withoutVariants: string;
+  readonly withLoud: string;
+}
+
+/** Variant entries stay off always-on collection until a handle is named. */
+export const run = (): VariantExample => {
+  const distillery = createExampleDistillery();
+  const demo = distillery.createStyleModule('toned', ({ css, tokens }) => ({
+    root: css`
+      color: ${tokens.colors.ink};
+    `,
+    tone: variants(
+      ['calm', 'loud'] as const,
+      (tone) => css`
+        outline-color: ${tone === 'calm' ? tokens.colors.surface : tokens.colors.accent};
+      `
+    ),
+  }));
+
+  const collector = distillery.artifactCollector('readable');
+  collector.use(demo);
+  const withoutVariants = distillery.renderStyles(collector);
+
+  collector.useHandles([demo.handles.tone.loud]);
+  const withLoud = distillery.renderStyles(collector);
+
+  return { withoutVariants, withLoud };
+};

package/docs/examples/04-emotion.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { createEmotion } from '../../src/emotion';
+
+import { createExampleDistillery } from './fixture';
+
+export interface EmotionExample {
+  readonly className: string;
+  readonly stylesheet: string;
+}
+
+/** Emotion-shaped authoring over the same distillery. */
+export const run = (): EmotionExample => {
+  const distillery = createExampleDistillery();
+  const emotion = createEmotion(distillery);
+  const { colors, gap } = distillery.tokens;
+  const { ink, accent } = colors;
+  const card = emotion.css`
+    color: ${ink};
+    &:hover {
+      color: ${accent};
+    }
+    @media (min-width: 600px) {
+      padding: ${gap};
+    }
+  `;
+  return { className: String(card), stylesheet: emotion.stylesheet() };
+};

package/docs/examples/05-var-invariant.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import {
+  assertVarRefsHaveDeclarations,
+  findVarRefViolations,
+} from '../../src/testing';
+
+import { createExampleDistillery } from './fixture';
+
+export interface VarInvariantExample {
+  readonly css: string;
+  readonly violationCount: number;
+}
+
+/** Checks that every `var(...)` in emitted CSS has a matching declaration. */
+export const run = (): VarInvariantExample => {
+  const distillery = createExampleDistillery();
+  distillery.createStyleModule('demo', ({ css, tokens }) => ({
+    root: css`
+      color: ${tokens.colors.ink};
+    `,
+  }));
+  const css = distillery.renderStyles(distillery.stylesheetCollector());
+  assertVarRefsHaveDeclarations(css);
+  return { css, violationCount: findVarRefViolations(css).length };
+};

package/docs/examples/06-payload.ts

@@ -0,0 +1,85 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { variants } from '../../src/index';
+
+import { createExampleDistillery } from './fixture';
+
+export interface PayloadExample {
+  readonly stylesheet: string;
+  readonly artifact: string;
+  readonly stylesheetBytes: number;
+  readonly artifactBytes: number;
+}
+
+const utf8Bytes = (css: string): number =>
+  new TextEncoder().encode(css).byteLength;
+
+/** Full readable stylesheet versus a compact artifact from one named render. */
+export const run = (): PayloadExample => {
+  const distillery = createExampleDistillery();
+  const panel = distillery.createStyleModule(
+    'panel',
+    ({ css, tokens, vars }) => {
+      const look = vars('look', {
+        bg: tokens.colors.surface,
+        fg: tokens.colors.ink,
+        ring: tokens.colors.accent,
+      });
+      return {
+        root: css`
+          ${look}
+          display: grid;
+          gap: ${tokens.gap};
+          padding: ${tokens.gap};
+          background: ${look.bg};
+          color: ${look.fg};
+        `,
+        title: css`
+          margin: 0;
+          color: ${tokens.colors.accent};
+        `,
+        tone: variants(['calm', 'loud', 'danger'] as const, (tone) => {
+          if (tone === 'calm') {
+            return css`
+              outline-color: ${tokens.colors.surface};
+            `;
+          }
+          if (tone === 'loud') {
+            return css`
+              ${look}
+              outline-color: ${look.ring};
+              outline-width: ${tokens.gap};
+            `;
+          }
+          return css`
+            outline-color: ${tokens.colors.ink};
+            background: ${tokens.colors.accent};
+            color: ${tokens.colors.surface};
+          `;
+        }),
+        footer: css`
+          color: ${tokens.colors.accent};
+          padding: ${tokens.gap};
+          border-color: ${tokens.colors.ink};
+        `,
+      };
+    }
+  );
+
+  const stylesheet = distillery.renderStyles(distillery.stylesheetCollector());
+  const collector = distillery.artifactCollector('compact');
+  collector.useHandles([panel.handles.root, panel.handles.tone.calm]);
+  const artifact = distillery.renderStyles(collector);
+
+  return {
+    stylesheet,
+    artifact,
+    stylesheetBytes: utf8Bytes(stylesheet),
+    artifactBytes: utf8Bytes(artifact),
+  };
+};

package/docs/examples/fixture.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { cq, createDistillery, lightDark } from '../../src/index';
+
+export const createExampleDistillery = () =>
+  createDistillery({
+    prefix: 'eui',
+    themeScope: '.eui-view',
+    theme: {
+      colors: {
+        ink: lightDark('#111', '#eee'),
+        accent: lightDark('#06c', '#8cf'),
+        surface: lightDark('#fff', '#000'),
+      },
+      gap: cq('8px', '2cqi'),
+    },
+  });

package/docs/getting-started/index.md

@@ -0,0 +1,14 @@
+---
+navigation_title: Getting started
+description: Install Distillate and emit your first stylesheet.
+---
+
+# Getting started
+
+{{pkg}} targets Node.js 20 and later, published as ESM with a parallel CommonJS build for hosts that can only `require(...)`. Three pages get a library bound and emitting CSS:
+
+- [Installation](installation.md)
+- [Quick start](quick-start.md)
+- [Your first stylesheet](your-first-stylesheet.md)
+
+After that, read [the distillery](../concepts/distillery.md) and [naming and output](../concepts/naming-and-output.md), or try the [playground](https://elastic.github.io/distillate/playground/).

package/docs/getting-started/installation.md

@@ -0,0 +1,30 @@
+---
+navigation_title: Installation
+description: Add Distillate to a project.
+---
+
+# Installation
+
+The only supported install is the published package on the public npm registry:
+
+```sh
+npm install @elastic/distillate
+```
+
+pnpm and yarn work the same way (`pnpm add @elastic/distillate`). The package declares `engines.node` `>=20`. Git URL installs, GitHub Packages, and GitHub Release tarballs are not supported.
+
+The primary build is ESM (`"type": "module"`), reached through the `import` export condition. A parallel CommonJS build is published under the `require` condition for hosts whose loader cannot use ESM — for example a plugin-host platform (Kibana-style) whose server code is transpiled to CommonJS and calls `require(...)` rather than `import`. Bundlers and Node's own resolver pick whichever condition matches automatically; you do not select one yourself. See [dual-package hazard](../concepts/single-copy.md#dual-package-hazard) for the one thing this adds to watch for.
+
+## Entry points
+
+| Specifier                     | Use                                              |
+| ----------------------------- | ------------------------------------------------ |
+| `@elastic/distillate`         | Engine, authoring, tokens, collector, renderer.  |
+| `@elastic/distillate/emotion` | `createEmotion`, `createDomSink`.                |
+| `@elastic/distillate/testing` | Var-invariant helpers. Does not import `stylis`. |
+
+The root and emotion entries both reach `stylis@4.4.0`. Do not hoist a different stylis version; nested templates walk a pinned `compile()` tree shape.
+
+## Bundlers
+
+Exactly one copy of `@elastic/distillate` may load. Two copies break `variants(...)` tree-shaking. Library builds should list it as an external; apps should dedupe to the project-root install. Vite, Rollup, and webpack snippets: [single-copy invariant](../concepts/single-copy.md).

package/docs/getting-started/quick-start.md

@@ -0,0 +1,61 @@
+---
+navigation_title: Quick start
+description: Bind an environment, author a module, and emit CSS.
+---
+
+# Quick start
+
+Three calls cover the happy path: bind, author, emit.
+
+## Bind
+
+```ts
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      accent: lightDark('#06c', '#8cf'),
+      surface: lightDark('#fff', '#000'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+});
+```
+
+`prefix` must be a CSS identifier segment. `themeScope` is the selector that wraps emitted theme-variable declarations. Theme-tree keys match `/^[A-Za-z_][A-Za-z0-9_]*$/`. Strings and `lightDark` leaves become theme vars named `cssVarName(prefix, path)`; `cq` / `scaleToken` leaves inline. Differing `lightDark` values fold into `light-dark(...)`.
+
+## Author
+
+```ts
+const demo = distillery.createStyleModule('demo', ({ css, tokens }) => ({
+  root: css`
+    color: ${tokens.colors.ink}; <1>
+    padding: ${tokens.gap}; <2>
+  `,
+}));
+```
+
+1. Theme token: records a dependency, emits `var(--eui-colors-ink)`.
+2. Scale token: inlines `8px`.
+
+## Emit
+
+A full readable stylesheet:
+
+```ts
+distillery.renderStyles(distillery.stylesheetCollector()); // readable: .demo-root, --eui-colors-ink
+```
+
+A compact artifact that includes only `demo.handles.root`:
+
+```ts
+const collector = distillery.artifactCollector('compact');
+collector.use(demo.handles.root); // unused handles and tokens drop out
+distillery.renderStyles(collector); // compact: .a, --a
+```
+
+Those outputs are asserted in [`docs/examples/`](https://github.com/elastic/distillate/tree/main/docs/examples). Next: [your first stylesheet](your-first-stylesheet.md), [declare and select variations](../guides/theming.md), or skip to [naming and output](../concepts/naming-and-output.md).