@fusion.dev/helix-docs 0.2.0 → 0.3.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` | 134,650 | 44,269 | 37,972 | Element base class, mixins, decorators, floating positioning. |
-| `@fusion.dev/helix-headless` | 519,156 | 131,702 | 103,107 | Every headless family, which is what the barrel means. |
+| `@fusion.dev/helix-headless` | 519,154 | 131,672 | 103,150 | 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` | 956,713 | 216,830 | 159,002 | Every styled family. |
+| `@fusion.dev/helix` | 956,713 | 216,820 | 158,985 | 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 13,974 bytes gzipped alone and adds 2,409 to a page that already has Helix on it, so 83 percent of the first one is shared and 17 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,065 gzipped alone, the dearest `data-table` at 49,868, over 93 components. Every family at once is 216,830.
+Across the tier: the cheapest is `code` at 9,065 gzipped alone, the dearest `data-table` at 49,868, over 93 components. Every family at once is 216,820.
 
-**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 131,702 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 93 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 131,672 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 93 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 16,187 bytes gzipped alone.
 
@@ -126,7 +126,7 @@ Four other libraries of custom elements, pinned and measured on 2026-08-24 by `t
 | | Material Web | 50,155 | 14,577 | 12,935 |
 | | Shoelace | 37,833 | 11,814 | 10,568 |
 | | Spectrum | 62,322 | 15,059 | 13,321 |
-| `tabs` | **Helix** | 40,196 | 12,332 | 10,861 |
+| `tabs` | **Helix** | 40,196 | 12,348 | 10,882 |
 | | Carbon | 578,766 | 73,537 | 43,235 |
 | | Material Web | 38,883 | 12,820 | 11,368 |
 | | Shoelace | 54,573 | 17,140 | 15,068 |
@@ -254,7 +254,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | `steps` | 82,900 | 27,205 | 22,347 | 6,303 | 1,832 | 1,249 |
 | `switch` | 34,314 | 11,106 | 9,826 | 1,798 | 832 | 358 |
 | `table` | 31,861 | 10,274 | 9,086 | 4,373 | 1,299 | 831 |
-| `tabs` | 33,935 | 11,035 | 9,722 | 4,469 | 1,279 | 803 |
+| `tabs` | 33,935 | 11,060 | 9,721 | 4,469 | 1,277 | 735 |
 | `tag` | 74,439 | 24,760 | 20,435 | 897 | 464 | 219 |
 | `textarea` | 37,001 | 11,743 | 10,362 | 4,115 | 1,414 | 884 |
 | `time-input` | 136,201 | 43,547 | 36,687 | 28,643 | 7,661 | 6,120 |
@@ -353,7 +353,7 @@ The headless tier plus presentation. This is what `bun add @fusion.dev/helix` gi
 | `steps` | 96,252 | 29,575 | 24,410 | 19,643 | 4,202 | 3,353 |
 | `switch` | 38,603 | 12,160 | 10,668 | 6,072 | 1,891 | 1,318 |
 | `table` | 35,190 | 10,865 | 9,580 | 7,692 | 1,916 | 1,378 |
-| `tabs` | 40,196 | 12,332 | 10,861 | 10,719 | 2,598 | 1,976 |
+| `tabs` | 40,196 | 12,348 | 10,882 | 10,719 | 2,597 | 1,971 |
 | `tag` | 77,633 | 25,634 | 21,148 | 4,076 | 1,245 | 995 |
 | `text` | 29,734 | 9,670 | 8,508 | 3,922 | 958 | 605 |
 | `textarea` | 40,350 | 12,544 | 11,034 | 7,447 | 2,227 | 1,615 |
@@ -381,12 +381,12 @@ column is what was removed rather than part of what remains.
 
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
-| `@fusion.dev/helix-core` | 879,273 | 113 | 162,880 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 9,741,797 | 422 | 738,193 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
-| `@fusion.dev/helix-icons` | 66,379 | 11 | 20,959 | none |
+| `@fusion.dev/helix-core` | 655,135 | 113 | 154,658 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
+| `@fusion.dev/helix-headless` | 8,636,163 | 422 | 699,239 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-icons` | 65,943 | 11 | 20,928 | none |
 | `@fusion.dev/helix-styles` | 83,277 | 5 | 0 | none |
