@fusion.dev/helix-docs 0.111.1 → 0.112.0

package/content/intent-reference.mdx

@@ -10,11 +10,14 @@ title: Intent reference
 every field `ThemeIntent` accepts and what changes when you set it.
 
 ```ts
-import { derive } from '@fusion.dev/helix-theme'
+import { initTheme } from '@fusion.dev/helix-theme'
 
-const theme = derive({ brand: '#2563eb' })
+const engine = await initTheme('/theme.wasm')
+const theme = engine.derive({ brand: '#2563eb' })
 ```
 
+[Deriving a theme](./theming) shows how Node loads the engine.
+
 **`brand` is the only required input.** Every other field has a default,
 computed from `brand` or from the Helix design language. A theme that sets only
 `brand` is a valid theme.

package/content/metrics.mdx

@@ -60,7 +60,7 @@ either barrel. The per-component tables show what your page pays.
 | `@fusion.dev/helix-core` | 177,056 | 56,663 | 48,189 | The element base class, mixins, decorators, and floating positioning. |
 | `@fusion.dev/helix-headless` | 726,171 | 188,118 | 146,385 | Every headless family. The barrel entry includes all of them. |
 | `@fusion.dev/helix-icons` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
-| `@fusion.dev/helix-theme` | 3,288 | 1,571 | 1,355 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
+| `@fusion.dev/helix-theme` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
 | `@fusion.dev/helix` | 1,257,753 | 294,483 | 216,072 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
@@ -402,7 +402,7 @@ stripped column shows the bytes we removed.
 | `@fusion.dev/helix-headless` | 13,168,854 | 504 | 1,051,088 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
 | `@fusion.dev/helix-icons` | 150,162 | 21 | 50,346 | `svgo` |
 | `@fusion.dev/helix-styles` | 102,108 | 6 | 0 | none |
-| `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
+| `@fusion.dev/helix-theme` | 500,416 | 8 | 5,191 | none |
 | `@fusion.dev/helix` | 14,295,674 | 870 | 371,115 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet

package/content/theming.mdx

@@ -45,22 +45,35 @@ exact for the default seed and approximate for any other.
 target, measures every pair, and returns the theme with any violations:
 
 ```ts
-import { deriveTheme, toCss } from '@fusion.dev/helix-theme'
-
-const theme = deriveTheme({
-  brand: '#0b3d91',
-  contrastTarget: 4.5, // 4.5 is WCAG AA, 7 is AAA
-  scheme: 'light',
-})
+import { readFile } from 'node:fs/promises'
+import { initTheme } from '@fusion.dev/helix-theme'
+
+const engine = await initTheme(
+  await readFile(new URL(import.meta.resolve('@fusion.dev/helix-theme/wasm/fusion_helix_theme_bg.wasm'))),
+)
+
+const theme = engine.derive(
+  {
+    brand: '#0b3d91',
+    contrastTarget: 4.5, // 4.5 is WCAG AA, 7 is AAA
+    scheme: 'light',
+  },
+  [':root'],
+)
 
 if (theme.violations.length > 0) {
   throw new Error(theme.violations.join('\n'))
 }
 
-console.log(toCss(theme))
+console.log(theme.css[':root'])
 ```
 
-The CSS from `toCss` includes the seeds as well as the tokens. The stylesheet
+The engine is WebAssembly, so `initTheme` loads it once and you wait for it.
+Node passes the module's bytes, as above. A browser passes the URL you serve
+`fusion_helix_theme_bg.wasm` from, such as `initTheme('/theme.wasm')`.
+`derive` renders the CSS under each selector you name.
+
+The CSS includes the seeds as well as the tokens. The stylesheet
 computes the values the engine does not, from the same seeds the engine used:
 
 - The twenty-four series colors for charts
@@ -71,6 +84,32 @@ This keeps both ways of theming in agreement on the same page.
 
 Use tuned to try a color. Use verified for the theme you ship.
 
+## Derive both modes
+
+A site with light and dark mode needs both themes. `deriveModes` derives your
+intent in each mode and renders one block, with each color as a
+`light-dark()` pair, the way the shipped stylesheet writes its tokens:
+
+```ts
+import { initTheme } from '@fusion.dev/helix-theme'
+
+const engine = await initTheme('/theme.wasm')
+const { css, dark, light } = engine.deriveModes({ brand: '#0b3d91' }, [':root'])
+
+for (const theme of [light, dark]) {
+  if (theme.violations.length > 0) {
+    throw new Error(theme.violations.join('\n'))
+  }
+}
+
+console.log(css[':root'])
+```
+
+`color-scheme` picks the half, so the block follows the operating system and
+`[data-color-mode]` on any element, as described in [Color modes](./color-modes).
+A value that is not a color and still changes with the mode, such as the edge
+of a floating surface, is set by rules after the block, one for each mode.
+
 ## Why Helix uses OKLCH
 
 Equal numeric steps in sRGB do not look like equal steps. That makes scales and
@@ -106,7 +145,7 @@ engine solves each foreground color against the hardest surface it appears on.
 Each derived token includes the result of its contrast check:
 
 ```ts
