@fusion.dev/helix-docs 0.142.0 → 0.143.0

package/content/accessibility.mdx

@@ -18,10 +18,11 @@ accessible only when you also handle your parts.
 Every component implements the keyboard pattern for its role. You do not write
 any of it:
 
-- Arrow keys move within `Tabs`, `Listbox`, and `Menu`.
+- Arrow keys move within `Tabs`, `Listbox`, `Menu`, `Select`, `Combobox`, and
+  the days of a date picker.
 - `Escape` closes an overlay.
 - `Home` and `End` go to the first and last item.
-- Typing jumps to a matching item.
+- In `Listbox`, `Select`, `Menu`, and `Tree`, typing jumps to a matching item.
 
 ### Focus
 
@@ -106,11 +107,24 @@ and is read where it sits. Neither component is a variant of the other.
 
 `aria-labelledby` and `aria-describedby` inside a shadow root cannot point to an
 id in your document. The browser drops the reference silently and reports no
-error. For this reason, every control renders its own label, and connecting two
-components by id does not work. See [Forms and validation](./forms).
-
-A `<label for>` in your markup cannot reach into a shadow root either, so it
-does not name a Helix control. Use the control's own `label`.
+error. For this reason, every control renders its own label. See
+[Forms and validation](./forms).
+
+**What you write on the host reaches the control inside it.** The form controls,
+`Button`, and `IconButton` carry these down to the element a screen reader is on:
+
+- `aria-labelledby` and `aria-describedby`, as element references, so the ids
+  you name in your document resolve.
+- A `<label for>` that points at the host, or a `<label>` around it, when the
+  control has no `label` of its own.
+- `aria-expanded`, `aria-haspopup`, `aria-controls`, `aria-invalid`, and
+  `aria-pressed`.
+- `aria-label` on `Button`, `IconButton`, and `Switch`. A field renders its
+  `aria-label` as a hidden label.
+
+A `<label>` around a control also reads the words inside the control, such as
+the names of its buttons. Use `<label for>` or the control's own `label` to name
+it with your words alone.
 
 When a relationship has to cross the boundary, the components use
 `ElementInternals` and element-reference properties. They are the only mechanism

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

@@ -39,8 +39,8 @@ customElements.define('acme-combobox', AcmeCombobox)
 ```
 
 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.
+`static override tier = 'helix-'` and nothing else. Every element in the
+headless manifest carries the static, so you can find it there.
 
 ## Register every component a component renders
 
@@ -108,24 +108,26 @@ Use `visibility` so the page does not reflow when the definitions arrive.
 
 ### 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`:
+Your typings come from a manifest of your package. `helix manifest build`, in
+`@fusion.dev/helix-cli`, writes one that includes every member your subclasses
+inherit from ours. Name each Helix package you extend and where its manifest is:
 
-```ts
-import type { HelixCemOptions } from '@fusion.dev/helix-cem'
-
-export default {
-  frameworkTypes: true,
-  packageName: 'acme-system',
-  tier: 'styled',
-} satisfies HelixCemOptions
+```sh
+helix manifest build . --tier styled \
+  --dependency @fusion.dev/helix=node_modules/@fusion.dev/helix/custom-elements.json \
+  --dependency @fusion.dev/helix-headless=node_modules/@fusion.dev/helix-headless/custom-elements.json \
+  --dependency @fusion.dev/helix-core=node_modules/@fusion.dev/helix-core/custom-elements.json \
+  > custom-elements.json
 ```
 
-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.
+Then run a typings generator over it. Our own typings start from
+`@wc-toolkit/jsx-types` and `@wc-toolkit/vuejs-types`. The typings for
+`acme-combobox` then include the hundred or so members it inherits, as well as
+the two you wrote.
+
+`@fusion.dev/helix-cem`, the step that runs those generators for our packages
+and corrects what they write, is not published. It is build tooling for this
+repository.
 
 ### The tag map
 

package/content/charting.mdx

@@ -84,6 +84,32 @@ table should not be seen, hide it visually, and the data is still there:
 The table's caption becomes the chart's accessible name unless you set `label`.
 The caption usually has the right words already.
 
+Each chart writes a short summary for screen readers, which starts with that
+name. The drawing is hidden from screen readers, and the summary gives the one
+reading a chart is usually read for:
+
+- `Bar Chart`: each series' highest reading.
+- `Line Chart`: each series' latest reading.
+- `Area Chart`: the latest total and each part's share of it.
+- `Donut Chart`: each slice's share of the whole.
+- `Scatter Chart`: each series' number of points and how strongly the two
+  measures relate.
+
+`Heatmap` is an image with that name. `Sparkline` takes a `label` of its own.
+
+## Tables that change
+
+A chart follows its table. It redraws when you edit a cell, add a row, or
+replace the table with a new one under the same id. It also draws a table that
+arrives after the chart does, such as one a framework renders once its data
+loads.
+
+A blank cell, or one that does not hold a number, is a gap in its series. The
+row keeps its place on the axis, a line breaks at the gap, a bar chart draws no
+bar there, and a heatmap draws the cell with no tone. The readings after the gap
+stay under their own labels, and the tooltip for that row still shows the
+row's cells.
+
 ## Series colors
 
 Helix has twenty-four series color tokens, in order, from

package/content/color.mdx

@@ -6,8 +6,8 @@ title: Color
 
 # Color
 
-Seventy-four of the library's 185 tokens are colors, and they make up most of a
-theme. Each color token is named for its role. No token is named for how it
+Colors are the largest group of the library's tokens, and they make up most of
+a theme. Each color token is named for its role. No token is named for how it
 looks, because a name like `--brand-blue-500` becomes wrong as soon as you change
 the theme.
 

package/content/composition.mdx

@@ -66,11 +66,18 @@ for a slot of the same name. Helix never renders both.
 
 ```html
 <!-- The property -->
