@fusion.dev/helix-docs 0.111.2 → 0.113.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/maps.mdx

@@ -106,6 +106,19 @@ It also draws landmarks, highway signs, and neighborhood names:
   roads.
 - Neighborhoods are in spaced capitals, quieter than the towns.
 
+Pass `landmarks` to choose which kinds the map draws. `false` draws none, for a
+map whose own markers are the places a reader is looking for. A list draws only
+those kinds:
+
+```js
+mapLibreStyle(colors, { landmarks: ['nature', 'transit'] })
+```
+
+The kinds are `culture`, `food`, `health`, `learning`, `lodging`, `nature`,
+`shopping`, `sport`, and `transit`, and `MAP_LANDMARKS` lists them. The option
+holds when `followTheme` restyles the map, because it builds the style from the
+same options.
+
 The same call builds a light map for a light theme and a dark map for a dark
 theme. Map labels meet a contrast target of 4.5 against the land. Pass
 `contrast` to change it, `language` to choose which name each place is labeled
@@ -139,6 +152,42 @@ changes its theme another way, such as by replacing a stylesheet, call
 a frame or two after the page loads. If the colors never become available, it
 reports which one is missing.
 
+## Put a map behind your content
+
+Set `fill` to lay a map behind your page's own content, such as a hero whose
+words decide its height. The frame covers its container instead of taking a
+height of its own, and draws no border or corners, because the container's edge
+is the map's. Give the container a position, such as `position: relative`:
+
+```html
+<section class="hero">
+  <helix-map fill credit-placement="bottom-end" label="Downtown Austin">
+    <div id="map"></div>
+  </helix-map>
+  <div class="hero-words">
+    <h1>Every stop, one map</h1>
+  </div>
+</section>
+```
+
+```css
+.hero,
+.hero-words {
+  position: relative;
+}
+```
+
+Content after the map, with a position of its own, is drawn over it. Give that
+content a ground of its own, such as a translucent panel, so it reads over any
+part of the map.
+
+`credit-placement` draws the map's credit in a corner over the map instead of in
+a strip under it. Use `bottom-end` or `bottom-start`, and keep it away from the
+corner your controls are in. The credit is one line until it is pointed at or
+its links are focused, and then it shows in full. That compact form is the one
+OpenStreetMap's attribution guidance accepts for a small credit. Most tile
+licenses require the credit to stay visible, so Helix never hides it.
+
 ## Draw the map before it loads
 
 `mapSnapshot(view)` draws the map on your server as an SVG, from the same tiles

package/content/metrics.mdx

@@ -60,8 +60,8 @@ 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` | 1,257,753 | 294,483 | 216,072 | Every styled family. |
+| `@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,259,099 | 294,668 | 216,376 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -84,7 +84,7 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 20,614 bytes gzipped alone, and it adds 2,224 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 103 styled components, the smallest is `code` at 9,782 bytes gzipped alone, and the largest is `data-table` at 63,610. Every family together is 294,483.
+Across the 103 styled components, the smallest is `code` at 9,782 bytes gzipped alone, and the largest is `data-table` at 63,610. Every family together is 294,668.
 
 No family imports a barrel. The `barrels` rule in `fusion workspace` enforces that. `@fusion.dev/helix-headless` marks every module in `dist` as having side effects, which is true of a file that calls `customElements.define`. A bundler can remove none of it. One `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 188,118 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets `sideEffects`, whatever its name.
 
@@ -337,7 +337,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `list` | 36,624 | 11,044 | 9,710 | 5,782 | 1,307 | 1,089 |
 | `listbox` | 111,463 | 35,406 | 28,903 | 15,768 | 4,108 | 3,250 |
 | `loader` | 34,908 | 10,789 | 9,500 | 4,051 | 1,003 | 806 |
-| `map` | 160,886 | 43,420 | 36,165 | 66,396 | 12,712 | 10,488 |
+| `map` | 162,232 | 43,691 | 36,301 | 67,742 | 12,991 | 10,725 |
 | `megamenu` | 66,881 | 21,799 | 19,289 | 9,805 | 2,417 | 1,975 |
 | `menu` | 133,249 | 43,442 | 36,482 | 16,362 | 3,837 | 3,101 |
 | `meter` | 40,330 | 12,019 | 10,617 | 9,479 | 2,223 | 1,972 |
@@ -402,8 +402,8 @@ 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` | 471,326 | 8 | 4,708 | none |
-| `@fusion.dev/helix` | 14,295,674 | 870 | 371,115 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix-theme` | 500,416 | 8 | 5,191 | none |
+| `@fusion.dev/helix` | 14,306,888 | 870 | 371,453 | `@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.
@@ -2382,6 +2385,19 @@ It also draws landmarks, highway signs, and neighborhood names:
   roads.
 - Neighborhoods are in spaced capitals, quieter than the towns.
 