-| `@fusion.dev/helix-theme` | 463,476 | 8 | 4,764 | none |
-| `@fusion.dev/helix` | 9,714,436 | 718 | 287,181 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix-theme` | 461,551 | 8 | 4,699 | none |
+| `@fusion.dev/helix` | 9,306,931 | 718 | 278,170 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/dist/catalog.js

@@ -1,85 +1,25 @@
 import { displayName, startCase, tierOf } from './naming.js';
 import { place } from './reference.js';
-/**
- * The canonical example's slug, named once because three places ask for it.
- *
- * The tier pairing, the first-position pin and the label all read it. A fact
- * three places hold is a fact that drifts.
- */
 const CANONICAL = 'preview';
-/* The headless twin's slug, and the suffix every other one carries. */
 const HEADLESS = 'headless';
 const HEADLESS_SUFFIX = /\.headless$/;
-/**
- * Drops `undefined` from a union.
- *
- * Every reflected property is optional, because the default state of a Helix
- * component is the absent attribute: a reflected default would put an attribute
- * on the host that a React consumer's server markup never had. That makes the
- * declared type `'primary' | 'neutral' | undefined`, and the `undefined` is an
- * implementation detail of how the default is expressed rather than a value
- * anyone sets.
- */
 const withoutUndefined = (text) => text
     .split('|')
     .map((part) => part.trim())
     .filter((part) => part !== 'undefined')
     .join(' | ');
-/**
- * A method the platform calls, rather than one a consumer does.
- *
- * `formResetCallback` and its siblings are public because the platform has to
- * reach them, and they are 55 of the 152 public methods in the library:
- * documenting them puts a reader's own `focus()` and `show()` in a minority on
- * their own component's page. Matching the suffix rather than listing the names
- * covers the custom-element lifecycle and the form-associated one together, and
- * keeps covering them when the platform adds a third.
- */
 const PLATFORM_CALLBACK = /Callback$/;
-/** Public only. Private and protected are the component's business. */
 const isPublic = (row) => row.privacy === undefined || row.privacy === 'public';
-/**
- * Properties, with the default each one falls back to.
- *
- * Fields rather than attributes: an attribute carries no default in the
- * manifest, so a table built from attributes can say a component takes a
- * property and never what it does when you leave it alone.
- */
 const properties = (rows) => (rows ?? [])
-    /* Instance fields only. A static is the class's, not an element's, and the
-       two that reach here are the platform's rather than ours:
-       `shadowRootOptions` is Lit's and `formAssociated` is the flag the browser
-       reads to decide a control participates in a form. Thirty-five rows across
-       the library, none of them anything a consumer sets on a tag. */
-    /* `@internal` needs nothing here: the analyzer drops a member carrying it
-       before the manifest is written. */
     .filter((row) => row.kind === 'field' && isPublic(row) && row.static !== true)
     .map((row) => ({
-    /* `undefined` is not a default, it is the absence of one, and the
-       analyzer records the initializer verbatim. Printed, the column reads
-       "undefined" for every optional property, which is a table telling a
-       reader a word rather than a value. Blank says the same thing and says
-       it quietly. */
     default: row.default === 'undefined' ? '' : (row.default ?? ''),
     description: row.description ?? '',
     name: row.name ?? '',
-    /* A getter reads as a field in the manifest and assigning to one throws,
-       which is the same trap the React generator already skips these for. In
-       a table they are indistinguishable from a property a reader may set:
-       `AvatarGroup.avatars` sat beside its slot looking like a second way to
-       pass the same thing, and there is no second way. A hundred and
-       fifty-five of them. */
     readonly: row.readonly === true,
-    /* From `@reference` on the property. A row for `command` can say it is
-       the Invoker Commands API and point at where that is specified, which a
-       description sentence can gesture at and cannot carry. */
     references: row.helix?.references ?? [],
     type: withoutUndefined(row.type?.text ?? ''),
 }));
-/**
- * Methods, typed by the signature a caller writes rather than by a return type
- * alone. `(next: string) => boolean` says what to pass; `boolean` does not.
- */
 const methods = (rows) => (rows ?? [])
     .filter((row) => row.kind === 'method' && isPublic(row) && !PLATFORM_CALLBACK.test(row.name ?? ''))
     .map((row) => {
@@ -97,60 +37,14 @@ const members = (rows) => (rows ?? []).map((row) => ({
     name: row.name ?? '',
     type: withoutUndefined(row.type?.text ?? ''),
 }));
-/**
- * An annotation comment: a leading `@` inside an HTML comment, and its line.
- *
- * **Only comments that begin with `@`.** An example is allowed one comment
- * about its own scaffolding, and those are written for the reader:
- * `<!-- Preview frame: the submit is swallowed. -->` exists so nobody copies
- * `onsubmit="event.preventDefault()"` into production. Stripping every comment
- * would take that note with it. The sigil is what separates a line addressed to
- * this documentation system from a line addressed to a person.
- */
 const ANNOTATION = /^[^\S\n]*<!--\s*@[\s\S]*?-->[^\S\n]*\n?/gm;
-/**
- * The example's markup as a reader should receive it.
- *
- * `@summary` is metadata about the example rather than part of it: the cem
- * plugin lifts it into the manifest and the reference prints it as the
- * description, so left in place it makes the copy button hand back a comment
- * describing the thing you just copied.
- *
- * Stripped here rather than at the reader, because every consumer of the
- * catalog wants the same thing and a site that trimmed it in its own renderer
- * would leave the sandbox and any other consumer showing it.
- */
 const withoutAnnotations = (html) => html.replace(ANNOTATION, '').trimStart();
-/**
- * The examples of one family, named and ordered.
- *
- * The prose comes from the manifest and the markup from the caller. The
- * composition plugin reads the same folder and records what each example is;
- * the payload stays on disk because it is large and the manifest is parsed by
- * everything. Keyed by slug so the two halves cannot drift into each other's
- * order.
- */
 const examplesOf = (slug, declared, sources) => {
     const described = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.description ?? '']));
-    /* Keyed on slug the same way the descriptions are, and for the same reason:
-       the manifest half and the on-disk half are matched rather than zipped, so
-       the two cannot drift into each other's order. */
     const layouts = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.layout ?? '']));
     const minimums = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.min ?? 0]));
     return (sources
         .filter((source) => source.family === slug)
-        /* `preview` first, then alphabetical, with each headless twin directly
-           behind the example it mirrors.
-  
-           By slug, never by filename. Comparing `compact-counts.html` against
-           `compact.html` puts the longer name first, `-` preceding `.`, which is
-           a list ordered by a file extension no reader ever sees.
-  
-           **Pair on the mirrored name, not on the raw slug.** Sorting on the raw
-           slug puts the twin wherever the tier's name happens to fall in the
-           alphabet, which is only ever right by luck. The tabs have to show the
-           same list on both tiers, and `mirrored` below is that relationship: sort
-           on it and the position follows from the pairing. */
         .sort((a, b) => {
         const pairOf = (slug) => slug === HEADLESS ? CANONICAL : slug.replace(HEADLESS_SUFFIX, '');
         const twin = (slug) => (slug === HEADLESS || HEADLESS_SUFFIX.test(slug) ? 1 : 0);
@@ -162,14 +56,6 @@ const examplesOf = (slug, declared, sources) => {
         return twin(a.slug) - twin(b.slug);
     })
         .map((source) => {
-        /* Which styled example this one is the headless twin of. `headless` is
-         the twin of `preview`, and `<name>.headless` of `<name>`. This is the
-         one place that has to know the pairing, because a headless example is
-         not named for itself. */
-        /* Read once and narrowed here rather than spread from the map
-           directly: `get` answers `string | undefined`, and under
-           `exactOptionalPropertyTypes` an optional property will not take the
-           `undefined`. */
         const layout = layouts.get(source.slug);
         const min = minimums.get(source.slug);
         const mirrored = source.slug === HEADLESS ? CANONICAL : source.slug.replace(HEADLESS_SUFFIX, '');
@@ -177,14 +63,6 @@ const examplesOf = (slug, declared, sources) => {
             css: source.css,
             description: described.get(source.slug) ?? '',
             html: withoutAnnotations(source.html),
-            /* **The label is the file's name, with no special case.** `startCase`
-             gives "Preview" for the canonical example on its own.
-  
-             **A headless example takes the name of the one it mirrors**, so the two
-             tiers show the same list rather than a list that changes its labels
-             when a reader changes a preference. Only one of a pair is ever on
-             screen, the tier deciding which, so a differing name would be the only
-             thing suggesting they are different examples. */
             label: startCase(mirrored),
             ...(layout ? { layout } : {}),
             ...(min ? { min } : {}),
@@ -194,15 +72,6 @@ const examplesOf = (slug, declared, sources) => {
         };
     }));
 };
-/**
- * Every family across the given manifests, alphabetical, each with its elements
- * and examples.
- *
- * The family a declaration belongs to comes from where its file is rather than
- * from its tag name, which is the same reasoning `place()` carries for the
- * reference: `helix-button-group` is one family and `helix-tab` is a part
- * of another, and nothing in the name says which.
- */
 export const catalog = (manifests, examples = []) => {
     const byFamily = new Map();
     for (const manifest of manifests) {
@@ -221,8 +90,6 @@ export const catalog = (manifests, examples = []) => {
     }
     return [...byFamily.entries()]
         .map(([slug, entries]) => {
-        /* The family's own description comes from its styled root: the element
-           whose tag is the family name, rather than a part of it. */
         const root = entries.find((entry) => entry.tagName === `helix-${slug}`) ??
             entries[0];
         return {
@@ -243,10 +110,6 @@ export const catalog = (manifests, examples = []) => {
                 })),
                 label: displayName(entry.tagName),
                 methods: methods(entry.members),
-                /* From the manifest, not by stripping the family name off the
-                   label. The composition plugin already derives this from the
-                   folder, and "Avatar Group" minus "Avatar" is a string operation
-                   that happens to work until a part's name contains the family's. */
                 part: entry.helix?.part ?? '',
                 properties: properties(entry.members),
                 slots: members(entry.slots),
@@ -254,9 +117,6 @@ export const catalog = (manifests, examples = []) => {
                 tagName: entry.tagName,
                 tier: tierOf(entry.tagName),
             }))
-                /* Styled first, then headless. Alphabetical order would put the
-                   headless tier on top, which is the one most readers never reach
-                   for. */
                 .sort((a, b) => Number(a.tier === 'headless') - Number(b.tier === 'headless') ||
                 a.tagName.localeCompare(b.tagName)),
             examples: examplesOf(slug, root.helix, examples),
@@ -270,5 +130,4 @@ export const catalog = (manifests, examples = []) => {
     })
         .sort((a, b) => a.label.localeCompare(b.label));
 };
-/** The family of a given slug, from an already-built catalog. */
 export const findInCatalog = (families, slug) => families.find((family) => family.slug === slug);

package/dist/naming.js

@@ -1,28 +1,8 @@
-/**
- * Display names for components.
- *
- * The product is Helix, so every component being called "HelixCard" inside the
- * Helix site is noise: it repeats the one thing the reader already knows on
- * every row of the sidebar. The tag keeps its prefix, because that is a real
- * identifier a consumer types.
- */
-/**
- * Words a slug spells in lower case that are read as letters.
- *
- * Capitalizing the first letter of `qr` gives `Qr`, which is a word nobody says.
- * A slug is lower case because a URL is, and the initialism it came from is
- * lost by the time this sees it, so it has to be put back by name. Kept small
- * and explicit rather than guessed at from length: `ui`, `id` and `api` are
- * initialisms and `is`, `on` and `to` are not.
- */
 const INITIALISMS = new Set(['api', 'css', 'html', 'id', 'qr', 'ui', 'url']);
-/** `app-header` becomes `App Header`, and `qr-code` becomes `QR Code`. */
 export const startCase = (slug) => slug
     .split('-')
     .filter(Boolean)
     .map((word) => INITIALISMS.has(word) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
-/** `helix-app-header` becomes `App Header`, `helix-headless-card` becomes `Card`. */
 export const displayName = (tagName) => startCase(tagName.replace(/^helix-(?:headless-)?/, ''));
-/** Which tier a tag belongs to, read from the prefix rather than the manifest. */
 export const tierOf = (tagName) => tagName.startsWith('helix-headless-') ? 'headless' : 'styled';

package/dist/reference.js

@@ -1,26 +1,10 @@
 import { startCase } from './naming.js';
-/**
- * Whether a member belongs in a reference at all.
- *
- * Public only, and nothing inherited from `HelixElement`. Every component in
- * the library extends it, so its members would appear on all of them: an
- * `internals` field and two lifecycle methods that exist so components do not
- * have to think about the shadow root. Printing them everywhere says the same
- * infrastructural thing once per component and buries the four properties a
- * consumer came to read.
- *
- * `HelixFormElement` is deliberately not on that list. What it contributes is
- * form participation, which is the API of a form control.
- */
 const INFRASTRUCTURE = new Set(['HelixElement']);
 const isPublic = (member) => member.privacy !== 'private' &&
     member.privacy !== 'protected' &&
     !INFRASTRUCTURE.has(member.inheritedFrom?.name ?? '');
-/** A cell's worth of a description: the first paragraph, on one line. */
 const cell = (text) => (text ?? '').split('\n\n')[0]?.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim() ?? '';
-/** A type, escaped so its unions do not end the column they are in. */
 const code = (text) => text ? `\`${text.replace(/\|/g, '\\|')}\`` : '-';