-<helix-tooltip content="Save"></helix-tooltip>
+<helix-tooltip
+  content="Save"
+  for="save"
+  id="save-tip"
+></helix-tooltip>
 
 <!-- The slot, which replaces it -->
-<helix-tooltip>
-  <strong>Save</strong>, or press <helix-kbd>⌘S</helix-kbd>
+<helix-tooltip
+  for="save"
+  id="save-tip"
+>
+  <span slot="content"><strong>Save</strong>, or press <helix-kbd>⌘S</helix-kbd></span>
 </helix-tooltip>
 ```
 
@@ -84,8 +91,9 @@ examples put the closing tag on the same line as the opening tag.
 
 ## Set a button's width with the layout
 
-A button has no `width` or `fill` property, for the same reason it has no `size`
-property. How wide a control is depends on the region it is in.
+A button has no `fill` property and no `size` property. How wide a control is
+depends on the region it is in. `width="full"` fills the row a button sits in,
+and the layout decides everything else.
 
 A button already stretches in a column flex or a grid, because a stretch-aligned
 parent stretches its children:
@@ -163,8 +171,8 @@ and then a second attribute to hide it is the same as having no visible label.
 
 `Option`, `Listbox`, and `Select` are three families so that the keyboard
 handling, the filtering, the multi-select rules, and the active-item tracking
-are written once. `Select` renders a `Listbox` internally. A future combobox
-will too, and so would a command palette.
+are written once. `Select` renders a `Listbox` internally, and so does `Combobox`. A command
+palette would too.
 
 For the same reason, we wrote `DrilldownController`. Since it was first written,
 `Menu` had held a page stack and derived its rows, and none of that code

package/content/events.mdx

@@ -105,6 +105,10 @@ against a dispatch, so every event you can listen for is documented.
 | `helix-before-change` | A value is about to change, cancelable |
 | `helix-before-toggle` | A checked state is about to flip, cancelable |
 | `helix-before-open`, `helix-before-close` | An open state is about to change, cancelable |
+| `helix-before-activate`, `helix-activate` | A set is about to make a different child current, cancelable, and then did |
+| `helix-before-pin`, `helix-pin` | A chat transcript is about to be pinned to the bottom or let go of it, cancelable, and then was |
+| `helix-before-resize`, `helix-resized` | A splitter's divider is about to settle, cancelable, and then did |
+| `helix-before-collapse`, `helix-collapse` | A splitter's pane is about to shut or reopen, cancelable, and then did |
 | `helix-select` | An item was chosen from a set |
 | `helix-dismiss` | A user asked for something to close |
 | `helix-next`, `helix-previous` | Movement through a sequence |
@@ -121,12 +125,36 @@ Every stateful component also sends native events once the change is applied:
 
 - `input` and `change` on a value control
 - `toggle` on anything that opens, carrying `newState` and `oldState` as
-  `<details>` does
+  `<details>` does. It is a `ToggleEvent` in browsers that have one, and it is
+  sent whether the change came from a reader or from assigning `open`
 - `close` on a dialog
 - `load` and `error` on an image
 
 Each component's page lists the events it dispatches, with the class and the
-detail.
+detail. The table above lists the common ones.
+
+## Requests under a plain name
+
+A few events with no `before` in their name are also cancelable requests. Each
+is sent before the change, and you refuse the change with `preventDefault()`:
+
+- `helix-navigate` on Pagination, Data Table, and Date Picker
+- `helix-sort`, `helix-filter`, `helix-select`, and `helix-reorder` on Data Table
+- `helix-select` on Carousel
+
+Each of these requests had its name before the library had a word for the
+notification, so the notification has its own name. It is sent after the
+change, is not cancelable, and carries the new state:
+
+- `helix-activate` after the page moves on Pagination and Data Table, and after
+  the slide moves on Carousel
+- `helix-sorted`, `helix-filtered`, `helix-selected`, and `helix-reordered` on
+  Data Table
+- `input` and `change` together on Pagination Size, as a native `<select>`
+  sends them
+
+A request that is refused sends no notification. Date Picker's `helix-navigate`
+moves the month on show, and the month sends no notification.
 
 ## Events in a framework
 

package/content/forms.mdx

@@ -101,23 +101,62 @@ participants:
 ></helix-input>
 ```
 