-const theme = deriveTheme({ brand })
+const theme = engine.derive({ brand })
 
 for (const token of theme.tokens) {
   console.log(token.name, token.hex, token.contrast, token.chromaReduced)

package/dist/sources.generated.js

@@ -1905,11 +1905,14 @@ title: Intent reference
 every field \`ThemeIntent\` accepts and what changes when you set it.
 
 \`\`\`ts
-import { derive } from '@fusion.dev/helix-theme'
+import { initTheme } from '@fusion.dev/helix-theme'
 
-const theme = derive({ brand: '#2563eb' })
+const engine = await initTheme('/theme.wasm')
+const theme = engine.derive({ brand: '#2563eb' })
 \`\`\`
 
+[Deriving a theme](./theming) shows how Node loads the engine.
+
 **\`brand\` is the only required input.** Every other field has a default,
 computed from \`brand\` or from the Helix design language. A theme that sets only
 \`brand\` is a valid theme.
@@ -2830,7 +2833,7 @@ either barrel. The per-component tables show what your page pays.
 | \`@fusion.dev/helix-core\` | 177,056 | 56,663 | 48,189 | The element base class, mixins, decorators, and floating positioning. |
 | \`@fusion.dev/helix-headless\` | 726,171 | 188,118 | 146,385 | Every headless family. The barrel entry includes all of them. |
 | \`@fusion.dev/helix-icons\` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
-| \`@fusion.dev/helix-theme\` | 3,288 | 1,571 | 1,355 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
+| \`@fusion.dev/helix-theme\` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
 | \`@fusion.dev/helix\` | 1,257,753 | 294,483 | 216,072 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
@@ -3172,7 +3175,7 @@ stripped column shows the bytes we removed.
 | \`@fusion.dev/helix-headless\` | 13,168,854 | 504 | 1,051,088 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
 | \`@fusion.dev/helix-icons\` | 150,162 | 21 | 50,346 | \`svgo\` |
 | \`@fusion.dev/helix-styles\` | 102,108 | 6 | 0 | none |
-| \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
+| \`@fusion.dev/helix-theme\` | 500,416 | 8 | 5,191 | none |
 | \`@fusion.dev/helix\` | 14,295,674 | 870 | 371,115 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
@@ -5173,22 +5176,35 @@ exact for the default seed and approximate for any other.
 target, measures every pair, and returns the theme with any violations:
 
 \`\`\`ts
-import { deriveTheme, toCss } from '@fusion.dev/helix-theme'
-
-const theme = deriveTheme({
-  brand: '#0b3d91',
-  contrastTarget: 4.5, // 4.5 is WCAG AA, 7 is AAA
-  scheme: 'light',
-})
+import { readFile } from 'node:fs/promises'
+import { initTheme } from '@fusion.dev/helix-theme'
+
+const engine = await initTheme(
+  await readFile(new URL(import.meta.resolve('@fusion.dev/helix-theme/wasm/fusion_helix_theme_bg.wasm'))),
+)
+
+const theme = engine.derive(
+  {
+    brand: '#0b3d91',
+    contrastTarget: 4.5, // 4.5 is WCAG AA, 7 is AAA
+    scheme: 'light',
+  },
+  [':root'],
+)
 
 if (theme.violations.length > 0) {
   throw new Error(theme.violations.join('\\n'))
 }
 
-console.log(toCss(theme))
+console.log(theme.css[':root'])
 \`\`\`
 
-The CSS from \`toCss\` includes the seeds as well as the tokens. The stylesheet
+The engine is WebAssembly, so \`initTheme\` loads it once and you wait for it.
+Node passes the module's bytes, as above. A browser passes the URL you serve
+\`fusion_helix_theme_bg.wasm\` from, such as \`initTheme('/theme.wasm')\`.
+\`derive\` renders the CSS under each selector you name.
+
+The CSS includes the seeds as well as the tokens. The stylesheet
 computes the values the engine does not, from the same seeds the engine used:
 
 - The twenty-four series colors for charts
@@ -5199,6 +5215,32 @@ This keeps both ways of theming in agreement on the same page.
 
 Use tuned to try a color. Use verified for the theme you ship.
 
+## Derive both modes
+
+A site with light and dark mode needs both themes. \`deriveModes\` derives your
+intent in each mode and renders one block, with each color as a
+\`light-dark()\` pair, the way the shipped stylesheet writes its tokens:
+
+\`\`\`ts
+import { initTheme } from '@fusion.dev/helix-theme'
+
+const engine = await initTheme('/theme.wasm')
+const { css, dark, light } = engine.deriveModes({ brand: '#0b3d91' }, [':root'])
+
+for (const theme of [light, dark]) {
+  if (theme.violations.length > 0) {
+    throw new Error(theme.violations.join('\\n'))
+  }
+}
+
+console.log(css[':root'])
+\`\`\`
+
+\`color-scheme\` picks the half, so the block follows the operating system and
+\`[data-color-mode]\` on any element, as described in [Color modes](./color-modes).
+A value that is not a color and still changes with the mode, such as the edge
+of a floating surface, is set by rules after the block, one for each mode.
+
 ## Why Helix uses OKLCH
 
 Equal numeric steps in sRGB do not look like equal steps. That makes scales and
@@ -5234,7 +5276,7 @@ engine solves each foreground color against the hardest surface it appears on.
 Each derived token includes the result of its contrast check:
 
 \`\`\`ts
-const theme = deriveTheme({ brand })
+const theme = engine.derive({ brand })
 
 for (const token of theme.tokens) {
   console.log(token.name, token.hex, token.contrast, token.chromaReduced)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.111.1",
+  "version": "0.112.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -32,12 +32,18 @@
     "peers": "bun scripts/build-peers.mjs",
     "test": "bun test src",
     "timings": "bun scripts/build-timings.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit && bun scripts/check-snippets.mjs"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.111.1",
-    "@fusion.dev/helix-testing": "0.111.1",
+    "@fusion.dev/helix": "0.112.0",
+    "@fusion.dev/helix-cem": "0.112.0",
+    "@fusion.dev/helix-headless": "0.112.0",
+    "@fusion.dev/helix-icons": "0.112.0",
+    "@fusion.dev/helix-map": "0.112.0",
+    "@fusion.dev/helix-styles": "0.112.0",
+    "@fusion.dev/helix-testing": "0.112.0",
+    "@fusion.dev/helix-theme": "0.112.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"