-/** A markdown table, or nothing at all where there are no rows to put in one. */
 const table = (depth, heading, columns, rows) => {
     if (rows.length === 0) {
         return '';
@@ -30,24 +14,10 @@ const table = (depth, heading, columns, rows) => {
     const body = rows.map((row) => `| ${row.join(' | ')} |`).join('\n');
     return `\n${'#'.repeat(depth)} ${heading}\n\n${head}\n${rule}\n${body}\n`;
 };
-/**
- * The family and part a declaration belongs to, from where its file is.
- *
- * Not from the tag name. A tag is a string the family prefix can only be
- * guessed out of: `helix-button-group` is one family and `helix-tab` is a
- * part of another, and nothing in the name says which. The path says both.
- */
 export const place = (path) => {
     const [, family = '', part = ''] = /^src\/([^/]+)\/([^/]+)\//.exec(path ?? '') ?? [];
     return { family, part };
 };
-/**
- * Every family in a manifest, alphabetical, each with its parts.
- *
- * Root first inside a family, then the rest alphabetically. A family reads from
- * the thing that holds the others, and `item` before `root` is alphabetical
- * order telling you about the alphabet rather than about the component.
- */
 export const referenceFamilies = (manifest) => {
     const families = new Map();
     for (const module of manifest.modules ?? []) {
@@ -69,7 +39,6 @@ export const referenceFamilies = (manifest) => {
         parts: [...parts].sort((a, b) => a.part === 'root' ? -1 : b.part === 'root' ? 1 : a.part.localeCompare(b.part)),
     }));
 };
-/** The tables for one element, in the order they are printed. */
 const element = (depth, declaration, part) => {
     const { attributes = [], cssParts = [], cssProperties = [], description, events = [], members = [], slots = [], summary, superclass, tagName, } = declaration;
     const lines = [`${'#'.repeat(depth)} ${startCase(part)} (\`${tagName}\`)`, ''];
@@ -100,26 +69,14 @@ const element = (depth, declaration, part) => {
     ])).trimEnd(), table(depth + 1, 'Events', ['Event', 'Type', 'Description'], events.map((event) => [`\`${event.name}\``, code(event.type?.text), cell(event.description)])).trimEnd(), table(depth + 1, 'Slots', ['Slot', 'Description'], slots.map((slot) => [
         slot.name ? `\`${slot.name}\`` : '*(default)*',
         cell(slot.description),
-    ])).trimEnd(), table(depth + 1, 'Parts', ['Part', 'Description'], cssParts.map((one) => [`\`${one.name}\``, cell(one.description)])).trimEnd(), 
-    /* A "From" column, because a hook can now arrive from a component this one
-       borrowed a stylesheet from rather than be its own. Without it a borrowed
-       `--icon-button-radii` reads on the Copy Button page as a hook Copy Button
-       named, and a consumer who guesses `--copy-button-radii` from that gets
-       nothing. */
-    table(depth + 1, 'Custom properties', ['Property', 'From', 'Description'], cssProperties.map((one) => [
+    ])).trimEnd(), table(depth + 1, 'Parts', ['Part', 'Description'], cssParts.map((one) => [`\`${one.name}\``, cell(one.description)])).trimEnd(), table(depth + 1, 'Custom properties', ['Property', 'From', 'Description'], cssProperties.map((one) => [
         `\`${one.name}\``,
         one.inheritedFrom?.name ? `\`${one.inheritedFrom.name}\`` : '-',
         cell(one.description),
     ])).trimEnd(), '');
     return lines;
 };