-Submitting an empty form is blocked, and the browser points to the control.
-`checkValidity()`, `reportValidity()`, and `:invalid` work as they do for native
-controls.
+Submitting an empty form is blocked, and the browser moves focus to the control
+and shows its message there. Each control has the validity API of a native
+control:
 
-`feedback` replaces the browser's message. When `feedback` is empty, the
-browser shows its own message, which is localized and familiar. When you set it,
-the control shows the message in the words your product uses:
+- `checkValidity()` and `reportValidity()`
+- `setCustomValidity(message)`
+- `validity`, `validationMessage`, and `willValidate`
+
+`:invalid` matches the control as it matches a native one.
+
+`value-missing-message` replaces the browser's message for a required control
+that is empty. When it is not set, the browser shows its own message, which is
+localized and familiar:
 
 ```html
 <helix-input
-  feedback="We need this to send your receipt."
   label="Email"
   name="email"
   required
+  value-missing-message="We need this to send your receipt."
+></helix-input>
+```
+
+**`feedback` says what is wrong, and the form does not submit while it is
+set.** Use it for a verdict the browser cannot reach, such as one your server
+returned. The control shows the message under itself and is invalid until you
+clear `feedback`:
+
+```html
+<helix-input
+  feedback="That name is taken."
+  label="Username"
+  name="username"
 ></helix-input>
 ```
 
+`setCustomValidity()` blocks the form in the same way, and the control shows
+its message once the reader has edited the field.
+
+## Focus and Enter
+
+`focus()` on a control moves focus to the element a reader would reach with
+Tab, and pressing a `<label>` that names the control does the same. In a group,
+that is the chosen radio, or the first one when nothing is chosen.
+
+Pressing Enter in a single-line field submits its form, as Enter in a native
+text field does. These fields do it:
+
+- `Input`, `NumberInput`, and `PinInput`
+- `DateInput`, `TimeInput`, and `ColorInput`
+- `Combobox`, while its list is closed
+
+The form's first submit button is pressed, and a `helix-button type="submit"`
+counts as one, for a native field too. A form with no submit button is
+submitted when it has only one text field.
+
 `Radio.Group` and `Toggle.Group` take part in the form for their members. Each
 group owns the `name`, the `value`, and the validity. A single radio is an
 answer, and the group is the control it answers. `Checkbox.Group` works the

package/content/graphs.mdx

@@ -31,7 +31,7 @@ Add the frame, with an element inside it for the renderer to draw in:
 Give the frame its notes and links, make the renderer, and connect the two:
 
 ```js
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/graph'
 import { connectGraph } from '@fusion.dev/helix-graph'
 import { sigmaDriver } from '@fusion.dev/helix-graph/sigma'
 import Graph from 'graphology'
@@ -186,7 +186,10 @@ is a button that shows or hides the group's notes, in the drawing and in the
 list:
 
 ```html
-<helix-graph label="Company notes" legend>
+<helix-graph
+  label="Company notes"
+  legend
+>
   <div></div>
 </helix-graph>
 ```
@@ -234,7 +237,10 @@ and the frame brings it into view with its neighbors. Start with one selected
 with `default-active`:
 
 ```html
-<helix-graph default-active="roadmap" label="Research notes">
+<helix-graph
+  default-active="roadmap"
+  label="Research notes"
+>
   <div></div>
 </helix-graph>
 ```
@@ -246,7 +252,11 @@ Set `depth` to show only the notes within that many links of the selected one,
 for a graph too large to read at once:
 
 ```html
