@fusion.dev/helix-docs 0.104.1 → 0.105.0

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

@@ -1,24 +1,32 @@
 ---
-description: Using the headless tier as the foundation for a design system of your own.
+description: Build your own design system on the Helix headless tier, with your own tag names and styles.
 section: Essentials
 title: Building on the headless tier
 ---
 
 # Building on the headless tier
 
-The headless tier is a set of components with no stylesheet: structure, ARIA,
-keyboard behavior, state and form participation, and nothing about how any of it
-looks. That makes it usable as a foundation rather than as a library you consume
-whole. Your tags, your stylesheets, our accessibility.
+The headless tier is a set of components with no stylesheet. Each component
+provides:
 
-This is a different thing from theming Helix. Theming keeps our components and
-changes their tokens. This keeps our behavior and replaces the presentation
-layer outright, under names of your own.
+- structure
+- ARIA
+- keyboard behavior
+- state
+- form participation
 
-## One line does it
+None of it sets how the component looks. You can use the headless tier as the
+foundation of your own design system, with your own tag names and your own
+stylesheets.
 
-Every headless component renders its children by interpolating a tag rather than
-naming one, and the prefix comes from a static on the class:
+Theming Helix keeps our components and changes their tokens. Building on the
+headless tier keeps our behavior and replaces the whole presentation layer,
+under names of your own.
+
+## Set your own tag prefix
+
+Every headless component renders its children with an interpolated tag name.
+The prefix of that name comes from a static on the class:
 
 ```ts
 import { HelixHeadlessCombobox } from '@fusion.dev/helix-headless/combobox'
@@ -30,19 +38,18 @@ export class AcmeCombobox extends HelixHeadlessCombobox {
 customElements.define('acme-combobox', AcmeCombobox)
 ```
 
-That is the whole mechanism, and it is the same one the styled tier uses: it
-writes `static override tier = 'helix-'` and nothing else. The static appears 116
-times in the headless manifest, so it is discoverable rather than folklore.
+That one line sets the prefix. The styled tier sets its prefix the same way, with
+`static override tier = 'helix-'` and nothing else. The static appears 116 times
+in the headless manifest, so you can find it there.
 
-## The render graph is the part that will catch you
+## Register every component a component renders
 
-**A component that renders another gives you two things to register, and only
-one of them is obvious.**
+**When a component renders another component, register both.**
 
