@fusion.dev/helix-docs 0.97.0 → 0.99.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/content/building-on-the-headless-tier.mdx +39 -13
  2. package/content/iconography.mdx +47 -5
  3. package/content/metrics.mdx +20 -20
  4. package/dist/sources.generated.js +106 -38
  5. package/package.json +3 -3
package/content/building-on-the-headless-tier.mdx CHANGED
@@ -37,26 +37,30 @@ times in the headless manifest, so it is discoverable rather than folklore.
37
37
  ## The render graph is the part that will catch you
38
38
 
39
39
  **A component that renders another gives you two things to register, and only
40
- one of them is obvious.** Twenty-two of the 88 headless families interpolate
41
- another family's tag, across 89 call sites and seventeen distinct children.
40
+ one of them is obvious.**
42
41
 
43
42
  Register `acme-combobox` without also registering `acme-listbox` and the panel
44
43
  renders a tag nobody defined. That is not an error and not a warning: an
45
44
  unregistered custom element is an inert, unstyled inline box, so what you see is
46
45
  a combobox that appears not to open.
47
46
 
47
+ [//]: # (renders)
48
+
49
+ **27 of the 94 headless families interpolate another family's tag**, across 20 distinct children.
50
+
48
51
  | Family | Renders |
49
52
  |---|---|
50
- | `bar-chart`, `donut-chart`, `heatmap`, `line-chart` | `tooltip` |
51
- | `code-block` | `copy-button` |
53
+ | `area-chart`, `bar-chart`, `copy-button`, `donut-chart`, `heatmap`, `line-chart`, `scatter-chart` | `tooltip` |
54
+ | `chat` | `chat-message` |
55
+ | `code-block`, `object-inspector` | `copy-button` |
52
56
  | `color-input` | `color-picker` |
53
57
  | `color-picker` | `button`, `button-group`, `slider` |
54
58
  | `combobox` | `listbox`, `tag` |
55
59
  | `command` | `dialog`, `listbox` |
56
- | `copy-button` | `tooltip` |
57
- | `data-table` | `pagination` |
60
+ | `data-table` | `checkbox`, `pagination` |
58
61
  | `date-input` | `date-picker`, `tag` |
59
62
  | `file-input` | `tag` |
63
+ | `filter-input` | `divider`, `menu`, `menu-item` |
60
64
  | `notifications` | `format-date` |
61
65
  | `pagination` | `option`, `select` |
62
66
  | `select` | `listbox` |
@@ -65,14 +69,16 @@ a combobox that appears not to open.
65
69
  | `time-picker` | `listbox`, `option` |
66
70
  | `video`, `video-playlist` | `menu`, `menu-item` |
67
71
 
72
+ [//]: # (/renders)
73
+
68
74
  The safe rule is to subclass and register a family together with everything it
69
75
  renders, transitively: `command` reaches `dialog` and `listbox`, and `listbox`
70
76
  reaches `option`.
71
77
 
72
- **This table is maintained by hand today and should not be.** The graph is
73
- already computed inside this repository, by the check that stops us shipping the
74
- same fault, and it is thrown away afterward rather than written to the manifest.
75
- Until it is published, treat the table above as the version that can go stale.
78
+ **This table is generated from the manifest**, which publishes the graph as
79
+ `helix.renders` on every element that interpolates a tag. It was kept by hand
80
+ until 22 September 2026 and was wrong by four families when it stopped being, so
81
+ read it as current rather than as maintained.
76
82
 
77
83
  ## What you have to supply yourself
78
84
 
@@ -92,8 +98,26 @@ acme-listbox:not(:defined) {
92
98
  Visibility rather than `display`, so the page does not reflow when the
93
99
  definitions arrive.
94
100
 
95
- **Your own typings.** The generated `jsx.d.ts`, `vue.d.ts` and `svelte.d.ts`
96
- carry our tag names. For yours, merge each element into the tag map:
101
+ **Your own typings, from the same generator we use.** `@fusion.dev/helix-cem`
102
+ reads your package and writes `jsx.d.ts`, `vue.d.ts` and `svelte.d.ts` for your
103
+ tags, with every member your subclass inherited from ours. Add a `cem.config.ts`
104
+ beside your `package.json`:
105
+
106
+ ```ts
107
+ import type { HelixCemOptions } from '@fusion.dev/helix-cem'
108
+
109
+ export default {
110
+ frameworkTypes: true,
111
+ packageName: 'acme-system',
112
+ tier: 'styled',
113
+ } satisfies HelixCemOptions
114
+ ```
115
+
116
+ and run `bun --bun helix-cem`. It finds what you extend through your
117
+ `dependencies`, so `acme-combobox` arrives with the hundred-odd members it
118
+ inherited rather than the two you wrote.
119
+
120
+ **The tag map is still yours to write**, one line per element, beside the class:
97
121
 
98
122
  ```ts
99
123
  declare global {
@@ -103,7 +127,9 @@ declare global {
103
127
  }
104
128
  ```
105
129
 
106
- Per element, by hand. There is no generated version of this for consumer names.
130
+ That is TypeScript's own convention for a custom element rather than a gap in
131
+ this: the interface merges from your source, and nothing generated can name a
132
+ class it is not in the same program as.
107
133
 
108
134
  ## What you get without asking
109
135
 
package/content/iconography.mdx CHANGED
@@ -10,7 +10,7 @@ title: Iconography
10
10
  <helix-icon name="trash"></helix-icon>
11
11
  ```
12
12
 
13
- 105 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
13
+ 108 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
14
14
  Phosphor's own geometry and it is kept rather than rescaled: normalizing to a 24
15
15
  box would change the optical weight of every glyph and stop the set matching
16
16
  anything upstream. Bold rather than regular, because Phosphor's regular is a
@@ -72,10 +72,52 @@ page, which every caret the library draws already does.
72
72
  import { trash } from '@fusion.dev/helix-icons'
73
73
  ```
74
74
 
75
- Each glyph is an exported string, so you can put one in your own markup, in a
76
- canvas, or anywhere an element is not what you want. Every `name` the library
77
- uses is held to the set of glyphs that actually exist, so a typo is a build
78
- failure rather than an empty box.
75
+ Each glyph is data, `{ content, name, viewBox }`, so you can put one in your own
76
+ markup, in a canvas, or anywhere an element is not what you want. Every `name`
77
+ the library uses is held to the set of glyphs that actually exist, so a typo is a
78
+ build failure rather than an empty box.
79
+
80
+ **Hand one to the element and it draws it**, whatever set it came from:
81
+
82
+ ```tsx
83
+ import { trash } from '@fusion.dev/helix-icons'
84
+
85
+ <helix-icon icon={trash} />
86
+ ```
87
+
88
+ A property rather than an attribute, because an object is not a string: the
89
+ frameworks set properties and plain HTML cannot, which is what `name` is for.
90
+ Both set, the value wins.
91
+
92
+ **This is the door that scales.** `name` resolves through an index of the whole
93
+ set, which no bundler can shake, so a consumer who renders one named icon ships
94
+ all of it: 15 kB gzipped for 108 glyphs. A value ships the one glyph you
95
+ imported. It is also the door out of this set entirely, since anything exporting
96
+ that shape works, whether it is Phosphor at another weight, another library, or
97
+ your own drawings:
98
+
99
+ ```ts
100
+ const dot = { content: '<circle cx="12" cy="12" r="10" fill="currentColor" />', name: 'dot', viewBox: '0 0 24 24' }
101
+ ```
102
+
103
+ ## Weight is a subpath
104
+
105
+ ```ts
106
+ import { caretDown } from '@fusion.dev/helix-icons/regular'
107
+ import { trash } from '@fusion.dev/helix-icons/bold'
108
+ ```
109
+
110
+ The default is bold, and `/bold` is the same set under a name that says so.
111
+
112
+ **A subpath rather than an attribute, because a weight is data rather than a
113
+ dial.** Phosphor's weights are outlined filled paths: `caret-down` is `a12,12`
114
+ at bold and `a8,8` at regular, so there is nothing for CSS to turn and every
115
+ weight offered is bytes shipped. A subpath is shaken per import site; a `weight`
116
+ attribute would put every weight into the index that `name` reads, taking one
117
+ consumer's 15 kB to about 90.
118
+
119
+ Only the default weight carries that index, so `name` draws bold. A consumer who
120
+ wants the set in another weight imports the values and hands them over.
79
121
 
80
122
  ## Adding one
81
123
 
package/content/metrics.mdx CHANGED
@@ -59,10 +59,10 @@ repository does that. The per-component tables are what a page pays.
59
59
  | Package | Raw | Gzip | Brotli | |
60
60
  |---|---|---|---|---|
61
61
  | `@fusion.dev/helix-core` | 156,003 | 51,384 | 43,598 | Element base class, mixins, decorators, floating positioning. |
62
- | `@fusion.dev/helix-headless` | 604,479 | 156,914 | 122,396 | Every headless family, which is what the barrel means. |
62
+ | `@fusion.dev/helix-headless` | 604,545 | 156,940 | 122,421 | Every headless family, which is what the barrel means. |
63
63
  | `@fusion.dev/helix-icons` | 47,484 | 14,907 | 12,553 | The whole glyph set. |
64
64
  | `@fusion.dev/helix-theme` | 3,288 | 1,571 | 1,355 | The derivation engine. Build time for most consumers, runtime for a theme switcher. |
65
- | `@fusion.dev/helix` | 1,081,557 | 253,237 | 186,164 | Every styled family. |
65
+ | `@fusion.dev/helix` | 1,081,623 | 253,263 | 186,323 | Every styled family. |
66
66
  | `lit` | 15,394 | 6,118 | 5,460 | Not ours. Here so it can be subtracted from every row above it. |
67
67
 
68
68
  ## The stylesheets
@@ -85,9 +85,9 @@ is the whole cost of adopting the base layer on its own.
85
85
 
86
86
  **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.
87
87
 
88
- 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,237.
88
+ 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.
89
89
 
90
- **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,914 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.
90
+ **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.
91
91
 
92
92
  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.
93
93
 
@@ -220,7 +220,7 @@ Structure, accessibility, state and form participation. No presentation, and no
220
220
  | `filter-input` | 143,432 | 45,722 | 38,394 | 27,857 | 6,742 | 5,700 |
221
221
  | `format-date` | 31,933 | 10,735 | 9,501 | 2,867 | 720 | 611 |
222
222
  | `heatmap` | 73,764 | 24,818 | 21,960 | 10,796 | 3,045 | 2,463 |
223
- | `icon` | 75,148 | 25,011 | 20,634 | 952 | 231 | 179 |
223
+ | `icon` | 75,212 | 25,034 | 20,674 | 1,018 | 246 | 244 |
224
224
  | `icon-button` | 33,400 | 10,918 | 9,616 | 3,494 | 849 | 682 |
225
225
  | `image` | 30,493 | 10,124 | 8,925 | 3,156 | 839 | 708 |
226
226
  | `input` | 86,357 | 28,367 | 23,214 | 4,742 | 1,328 | 1,072 |
@@ -263,7 +263,7 @@ Structure, accessibility, state and form participation. No presentation, and no
263
263
  | `tabs` | 36,095 | 11,583 | 10,224 | 3,925 | 934 | 734 |
264
264
  | `tag` | 75,925 | 25,304 | 20,730 | 895 | 197 | 187 |
265
265
  | `textarea` | 38,623 | 12,198 | 10,752 | 3,996 | 1,108 | 812 |
266
- | `time-input` | 142,822 | 45,480 | 38,130 | 27,718 | 6,829 | 5,639 |
266
+ | `time-input` | 142,888 | 45,492 | 38,287 | 27,784 | 6,855 | 5,700 |
267
267
  | `time-picker` | 103,171 | 33,347 | 27,433 | 18,573 | 5,003 | 4,158 |
268
268
  | `timeline` | 76,374 | 25,276 | 20,869 | 1,809 | 400 | 322 |
269
269
  | `toast` | 79,658 | 26,392 | 21,616 | 4,005 | 969 | 800 |
@@ -303,8 +303,8 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
303
303
  | `checkbox-group` | 41,649 | 12,888 | 11,365 | 6,981 | 1,845 | 1,444 |
304
304
  | `code` | 28,016 | 9,451 | 8,318 | 1,511 | 377 | 343 |
305
305
  | `code-block` | 137,621 | 43,305 | 36,555 | 33,551 | 7,204 | 6,228 |
306
- | `color-input` | 168,820 | 48,992 | 41,481 | 56,582 | 10,741 | 9,275 |
307
- | `color-picker` | 130,635 | 37,628 | 31,347 | 45,256 | 8,827 | 7,546 |
306
+ | `color-input` | 168,886 | 49,016 | 41,449 | 56,648 | 10,765 | 9,164 |
307
+ | `color-picker` | 130,700 | 37,642 | 31,334 | 45,322 | 8,845 | 7,620 |
308
308
  | `combobox` | 147,229 | 45,439 | 38,172 | 35,167 | 7,748 | 6,491 |
309
309
  | `command` | 113,324 | 34,745 | 28,635 | 28,199 | 6,596 | 5,569 |
310
310
  | `copy-button` | 125,773 | 40,563 | 34,144 | 21,706 | 4,680 | 3,919 |
@@ -318,16 +318,16 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
318
318
  | `drawer` | 34,988 | 11,255 | 9,908 | 6,007 | 1,504 | 1,295 |
319
319
  | `drilldown` | 88,562 | 29,007 | 23,738 | 10,153 | 2,506 | 2,090 |
320
320
  | `empty` | 29,763 | 9,992 | 8,809 | 2,087 | 544 | 546 |
321
- | `file-input` | 98,353 | 31,005 | 25,482 | 17,337 | 3,944 | 3,315 |
322
- | `filter-input` | 171,429 | 50,149 | 42,195 | 55,844 | 11,352 | 9,537 |
321
+ | `file-input` | 98,415 | 31,017 | 25,505 | 17,403 | 3,961 | 3,359 |
322
+ | `filter-input` | 171,495 | 50,168 | 42,196 | 55,910 | 11,374 | 9,511 |
323
323
  | `flex` | 29,377 | 9,803 | 8,625 | 2,078 | 473 | 421 |
324
324
  | `format-date` | 32,581 | 10,883 | 9,622 | 3,497 | 875 | 714 |
325
325
  | `grid` | 29,831 | 9,956 | 8,764 | 2,528 | 610 | 595 |
326
326
  | `heatmap` | 80,562 | 26,229 | 23,247 | 17,575 | 4,485 | 3,784 |
327
- | `icon` | 75,854 | 25,190 | 20,767 | 1,641 | 395 | 391 |
327
+ | `icon` | 75,918 | 25,214 | 20,750 | 1,707 | 408 | 326 |
328
328
  | `icon-button` | 39,415 | 11,931 | 10,493 | 9,495 | 1,879 | 1,572 |
329
329
  | `image` | 32,195 | 10,599 | 9,341 | 4,840 | 1,327 | 1,060 |
330
- | `input` | 92,560 | 29,708 | 24,352 | 10,938 | 2,676 | 2,170 |
330
+ | `input` | 92,624 | 29,730 | 24,373 | 11,004 | 2,686 | 2,186 |
331
331
  | `kbd` | 31,686 | 10,798 | 9,494 | 4,373 | 1,491 | 1,217 |
332
332
  | `legend` | 37,142 | 11,968 | 10,511 | 5,790 | 1,395 | 1,125 |
333
333
  | `line-chart` | 84,111 | 27,333 | 24,253 | 20,340 | 5,147 | 4,337 |
@@ -360,7 +360,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
360
360
  | `skip-link` | 30,085 | 10,152 | 8,925 | 2,624 | 763 | 648 |
361
361
  | `slider` | 50,467 | 14,467 | 12,810 | 16,150 | 3,419 | 2,967 |
362
362
  | `sparkline` | 38,663 | 12,813 | 11,353 | 6,293 | 1,767 | 1,587 |
363
- | `speed-dial` | 113,393 | 37,713 | 31,732 | 11,289 | 2,402 | 1,980 |
363
+ | `speed-dial` | 113,459 | 37,745 | 31,702 | 11,355 | 2,421 | 1,980 |
364
364
  | `splitter` | 43,992 | 13,149 | 11,685 | 16,134 | 3,619 | 3,134 |
365
365
  | `stat` | 31,624 | 10,248 | 9,065 | 3,954 | 845 | 670 |
366
366
  | `steps` | 98,250 | 30,218 | 24,980 | 19,783 | 3,931 | 3,389 |
@@ -370,7 +370,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
370
370
  | `tag` | 79,128 | 26,167 | 21,488 | 4,083 | 1,031 | 920 |
371
371
  | `text` | 31,284 | 10,086 | 8,873 | 3,987 | 817 | 714 |
372
372
  | `textarea` | 41,960 | 13,007 | 11,474 | 7,319 | 1,976 | 1,576 |
373
- | `time-input` | 164,064 | 48,994 | 41,268 | 48,940 | 10,439 | 8,733 |
373
+ | `time-input` | 164,130 | 49,012 | 41,331 | 49,006 | 10,465 | 8,790 |
374
374
  | `time-picker` | 114,652 | 35,487 | 29,260 | 30,044 | 7,192 | 6,020 |
375
375
  | `timeline` | 79,687 | 26,034 | 21,488 | 5,110 | 1,147 | 1,058 |
376
376
  | `toast` | 87,191 | 28,068 | 23,160 | 11,526 | 2,626 | 2,266 |
@@ -379,9 +379,9 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
379
379
  | `tooltip` | 63,163 | 21,452 | 18,976 | 9,352 | 2,508 | 2,093 |
380
380
  | `tour` | 75,388 | 23,666 | 20,981 | 20,453 | 4,395 | 3,668 |
381
381
  | `tree` | 92,117 | 29,903 | 24,578 | 12,881 | 3,327 | 2,769 |
382
- | `trend` | 78,409 | 25,784 | 21,316 | 4,205 | 969 | 888 |
383
- | `video` | 159,049 | 48,469 | 41,085 | 49,625 | 10,810 | 9,332 |
384
- | `video-playlist` | 135,523 | 42,690 | 35,871 | 28,774 | 5,971 | 4,981 |
382
+ | `trend` | 78,471 | 25,809 | 21,286 | 4,271 | 981 | 940 |
383
+ | `video` | 159,115 | 48,484 | 41,085 | 49,691 | 10,823 | 9,313 |
384
+ | `video-playlist` | 135,589 | 42,718 | 35,901 | 28,840 | 5,991 | 5,063 |
385
385
  | `virtual-list` | 35,013 | 11,768 | 10,403 | 3,187 | 955 | 789 |
386
386
 
387
387
  ## What lands in `node_modules`
@@ -395,11 +395,11 @@ column is what was removed rather than part of what remains.
395
395
  | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
396
396
  |---|---|---|---|---|
397
397
  | `@fusion.dev/helix-core` | 984,477 | 153 | 222,482 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
398
- | `@fusion.dev/helix-headless` | 11,355,368 | 464 | 836,734 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
399
- | `@fusion.dev/helix-icons` | 65,943 | 11 | 20,928 | none |
398
+ | `@fusion.dev/helix-headless` | 11,366,181 | 464 | 836,952 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
399
+ | `@fusion.dev/helix-icons` | 121,091 | 17 | 37,263 | none |
400
400
  | `@fusion.dev/helix-styles` | 101,139 | 6 | 0 | none |
401
401
  | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
402
- | `@fusion.dev/helix` | 12,491,633 | 796 | 333,986 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
402
+ | `@fusion.dev/helix` | 12,499,093 | 796 | 333,986 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
403
403
 
404
404
  ## Not measured yet
405
405
 
package/dist/sources.generated.js CHANGED
@@ -307,26 +307,30 @@ times in the headless manifest, so it is discoverable rather than folklore.
307
307
  ## The render graph is the part that will catch you
308
308
 
309
309
  **A component that renders another gives you two things to register, and only
310
- one of them is obvious.** Twenty-two of the 88 headless families interpolate
311
- another family's tag, across 89 call sites and seventeen distinct children.
310
+ one of them is obvious.**
312
311
 
313
312
  Register \`acme-combobox\` without also registering \`acme-listbox\` and the panel
314
313
  renders a tag nobody defined. That is not an error and not a warning: an
315
314
  unregistered custom element is an inert, unstyled inline box, so what you see is
316
315
  a combobox that appears not to open.
317
316
 
317
+ [//]: # (renders)
318
+
319
+ **27 of the 94 headless families interpolate another family's tag**, across 20 distinct children.
320
+
318
321
  | Family | Renders |
319
322
  |---|---|
320
- | \`bar-chart\`, \`donut-chart\`, \`heatmap\`, \`line-chart\` | \`tooltip\` |
321
- | \`code-block\` | \`copy-button\` |
323
+ | \`area-chart\`, \`bar-chart\`, \`copy-button\`, \`donut-chart\`, \`heatmap\`, \`line-chart\`, \`scatter-chart\` | \`tooltip\` |
324
+ | \`chat\` | \`chat-message\` |
325
+ | \`code-block\`, \`object-inspector\` | \`copy-button\` |
322
326
  | \`color-input\` | \`color-picker\` |
323
327
  | \`color-picker\` | \`button\`, \`button-group\`, \`slider\` |
324
328
  | \`combobox\` | \`listbox\`, \`tag\` |
325
329
  | \`command\` | \`dialog\`, \`listbox\` |
326
- | \`copy-button\` | \`tooltip\` |
327
- | \`data-table\` | \`pagination\` |
330
+ | \`data-table\` | \`checkbox\`, \`pagination\` |
328
331
  | \`date-input\` | \`date-picker\`, \`tag\` |
329
332
  | \`file-input\` | \`tag\` |
333
+ | \`filter-input\` | \`divider\`, \`menu\`, \`menu-item\` |
330
334
  | \`notifications\` | \`format-date\` |
331
335
  | \`pagination\` | \`option\`, \`select\` |
332
336
  | \`select\` | \`listbox\` |
@@ -335,14 +339,16 @@ a combobox that appears not to open.
335
339
  | \`time-picker\` | \`listbox\`, \`option\` |
336
340
  | \`video\`, \`video-playlist\` | \`menu\`, \`menu-item\` |
337
341
 
342
+ [//]: # (/renders)
343
+
338
344
  The safe rule is to subclass and register a family together with everything it
339
345
  renders, transitively: \`command\` reaches \`dialog\` and \`listbox\`, and \`listbox\`
340
346
  reaches \`option\`.
341
347
 
342
- **This table is maintained by hand today and should not be.** The graph is
343
- already computed inside this repository, by the check that stops us shipping the
344
- same fault, and it is thrown away afterward rather than written to the manifest.
345
- Until it is published, treat the table above as the version that can go stale.
348
+ **This table is generated from the manifest**, which publishes the graph as
349
+ \`helix.renders\` on every element that interpolates a tag. It was kept by hand
350
+ until 22 September 2026 and was wrong by four families when it stopped being, so
351
+ read it as current rather than as maintained.
346
352
 
347
353
  ## What you have to supply yourself
348
354
 
@@ -362,8 +368,26 @@ acme-listbox:not(:defined) {
362
368
  Visibility rather than \`display\`, so the page does not reflow when the
363
369
  definitions arrive.
364
370
 
365
- **Your own typings.** The generated \`jsx.d.ts\`, \`vue.d.ts\` and \`svelte.d.ts\`
366
- carry our tag names. For yours, merge each element into the tag map:
371
+ **Your own typings, from the same generator we use.** \`@fusion.dev/helix-cem\`
372
+ reads your package and writes \`jsx.d.ts\`, \`vue.d.ts\` and \`svelte.d.ts\` for your
373
+ tags, with every member your subclass inherited from ours. Add a \`cem.config.ts\`
374
+ beside your \`package.json\`:
375
+
376
+ \`\`\`ts
377
+ import type { HelixCemOptions } from '@fusion.dev/helix-cem'
378
+
379
+ export default {
380
+ frameworkTypes: true,
381
+ packageName: 'acme-system',
382
+ tier: 'styled',
383
+ } satisfies HelixCemOptions
384
+ \`\`\`
385
+
386
+ and run \`bun --bun helix-cem\`. It finds what you extend through your
387
+ \`dependencies\`, so \`acme-combobox\` arrives with the hundred-odd members it
388
+ inherited rather than the two you wrote.
389
+
390
+ **The tag map is still yours to write**, one line per element, beside the class:
367
391
 
368
392
  \`\`\`ts
369
393
  declare global {
@@ -373,7 +397,9 @@ declare global {
373
397
  }
374
398
  \`\`\`
375
399
 
376
- Per element, by hand. There is no generated version of this for consumer names.
400
+ That is TypeScript's own convention for a custom element rather than a gap in
401
+ this: the interface merges from your source, and nothing generated can name a
402
+ class it is not in the same program as.
377
403
 
378
404
  ## What you get without asking
379
405
 
@@ -1435,7 +1461,7 @@ title: Iconography
1435
1461
  <helix-icon name="trash"></helix-icon>
1436
1462
  \`\`\`
1437
1463
 
1438
- 105 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
1464
+ 108 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
1439
1465
  Phosphor's own geometry and it is kept rather than rescaled: normalizing to a 24
1440
1466
  box would change the optical weight of every glyph and stop the set matching
1441
1467
  anything upstream. Bold rather than regular, because Phosphor's regular is a
@@ -1497,10 +1523,52 @@ page, which every caret the library draws already does.
1497
1523
  import { trash } from '@fusion.dev/helix-icons'
1498
1524
  \`\`\`
1499
1525
 
1500
- Each glyph is an exported string, so you can put one in your own markup, in a
1501
- canvas, or anywhere an element is not what you want. Every \`name\` the library
1502
- uses is held to the set of glyphs that actually exist, so a typo is a build
1503
- failure rather than an empty box.
1526
+ Each glyph is data, \`{ content, name, viewBox }\`, so you can put one in your own
1527
+ markup, in a canvas, or anywhere an element is not what you want. Every \`name\`
1528
+ the library uses is held to the set of glyphs that actually exist, so a typo is a
1529
+ build failure rather than an empty box.
1530
+
1531
+ **Hand one to the element and it draws it**, whatever set it came from:
1532
+
1533
+ \`\`\`tsx
1534
+ import { trash } from '@fusion.dev/helix-icons'
1535
+
1536
+ <helix-icon icon={trash} />
1537
+ \`\`\`
1538
+
1539
+ A property rather than an attribute, because an object is not a string: the
1540
+ frameworks set properties and plain HTML cannot, which is what \`name\` is for.
1541
+ Both set, the value wins.
1542
+
1543
+ **This is the door that scales.** \`name\` resolves through an index of the whole
1544
+ set, which no bundler can shake, so a consumer who renders one named icon ships
1545
+ all of it: 15 kB gzipped for 108 glyphs. A value ships the one glyph you
1546
+ imported. It is also the door out of this set entirely, since anything exporting
1547
+ that shape works, whether it is Phosphor at another weight, another library, or
1548
+ your own drawings:
1549
+
1550
+ \`\`\`ts
1551
+ const dot = { content: '<circle cx="12" cy="12" r="10" fill="currentColor" />', name: 'dot', viewBox: '0 0 24 24' }
1552
+ \`\`\`
1553
+
1554
+ ## Weight is a subpath
1555
+
1556
+ \`\`\`ts
1557
+ import { caretDown } from '@fusion.dev/helix-icons/regular'
1558
+ import { trash } from '@fusion.dev/helix-icons/bold'
1559
+ \`\`\`
1560
+
1561
+ The default is bold, and \`/bold\` is the same set under a name that says so.
1562
+
1563
+ **A subpath rather than an attribute, because a weight is data rather than a
1564
+ dial.** Phosphor's weights are outlined filled paths: \`caret-down\` is \`a12,12\`
1565
+ at bold and \`a8,8\` at regular, so there is nothing for CSS to turn and every
1566
+ weight offered is bytes shipped. A subpath is shaken per import site; a \`weight\`
1567
+ attribute would put every weight into the index that \`name\` reads, taking one
1568
+ consumer's 15 kB to about 90.
1569
+
1570
+ Only the default weight carries that index, so \`name\` draws bold. A consumer who
1571
+ wants the set in another weight imports the values and hands them over.
1504
1572
 
1505
1573
  ## Adding one
1506
1574
 
@@ -2023,10 +2091,10 @@ repository does that. The per-component tables are what a page pays.
2023
2091
  | Package | Raw | Gzip | Brotli | |
2024
2092
  |---|---|---|---|---|
2025
2093
  | \`@fusion.dev/helix-core\` | 156,003 | 51,384 | 43,598 | Element base class, mixins, decorators, floating positioning. |
2026
- | \`@fusion.dev/helix-headless\` | 604,479 | 156,914 | 122,396 | Every headless family, which is what the barrel means. |
2094
+ | \`@fusion.dev/helix-headless\` | 604,545 | 156,940 | 122,421 | Every headless family, which is what the barrel means. |
2027
2095
  | \`@fusion.dev/helix-icons\` | 47,484 | 14,907 | 12,553 | The whole glyph set. |
2028
2096
  | \`@fusion.dev/helix-theme\` | 3,288 | 1,571 | 1,355 | The derivation engine. Build time for most consumers, runtime for a theme switcher. |
2029
- | \`@fusion.dev/helix\` | 1,081,557 | 253,237 | 186,164 | Every styled family. |
2097
+ | \`@fusion.dev/helix\` | 1,081,623 | 253,263 | 186,323 | Every styled family. |
2030
2098
  | \`lit\` | 15,394 | 6,118 | 5,460 | Not ours. Here so it can be subtracted from every row above it. |
2031
2099
 
2032
2100
  ## The stylesheets
@@ -2049,9 +2117,9 @@ is the whole cost of adopting the base layer on its own.
2049
2117
 
2050
2118
  **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.
2051
2119
 
2052
- 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,237.
2120
+ 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.
2053
2121
 
2054
- **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,914 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.
2122
+ **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.
2055
2123
 
2056
2124
  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.
2057
2125
 
@@ -2184,7 +2252,7 @@ Structure, accessibility, state and form participation. No presentation, and no
2184
2252
  | \`filter-input\` | 143,432 | 45,722 | 38,394 | 27,857 | 6,742 | 5,700 |
2185
2253
  | \`format-date\` | 31,933 | 10,735 | 9,501 | 2,867 | 720 | 611 |
2186
2254
  | \`heatmap\` | 73,764 | 24,818 | 21,960 | 10,796 | 3,045 | 2,463 |
2187
- | \`icon\` | 75,148 | 25,011 | 20,634 | 952 | 231 | 179 |
2255
+ | \`icon\` | 75,212 | 25,034 | 20,674 | 1,018 | 246 | 244 |
2188
2256
  | \`icon-button\` | 33,400 | 10,918 | 9,616 | 3,494 | 849 | 682 |
2189
2257
  | \`image\` | 30,493 | 10,124 | 8,925 | 3,156 | 839 | 708 |
2190
2258
  | \`input\` | 86,357 | 28,367 | 23,214 | 4,742 | 1,328 | 1,072 |
@@ -2227,7 +2295,7 @@ Structure, accessibility, state and form participation. No presentation, and no
2227
2295
  | \`tabs\` | 36,095 | 11,583 | 10,224 | 3,925 | 934 | 734 |
2228
2296
  | \`tag\` | 75,925 | 25,304 | 20,730 | 895 | 197 | 187 |
2229
2297
  | \`textarea\` | 38,623 | 12,198 | 10,752 | 3,996 | 1,108 | 812 |
2230
- | \`time-input\` | 142,822 | 45,480 | 38,130 | 27,718 | 6,829 | 5,639 |
2298
+ | \`time-input\` | 142,888 | 45,492 | 38,287 | 27,784 | 6,855 | 5,700 |
2231
2299
  | \`time-picker\` | 103,171 | 33,347 | 27,433 | 18,573 | 5,003 | 4,158 |
2232
2300
  | \`timeline\` | 76,374 | 25,276 | 20,869 | 1,809 | 400 | 322 |
2233
2301
  | \`toast\` | 79,658 | 26,392 | 21,616 | 4,005 | 969 | 800 |
@@ -2267,8 +2335,8 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
2267
2335
  | \`checkbox-group\` | 41,649 | 12,888 | 11,365 | 6,981 | 1,845 | 1,444 |
2268
2336
  | \`code\` | 28,016 | 9,451 | 8,318 | 1,511 | 377 | 343 |
2269
2337
  | \`code-block\` | 137,621 | 43,305 | 36,555 | 33,551 | 7,204 | 6,228 |
2270
- | \`color-input\` | 168,820 | 48,992 | 41,481 | 56,582 | 10,741 | 9,275 |
2271
- | \`color-picker\` | 130,635 | 37,628 | 31,347 | 45,256 | 8,827 | 7,546 |
2338
+ | \`color-input\` | 168,886 | 49,016 | 41,449 | 56,648 | 10,765 | 9,164 |
2339
+ | \`color-picker\` | 130,700 | 37,642 | 31,334 | 45,322 | 8,845 | 7,620 |
2272
2340
  | \`combobox\` | 147,229 | 45,439 | 38,172 | 35,167 | 7,748 | 6,491 |
2273
2341
  | \`command\` | 113,324 | 34,745 | 28,635 | 28,199 | 6,596 | 5,569 |
2274
2342
  | \`copy-button\` | 125,773 | 40,563 | 34,144 | 21,706 | 4,680 | 3,919 |
@@ -2282,16 +2350,16 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
2282
2350
  | \`drawer\` | 34,988 | 11,255 | 9,908 | 6,007 | 1,504 | 1,295 |
2283
2351
  | \`drilldown\` | 88,562 | 29,007 | 23,738 | 10,153 | 2,506 | 2,090 |
2284
2352
  | \`empty\` | 29,763 | 9,992 | 8,809 | 2,087 | 544 | 546 |
2285
- | \`file-input\` | 98,353 | 31,005 | 25,482 | 17,337 | 3,944 | 3,315 |
2286
- | \`filter-input\` | 171,429 | 50,149 | 42,195 | 55,844 | 11,352 | 9,537 |
2353
+ | \`file-input\` | 98,415 | 31,017 | 25,505 | 17,403 | 3,961 | 3,359 |
2354
+ | \`filter-input\` | 171,495 | 50,168 | 42,196 | 55,910 | 11,374 | 9,511 |
2287
2355
  | \`flex\` | 29,377 | 9,803 | 8,625 | 2,078 | 473 | 421 |
2288
2356
  | \`format-date\` | 32,581 | 10,883 | 9,622 | 3,497 | 875 | 714 |
2289
2357
  | \`grid\` | 29,831 | 9,956 | 8,764 | 2,528 | 610 | 595 |
2290
2358
  | \`heatmap\` | 80,562 | 26,229 | 23,247 | 17,575 | 4,485 | 3,784 |
2291
- | \`icon\` | 75,854 | 25,190 | 20,767 | 1,641 | 395 | 391 |
2359
+ | \`icon\` | 75,918 | 25,214 | 20,750 | 1,707 | 408 | 326 |
2292
2360
  | \`icon-button\` | 39,415 | 11,931 | 10,493 | 9,495 | 1,879 | 1,572 |
2293
2361
  | \`image\` | 32,195 | 10,599 | 9,341 | 4,840 | 1,327 | 1,060 |
2294
- | \`input\` | 92,560 | 29,708 | 24,352 | 10,938 | 2,676 | 2,170 |
2362
+ | \`input\` | 92,624 | 29,730 | 24,373 | 11,004 | 2,686 | 2,186 |
2295
2363
  | \`kbd\` | 31,686 | 10,798 | 9,494 | 4,373 | 1,491 | 1,217 |
2296
2364
  | \`legend\` | 37,142 | 11,968 | 10,511 | 5,790 | 1,395 | 1,125 |
2297
2365
  | \`line-chart\` | 84,111 | 27,333 | 24,253 | 20,340 | 5,147 | 4,337 |
@@ -2324,7 +2392,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
2324
2392
  | \`skip-link\` | 30,085 | 10,152 | 8,925 | 2,624 | 763 | 648 |
2325
2393
  | \`slider\` | 50,467 | 14,467 | 12,810 | 16,150 | 3,419 | 2,967 |
2326
2394
  | \`sparkline\` | 38,663 | 12,813 | 11,353 | 6,293 | 1,767 | 1,587 |
2327
- | \`speed-dial\` | 113,393 | 37,713 | 31,732 | 11,289 | 2,402 | 1,980 |
2395
+ | \`speed-dial\` | 113,459 | 37,745 | 31,702 | 11,355 | 2,421 | 1,980 |
2328
2396
  | \`splitter\` | 43,992 | 13,149 | 11,685 | 16,134 | 3,619 | 3,134 |
2329
2397
  | \`stat\` | 31,624 | 10,248 | 9,065 | 3,954 | 845 | 670 |
2330
2398
  | \`steps\` | 98,250 | 30,218 | 24,980 | 19,783 | 3,931 | 3,389 |
@@ -2334,7 +2402,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
2334
2402
  | \`tag\` | 79,128 | 26,167 | 21,488 | 4,083 | 1,031 | 920 |
2335
2403
  | \`text\` | 31,284 | 10,086 | 8,873 | 3,987 | 817 | 714 |
2336
2404
  | \`textarea\` | 41,960 | 13,007 | 11,474 | 7,319 | 1,976 | 1,576 |
2337
- | \`time-input\` | 164,064 | 48,994 | 41,268 | 48,940 | 10,439 | 8,733 |
2405
+ | \`time-input\` | 164,130 | 49,012 | 41,331 | 49,006 | 10,465 | 8,790 |
2338
2406
  | \`time-picker\` | 114,652 | 35,487 | 29,260 | 30,044 | 7,192 | 6,020 |
2339
2407
  | \`timeline\` | 79,687 | 26,034 | 21,488 | 5,110 | 1,147 | 1,058 |
2340
2408
  | \`toast\` | 87,191 | 28,068 | 23,160 | 11,526 | 2,626 | 2,266 |
@@ -2343,9 +2411,9 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
2343
2411
  | \`tooltip\` | 63,163 | 21,452 | 18,976 | 9,352 | 2,508 | 2,093 |
2344
2412
  | \`tour\` | 75,388 | 23,666 | 20,981 | 20,453 | 4,395 | 3,668 |
2345
2413
  | \`tree\` | 92,117 | 29,903 | 24,578 | 12,881 | 3,327 | 2,769 |
2346
- | \`trend\` | 78,409 | 25,784 | 21,316 | 4,205 | 969 | 888 |
2347
- | \`video\` | 159,049 | 48,469 | 41,085 | 49,625 | 10,810 | 9,332 |
2348
- | \`video-playlist\` | 135,523 | 42,690 | 35,871 | 28,774 | 5,971 | 4,981 |
2414
+ | \`trend\` | 78,471 | 25,809 | 21,286 | 4,271 | 981 | 940 |
2415
+ | \`video\` | 159,115 | 48,484 | 41,085 | 49,691 | 10,823 | 9,313 |
2416
+ | \`video-playlist\` | 135,589 | 42,718 | 35,901 | 28,840 | 5,991 | 5,063 |
2349
2417
  | \`virtual-list\` | 35,013 | 11,768 | 10,403 | 3,187 | 955 | 789 |
2350
2418
 
2351
2419
  ## What lands in \`node_modules\`
@@ -2359,11 +2427,11 @@ column is what was removed rather than part of what remains.
2359
2427
  | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
2360
2428
  |---|---|---|---|---|
2361
2429
  | \`@fusion.dev/helix-core\` | 984,477 | 153 | 222,482 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
2362
- | \`@fusion.dev/helix-headless\` | 11,355,368 | 464 | 836,734 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
2363
- | \`@fusion.dev/helix-icons\` | 65,943 | 11 | 20,928 | none |
2430
+ | \`@fusion.dev/helix-headless\` | 11,366,181 | 464 | 836,952 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
2431
+ | \`@fusion.dev/helix-icons\` | 121,091 | 17 | 37,263 | none |
2364
2432
  | \`@fusion.dev/helix-styles\` | 101,139 | 6 | 0 | none |
2365
2433
  | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
2366
- | \`@fusion.dev/helix\` | 12,491,633 | 796 | 333,986 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
2434
+ | \`@fusion.dev/helix\` | 12,499,093 | 796 | 333,986 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
2367
2435
 
2368
2436
  ## Not measured yet
2369
2437
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@fusion.dev/helix-docs",
3
3
  "description": "Versioned documentation content and registry for Helix.",
4
- "version": "0.97.0",
4
+ "version": "0.99.0",
5
5
  "license": "MIT",
6
6
  "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
7
7
  "repository": {
@@ -36,8 +36,8 @@
36
36
  },
37
37
  "bugs": "https://github.com/project-fusion/fusion/issues",
38
38
  "devDependencies": {
39
- "@fusion.dev/helix-cem": "0.97.0",
40
- "@fusion.dev/helix-testing": "0.97.0",
39
+ "@fusion.dev/helix-cem": "0.99.0",
40
+ "@fusion.dev/helix-testing": "0.99.0",
41
41
  "@fusion.dev/scripts": "0.0.0-dev",
42
42
  "lit": "^3.2.1",
43
43
  "playwright": "^1.62.1"