@fusion.dev/helix-docs 0.33.5 → 0.34.0

package/content/metrics.mdx

@@ -59,10 +59,10 @@ repository does that. The per-component tables are what a page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 145,460 | 47,853 | 40,503 | Element base class, mixins, decorators, floating positioning. |
-| `@fusion.dev/helix-headless` | 601,347 | 155,590 | 121,108 | Every headless family, which is what the barrel means. |
+| `@fusion.dev/helix-headless` | 601,399 | 155,615 | 121,088 | Every headless family, which is what the barrel means. |
 | `@fusion.dev/helix-icons` | 47,484 | 14,907 | 12,553 | The whole glyph set. |
 | `@fusion.dev/helix-theme` | 3,288 | 1,571 | 1,355 | The derivation engine. Build time for most consumers, runtime for a theme switcher. |
-| `@fusion.dev/helix` | 1,073,085 | 251,160 | 183,860 | Every styled family. |
+| `@fusion.dev/helix` | 1,073,751 | 251,340 | 184,020 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Not ours. Here so it can be subtracted from every row above it. |
 
 ## The stylesheets
@@ -85,9 +85,9 @@ is the whole cost of adopting the base layer on its own.
 
 **Most of a first component is the runtime under it.** The median styled family is 18,709 bytes gzipped alone and adds 2,213 to a page that already has Helix on it, so 88 percent of the first one is shared and 12 percent is the component. Ten typical components are one plus nine additions rather than ten of the first number, and the pair of columns below is what lets that be worked out rather than guessed.
 
-Across the tier: the cheapest is `code` at 9,408 gzipped alone, the dearest `data-table` at 58,933, over 100 components. Every family at once is 251,160.
+Across the tier: the cheapest is `code` at 9,408 gzipped alone, the dearest `data-table` at 58,933, over 100 components. Every family at once is 251,340.
 
-**No family imports a barrel, and the `barrels` rule in `fusion workspace` is what keeps it that way.** `@fusion.dev/helix-headless` is `sideEffects` over every module in `dist`, which is true of a file that calls `customElements.define` and which means a bundler may drop none of it: one `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 155,590 bytes gzipped whatever else the page does, which is 8 times the median family measured above. The styled tier imports the family it extends instead, all 100 of them, and the check refuses the shape rather than the package name, so the rule follows `sideEffects` wherever it goes.
+**No family imports a barrel, and the `barrels` rule in `fusion workspace` is what keeps it that way.** `@fusion.dev/helix-headless` is `sideEffects` over every module in `dist`, which is true of a file that calls `customElements.define` and which means a bundler may drop none of it: one `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 155,615 bytes gzipped whatever else the page does, which is 8 times the median family measured above. The styled tier imports the family it extends instead, all 100 of them, and the check refuses the shape rather than the package name, so the rule follows `sideEffects` wherever it goes.
 
 The headless tier never had the problem, and it is the control: `@fusion.dev/helix-core` is `sideEffects: false`, and a headless family is a median of 20,496 bytes gzipped alone.
 
@@ -271,7 +271,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | `toolbar` | 30,291 | 10,244 | 9,039 | 2,933 | 942 | 658 |
 | `tooltip` | 60,000 | 20,657 | 18,277 | 6,432 | 1,807 | 1,330 |
 | `tour` | 65,738 | 21,993 | 19,463 | 11,006 | 2,771 | 2,164 |
-| `tree` | 86,155 | 28,426 | 23,245 | 7,125 | 1,950 | 1,518 |
+| `tree` | 86,207 | 28,440 | 23,234 | 7,177 | 1,973 | 1,517 |
 | `trend` | 75,181 | 25,041 | 20,668 | 1,056 | 278 | 191 |
 | `video` | 139,358 | 44,823 | 37,815 | 33,883 | 8,222 | 7,111 |
 | `video-playlist` | 121,595 | 40,146 | 33,651 | 14,968 | 3,503 | 2,890 |
@@ -378,7 +378,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
 | `toolbar` | 31,583 | 10,541 | 9,268 | 4,208 | 1,250 | 960 |
 | `tooltip` | 63,078 | 21,403 | 18,968 | 9,492 | 2,546 | 2,061 |
 | `tour` | 75,289 | 23,611 | 20,886 | 20,537 | 4,381 | 3,576 |
