@fusion.dev/helix-docs 0.205.2 → 0.207.0

package/README.md

@@ -1,15 +1,35 @@
 # @fusion.dev/helix-docs
 
-The Helix documentation as content: the pages, and the registry that names them.
+The Helix documentation as content: the pages, the registry that names them,
+and the renderer for the component reference.
 
 ```sh
 npm install @fusion.dev/helix-docs
 ```
 
 ```js
-import { catalog, findInCatalog, reference } from '@fusion.dev/helix-docs'
+import { docSources, findPage, navigation, reference } from '@fusion.dev/helix-docs'
 ```
 
+- `pages` is every page, each with its `slug`, `title`, `section`, and
+  `description`. `findPage(slug)` returns one page.
+- `navigation()` returns the sidebar: each section in order, the pages under it
+  in the order a sidebar renders them, and each page's children.
+- `sections` is the sections in order, and `findSection(title)` returns one.
+- `docSources` holds each page's MDX, keyed by slug.
+- `contentPath(page)` takes a page from `pages` and returns the path of its MDX
+  in the package, such as `content/theming.mdx`. Import the file as
+  `@fusion.dev/helix-docs/content/theming.mdx`.
+- `reference(manifest, options)` renders a `custom-elements.json` as the
+  markdown component reference. `referenceFamilies(manifest)` returns each
+  family and its parts in the order the reference prints them.
+
+The component catalog ships in each tier as `api.json` and `examples.json`,
+such as `@fusion.dev/helix/api.json`: every family with its elements, imports,
+and examples. An add-on package ships them too, listing the elements it adds
+to a family: `@fusion.dev/helix-sandbox/api.json` lists its editor under the
+Sandbox family.
+
 Published as a package rather than served only from a site so that the
 documentation carries the version of the library it documents. A docs package at
 version x describes Helix at version x, which is why versioning here is per

package/content/angular.mdx

@@ -31,7 +31,8 @@ typos, in your other components.
 
 ```html
 <helix-input
-  (change)="name = $event.target.value"
+  #field
+  (change)="name = field.value"
   [value]="name"
 />
 ```
@@ -39,6 +40,10 @@ typos, in your other components.
 `[prop]` sets a property, which a value that is not a string needs. `(event)`
 binds with `addEventListener`, so use the event's own name.
 
+`#field` gives the template a reference to the element, typed as its class once
+you import its family. Under `strictTemplates`, `$event.target` is an
+`EventTarget | null`, which has no `value`.
+
 **Do not use `attr.` for a stateful property.** `[attr.value]="name"` writes the
 attribute. The attribute seeds the control and is out of date as soon as someone
 types in it. The property holds the current value.
@@ -50,9 +55,17 @@ checking that typings would feed, so Angular would not enforce a generated file.
 We publish the manifest as `@fusion.dev/helix/custom-elements.json`, so you can
 generate your own files from it.
 
-As a result, a misspelled property fails without an error in Angular. In React,
-Vue, and Svelte, the same mistake is a compile error. Check property names in
-code review.
+As a result, a misspelled property fails without an error in Angular. Check
+property names in code review.
+
+The other frameworks check a misspelled name to different degrees:
+
+- In React, TypeScript reports a misspelled prop unless its name has a hyphen.
+  See [React](./react).
+- In Vue, `vue-tsc` reports one only when `checkUnknownProps` is on. See
+  [Vue](./vue).
+- In Svelte, `svelte-check` reports an attribute that the Helix tag does not
+  declare.
 
 ## Refuse a change
 
@@ -60,3 +73,23 @@ code review.
 value you set and then applies its own changes. To refuse a change, listen for
 the `helix-before-*` event and call `preventDefault()`. See
 [State and control](./state-and-control).
+
+To write your own value into a field you type into, set your signal and then
+call `detectChanges()` on the component's `ChangeDetectorRef`:
+
+```ts
+private readonly view = inject(ChangeDetectorRef)
+
+protected takeHandle(event: Event): void {
+  event.preventDefault()
+  const { value } = (event as CustomEvent<{ value: string }>).detail
+  this.handle.set(clean(value))
+  this.view.detectChanges()
+}
+```
+
+Without zone.js, Angular renders a signal change in a later task. A key that
+arrives before that task lands in the text from before your value, and the keys
+typed in between are lost. A barcode scanner, a password manager, and a test
+send keys that fast. `detectChanges()` renders the change before your handler
+returns.

