@fusion.dev/helix-docs 0.99.0 → 0.101.0

package/content/building-on-the-headless-tier.mdx

@@ -46,7 +46,7 @@ a combobox that appears not to open.
 
 [//]: # (renders)
 
-**27 of the 94 headless families interpolate another family's tag**, across 20 distinct children.
+**27 of the 95 headless families interpolate another family's tag**, across 20 distinct children.
 
 | Family | Renders |
 |---|---|

package/content/iconography.mdx

@@ -119,7 +119,41 @@ consumer's 15 kB to about 90.
 Only the default weight carries that index, so `name` draws bold. A consumer who
 wants the set in another weight imports the values and hands them over.
 
-## Adding one
+## A set of your own
+
+The generator that builds this set is the package's own command, so you are not
+waiting on us to carry a glyph:
+
+```sh
+npx helix-icons build --source ./brand-icons --out src/icons.ts
+```
+
+```tsx
+import { peak } from './icons'
+
+<helix-icon icon={peak} />
+```
+
+It reads a directory of SVG files and writes the module the element draws from,
+which is the same job whether the drawings are yours, another library's, or the
+1,404 Phosphor glyphs this set does not carry:
+
+```sh
+npx helix-icons build \
+  --source node_modules/@phosphor-icons/core/assets/regular \
+  --list mine.txt --out src/icons.ts
+```
+
+`--suffix` is for a set that spells the weight into the file name, Phosphor's
+bold being `caret-down-bold.svg`. `--index` also writes the record `name` reads,
+which you want if your own elements take a name in markup and do not want
+otherwise, since it is the part nothing can drop.
+
+**A name in two sources is refused rather than decided.** A precedence decides
+silently, and the glyph on the page would be whichever directory sat higher with
+nothing looking wrong afterwards.
+
+## Adding one to this set
 
 Add the name to `helix/icons/icons.txt` and run `turbo run icons`. Phosphor names
 resolve from `@phosphor-icons/core` at build time, so adding a glyph is adding a

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,545 | 156,940 | 122,421 | Every headless family, which is what the barrel means. |
+| `@fusion.dev/helix-headless` | 609,467 | 158,001 | 122,755 | 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,081,623 | 253,263 | 186,323 | Every styled family. |
+| `@fusion.dev/helix` | 1,089,445 | 254,911 | 187,079 | 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
@@ -76,20 +76,20 @@ is the whole cost of adopting the base layer on its own.
 | File | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | `base.css` | 30,672 | 4,430 | 3,844 | The base layer. Recipes for markup Helix does not render, usable with no JavaScript at all. |
-| `elements.css` | 7,848 | 1,341 | 1,202 | Hides each element until its definition loads, generated from the tags in `@fusion.dev/helix`. |
+| `elements.css` | 7,964 | 1,356 | 1,217 | Hides each element until its definition loads, generated from the tags in `@fusion.dev/helix`. |
 | `helix.css` | 207 | 148 | 118 | The four above in one import, in the order they have to be in. |
 | `primitives.css` | 6,390 | 1,260 | 1,084 | The primitive layer. Private, shipped because `tokens.css` resolves into it. |
 | `tokens.css` | 20,987 | 2,567 | 2,138 | The 191 semantic tokens. Nothing paints without this. |
 
 ## What the numbers say
 
-**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.
+**Most of a first component is the runtime under it.** The median styled family is 17,431 bytes gzipped alone and adds 2,218 to a page that already has Helix on it, so 87 percent of the first one is shared and 13 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,263.
+Across the tier: the cheapest is `code` at 9,451 gzipped alone, the dearest `data-table` at 59,280, over 101 components. Every family at once is 254,911.
 
-**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,940 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 158,001 bytes gzipped whatever else the page does, which is 9 times the median family measured above. The styled tier imports the family it extends instead, all 101 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.
+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,365 bytes gzipped alone.
 
 ## Against other systems
 
@@ -226,6 +226,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | `input` | 86,357 | 28,367 | 23,214 | 4,742 | 1,328 | 1,072 |
 | `kbd` | 30,274 | 10,348 | 9,112 | 2,976 | 1,036 | 863 |
 | `legend` | 32,326 | 10,852 | 9,561 | 1,080 | 299 | 308 |
+| `lightbox` | 36,221 | 11,642 | 10,265 | 4,740 | 1,295 | 1,048 |
 | `line-chart` | 74,340 | 25,327 | 22,436 | 10,591 | 3,107 | 2,621 |
 | `list` | 29,376 | 9,761 | 8,590 | 1,726 | 354 | 293 |
 | `listbox` | 94,570 | 30,854 | 25,190 | 10,942 | 3,007 | 2,401 |
@@ -330,6 +331,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
 | `input` | 92,624 | 29,730 | 24,373 | 11,004 | 2,686 | 2,186 |
 | `kbd` | 31,686 | 10,798 | 9,494 | 4,373 | 1,491 | 1,217 |
 | `legend` | 37,142 | 11,968 | 10,511 | 5,790 | 1,395 | 1,125 |
+| `lightbox` | 39,168 | 12,359 | 10,889 | 7,670 | 2,017 | 1,697 |
 | `line-chart` | 84,111 | 27,333 | 24,253 | 20,340 | 5,147 | 4,337 |
 | `list` | 33,442 | 10,705 | 9,446 | 5,782 | 1,313 | 1,161 |
 | `listbox` | 98,839 | 31,853 | 26,044 | 15,204 | 3,989 | 3,280 |
@@ -395,11 +397,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 984,477 | 153 | 222,482 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 11,366,181 | 464 | 836,952 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
-| `@fusion.dev/helix-icons` | 121,091 | 17 | 37,263 | none |
-| `@fusion.dev/helix-styles` | 101,139 | 6 | 0 | none |
+| `@fusion.dev/helix-headless` | 11,510,142 | 470 | 847,366 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-icons` | 131,512 | 21 | 44,809 | `svgo` |
+| `@fusion.dev/helix-styles` | 101,255 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
-| `@fusion.dev/helix` | 12,499,093 | 796 | 333,986 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 12,639,631 | 806 | 337,152 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/dist/sources.generated.js

@@ -316,7 +316,7 @@ a combobox that appears not to open.
 
 [//]: # (renders)
 
-**27 of the 94 headless families interpolate another family's tag**, across 20 distinct children.
+**27 of the 95 headless families interpolate another family's tag**, across 20 distinct children.
 
 | Family | Renders |
 |---|---|
@@ -1570,7 +1570,41 @@ consumer's 15 kB to about 90.
 Only the default weight carries that index, so \`name\` draws bold. A consumer who
 wants the set in another weight imports the values and hands them over.
 
-## Adding one
+## A set of your own
+
+The generator that builds this set is the package's own command, so you are not
+waiting on us to carry a glyph:
+
+\`\`\`sh
+npx helix-icons build --source ./brand-icons --out src/icons.ts
+\`\`\`
+
+\`\`\`tsx
+import { peak } from './icons'
+
+<helix-icon icon={peak} />
+\`\`\`
+
+It reads a directory of SVG files and writes the module the element draws from,
+which is the same job whether the drawings are yours, another library's, or the
+1,404 Phosphor glyphs this set does not carry:
+
+\`\`\`sh
+npx helix-icons build \\
+  --source node_modules/@phosphor-icons/core/assets/regular \\
+  --list mine.txt --out src/icons.ts
+\`\`\`
+
+\`--suffix\` is for a set that spells the weight into the file name, Phosphor's
+bold being \`caret-down-bold.svg\`. \`--index\` also writes the record \`name\` reads,
+which you want if your own elements take a name in markup and do not want
+otherwise, since it is the part nothing can drop.
+
+**A name in two sources is refused rather than decided.** A precedence decides
+silently, and the glyph on the page would be whichever directory sat higher with
+nothing looking wrong afterwards.
+
+## Adding one to this set
 
 Add the name to \`helix/icons/icons.txt\` and run \`turbo run icons\`. Phosphor names
 resolve from \`@phosphor-icons/core\` at build time, so adding a glyph is adding a
@@ -2091,10 +2125,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,545 | 156,940 | 122,421 | Every headless family, which is what the barrel means. |
+| \`@fusion.dev/helix-headless\` | 609,467 | 158,001 | 122,755 | 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,081,623 | 253,263 | 186,323 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,089,445 | 254,911 | 187,079 | 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
@@ -2108,20 +2142,20 @@ is the whole cost of adopting the base layer on its own.
 | File | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | \`base.css\` | 30,672 | 4,430 | 3,844 | The base layer. Recipes for markup Helix does not render, usable with no JavaScript at all. |
-| \`elements.css\` | 7,848 | 1,341 | 1,202 | Hides each element until its definition loads, generated from the tags in \`@fusion.dev/helix\`. |
+| \`elements.css\` | 7,964 | 1,356 | 1,217 | Hides each element until its definition loads, generated from the tags in \`@fusion.dev/helix\`. |
 | \`helix.css\` | 207 | 148 | 118 | The four above in one import, in the order they have to be in. |
 | \`primitives.css\` | 6,390 | 1,260 | 1,084 | The primitive layer. Private, shipped because \`tokens.css\` resolves into it. |
 | \`tokens.css\` | 20,987 | 2,567 | 2,138 | The 191 semantic tokens. Nothing paints without this. |
 
 ## What the numbers say
 
-**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.
+**Most of a first component is the runtime under it.** The median styled family is 17,431 bytes gzipped alone and adds 2,218 to a page that already has Helix on it, so 87 percent of the first one is shared and 13 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,263.
+Across the tier: the cheapest is \`code\` at 9,451 gzipped alone, the dearest \`data-table\` at 59,280, over 101 components. Every family at once is 254,911.
 
-**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,940 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 158,001 bytes gzipped whatever else the page does, which is 9 times the median family measured above. The styled tier imports the family it extends instead, all 101 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.
+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,365 bytes gzipped alone.
 
 ## Against other systems
 
@@ -2258,6 +2292,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | \`input\` | 86,357 | 28,367 | 23,214 | 4,742 | 1,328 | 1,072 |
 | \`kbd\` | 30,274 | 10,348 | 9,112 | 2,976 | 1,036 | 863 |
 | \`legend\` | 32,326 | 10,852 | 9,561 | 1,080 | 299 | 308 |
+| \`lightbox\` | 36,221 | 11,642 | 10,265 | 4,740 | 1,295 | 1,048 |
 | \`line-chart\` | 74,340 | 25,327 | 22,436 | 10,591 | 3,107 | 2,621 |
 | \`list\` | 29,376 | 9,761 | 8,590 | 1,726 | 354 | 293 |
 | \`listbox\` | 94,570 | 30,854 | 25,190 | 10,942 | 3,007 | 2,401 |
@@ -2362,6 +2397,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
 | \`input\` | 92,624 | 29,730 | 24,373 | 11,004 | 2,686 | 2,186 |
 | \`kbd\` | 31,686 | 10,798 | 9,494 | 4,373 | 1,491 | 1,217 |
 | \`legend\` | 37,142 | 11,968 | 10,511 | 5,790 | 1,395 | 1,125 |
+| \`lightbox\` | 39,168 | 12,359 | 10,889 | 7,670 | 2,017 | 1,697 |
 | \`line-chart\` | 84,111 | 27,333 | 24,253 | 20,340 | 5,147 | 4,337 |
 | \`list\` | 33,442 | 10,705 | 9,446 | 5,782 | 1,313 | 1,161 |
 | \`listbox\` | 98,839 | 31,853 | 26,044 | 15,204 | 3,989 | 3,280 |
@@ -2427,11 +2463,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 984,477 | 153 | 222,482 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 11,366,181 | 464 | 836,952 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
-| \`@fusion.dev/helix-icons\` | 121,091 | 17 | 37,263 | none |
-| \`@fusion.dev/helix-styles\` | 101,139 | 6 | 0 | none |
+| \`@fusion.dev/helix-headless\` | 11,510,142 | 470 | 847,366 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-icons\` | 131,512 | 21 | 44,809 | \`svgo\` |
+| \`@fusion.dev/helix-styles\` | 101,255 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
-| \`@fusion.dev/helix\` | 12,499,093 | 796 | 333,986 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 12,639,631 | 806 | 337,152 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 

package/package.json

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