-| `tree` | 91,242 | 29,636 | 24,321 | 12,201 | 3,165 | 2,607 |
+| `tree` | 91,907 | 29,785 | 24,444 | 12,867 | 3,305 | 2,769 |
 | `trend` | 78,338 | 25,747 | 21,284 | 4,205 | 948 | 823 |
 | `video` | 158,345 | 48,236 | 40,754 | 52,850 | 11,669 | 10,126 |
 | `video-playlist` | 135,495 | 42,650 | 35,778 | 28,847 | 5,972 | 4,969 |
@@ -395,11 +395,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 837,166 | 123 | 184,846 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 11,022,623 | 472 | 853,430 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-headless` | 11,039,809 | 472 | 853,585 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
 | `@fusion.dev/helix-icons` | 65,943 | 11 | 20,928 | none |
 | `@fusion.dev/helix-styles` | 101,139 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
-| `@fusion.dev/helix` | 12,005,465 | 798 | 337,086 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 12,021,191 | 798 | 337,103 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/visual-axes.mdx

@@ -1,19 +1,21 @@
 ---
-description: Four words with fixed vocabularies, one escape hatch, and the word that is refused.
+description: Registered words with fixed vocabularies, one escape hatch, and the word that is refused.
 section: Theming
 title: Visual axes
 ---
 
 # Visual axes
 
-A component's visual choices come from four registered axes with fixed
+A component's visual choices come from a registry of axes with fixed
 vocabularies. You cannot invent a value, and a component may take a subset.
 
 | Axis | Values |
 |---|---|
 | `emphasis` | `ghost`, `muted`, `outlined`, `solid`, `subtle` |
 | `material` | `frosted`, `glass`, `transparent` |
+| `nesting` | `heading`, `peer`, `subordinate` |
 | `separation` | `elevated`, `filled`, `outlined`, `plain` |
+| `shape` | `arc`, `circle`, `dots`, `ring`, `rounded`, `square`, `text` |
 | `tone` | The status and intent words: `primary`, `accent`, `neutral`, `danger`, and so on |
 | `width` | `auto`, `full`, `standard` |
 
@@ -66,8 +68,30 @@ on either tier.
 **What it may not be is a place to put something that is on an axis.** That is
 the failure mode `appearance` demonstrated.
 
-## `tone` is the one axis both tiers carry
+## Some axes are carried by both tiers
 
 A styled axis never appears on the headless tier, which has nothing to paint and
-no box to size. `tone` is the exception and a principled one: it says what a
-thing *means*, and meaning survives having no stylesheet.
+no box to size. The exceptions are the axes that are not about paint. `tone` says
+what a thing *means*, and meaning survives having no stylesheet. `shape` says
+what gets *rendered*: a meter at `ring` emits an arc rather than a bar, so the
+markup differs before any rule is written. `nesting` says what depth *is*: a
+tree at `subordinate` ranks its rows, a tree at `heading` makes each branch the
+name of the list under it, a file explorer does neither, and that is true of a
+tree nobody has styled.
+
+## What a step inward means
+
+`nesting` is the one axis whose values are three readings of the same fact, so
+it is worth saying which tree each is for.
+
+| Value | The tree it suits | What moves |
+|---|---|---|
+| `heading` | A documentation sidebar, where a branch names the list it holds and is not a page | The branch, which takes the rail heading. Its children keep the row they had |
+| `peer` | A file explorer, where every row is the same kind of thing | Nothing. The indent is the whole of what depth says |
+| `subordinate` | Side navigation, a categorization, a facet list | The nested row, one step down the type scale and no further |
+
+`heading` and `subordinate` are not one answer said twice. `subordinate` keys on
+depth and quiets the child; `heading` keys on holding children and relabels the
+parent, which is why a branch at any depth is a heading while the step below
+stops after one, and why a top-level leaf sitting beside a branch is left alone
+by both for opposite reasons.

package/dist/pages.generated.js

@@ -261,7 +261,7 @@ export const docPages = [
         title: 'Versioning',
     },
     {
-        description: 'Four words with fixed vocabularies, one escape hatch, and the word that is refused.',
+        description: 'Registered words with fixed vocabularies, one escape hatch, and the word that is refused.',
         section: 'Theming',
         slug: 'visual-axes',
         title: 'Visual axes',

package/dist/sources.generated.js

@@ -2023,10 +2023,10 @@ repository does that. The per-component tables are what a page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 145,460 | 47,853 | 40,503 | Element base class, mixins, decorators, floating positioning. |
-| \`@fusion.dev/helix-headless\` | 601,347 | 155,590 | 121,108 | Every headless family, which is what the barrel means. |
+| \`@fusion.dev/helix-headless\` | 601,399 | 155,615 | 121,088 | Every headless family, which is what the barrel means. |
 | \`@fusion.dev/helix-icons\` | 47,484 | 14,907 | 12,553 | The whole glyph set. |
 | \`@fusion.dev/helix-theme\` | 3,288 | 1,571 | 1,355 | The derivation engine. Build time for most consumers, runtime for a theme switcher. |
-| \`@fusion.dev/helix\` | 1,073,085 | 251,160 | 183,860 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,073,751 | 251,340 | 184,020 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Not ours. Here so it can be subtracted from every row above it. |
 
 ## The stylesheets
@@ -2049,9 +2049,9 @@ is the whole cost of adopting the base layer on its own.
 
 **Most of a first component is the runtime under it.** The median styled family is 18,709 bytes gzipped alone and adds 2,213 to a page that already has Helix on it, so 88 percent of the first one is shared and 12 percent is the component. Ten typical components are one plus nine additions rather than ten of the first number, and the pair of columns below is what lets that be worked out rather than guessed.
 
-Across the tier: the cheapest is \`code\` at 9,408 gzipped alone, the dearest \`data-table\` at 58,933, over 100 components. Every family at once is 251,160.
+Across the tier: the cheapest is \`code\` at 9,408 gzipped alone, the dearest \`data-table\` at 58,933, over 100 components. Every family at once is 251,340.
 
-**No family imports a barrel, and the \`barrels\` rule in \`fusion workspace\` is what keeps it that way.** \`@fusion.dev/helix-headless\` is \`sideEffects\` over every module in \`dist\`, which is true of a file that calls \`customElements.define\` and which means a bundler may drop none of it: one \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 155,590 bytes gzipped whatever else the page does, which is 8 times the median family measured above. The styled tier imports the family it extends instead, all 100 of them, and the check refuses the shape rather than the package name, so the rule follows \`sideEffects\` wherever it goes.
+**No family imports a barrel, and the \`barrels\` rule in \`fusion workspace\` is what keeps it that way.** \`@fusion.dev/helix-headless\` is \`sideEffects\` over every module in \`dist\`, which is true of a file that calls \`customElements.define\` and which means a bundler may drop none of it: one \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 155,615 bytes gzipped whatever else the page does, which is 8 times the median family measured above. The styled tier imports the family it extends instead, all 100 of them, and the check refuses the shape rather than the package name, so the rule follows \`sideEffects\` wherever it goes.
 
 The headless tier never had the problem, and it is the control: \`@fusion.dev/helix-core\` is \`sideEffects: false\`, and a headless family is a median of 20,496 bytes gzipped alone.
 
@@ -2235,7 +2235,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | \`toolbar\` | 30,291 | 10,244 | 9,039 | 2,933 | 942 | 658 |
 | \`tooltip\` | 60,000 | 20,657 | 18,277 | 6,432 | 1,807 | 1,330 |
 | \`tour\` | 65,738 | 21,993 | 19,463 | 11,006 | 2,771 | 2,164 |
-| \`tree\` | 86,155 | 28,426 | 23,245 | 7,125 | 1,950 | 1,518 |
+| \`tree\` | 86,207 | 28,440 | 23,234 | 7,177 | 1,973 | 1,517 |
 | \`trend\` | 75,181 | 25,041 | 20,668 | 1,056 | 278 | 191 |
 | \`video\` | 139,358 | 44,823 | 37,815 | 33,883 | 8,222 | 7,111 |
 | \`video-playlist\` | 121,595 | 40,146 | 33,651 | 14,968 | 3,503 | 2,890 |
@@ -2342,7 +2342,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
 | \`toolbar\` | 31,583 | 10,541 | 9,268 | 4,208 | 1,250 | 960 |
 | \`tooltip\` | 63,078 | 21,403 | 18,968 | 9,492 | 2,546 | 2,061 |
 | \`tour\` | 75,289 | 23,611 | 20,886 | 20,537 | 4,381 | 3,576 |
-| \`tree\` | 91,242 | 29,636 | 24,321 | 12,201 | 3,165 | 2,607 |
+| \`tree\` | 91,907 | 29,785 | 24,444 | 12,867 | 3,305 | 2,769 |
 | \`trend\` | 78,338 | 25,747 | 21,284 | 4,205 | 948 | 823 |
 | \`video\` | 158,345 | 48,236 | 40,754 | 52,850 | 11,669 | 10,126 |
 | \`video-playlist\` | 135,495 | 42,650 | 35,778 | 28,847 | 5,972 | 4,969 |
@@ -2359,11 +2359,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 837,166 | 123 | 184,846 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 11,022,623 | 472 | 853,430 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-headless\` | 11,039,809 | 472 | 853,585 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
 | \`@fusion.dev/helix-icons\` | 65,943 | 11 | 20,928 | none |
 | \`@fusion.dev/helix-styles\` | 101,139 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
-| \`@fusion.dev/helix\` | 12,005,465 | 798 | 337,086 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 12,021,191 | 798 | 337,103 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5064,21 +5064,23 @@ because a second copy of the release notes is a second thing to keep in step and
 the one that goes stale is the one nobody is reading that week.
 `,
     'visual-axes': `---
-description: Four words with fixed vocabularies, one escape hatch, and the word that is refused.
+description: Registered words with fixed vocabularies, one escape hatch, and the word that is refused.
 section: Theming
 title: Visual axes
 ---
 
 # Visual axes
 
-A component's visual choices come from four registered axes with fixed
+A component's visual choices come from a registry of axes with fixed
 vocabularies. You cannot invent a value, and a component may take a subset.
 
 | Axis | Values |
 |---|---|
 | \`emphasis\` | \`ghost\`, \`muted\`, \`outlined\`, \`solid\`, \`subtle\` |
 | \`material\` | \`frosted\`, \`glass\`, \`transparent\` |
+| \`nesting\` | \`heading\`, \`peer\`, \`subordinate\` |
 | \`separation\` | \`elevated\`, \`filled\`, \`outlined\`, \`plain\` |
+| \`shape\` | \`arc\`, \`circle\`, \`dots\`, \`ring\`, \`rounded\`, \`square\`, \`text\` |
 | \`tone\` | The status and intent words: \`primary\`, \`accent\`, \`neutral\`, \`danger\`, and so on |
 | \`width\` | \`auto\`, \`full\`, \`standard\` |
 
@@ -5131,11 +5133,33 @@ on either tier.
 **What it may not be is a place to put something that is on an axis.** That is
 the failure mode \`appearance\` demonstrated.
 
-## \`tone\` is the one axis both tiers carry
+## Some axes are carried by both tiers
 
 A styled axis never appears on the headless tier, which has nothing to paint and
-no box to size. \`tone\` is the exception and a principled one: it says what a
-thing *means*, and meaning survives having no stylesheet.
+no box to size. The exceptions are the axes that are not about paint. \`tone\` says
+what a thing *means*, and meaning survives having no stylesheet. \`shape\` says
+what gets *rendered*: a meter at \`ring\` emits an arc rather than a bar, so the
+markup differs before any rule is written. \`nesting\` says what depth *is*: a
+tree at \`subordinate\` ranks its rows, a tree at \`heading\` makes each branch the
+name of the list under it, a file explorer does neither, and that is true of a
+tree nobody has styled.
+
+## What a step inward means
+
+\`nesting\` is the one axis whose values are three readings of the same fact, so
+it is worth saying which tree each is for.
+
+| Value | The tree it suits | What moves |
+|---|---|---|
+| \`heading\` | A documentation sidebar, where a branch names the list it holds and is not a page | The branch, which takes the rail heading. Its children keep the row they had |
+| \`peer\` | A file explorer, where every row is the same kind of thing | Nothing. The indent is the whole of what depth says |
+| \`subordinate\` | Side navigation, a categorization, a facet list | The nested row, one step down the type scale and no further |
+
+\`heading\` and \`subordinate\` are not one answer said twice. \`subordinate\` keys on
+depth and quiets the child; \`heading\` keys on holding children and relabels the
+parent, which is why a branch at any depth is a heading while the step below
+stops after one, and why a top-level leaf sitting beside a branch is left alone
+by both for opposite reasons.
 `,
     vue: `---
 description: The one compiler setting Vue needs, and why props and events already work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.33.5",
+  "version": "0.34.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.33.5",
-    "@fusion.dev/helix-testing": "0.33.5",
+    "@fusion.dev/helix-cem": "0.34.0",
+    "@fusion.dev/helix-testing": "0.34.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"