@fusion.dev/helix-docs 0.59.0 → 0.59.2

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` | 156,003 | 51,384 | 43,598 | Element base class, mixins, decorators, floating positioning. |
-| `@fusion.dev/helix-headless` | 604,405 | 156,858 | 122,393 | Every headless family, which is what the barrel means. |
+| `@fusion.dev/helix-headless` | 604,476 | 156,936 | 122,329 | 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,080,439 | 253,111 | 186,250 | Every styled family. |
+| `@fusion.dev/helix` | 1,080,510 | 253,168 | 186,220 | 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,837 bytes gzipped alone and adds 2,220 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,451 gzipped alone, the dearest `data-table` at 59,280, over 100 components. Every family at once is 253,111.
+Across the tier: the cheapest is `code` at 9,451 gzipped alone, the dearest `data-table` at 59,280, over 100 components. Every family at once is 253,168.
 
-**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 156,858 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 156,936 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,531 bytes gzipped alone.
 
@@ -236,7 +236,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | `navigation` | 30,254 | 10,225 | 9,039 | 1,361 | 373 | 270 |
 | `notifications` | 91,555 | 29,712 | 24,386 | 11,333 | 2,683 | 2,227 |
 | `number-input` | 88,718 | 29,001 | 23,737 | 7,190 | 1,948 | 1,588 |
-| `object-inspector` | 128,519 | 42,936 | 36,169 | 19,231 | 5,173 | 4,353 |
+| `object-inspector` | 128,505 | 42,925 | 36,132 | 19,158 | 5,146 | 4,343 |
 | `option` | 30,590 | 10,121 | 8,951 | 2,933 | 669 | 440 |
 | `outline` | 33,689 | 11,399 | 10,047 | 4,590 | 1,415 | 1,077 |
 | `pagination` | 136,644 | 43,500 | 36,531 | 27,201 | 6,365 | 5,264 |
@@ -273,9 +273,9 @@ Structure, accessibility, state and form participation. No presentation, and no
 | `tour` | 65,837 | 22,059 | 19,525 | 10,924 | 2,757 | 2,289 |
 | `tree` | 86,417 | 28,562 | 23,363 | 7,191 | 1,998 | 1,559 |
 | `trend` | 75,252 | 25,076 | 20,677 | 1,056 | 298 | 432 |
-| `video` | 139,631 | 44,963 | 37,999 | 30,227 | 7,275 | 6,284 |
+| `video` | 139,846 | 45,052 | 38,013 | 30,442 | 7,363 | 6,318 |
 | `video-playlist` | 121,622 | 40,189 | 33,737 | 14,893 | 3,507 | 2,886 |
-| `virtual-list` | 34,078 | 11,490 | 10,128 | 2,485 | 766 | 590 |
+| `virtual-list` | 34,221 | 11,557 | 10,170 | 2,413 | 759 | 626 |
 
 ### Styled tier
 
@@ -340,7 +340,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
 | `navigation` | 31,635 | 10,614 | 9,354 | 2,726 | 776 | 551 |
 | `notifications` | 104,511 | 32,059 | 26,461 | 24,276 | 5,036 | 4,268 |
 | `number-input` | 93,500 | 30,132 | 24,759 | 11,960 | 3,059 | 2,497 |
-| `object-inspector` | 142,156 | 45,283 | 38,229 | 32,848 | 7,511 | 6,360 |
+| `object-inspector` | 142,142 | 45,272 | 38,221 | 32,775 | 7,491 | 6,313 |
 | `option` | 33,844 | 11,025 | 9,728 | 6,175 | 1,565 | 1,269 |
 | `orb` | 38,554 | 13,412 | 11,856 | 8,604 | 3,194 | 2,817 |
 | `outline` | 37,429 | 12,173 | 10,768 | 8,313 | 2,221 | 1,744 |
@@ -380,9 +380,9 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
 | `tour` | 75,388 | 23,666 | 20,981 | 20,453 | 4,395 | 3,668 |
 | `tree` | 92,117 | 29,903 | 24,578 | 12,881 | 3,327 | 2,769 |
 | `trend` | 78,409 | 25,784 | 21,316 | 4,205 | 969 | 888 |
-| `video` | 158,637 | 48,366 | 40,953 | 49,213 | 10,706 | 9,306 |
+| `video` | 158,852 | 48,453 | 40,959 | 49,428 | 10,793 | 9,265 |
 | `video-playlist` | 135,523 | 42,690 | 35,871 | 28,774 | 5,971 | 4,981 |
-| `virtual-list` | 34,870 | 11,699 | 10,331 | 3,259 | 971 | 837 |
+| `virtual-list` | 35,013 | 11,768 | 10,403 | 3,187 | 955 | 789 |
 
 ## What lands in `node_modules`
 
@@ -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` | 983,274 | 153 | 222,331 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 11,340,991 | 464 | 836,460 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-headless` | 11,353,229 | 464 | 836,734 | `@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,457,534 | 796 | 333,797 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 12,470,065 | 796 | 333,806 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/visual-axes.mdx