-/**
- * The leading `<!-- @summary -->` comment, which the description above already
- * carries. It is how an example declares its own one-liner to the analyzer, so
- * it belongs in the file and not a second time in the prose beside it.
- */
 const withoutSummary = (html) => html.replace(/^<!--\s*@summary[\s\S]*?-->\n*/, '');
-/** One family's examples, as the markdown a reader or an agent can run. */
 const shown = (depth, examples) => {
     if (examples.length === 0) {
         return [];
@@ -137,17 +94,6 @@ const shown = (depth, examples) => {
     }
     return lines;
 };
-/**
- * A manifest, as the markdown reference for everything in it.
- *
- * The caller supplies the manifest and whatever preamble belongs above it, so
- * the same renderer serves the whole-library document in `docs/` and a
- * per-family page without either one knowing about the other.
- *
- * **A single family gets no heading naming it**, because the title already
- * does: a document about the accordion should not say Accordion twice before
- * its first sentence. More than one and the headings are what separate them.
- */
 export const reference = (manifest, options = {}) => {
     const front = options.frontmatter ?? [];
     const lines = [
@@ -160,10 +106,6 @@ export const reference = (manifest, options = {}) => {
     ];
     const wanted = options.families;
     const families = referenceFamilies(manifest).filter((entry) => wanted === undefined || wanted.includes(entry.family));
-    /* Everything under a family heading sits one level deeper than it would in a
-       document that has no family heading to sit under. Without this a page about
-       one component opens at `###`, which is a heading level with nothing above
-       it and reads as a fragment of a larger file. */
     const depth = families.length > 1 ? 3 : 2;
     for (const { family, parts } of families) {
         if (families.length > 1) {

package/dist/registry.js

@@ -1,40 +1,8 @@
-/**
- * Documentation registry for Helix.
- *
- * Docs are a package rather than a folder inside a site so that the docs are
- * pinned to the version of the code they describe. A site renders this
- * registry; it does not own it.
- *
- * **There is no version axis in here.** The package version is the version:
- * `@fusion.dev/helix-docs@0.2.0` documents Helix 0.2.0, because every package in a
- * domain moves in lockstep. A `versions` array beside that would be a second
- * source of truth with nothing keeping the two in step, and the first time they
- * disagreed the registry would win over the package that shipped it.
- *
- * A site serving several versions installs several versions, which is the
- * mechanism npm already provides and the only one that cannot drift.
- *
- * **Nothing about a page is written here.** `pages.generated.ts` is derived
- * from each file's frontmatter by `turbo run docs`, because the frontmatter is
- * what a `.md` consumer receives and a second copy would be a second source of
- * truth. This module is the types and the reading of them; `sections.ts` is the
- * spine that frontmatter has nowhere to live.
- */
 import { docPages } from './pages.generated.js';
 import { docSections } from './sections.js';
 export { docPages as pages, docSections as sections };
 export const findPage = (slug) => docPages.find((page) => page.slug === slug);
-/** Case-insensitive, so `Tokens` and `tokens` do not sort into two groups. */
 const byTitle = (a, b) => a.title.toLowerCase() < b.title.toLowerCase() ? -1 : 1;
-/**
- * The pages of one section, in the order a sidebar renders them.
- *
- * **Alphabetical, except a section that is a path, and except one pinned entry
- * page where a section has one.** The exemption is the same one `AGENTS.md`
- * grants positional arguments and middleware chains, that ordering is skipped
- * where order is semantic. Written down so a section is not silently reordered
- * by whoever next notices it is not alphabetical.
- */
 const ordered = (pages, section) => {
     if (section.path) {
         return [...pages].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
@@ -43,17 +11,6 @@ const ordered = (pages, section) => {
     const rest = pages.filter((page) => !page.pinned).sort(byTitle);
     return [...pinned, ...rest];
 };
-/**
- * The whole sidebar: every declared section, its pages in render order, and
- * each page's children beneath it.
- *
- * A section with no pages cannot appear, because `turbo run docs -- --check` refuses
- * to generate one. Children are alphabetical, because nesting exists for the
- * per-framework installation pages and a reader picking their framework out of
- * a list is looking one up rather than reading a sequence, and then the
- * `trailing` ones, which are the pages that answer "none of the above" and
- * which the alphabet was interleaving with the answers they follow from.
- */
 export const navigation = () => docSections.map((section) => {
     const own = docPages.filter((page) => page.section === section.title && page.parent === undefined);
     return {
@@ -66,5 +23,4 @@ export const navigation = () => docSections.map((section) => {
         })),
     };
 });
-/** Path to a page's MDX, relative to the package root. */
 export const contentPath = (page) => `content/${page.slug}.mdx`;

package/dist/sections.js

@@ -1,26 +1,3 @@
-/**
- * The navigation's spine: which sections exist, in what order, and how each
- * one orders the pages inside it.
- *
- * **Hand-authored, where the pages are not.** A page's own facts come from its
- * frontmatter and are generated into `pages.generated.ts`, because the
- * frontmatter is what a `.md` consumer actually receives and a second copy in
- * a registry is a second source of truth. A section is not a page and has no
- * frontmatter to derive from, so it is written here.
- *
- * **A section with no pages is not declared.** A navigation entry is the
- * strongest existence claim a site can make, so a section is added with the
- * pages that fill it rather than ahead of them. `turbo run docs -- --check` fails
- * on an empty section rather than rendering a heading with nothing under it.
- */
-/**
- * Every section, in the order the sidebar renders them.
- *
- * Deliberately an array rather than an alphabetized record: this is the one
- * place where order is the content. Foundations sits above Theming because a
- * reader needs the vocabulary before the thing that changes it, and no
- * alphabetization expresses that.
- */
 export const docSections = [
     { path: true, title: 'Getting started' },
     { title: 'Foundations' },
@@ -28,5 +5,4 @@ export const docSections = [
     { title: 'Essentials' },
     { title: 'Tooling' },
 ];
-/** The section of a given name, if it is declared. */
 export const findSection = (title) => docSections.find((section) => section.title === title);

package/dist/sources.generated.js

@@ -1,8 +1,3 @@
-/**
- * Every page's MDX, inlined by `turbo run docs`. Do not edit: the files in
- * `content/` are the source, and `turbo run docs -- --check` fails when this module
- * and they disagree.
- */
 export const docSources = {
     accessibility: `---
 description: What the library guarantees, what it cannot, and where the line is.
@@ -1918,10 +1913,10 @@ repository does that. The per-component tables are what a page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 134,650 | 44,269 | 37,972 | Element base class, mixins, decorators, floating positioning. |
-| \`@fusion.dev/helix-headless\` | 519,156 | 131,702 | 103,107 | Every headless family, which is what the barrel means. |
+| \`@fusion.dev/helix-headless\` | 519,154 | 131,672 | 103,150 | 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\` | 956,713 | 216,830 | 159,002 | Every styled family. |
+| \`@fusion.dev/helix\` | 956,713 | 216,820 | 158,985 | 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
@@ -1944,9 +1939,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 13,974 bytes gzipped alone and adds 2,409 to a page that already has Helix on it, so 83 percent of the first one is shared and 17 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,065 gzipped alone, the dearest \`data-table\` at 49,868, over 93 components. Every family at once is 216,830.
+Across the tier: the cheapest is \`code\` at 9,065 gzipped alone, the dearest \`data-table\` at 49,868, over 93 components. Every family at once is 216,820.
 
-**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 131,702 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 93 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 131,672 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 93 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 16,187 bytes gzipped alone.
 
@@ -1985,7 +1980,7 @@ Four other libraries of custom elements, pinned and measured on 2026-08-24 by \`
 | | Material Web | 50,155 | 14,577 | 12,935 |
 | | Shoelace | 37,833 | 11,814 | 10,568 |
 | | Spectrum | 62,322 | 15,059 | 13,321 |
-| \`tabs\` | **Helix** | 40,196 | 12,332 | 10,861 |
+| \`tabs\` | **Helix** | 40,196 | 12,348 | 10,882 |
 | | Carbon | 578,766 | 73,537 | 43,235 |
 | | Material Web | 38,883 | 12,820 | 11,368 |
 | | Shoelace | 54,573 | 17,140 | 15,068 |
@@ -2113,7 +2108,7 @@ Structure, accessibility, state and form participation. No presentation, and no
 | \`steps\` | 82,900 | 27,205 | 22,347 | 6,303 | 1,832 | 1,249 |
 | \`switch\` | 34,314 | 11,106 | 9,826 | 1,798 | 832 | 358 |
 | \`table\` | 31,861 | 10,274 | 9,086 | 4,373 | 1,299 | 831 |
-| \`tabs\` | 33,935 | 11,035 | 9,722 | 4,469 | 1,279 | 803 |
+| \`tabs\` | 33,935 | 11,060 | 9,721 | 4,469 | 1,277 | 735 |
 | \`tag\` | 74,439 | 24,760 | 20,435 | 897 | 464 | 219 |
 | \`textarea\` | 37,001 | 11,743 | 10,362 | 4,115 | 1,414 | 884 |
 | \`time-input\` | 136,201 | 43,547 | 36,687 | 28,643 | 7,661 | 6,120 |
@@ -2212,7 +2207,7 @@ The headless tier plus presentation. This is what \`bun add @fusion.dev/helix\`
 | \`steps\` | 96,252 | 29,575 | 24,410 | 19,643 | 4,202 | 3,353 |
 | \`switch\` | 38,603 | 12,160 | 10,668 | 6,072 | 1,891 | 1,318 |
 | \`table\` | 35,190 | 10,865 | 9,580 | 7,692 | 1,916 | 1,378 |
-| \`tabs\` | 40,196 | 12,332 | 10,861 | 10,719 | 2,598 | 1,976 |
+| \`tabs\` | 40,196 | 12,348 | 10,882 | 10,719 | 2,597 | 1,971 |
 | \`tag\` | 77,633 | 25,634 | 21,148 | 4,076 | 1,245 | 995 |
 | \`text\` | 29,734 | 9,670 | 8,508 | 3,922 | 958 | 605 |
 | \`textarea\` | 40,350 | 12,544 | 11,034 | 7,447 | 2,227 | 1,615 |
@@ -2240,12 +2235,12 @@ column is what was removed rather than part of what remains.
 
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
-| \`@fusion.dev/helix-core\` | 879,273 | 113 | 162,880 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 9,741,797 | 422 | 738,193 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
-| \`@fusion.dev/helix-icons\` | 66,379 | 11 | 20,959 | none |
+| \`@fusion.dev/helix-core\` | 655,135 | 113 | 154,658 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
+| \`@fusion.dev/helix-headless\` | 8,636,163 | 422 | 699,239 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-icons\` | 65,943 | 11 | 20,928 | none |
 | \`@fusion.dev/helix-styles\` | 83,277 | 5 | 0 | none |
-| \`@fusion.dev/helix-theme\` | 463,476 | 8 | 4,764 | none |
-| \`@fusion.dev/helix\` | 9,714,436 | 718 | 287,181 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix-theme\` | 461,551 | 8 | 4,699 | none |
+| \`@fusion.dev/helix\` | 9,306,931 | 718 | 278,170 | \`@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.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -25,7 +25,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.types.json",
     "docs": "node scripts/build-docs.mjs",
     "peers": "bun scripts/build-peers.mjs",
     "test": "bun test src",
@@ -34,7 +34,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.2.0",
+    "@fusion.dev/helix-cem": "0.3.0",
     "@fusion.dev/scripts": "0.0.0-dev"
   },
   "homepage": "https://fusion.dev",