-Register `acme-combobox` without also registering `acme-listbox` and the panel
-renders a tag nobody defined. That is not an error and not a warning: an
-unregistered custom element is an inert, unstyled inline box, so what you see is
-a combobox that appears not to open.
+If you register `acme-combobox` without `acme-listbox`, the panel renders a tag
+that is not defined. The browser shows no error or warning. An unregistered
+custom element is an inert, unstyled inline box, so the combobox appears not to
+open.
 
 [//]: # (renders)
 
@@ -71,22 +78,24 @@ a combobox that appears not to open.
 
 [//]: # (/renders)
 
-The safe rule is to subclass and register a family together with everything it
-renders, transitively: `command` reaches `dialog` and `listbox`, and `listbox`
-reaches `option`.
+Subclass and register each family together with everything it renders, and
+everything those families render in turn. For example, `command` reaches
+`dialog` and `listbox`, and `listbox` reaches `option`.
+
+We generate the table from the manifest, which publishes the graph as
+`helix.renders` on every element that interpolates a tag. We kept the table by
+hand until September 22, 2026. By then, four families in it were wrong. The
+generated table is always current.
 
-**This table is generated from the manifest**, which publishes the graph as
-`helix.renders` on every element that interpolates a tag. It was kept by hand
-until 22 September 2026 and was wrong by four families when it stopped being, so
-read it as current rather than as maintained.
+## What you write yourself
 
-## What you have to supply yourself
+### A `:not(:defined)` rule
 
-**A `:not(:defined)` guard.** `@fusion.dev/helix` ships an `elements.css` that
-hides each of its tags until the definition lands, so a page does not show a run
-of unstyled text and then snap. The headless package ships no such file, and
-nothing can generate one for tags you have not named yet. Write the rule for
-your own elements:
+`@fusion.dev/helix` ships an `elements.css` that hides each of its tags until
+the tag's definition loads. Your page then does not show unstyled text that
+changes into components. The headless package ships no such file, and no tool
+can generate one for tags you have not named yet. Write the rule for your own
+elements:
 
 ```css
 acme-combobox:not(:defined),
@@ -95,12 +104,13 @@ acme-listbox:not(:defined) {
 }
 ```
 
-Visibility rather than `display`, so the page does not reflow when the
-definitions arrive.
+Use `visibility` so the page does not reflow when the definitions arrive.
 
-**Your own typings, from the same generator we use.** `@fusion.dev/helix-cem`
-reads your package and writes `jsx.d.ts`, `vue.d.ts` and `svelte.d.ts` for your
-tags, with every member your subclass inherited from ours. Add a `cem.config.ts`
+### Typings for your tags
+
+`@fusion.dev/helix-cem` is the generator we use for our own typings. It reads
+your package and writes `jsx.d.ts`, `vue.d.ts`, and `svelte.d.ts` for your tags,
+with every member your subclasses inherit from ours. Add a `cem.config.ts`
 beside your `package.json`:
 
 ```ts
@@ -113,11 +123,13 @@ export default {
 } satisfies HelixCemOptions
 ```
 
-and run `bun --bun helix-cem`. It finds what you extend through your
-`dependencies`, so `acme-combobox` arrives with the hundred-odd members it
-inherited rather than the two you wrote.
+Then run `bun --bun helix-cem`. It finds the classes you extend through your
+`dependencies`. The typings for `acme-combobox` then include the hundred or so
+members it inherits, as well as the two you wrote.
+
+### The tag map
 
-**The tag map is still yours to write**, one line per element, beside the class:
+Write the tag map yourself, with one line per element, beside the class:
 
 ```ts
 declare global {
@@ -127,43 +139,57 @@ declare global {
 }
 ```
 
-That is TypeScript's own convention for a custom element rather than a gap in
-this: the interface merges from your source, and nothing generated can name a
-class it is not in the same program as.
+TypeScript declares custom elements this way. The interface merges from your
+source, and a generated file cannot name a class that is not in the same
+program.
+
+## What the headless tier handles for you
+
+### Tree-shaking
+
+`@fusion.dev/helix-headless` declares `sideEffects: ["./dist/**/*.js"]`. The
+declaration is accurate, because the modules register elements when you import
+them. A bundler that treated them as free of side effects would drop a
+registration, and a tag would never upgrade.
+
+### Documented parts
+
+Every part has an `@csspart` entry, so every `::part()` you can use is
+published. You write your presentation layer against these named parts, and it
+does not depend on our internal markup.
+
+### Behavior
+
+These features live below the tier you replace, so they keep working under your
+tag names:
 
-## What you get without asking
+- focus management
+- typeahead
+- the roving tab stop
+- form participation
+- validity
 
-**Tree-shaking is honest.** `@fusion.dev/helix-headless` declares
-`sideEffects: ["./dist/**/*.js"]`, which is true rather than convenient: the
-modules register elements on import, so a bundler that believed otherwise would
-drop a registration and leave you debugging a tag that does not upgrade.
+## `tier` is not yet a versioned API
 
-**A styling surface that is documented.** Every part carries an `@csspart`, so
-`::part()` is a published door rather than a shadow tree you have to guess at.
-That is what makes replacing the presentation layer tractable: you are writing
-against named parts, not against our internals.
+`tier` is an implementation detail that is visible in the manifest. Using it to
+set your own prefix makes it an API that needs a stability contract, and we
+have not written that contract yet. The pattern is supported but not yet
+versioned, so pin your Helix version.
 
-**Composition stays ours.** Focus management, typeahead, the roving tab stop,
-form participation and validity all live below the tier you are replacing, so
-they keep working under your names.
+## Building on the headless tier compared with white-labeling
 
-## What is not promised yet
+Building on the headless tier fits you if you are building a design system on
+top of ours and our tags can appear beside yours.
 
-`tier` is an implementation detail that happens to be visible in the manifest.
-Using it the way this page describes turns it into API with a stability contract
-attached, and that contract is not written. Treat this as a supported pattern
-that is not yet a versioned promise, and pin your Helix version.
+White-labeling fits a customer who wants Helix shipped under their own name,
+with no Helix tags. It costs more, and it needs:
 
-## How this differs from white-labeling
+- the tag literals rewritten at build time
+- a second distribution to publish
+- an artifact per customer
 
-Two different customers get confused for each other here. This page is for the
-one building a design system on top of ours and content for our tags to sit
-beside theirs. The other wants Helix shipped under their name with ours absent,
-which is a different and more expensive mechanism: rewriting the tag literals at
-build time, a second distribution to publish, and an artifact per customer.
-Nothing on this page needs any of that.
+Building on the headless tier needs none of these.
 
-The ownership question answers itself in this direction. You hold the
-presentation layer, the tags and the build. If Fusion stopped tomorrow you would
-keep a working design system and lose upstream fixes to the behavior underneath
-it.
+You own the presentation layer, the tags, and the build. If we stopped
+tomorrow, you would keep a working design system. You would lose our fixes to
+the behavior underneath it.

package/content/charting.mdx

@@ -1,37 +1,49 @@
 ---
-description: The data channel nobody expects, and why it is a real table.
+description: Which chart to use, and how charts read their data from a table in the document.
 section: Essentials
 title: Charting
 ---
 
 # Charting
 
-The chart families are `Bar Chart`, `Line Chart`, `Area Chart`,
-`Scatter Chart`, `Donut Chart`, `Heatmap`, `Sparkline`, `Trend` and the shared
-`Legend`. Each has its own API page. Here is which one answers which question,
-and how the data gets in, which is the same for all of them.
+Helix has these chart families, and each one has its own API page:
 
-## Which chart
+- `Bar Chart`
+- `Line Chart`
+- `Area Chart`
+- `Scatter Chart`
+- `Donut Chart`
+- `Heatmap`
+- `Sparkline`
+- `Trend`
+- `Legend`, which all of the charts share
 
-Pick by the question, not by the picture.
+This guide covers which chart fits which question, and how data gets into a
+chart. Data gets in the same way for every chart.
+
+## Choose a chart
+
+Choose a chart by the question it answers.
 
 - **How much, compared.** `Bar Chart`. A bar's length is its value, so it always
   starts at zero.
 - **How something moved over time.** `Line Chart`. It measures from the data's
   own range, so a small change still shows. Its `area` puts a light wash under
-  each line, each drawn from the floor on its own and overlapping the others.
+  each line. Each wash is drawn from the floor on its own and overlaps the
+  others.
 - **How a total is made up over time.** `Area Chart`. Each column is stacked on
   the one below, so the top edge is the total and a band's thickness is its
-  share. This is the one to reach for when the parts add up to something, and
-  `Line Chart` with `area` is not a substitute: that overlaps the series, this
-  adds them.
+  share. Use it when the parts add up to a total. `Line Chart` with `area`
+  overlaps the series, and `Area Chart` adds them.
 - **Parts of one whole, at one moment.** `Donut Chart`.
-- **Whether two measures relate.** `Scatter Chart`, one point per row.
-- **How each day or check went.** `Heatmap`: uptime, contributions, activity.
-- **The shape of a series beside its number.** `Sparkline`, with no axes. And
-  `Trend` for which way one measurement moved and whether that is good news.
+- **Whether two measures relate.** `Scatter Chart`, with one point per row.
+- **How each day or check went.** `Heatmap`, for uptime, contributions, or
+  activity.
+- **The shape of a series beside its number.** `Sparkline`, drawn with no axes.
+  Use `Trend` to show which way one measurement moved and whether that is good
+  news.
 
-## The data is a table in the document
+## Charts read their data from a table
 
 ```html
 <table id="revenue">
@@ -48,20 +60,19 @@ Pick by the question, not by the picture.
 <helix-bar-chart for="revenue"></helix-bar-chart>
 ```
 
-`for` points at a real `<table>` by id, and the chart reads its series from it.
-That is unlike every other component in the library, and it is not a
-convenience.
+`for` points to a real `<table>` by id, and the chart reads its series from that
+table. No other Helix component gets its data this way. There are two reasons.
 
-**A property cannot survive hydration.** A framework's server render emits
-markup, and a property is not markup: an array assigned to `items` exists only
+First, a property does not survive hydration. A framework's server render emits
+markup, and a property is not markup. An array assigned to `items` exists only
 after JavaScript has run, so the server has nothing to send and the first paint
-has nothing to draw. Text in the document is the one channel that both a server
-and a client can see.
+has nothing to draw. Text in the document is the one channel that both the
+server and the client can see.
 
-**And the table is not a workaround, it is the accessible version.** A chart is
-a picture of numbers, and a screen reader cannot read a picture. The table is
-the numbers, in the document, navigable, and the chart is the drawing of them.
-Hide the table visually if it should not be seen, and the data is still there:
+Second, the table is what a screen reader reads. A chart is a picture of
+numbers, and a screen reader cannot read a picture. The table holds the numbers
+in the document, where you can navigate them, and the chart draws them. If the
+table should not be seen, hide it visually, and the data is still there:
 
 ```html
 <table
@@ -70,67 +81,75 @@ Hide the table visually if it should not be seen, and the data is still there:
 >…</table>
 ```
 
-The caption becomes the chart's accessible name unless you set `label`, which is
-usually the right words and is already written.
+The table's caption becomes the chart's accessible name unless you set `label`.
+The caption usually has the right words already.
 
 ## Series colors
 
-Twenty-four `--helix-color-series-*` tokens, in order. A chart with three series
-uses the first three. They are ordered to stay distinguishable in that order
-rather than to look good as a full set of twenty-four.
+Helix has twenty-four series color tokens, in order, from
+`--helix-color-series-1` to `--helix-color-series-24`. A chart with three series
+uses the first three. The tokens are ordered so that each color
+stays distinguishable from the ones before it. They are not designed to look
+good as a full set of twenty-four.
 
-The palette wraps, and where it wraps is one number in one place, so a chart and
-the legend beside it can never disagree about which color a series is.
+The palette wraps after the last color. One number in one place sets where it
+wraps, so a chart and the legend beside it always agree on each series' color.
 
-**A chart's mark carries its own series color as a custom property**, because a
-chart knows which series a bar belongs to and CSS cannot count it. That is what
-lets you restyle a series from outside without knowing the drawing order.
+Each mark in a chart carries its series color as a custom property. The chart
+tracks which series each bar belongs to, and CSS cannot count that. With the
+custom property, you can restyle a series from outside the chart without knowing
+the drawing order.
 
-## Legends
+## Add a legend
 
 ```html
 <helix-legend for="revenue"></helix-legend>
 <helix-bar-chart for="revenue"></helix-bar-chart>
 ```
 
-The legend reads the same table, so the names and the colors cannot disagree
-with the chart's. Pointing them at two different tables is the only way to make
-them disagree, and it is not something to do by accident.
-
-## Right-to-left
-
-On a page with `dir="rtl"`, an axis that follows reading order starts where the
-text does, on the right: categories and time. The words around a drawing are
-HTML and turn on their own, and the drawing turns with them, so the name under
-a column is that column's name in either direction. The pointer and the tooltip
-read the drawing the same way. An axis of values keeps its own direction.
-
-- **What turns.** `Bar Chart`'s columns, and its rows, which grow out of their
-  names at the right. `Line Chart`, `Area Chart` and `Sparkline`, with their
-  end marks. `Heatmap`'s weeks, which were already a grid laid out along the
-  line. A half `Donut Chart`, which is read across.
-- **What does not.** Up is more in every script, so values keep their vertical
-  sense, and numerals are text beside the drawing, so none reads backwards. A
-  whole `Donut Chart` keeps its first slice at twelve and runs clockwise, which
-  is a clock's convention rather than a script's. `Scatter Chart` is laid out as
-  on a left-to-right page, its y axis on the left and more to the right, because
-  both of its axes are measures and a number line runs that way in every
-  script. Its axis names read in their own direction, so a name in Arabic reads
-  right to left under the plot's far end, and its summary and tooltip read the
-  way the page does.
-
-A chart that should read left to right anyway, a number line in a mathematics
-text for instance, takes `dir="ltr"` on the element, and the platform's own
-attribute is the whole of the switch.
-
-## Reduced motion
-
-Charts animate on entry and on data change, and every one of them answers
-`prefers-reduced-motion`. See [Motion](./motion).
-
-## What these are not
-
-**Not a charting library.** There is no axis configuration language, no plugin
-system, and no chart type you build by composing scales. Drawings that read a
-table, styled by the token system, with an accessible representation by
-construction. When you need a grammar of graphics, use one.
+The legend reads the same table as the chart, so their names and colors always
+match. They can differ only if you point them at two different tables.
+
+## Charts on right-to-left pages
+
+On a page with `dir="rtl"`, an axis that follows reading order starts on the
+right, where the text starts. Categories and time follow reading order. The
+words around a chart are HTML and change direction on their own. The drawing
+changes direction with them, so the name under a column belongs to that column
+in either direction. The pointer and the tooltip read the drawing the same way.
+An axis of values keeps its own direction.
+
+These parts change direction:
+
+- `Bar Chart`'s columns, and its rows, which grow out of their names at the
+  right
+- `Line Chart`, `Area Chart`, and `Sparkline`, with their end marks
+- `Heatmap`'s weeks, which were already a grid laid out along the line
+- A half `Donut Chart`, which is read across
+
+These parts keep their direction:
+
+- Values keep their vertical direction, because up means more in every script.
+- Numerals are text beside the drawing, so none of them reads backwards.
+- A whole `Donut Chart` keeps its first slice at twelve o'clock and runs
+  clockwise. That is a clock's convention, and it does not depend on the script.
+- `Scatter Chart` is laid out as on a left-to-right page, with its y axis on the
+  left and larger values to the right. Both of its axes are measures, and a
+  number line runs that way in every script. Its axis names read in their own
+  direction, so a name in Arabic reads right to left under the far end of the
+  plot. Its summary and tooltip follow the page's direction.
+
+To keep a chart left to right on a right-to-left page, such as a number line in
+a mathematics text, set `dir="ltr"` on the chart element. You need nothing else.
+
+## Chart animation and reduced motion
+
+Charts animate when they appear and when their data changes. Every chart
+responds to `prefers-reduced-motion`. See [Motion](./motion).
+
+## What Helix charts do not include
+
+Helix charts have no axis configuration language, no plugin system, and no chart
+types that you build by composing scales. Each chart is a drawing that reads a
+table and is styled by the token system, and the table is its accessible
+representation. When you need a grammar of graphics, use a charting library.