@@ -87,6 +87,29 @@ write it with nothing painted.
 and never of controls, which take their height from the region they sit in
 through `data-density`, so it lives only where something is painted.
 
+## When a family takes `neutral`
+
+`tone` is the one axis whose vocabulary the table above leaves open, and
+`neutral` is the value families have kept deciding about one at a time. Three
+have argued it at their own declarations and arrived at the same rule, so it
+belongs here once instead.
+
+**A family that reports a status takes the status words and stops.** `Callout`
+and `Toast` say it in nearly the same sentence: a callout reports a status and
+never a brand role, so it takes four of the seven. There is no neutral status,
+and a value that could not be drawn is worse than a value that cannot be named.
+
+**A family whose resting state is already untoned does not need it.** `Text`
+gives that reason against its own missing `default`: a value matching no rule
+would fall through to the inherited ink and read as working while saying
+nothing. The absent attribute is the resting case and says it better.
+
+**`neutral` is for a thing that carries a tone without reporting one**: a gray
+tag beside six colored ones, a button that is a button rather than the primary
+action. `Announcement` spells its own out rather than leaving the attribute off,
+which is what makes the tone sayable rather than only reachable, and that is the
+whole of when this value is worth taking.
+
 ## What each shape is
 
 `shape` is the axis whose values are geometries that look alike in a table and
@@ -107,6 +130,27 @@ not on a page, so it is worth saying what each one draws.
 `square` too, in the same registered axis. Membership is what a check can see,
 so nothing could have caught that, and a table is what stops it happening again.
 