-<helix-graph default-active="roadmap" depth="2" label="Research notes">
+<helix-graph
+  default-active="roadmap"
+  depth="2"
+  label="Research notes"
+>
   <div></div>
 </helix-graph>
 ```
@@ -319,7 +329,10 @@ finger moves it. A graph embedded in a page takes the wheel from a reader who
 is scrolling past it. Set `gestures` on the frame to share them:
 
 ```html
-<helix-graph gestures="cooperative" label="Research notes">
+<helix-graph
+  gestures="cooperative"
+  label="Research notes"
+>
   <div></div>
 </helix-graph>
 ```
@@ -340,7 +353,11 @@ drawing takes all of it, as at the top of a page. A Notes button among the
 controls opens them over the drawing:
 
 ```html
-<helix-graph gestures="cooperative" label="Research notes" no-panel>
+<helix-graph
+  gestures="cooperative"
+  label="Research notes"
+  no-panel
+>
   <div></div>
 </helix-graph>
 ```
@@ -409,7 +426,8 @@ leaves removing it to your framework.
   minus keys zoom it. Set `controls="pan zoom fullscreen"` to add buttons that
   move it.
 - The list is a listbox, named by `notes-label`. Arrow keys, Home, End, Page
-  Up, and Page Down move through it, and Enter or Space selects a note.
+  Up, and Page Down move through it, typing a letter moves to the next note
+  whose name starts with it, and Enter or Space selects a note.
 - In the search field, Down moves into the list, and Escape empties the search.
   With `no-panel`, Escape on an empty search closes the list.
 - Screen readers read the selected note first, then how each other note links

package/content/installation.mdx

@@ -44,15 +44,15 @@ Each file has its own export. If you bring your own reset or your own ramp,
 import the two files you want and skip `helix.css`.
 
 - **`primitives.css`** holds the raw ramp that the semantic layer is derived
-  from. The seven `--helix-seed-*` properties are read here. Your own code
-  should not name a primitive, and leaving the file out does not enforce that.
-  `tokens.css` refers to a primitive 297 times, so without `primitives.css`
-  every semantic token resolves to nothing. We measured a page without it:
+  from. The `--helix-seed-*` properties are read here. Your own code should
+  not name a primitive, and leaving the file out does not enforce that.
+  `tokens.css` refers to the primitives throughout, so without
+  `primitives.css` every semantic token resolves to nothing. We measured a page without it:
   `--helix-color-background` computes to `rgba(0, 0, 0, 0)`, and so does every
   other color. [Theming](theming.mdx) also depends on this file, because without
   it, setting `--helix-seed-brand` changes nothing.
-- **`tokens.css`** declares the semantic layer: 185 custom properties in 15
-  categories, plus `color-scheme: light dark` on `:root`. The files below read
+- **`tokens.css`** declares the semantic layer, the custom properties grouped
+  by category, plus `color-scheme: light dark` on `:root`. The files below read
   from it, and it reads from `primitives.css`.
 - **`base.css`** holds the element reset, the type scale on bare `h1` through
   `h6`, and the recipes for markup that Helix does not render. It reads tokens.
@@ -67,25 +67,23 @@ components. The order then stays visible in one place.
 
 ## Register the elements
 
-```ts
-import '@fusion.dev/helix'
-```
-
-This import has a side effect: it calls `customElements.define` once for every
-element. You can run it more than once. A second `define` for the same tag
-throws an error and stops the rest of the module, so the helper behind the
-import checks the registry first.
-
-To register only some elements, import them from subpaths:
+Import each family you use from its subpath:
 
 ```ts
 import '@fusion.dev/helix/button'
 import '@fusion.dev/helix/dialog'
 ```
 
-Import from subpaths when you use a few components. The package has side
-effects by design, so a bundler keeps everything you import. The whole-package
-import registers every element, and a subpath registers only its family.
+Each import has a side effect: it calls `customElements.define` for the
+elements of that family, and for the families they render. You can run it more
+than once. A second `define` for the same tag throws an error and stops the rest
+of the module, so the helper behind the import checks the registry first.
+
+The package has side effects by design, so a bundler keeps everything you
+import. `import '@fusion.dev/helix'` registers every element in the library,
+which is the whole library in your bundle. Use it for a prototype, and use
+subpaths in an app. [Metrics](./metrics) lists the size of each family and of
+the whole package.
 
 ## Check the installation
 

package/content/introduction.mdx

@@ -33,12 +33,12 @@ reason.
 bun add @fusion.dev/helix @fusion.dev/helix-styles
 ```
 