package/content/browser-support.mdx

@@ -13,7 +13,7 @@ support in older browsers. Your browser needs every feature Helix uses.
 
 ## What we test
 
-We test in Chromium, through Playwright. The DOM specs run in it, and 83 pixel
+We test in Chromium, through Playwright. The DOM specs run in it, and the pixel
 baselines are captured in it, on Linux, with the network blocked.
 
 We do not run the tests in Firefox or Safari. The rest of this page lists the
@@ -27,9 +27,9 @@ something broken, please report it. Our tests would not have caught it.
 | Custom elements and shadow DOM | Everything |
 | `ElementInternals` | Form participation, and ARIA that has to cross a shadow boundary |
 | Popover API | Every overlay: menu, tooltip, select, combobox, dialog |
-| `light-dark()` | 156 declarations in the shipped stylesheets, 71 of them in the token layer |
+| `light-dark()` | Every color token, and each component color that differs between the modes |
 | `oklch()` | Every color in the system |
-| `:has()` | 11 rules, mostly relational styling of slotted content |
+| `:has()` | Relational styling, mostly of slotted content |
 | `@starting-style` | Entry transitions on overlays |
 | `:state()` | Every boolean state the library publishes: `open`, `checked`, `selected`, `invalid`, `read`, `has-label`, `settled`, `empty`, `controls` |
 | `CSS.highlights` | Filter-match highlighting, in `Command` and `Combobox` |

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

@@ -47,9 +47,10 @@ headless manifest carries the static, so you can find it there.
 **When a component renders another component, register both.**
 
 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.
+that is not defined. An unregistered custom element is an inert, unstyled inline
+box, so the panel shows every option with no list around them, and typing
+filters nothing. In development, the combobox says so once in the console and
+names the tag to define.
 
 [//]: # (renders)
 
@@ -89,7 +90,8 @@ everything those families render in turn. For example, `command` reaches
 **The elements you write inside a component are yours to register as well.**
 A select renders none of the options you write in it, so `acme-select` needs
 your `acme-option` registered beside it. In development, a component holding a
-child of its tier that nobody registered says so once, with the import to add.
+child of its tier that nobody registered says so once and names the tag to
+define.
 A listbox given `items` and a filter input given a `source` draw options of
 your tier from data, and those need `acme-option` registered too.
 
@@ -102,7 +104,7 @@ generated table is always current.
 
 ### A `:not(:defined)` rule
 
-`@fusion.dev/helix` ships an `elements.css` that hides each of its tags until
+`@fusion.dev/helix-styles` 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
@@ -115,26 +117,85 @@ acme-listbox:not(:defined) {
 }
 ```
 
-Use `visibility` so the page does not reflow when the definitions arrive.
+The rule hides each element until its definition loads, and the layout
+settles when the elements upgrade.
+
+### A rule that hides the `live` parts
+
+A `live` part is a live region. It holds words only a screen reader should
+read, such as how many options a filter left, and the headless tier draws it
+as ordinary text. Hide each one visually with a clip, which keeps it in the
+accessibility tree:
+
+```css
+acme-combobox::part(live),
+acme-combobox::part(listbox-live) {
+  block-size: 1px;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+}
+```
+
+`display: none` and `visibility: hidden` take a region out of the
+accessibility tree as well, and a screen reader then hears nothing. A
+component forwards the `live` part of a component it renders under a name of
+its own, such as `listbox-live` on Combobox. The styled tier hides every one
+of them.
 
 ### Typings for your tags
 
-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:
+Your typings come from a custom elements manifest of your package, written by
+`@custom-elements-manifest/analyzer`:
 
 ```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
+npx @custom-elements-manifest/analyzer analyze --litelement --dependencies \
+  --globs "src/**/*.ts"
 ```
 
-Then run a typings generator over it. Our own typings start from
+Each flag does one job, and the manifest is incomplete without either:
+
+- `--dependencies` reads the `custom-elements.json` each Helix package ships
+  and names in its `package.json`, so `acme-combobox` gets the members,
+  attributes, events, slots and parts it inherits from ours.
+- `--litelement` reads Lit's decorators, so the properties you declare with
+  `@property` are attributes too.
+
+Then run a typings generator over the manifest. 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.
+`acme-combobox` then include the members it inherits, as well as the ones you
+wrote.
+
+The generated file names Helix's event classes, such as
+`HelixBeforeChangeEvent`, without importing them. Add one line at its top that
+imports the names TypeScript reports as missing:
+
+```ts
+import type { HelixBeforeChangeEvent, HelixFilterEvent } from '@fusion.dev/helix-core'
+```
+
+Without that line, a project that sets `skipLibCheck` gets no error, and each
+of those event handlers is typed `any`.
+
+For a few tags in React, you can skip the generator. Each headless family
+publishes its props in `@fusion.dev/helix-headless/jsx`, and your tag takes
+them:
+
+```ts
+import type { HelixHeadlessComboboxProps } from '@fusion.dev/helix-headless/jsx'
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'acme-combobox': HelixHeadlessComboboxProps
+    }
+  }
+}
+```
+
+A subclass that adds properties joins its own to them with `&`.
 
 `@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