+## What each separation draws
+
+`separation` says where a box ends, and `elevated` is the value nearly every
+family leaves out, so it is worth saying what each one draws and what that
+omission is about.
+
+| Value | What it draws |
+|---|---|
+| `elevated` | A surface lifted off the page, with a shadow under it |
+| `filled` | A ground of its own, and no edge |
+| `outlined` | An edge over the ground it already has |
+| `plain` | Neither, so the box ends where its content does |
+
+**Leaving `elevated` out is a fact about the value rather than about the family
+that skips it.** A shadow says the box floats above the page, which is true of a
+card picked up off a grid and of an announcement laid over the content, and
+false of a row in a feed, a groove a thumb sits in, a checkbox, or a bar across
+a video. A family taking the other three and stopping is following the value,
+not departing from the axis, and owes no argument for it. A family that *does*
+take it is the one saying something, and `Card` and `Announcement` both do.
+
 ## What a step inward means
 
 `nesting` is the one axis whose values are three readings of the same fact, so

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\` | 156,003 | 51,384 | 43,598 | Element base class, mixins, decorators, floating positioning. |
-| \`@fusion.dev/helix-headless\` | 604,405 | 156,858 | 122,393 | Every headless family, which is what the barrel means. |
+| \`@fusion.dev/helix-headless\` | 604,476 | 156,936 | 122,329 | 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,080,439 | 253,111 | 186,250 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,080,510 | 253,168 | 186,220 | 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,837 bytes gzipped alone and adds 2,220 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,451 gzipped alone, the dearest \`data-table\` at 59,280, over 100 components. Every family at once is 253,111.
+Across the tier: the cheapest is \`code\` at 9,451 gzipped alone, the dearest \`data-table\` at 59,280, over 100 components. Every family at once is 253,168.
 
-**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 156,858 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 156,936 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,531 bytes gzipped alone.
 
@@ -2200,7 +2200,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | \`navigation\` | 30,254 | 10,225 | 9,039 | 1,361 | 373 | 270 |
 | \`notifications\` | 91,555 | 29,712 | 24,386 | 11,333 | 2,683 | 2,227 |
 | \`number-input\` | 88,718 | 29,001 | 23,737 | 7,190 | 1,948 | 1,588 |
-| \`object-inspector\` | 128,519 | 42,936 | 36,169 | 19,231 | 5,173 | 4,353 |
+| \`object-inspector\` | 128,505 | 42,925 | 36,132 | 19,158 | 5,146 | 4,343 |
 | \`option\` | 30,590 | 10,121 | 8,951 | 2,933 | 669 | 440 |
 | \`outline\` | 33,689 | 11,399 | 10,047 | 4,590 | 1,415 | 1,077 |
 | \`pagination\` | 136,644 | 43,500 | 36,531 | 27,201 | 6,365 | 5,264 |
@@ -2237,9 +2237,9 @@ Structure, accessibility, state and form participation. No presentation, and no
 | \`tour\` | 65,837 | 22,059 | 19,525 | 10,924 | 2,757 | 2,289 |
 | \`tree\` | 86,417 | 28,562 | 23,363 | 7,191 | 1,998 | 1,559 |
 | \`trend\` | 75,252 | 25,076 | 20,677 | 1,056 | 298 | 432 |
-| \`video\` | 139,631 | 44,963 | 37,999 | 30,227 | 7,275 | 6,284 |
+| \`video\` | 139,846 | 45,052 | 38,013 | 30,442 | 7,363 | 6,318 |
 | \`video-playlist\` | 121,622 | 40,189 | 33,737 | 14,893 | 3,507 | 2,886 |
-| \`virtual-list\` | 34,078 | 11,490 | 10,128 | 2,485 | 766 | 590 |
+| \`virtual-list\` | 34,221 | 11,557 | 10,170 | 2,413 | 759 | 626 |
 
 ### Styled tier
 
@@ -2304,7 +2304,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
 | \`navigation\` | 31,635 | 10,614 | 9,354 | 2,726 | 776 | 551 |
 | \`notifications\` | 104,511 | 32,059 | 26,461 | 24,276 | 5,036 | 4,268 |
 | \`number-input\` | 93,500 | 30,132 | 24,759 | 11,960 | 3,059 | 2,497 |
-| \`object-inspector\` | 142,156 | 45,283 | 38,229 | 32,848 | 7,511 | 6,360 |
+| \`object-inspector\` | 142,142 | 45,272 | 38,221 | 32,775 | 7,491 | 6,313 |
 | \`option\` | 33,844 | 11,025 | 9,728 | 6,175 | 1,565 | 1,269 |
 | \`orb\` | 38,554 | 13,412 | 11,856 | 8,604 | 3,194 | 2,817 |
 | \`outline\` | 37,429 | 12,173 | 10,768 | 8,313 | 2,221 | 1,744 |
@@ -2344,9 +2344,9 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
 | \`tour\` | 75,388 | 23,666 | 20,981 | 20,453 | 4,395 | 3,668 |
 | \`tree\` | 92,117 | 29,903 | 24,578 | 12,881 | 3,327 | 2,769 |
 | \`trend\` | 78,409 | 25,784 | 21,316 | 4,205 | 969 | 888 |
-| \`video\` | 158,637 | 48,366 | 40,953 | 49,213 | 10,706 | 9,306 |
+| \`video\` | 158,852 | 48,453 | 40,959 | 49,428 | 10,793 | 9,265 |
 | \`video-playlist\` | 135,523 | 42,690 | 35,871 | 28,774 | 5,971 | 4,981 |
-| \`virtual-list\` | 34,870 | 11,699 | 10,331 | 3,259 | 971 | 837 |
+| \`virtual-list\` | 35,013 | 11,768 | 10,403 | 3,187 | 955 | 789 |
 
 ## What lands in \`node_modules\`
 
@@ -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\` | 983,274 | 153 | 222,331 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 11,340,991 | 464 | 836,460 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-headless\` | 11,353,229 | 464 | 836,734 | \`@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,457,534 | 796 | 333,797 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 12,470,065 | 796 | 333,806 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5156,6 +5156,29 @@ write it with nothing painted.
 and never of controls, which take their height from the region they sit in
 through \`data-density\`, so it lives only where something is painted.
 
+## When a family takes \`neutral\`
+
+\`tone\` is the one axis whose vocabulary the table above leaves open, and
+\`neutral\` is the value families have kept deciding about one at a time. Three
+have argued it at their own declarations and arrived at the same rule, so it
+belongs here once instead.
+
+**A family that reports a status takes the status words and stops.** \`Callout\`
+and \`Toast\` say it in nearly the same sentence: a callout reports a status and
+never a brand role, so it takes four of the seven. There is no neutral status,
+and a value that could not be drawn is worse than a value that cannot be named.
+
+**A family whose resting state is already untoned does not need it.** \`Text\`
+gives that reason against its own missing \`default\`: a value matching no rule
+would fall through to the inherited ink and read as working while saying
+nothing. The absent attribute is the resting case and says it better.
+
+**\`neutral\` is for a thing that carries a tone without reporting one**: a gray
+tag beside six colored ones, a button that is a button rather than the primary
+action. \`Announcement\` spells its own out rather than leaving the attribute off,
+which is what makes the tone sayable rather than only reachable, and that is the
+whole of when this value is worth taking.
+
 ## What each shape is
 
 \`shape\` is the axis whose values are geometries that look alike in a table and
@@ -5176,6 +5199,27 @@ not on a page, so it is worth saying what each one draws.
 \`square\` too, in the same registered axis. Membership is what a check can see,
 so nothing could have caught that, and a table is what stops it happening again.
 
+## What each separation draws
+
+\`separation\` says where a box ends, and \`elevated\` is the value nearly every
+family leaves out, so it is worth saying what each one draws and what that
+omission is about.
+
+| Value | What it draws |
+|---|---|
+| \`elevated\` | A surface lifted off the page, with a shadow under it |
+| \`filled\` | A ground of its own, and no edge |
+| \`outlined\` | An edge over the ground it already has |
+| \`plain\` | Neither, so the box ends where its content does |
+
+**Leaving \`elevated\` out is a fact about the value rather than about the family
+that skips it.** A shadow says the box floats above the page, which is true of a
+card picked up off a grid and of an announcement laid over the content, and
+false of a row in a feed, a groove a thumb sits in, a checkbox, or a bar across
+a video. A family taking the other three and stopping is following the value,
+not departing from the axis, and owes no argument for it. A family that *does*
+take it is the one saying something, and \`Card\` and \`Announcement\` both do.
+
 ## What a step inward means
 
 \`nesting\` is the one axis whose values are three readings of the same fact, so

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.59.0",
+  "version": "0.59.2",
   "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.59.0",
-    "@fusion.dev/helix-testing": "0.59.0",
+    "@fusion.dev/helix-cem": "0.59.2",
+    "@fusion.dev/helix-testing": "0.59.2",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"