-Add two imports at your app root, in this order. Then you can use the elements
-anywhere:
+Import the stylesheet at your app root, then each family you use. Then you can
+use those elements anywhere:
 
 ```ts
 import '@fusion.dev/helix-styles/helix.css'
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/accordion'
 ```
 
 ```html

package/content/localization.mdx

@@ -92,8 +92,8 @@ Six families format numbers or dates and take a `locale`:
 
 | | |
 |---|---|
-| `Date Input`, `Date Picker` | Date formats and first day of week |
-| `Time Input`, `Time Picker` | 12 or 24 hour, and separators |
+| `Date Input`, `Date Picker` | Date formats, and the first day of the week where `first-day-of-week` is not set |
+| `Time Input`, `Time Picker` | 12 or 24 hour, separators, and the AM and PM on the wheels |
 | `Pagination` | Grouped thousands in page numbers |
 | `File Input` | File sizes |
 
@@ -108,6 +108,15 @@ If you do not set `locale`, these controls use the browser's locale, which is
 usually correct. Set `locale` when your users choose your application's
 language separately from the language of their operating system.
 
+The first day of the week comes from `Intl.Locale`'s week information, which
+Firefox does not provide. There, and where you set no `locale`, the week starts
+on Sunday. Set `first-day-of-week` to choose the day yourself.
+
+`locale` formats dates, times, and numbers. It does not translate the words a
+control speaks, such as "Previous month" on a calendar or "Hour" on a time
+wheel. Set those through their properties, such as `previous-label` and
+`next-label` on Date Picker and Date Input, and `hour-label` on Time Picker.
+
 Formatting uses `Intl`, so Helix bundles no locale data, and you have nothing to
 keep up to date.
 
@@ -137,8 +146,13 @@ it reports:
 - `bad-input-message`
 - `range-underflow-message`
 - `range-overflow-message`
+- `step-mismatch-message`
 - `too-short-message`
 
+Date Picker, Date Input, Time Picker, and Time Input also take
+`unavailable-message`, for a date or time that `disable-dates`, `disable-days`,
+or `disable-times` rules out.
+
 A message appears in the browser's own validation bubble and on the line under
 the field. `feedback` does not reach the bubble. If you do not set a message, a
 text field shows the browser's own message, which is already in your user's

package/content/maps.mdx

@@ -36,7 +36,7 @@ Add the map frame, an element for MapLibre to draw in, and your places:
 Create the map with a style from your theme, then connect it to the frame:
 
 ```js
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/map'
 import 'maplibre-gl/dist/maplibre-gl.css'
 import { colorsReady, connectMap } from '@fusion.dev/helix-map'
 import { followTheme, mapLibreDriver, mapLibreStyle } from '@fusion.dev/helix-map/maplibre'
@@ -161,7 +161,11 @@ is the map's. Give the container a position, such as `position: relative`:
 
 ```html
 <section class="hero">
-  <helix-map fill credit-placement="bottom-end" label="Downtown Austin">
+  <helix-map
+    credit-placement="bottom-end"
+    fill
+    label="Downtown Austin"
+  >
     <div id="map"></div>
   </helix-map>
   <div class="hero-words">
@@ -235,7 +239,10 @@ A map embedded in a page, such as a hero, takes the wheel from a reader who is
 scrolling past it. Set `gestures` on the frame to share them:
 
 ```html
-<helix-map gestures="cooperative" label="Downtown Austin">
+<helix-map
+  gestures="cooperative"
+  label="Downtown Austin"
+>
   <div id="map"></div>
 </helix-map>
 ```
@@ -487,7 +494,10 @@ is a map type, which the frame's `map-type` attribute chooses:
 - `satellite`: the imagery alone, without the roads and names.
 
 With `layers` in the frame's `controls`, the layers menu opens with a card for
-each map type, showing a picture of the map in it. Set `max-zoom` to the deepest
+each map type, showing a picture of the map in it. Choosing a card sends
+`helix-before-change` with the type's name, `standard`, `hybrid`, or
+`satellite`, and `change` once `map-type` holds it. Cancel the first to keep the
+current type, or listen for the second to store the choice. Set `max-zoom` to the deepest
 zoom your provider has tiles for, and the map enlarges those tiles when a user
 zooms in further.
 
@@ -560,6 +570,10 @@ tile is lit while its layer is shown. Pressing a tile sets its layer's `hidden`
 attribute, and `connectMap` does not draw a hidden layer. Write `hidden` on a
 layer to start it turned off.
 
+Before it sets `hidden`, a tile sends `helix-before-toggle` from the layer, with
+`checked` true when the layer is to be shown. Store the choice from it, or
+cancel it to keep the layer as it is.
+
 Give layers the same `group` to show them as one tile, such as a route and the
 dotted legs at its ends. The tile takes the name of the first layer in the
 group, and shows or hides every layer in it. Keep labels short, such as