@@ -202,10 +263,12 @@ findings as data. The rules check what your components document and write:
 
 ### 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.
+`@fusion.dev/helix-headless` declares `"sideEffects": true`, because its
+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.
+Import each family from its own entry, such as
+`@fusion.dev/helix-headless/combobox`, so your bundle carries only the families
+you use.
 
 ### Documented parts
 

package/content/charting.mdx

@@ -169,6 +169,56 @@ 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.
 
+A cell holds a number when its whole text reads as one, such as `1200` or
+`-3.5`. A formatted number, such as `1,200` or `$1.2k`, is a gap. To chart a
+formatted cell, write its number in `data-value`:
+
+```html
+<tr><th>Q1</th><td data-value="1200">$1.2k</td><td data-value="800">$800</td></tr>
+```
+
+The chart reads `data-value` when a cell has one, and the cell's text otherwise.
+The table and the tooltip still show `$1.2k`.
+
+## Charts with many readings
+
+A chart builds what it can show, and that is bounded by its size. The readings
+themselves are read again each time the table or the data changes.
+
+- **Names on the axis.** `Line Chart`, `Area Chart`, and `Bar Chart` draw every
+  reading's name where every name fits. Where they do not, the chart draws a
+  regular share of them, and always the first and the last. Where every row
+  header holds a `<time>`, the names drawn start a period, such as the first
+  reading of each month or each year. Where the names are numbers in order,
+  such as years, they are round numbers. Other names are drawn every so many
+  readings, counted from the first. The chart works out the share again when it
+  is resized. The tooltip and the keys still say each reading's own name.
+- **Gridlines.** `gridlines="category"` rules the readings whose names are
+  drawn.
+- **Lines.** Where a line has more readings than the plot has pixels across, it
+  is drawn through the points those pixels can show: in each column of pixels,
+  the first reading, the lowest, the highest, and the last.
+- **Markers.** `markers` marks every reading, with one path for each series.
+- **Columns.** `Bar Chart` draws each column as an element while every column
+  and the space between two categories are at least a pixel wide. Past that, it
+  draws each series' columns as one path, each column of pixels as tall as the
+  tallest column in it, and draws the category the tooltip describes again over
+  them, at least two pixels thick.
+- **Points.** `Scatter Chart` draws each series' points as paths. Points that
+  overlap are drawn in separate groups, up to four deep, so each keeps its edge
+  and a cluster reads darker. The point the keys rest on is drawn again over
+  them.
+- **The table drawn from `data`.** Past a few hundred readings, the hidden table
+  holds one page of them at a time. Its markup gives a screen reader the number
+  of rows in the whole table and the place of each row, and the words after it
+  say which readings the page holds. Two buttons after it show the previous and
+  the next page. You press them with a screen reader as you read. They are left
+  out of the tab order, so the plot stays the chart's one tab stop. The keys on
+  the plot move through every reading.
+- **A table on the page.** A chart reads the whole table that `for` names, and
+  the table is part of your page, however many rows it has. Where the readings
+  are too many to put in the document, draw the chart from `data`.
+
 ## Series colors
 
 Helix has twenty-four series color tokens, in order, from