+Pass \`landmarks\` to choose which kinds the map draws. \`false\` draws none, for a
+map whose own markers are the places a reader is looking for. A list draws only
+those kinds:
+
+\`\`\`js
+mapLibreStyle(colors, { landmarks: ['nature', 'transit'] })
+\`\`\`
+
+The kinds are \`culture\`, \`food\`, \`health\`, \`learning\`, \`lodging\`, \`nature\`,
+\`shopping\`, \`sport\`, and \`transit\`, and \`MAP_LANDMARKS\` lists them. The option
+holds when \`followTheme\` restyles the map, because it builds the style from the
+same options.
+
 The same call builds a light map for a light theme and a dark map for a dark
 theme. Map labels meet a contrast target of 4.5 against the land. Pass
 \`contrast\` to change it, \`language\` to choose which name each place is labeled
@@ -2415,6 +2431,42 @@ changes its theme another way, such as by replacing a stylesheet, call
 a frame or two after the page loads. If the colors never become available, it
 reports which one is missing.
 
+## Put a map behind your content
+
+Set \`fill\` to lay a map behind your page's own content, such as a hero whose
+words decide its height. The frame covers its container instead of taking a
+height of its own, and draws no border or corners, because the container's edge
+is the map's. Give the container a position, such as \`position: relative\`:
+
+\`\`\`html
+<section class="hero">
+  <helix-map fill credit-placement="bottom-end" label="Downtown Austin">
+    <div id="map"></div>
+  </helix-map>
+  <div class="hero-words">
+    <h1>Every stop, one map</h1>
+  </div>
+</section>
+\`\`\`
+
+\`\`\`css
+.hero,
+.hero-words {
+  position: relative;
+}
+\`\`\`
+
+Content after the map, with a position of its own, is drawn over it. Give that
+content a ground of its own, such as a translucent panel, so it reads over any
+part of the map.
+
+\`credit-placement\` draws the map's credit in a corner over the map instead of in
+a strip under it. Use \`bottom-end\` or \`bottom-start\`, and keep it away from the
+corner your controls are in. The credit is one line until it is pointed at or
+its links are focused, and then it shows in full. That compact form is the one
+OpenStreetMap's attribution guidance accepts for a small credit. Most tile
+licenses require the credit to stay visible, so Helix never hides it.
+
 ## Draw the map before it loads
 
 \`mapSnapshot(view)\` draws the map on your server as an SVG, from the same tiles
@@ -2830,8 +2882,8 @@ 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\` | 1,257,753 | 294,483 | 216,072 | Every styled family. |
+| \`@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,259,099 | 294,668 | 216,376 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -2854,7 +2906,7 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 20,614 bytes gzipped alone, and it adds 2,224 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 103 styled components, the smallest is \`code\` at 9,782 bytes gzipped alone, and the largest is \`data-table\` at 63,610. Every family together is 294,483.
+Across the 103 styled components, the smallest is \`code\` at 9,782 bytes gzipped alone, and the largest is \`data-table\` at 63,610. Every family together is 294,668.
 
 No family imports a barrel. The \`barrels\` rule in \`fusion workspace\` enforces that. \`@fusion.dev/helix-headless\` marks every module in \`dist\` as having side effects, which is true of a file that calls \`customElements.define\`. A bundler can remove none of it. One \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 188,118 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets \`sideEffects\`, whatever its name.
 
@@ -3107,7 +3159,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`list\` | 36,624 | 11,044 | 9,710 | 5,782 | 1,307 | 1,089 |
 | \`listbox\` | 111,463 | 35,406 | 28,903 | 15,768 | 4,108 | 3,250 |
 | \`loader\` | 34,908 | 10,789 | 9,500 | 4,051 | 1,003 | 806 |
-| \`map\` | 160,886 | 43,420 | 36,165 | 66,396 | 12,712 | 10,488 |
+| \`map\` | 162,232 | 43,691 | 36,301 | 67,742 | 12,991 | 10,725 |
 | \`megamenu\` | 66,881 | 21,799 | 19,289 | 9,805 | 2,417 | 1,975 |
 | \`menu\` | 133,249 | 43,442 | 36,482 | 16,362 | 3,837 | 3,101 |
 | \`meter\` | 40,330 | 12,019 | 10,617 | 9,479 | 2,223 | 1,972 |
@@ -3172,8 +3224,8 @@ 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\` | 471,326 | 8 | 4,708 | none |
-| \`@fusion.dev/helix\` | 14,295,674 | 870 | 371,115 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix-theme\` | 500,416 | 8 | 5,191 | none |
+| \`@fusion.dev/helix\` | 14,306,888 | 870 | 371,453 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5173,22 +5225,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 +5264,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 +5325,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.2",
+  "version": "0.113.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.2",
-    "@fusion.dev/helix-testing": "0.111.2",
+    "@fusion.dev/helix": "0.113.0",
+    "@fusion.dev/helix-cem": "0.113.0",
+    "@fusion.dev/helix-headless": "0.113.0",
+    "@fusion.dev/helix-icons": "0.113.0",
+    "@fusion.dev/helix-map": "0.113.0",
+    "@fusion.dev/helix-styles": "0.113.0",
+    "@fusion.dev/helix-testing": "0.113.0",
+    "@fusion.dev/helix-theme": "0.113.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"