package/content/coding-agents.mdx

@@ -163,7 +163,8 @@ agent uses most:
 `helix scan`, `helix diagnostics --once`, and `helix theme audit` check what an
 agent wrote, and the MCP server runs the same checks.
 [Using Helix with an agent](./using-helix-with-an-agent#check-the-code-you-wrote)
-lists what each finds.
+lists what each finds, and [Diagnostics](./diagnostics) sets the checks up in
+your app and in CI.
 
 ## The index
 

package/content/color-modes.mdx

@@ -22,8 +22,8 @@ class, or a second copy of any value.
 Each token is written once, with its light and dark values in `light-dark()`.
 The `color-scheme` property alone decides which value applies. `color-scheme`
 inherits, so one property sets the mode for an element and everything inside
-it. The shipped stylesheets use `light-dark()` in 156 declarations, 71 of them
-in the token layer.
+it. A component that sets a color of its own for each mode uses `light-dark()`
+the same way.
 
 ## Set the mode
 

package/content/color.mdx

@@ -34,11 +34,20 @@ Choose a surface by where the element sits relative to the page. This is the
 choice people most often get wrong. See [Surfaces and
 separation](./surfaces-and-separation).
 
+A field is filled with `well`: 5% of `foreground` laid over whatever the field
+sits on, so its color depends on the surface under the field.
+
 ### Inks
 
 Inks are the colors that go on grounds. The base ink is `foreground`.
 
-- `foreground-muted` and `foreground-subtle` are for text that recedes.
+- `foreground-muted` is for text that recedes and is still read, such as a
+  placeholder, a hint, or a caption. The engine solves it to the contrast
+  target.
+- `foreground-subtle` recedes further. It is for marks that are not text, such
+  as a separator, a chevron, or a grip, and for the text of a disabled control.
+  It is a fixed step of the gray ramp, and the engine does not solve it, so its
+  contrast is not guaranteed. Use `foreground-muted` for text that is read.
 - Text on a filled color takes the ink named for that fill:
   - `foreground-on-primary` on `primary-surface`
   - `foreground-on-accent` on `accent-surface`
@@ -52,8 +61,16 @@ Intent colors show what something means.
   `-subtle` variants. With no brand color set, both are ink: near-black in
   light mode and near-white in dark mode.
 - `info`, `success`, `warning`, and `danger` are for status. Each has a
-  `-surface` and a `-surface-hover` variant for the tinted box that holds the
-  message.
+  `-surface` variant, the filled ground that carries `foreground-on-status`,
+  such as a danger button or a badge in a status tone, and a `-surface-hover`
+  variant for that fill under the pointer.
+
+### Rise and fall
+
+`rise` and `fall` color a value by which way it moved, such as a price. They
+are `success` and `danger` unless you set them. Mainland China, Taiwan, and
+Japan draw a rise in red, so a page for one of those markets swaps the two. See
+[Rise and fall colors](./localization#rise-and-fall-colors).
 
 ### Series
 
@@ -98,8 +115,21 @@ OKLCH lets the theme engine *solve* for a palette from your brand color. See
 
 The engine measures each ink against the ground it will be painted on. A brand
 color that already meets the target there is used as it is. For any other color,
-the engine searches for the lightness that meets the target. Every pair it
-produces meets the target.
+the engine searches for the lightness that meets the target. A pair that cannot
+meet its target, such as one with a color you pinned, is reported in
+`violations`.
+
+`foreground` and `foreground-muted` are also written in fields, so the engine
+solves them against the well over the page, a card, a raised surface, a dialog,
+and a sunken surface. The report names each of these grounds as the well over
+its surface, such as `color-well over color-surface`.
+
+`foreground-subtle` is the one ink the engine does not solve. The range of
+readable grays has room for one quiet ink, and `foreground-muted` is that ink, so
+`foreground-subtle` stays a fixed step of the stylesheet's gray ramp and its
+contrast is not guaranteed. A component paints its quiet text in
+`foreground-muted`, and keeps `foreground-subtle` for marks that are not text and
+for the text of a disabled control.
 
 The engine can solve only the pairs it knows about, so we check two things: