@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/accessibility.mdx

@@ -1,49 +1,62 @@
 ---
-description: What the library guarantees, what it cannot, and where the line is.
+description: What Helix components handle for you, what you handle, and what we do not test.
 section: Foundations
 title: Accessibility
 ---
 
 # Accessibility
 
-Some of accessibility is structural, and a component can own it. Some of it is
-about your content, and no component can. Knowing which is which is the
-difference between a page that is accessible and a page built out of accessible
-parts.
+Helix components handle the structural parts of accessibility, such as roles,
+keys, and focus. You handle the parts that depend on your content, such as
+names, heading order, and language. A page built from accessible components is
+accessible only when you also handle your parts.
 
-## What the library owns
+## What the components handle
 
-**Roles, states and keyboard interaction.** Every component implements the
-pattern its role implies: arrow keys move within a `Tabs`, a `Listbox` and a
-`Menu`, `Escape` dismisses an overlay, `Home` and `End` go to the ends, typing
-jumps to a match. None of that is yours to write.
+### Roles, states, and keyboard interaction
 
-**Focus, including trapping and restoring it.** A `Dialog` traps focus while
-open and returns it to whatever opened it. So do `Drawer` and the modal path of
-`Popover`.
+Every component implements the keyboard pattern for its role. You do not write
+any of it:
 
-**Contrast, by construction rather than by review.** The theme engine measures
-every foreground against the ground it is really painted on and solves for the
-target rather than checking afterwards. Every pairing is then re-measured on a
-laid-out page, including the great majority of rules that set an ink or a ground
-but not both, so a pairing nobody thought of is still checked. See [Surfaces and
+- Arrow keys move within `Tabs`, `Listbox`, and `Menu`.
+- `Escape` closes an overlay.
+- `Home` and `End` go to the first and last item.
+- Typing jumps to a matching item.
+
+### Focus
+
+A `Dialog` traps focus while it is open and returns focus to the element that
+opened it. `Drawer` and the modal mode of `Popover` do the same.
+
+### Contrast
+
+The theme engine measures each foreground color against the background it is
+actually drawn on. It solves for the contrast target when it computes your
+colors. Every pairing is then measured again on a laid-out page. That check
+includes the many rules that set only a text color or only a background, so a
+pairing nobody planned is still checked. See [Surfaces and
 separation](./surfaces-and-separation).
 
-**Reduced motion, per component.** Fifty-nine stylesheets answer
-`prefers-reduced-motion` individually, because they have to: the base layer's
-global rule is `*, *::before, *::after` in the document, and `*` does not cross
-a shadow boundary, so it reaches your prose and none of the components.
-A component that animates without answering fails the build.
+### Reduced motion
+
+Fifty-nine stylesheets respond to `prefers-reduced-motion` individually. Each
+component needs its own rule because the base layer's global rule is
+`*, *::before, *::after` in the document, and `*` does not cross a shadow
+boundary. That rule reaches your prose and none of the components. The build
+fails when a component animates without responding to `prefers-reduced-motion`.
+
+### Disabled controls
 
-**Disabled without disappearing.** `disabled` is mirrored to `aria-disabled`
-rather than removing the control from the accessibility tree, so a screen reader
-can still announce that the control exists and is currently off.
+`disabled` is mirrored to `aria-disabled`, and the control stays in the
+accessibility tree. A screen reader can still announce that the control exists
+and is turned off.
 
-## What you own
+## What you handle
 
-**Names.** A component can render a label; it cannot know what to call your
-thing. Every control takes `label`, and an icon-only control has nothing else to
-go on:
+### Names
+
+Every control takes `label`. A component renders the label you give it, and the
+words are yours to choose. An icon-only control has no other text to name it:
 
 ```html
 <helix-icon-button
@@ -52,66 +65,74 @@ go on:
 ></helix-icon-button>
 ```
 
-**`label` means a label and `aria-label` means a name.** They are not synonyms
-here. `label` renders visible text and names the control through it;
-`aria-label` names the control with nothing on screen. Reach for the second only
-when the page already makes the purpose plain, which is rarer than it feels.
+### `label` and `aria-label`
+
+`label` renders visible text and names the control through that text.
+`aria-label` names the control and shows nothing on screen. Use `aria-label`
+only when the page already makes the control's purpose plain. That case is less
+common than it seems.
+
+### Heading order
 
-**Heading order.** Components render the heading levels you give them, not
-levels they guess. A `Card` does not emit an `h2` on your behalf, because it
-cannot know what is above it.
+Components render the heading levels you give them. A `Card` does not add an
+`h2` for you, because the right level depends on the headings above the card.
 
-**Language and direction.** Set `lang` and `dir` on the document. Components use
-logical properties throughout, so a right-to-left document lays out correctly,
-but nothing infers the direction for you.
-See [Localization and RTL](./localization).
+### Language and direction
 
-**Live regions for your own updates.** The components announce their own state
-changes. A message from your application needs somewhere to be announced:
+Set `lang` and `dir` on the document. Components use logical properties
+throughout, so a right-to-left document lays out correctly. Helix does not
+detect the direction for you. See [Localization and RTL](./localization).
+
+### Live regions for your own updates
+
+Components announce their own state changes. To announce a message from your
+application, put it in an `Announcement`:
 
 ```html
 <helix-announcement tone="warning">Your trial ends on Friday.</helix-announcement>
 ```
 
-`Announcement` is always a polite live region, never assertive. `role="alert"`
-interrupts whatever is being read, which is right for something that appears
-mid-session and wrong for something that was in the served HTML: an assertive
-announcement would cut across a screen-reader user on every page load, before
-they had read anything. Politeness costs a moment and is never wrong.
+`Announcement` is always a polite live region. An assertive region, such as
+`role="alert"`, interrupts whatever the screen reader is reading. That suits a
+message that appears during a session. It does not suit a message in the served
+HTML, because an assertive announcement would interrupt a screen-reader user on
+every page load, before they had read anything. A polite announcement can arrive
+a moment later, and it is always safe to use.
 
-Note the distinction from `Callout`, which is a passage that interrupts a
-document and is read where it sits. Neither is a variant of the other.
+`Callout` is a different component. It is a passage that interrupts a document
+and is read where it sits. Neither component is a variant of the other.
 
 ## Two things the shadow boundary changes
 
-**IDREFs do not cross it.** `aria-labelledby` and `aria-describedby` inside a
-shadow root cannot resolve to an id in your document, and the reference is
-dropped silently rather than erroring. This is why every control renders its own
-label instead of being wrapped by one, and why wiring two components together by
-id does not work. See [Forms and validation](./forms).
+`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`.
 
-**`<label for>` cannot reach in either.** A `<label>` in your markup will not
-name a Helix control. Use the control's own `label`.
+When a relationship has to cross the boundary, the components use
+`ElementInternals` and element-reference properties. They are the only mechanism
+that works across the boundary. Use the same tools when your own components need
+such a relationship.
 
-Where a relationship genuinely has to cross the boundary, the components use
-`ElementInternals` and element-reference properties rather than ids, which is
-the only mechanism that works. If you need the same for your own composition,
-that is the tool.
+## Hide text visually
 
-## Hiding things correctly
+To hide text on screen and keep it for screen readers, add
+`data-hidden-visually`:
 
 ```html
 <span data-hidden-visually>Sorting by</span>
 ```
 
-The base layer's `[data-hidden-visually]` clips rather than using
-`display: none` or `visibility: hidden`, both of which take the element out of
-the accessibility tree entirely, which is the opposite of what visually-hidden
-text is for.
+The base layer's `[data-hidden-visually]` rule clips the element.
+`display: none` and `visibility: hidden` both remove the element from the
+accessibility tree, so they hide the text from screen readers too.
 
-## What is not covered
+## What we do not test
 
-The library is tested in Chromium, by automated specs and by pixel baselines. It
-is not run through a screen reader on every release, and the components'
-patterns follow the ARIA authoring practices rather than being certified against
-them. Where you find a real failure, it is a bug: report it.
+We test Helix in Chromium with automated specs and pixel baselines. We do not
+run it through a screen reader on every release. The component patterns follow
+the ARIA authoring practices, and they have not been certified against them. If
+you find a real failure, report it as a bug.

package/content/angular.mdx

@@ -1,5 +1,5 @@
 ---
-description: The schema Angular needs before it will compile an unknown tag.
+description: The schema Angular needs to compile Helix tags, and how to bind properties and events.
 parent: installation
 section: Getting started
 title: Angular
@@ -7,9 +7,9 @@ title: Angular
 
 # Angular
 
-Angular refuses to compile a template containing a tag it does not recognize.
-That is a good default and it is the one thing standing between you and working
-Helix components.
+Angular does not compile a template that contains a tag it does not recognize.
+To use Helix components, add `CUSTOM_ELEMENTS_SCHEMA` to the components that
+render them.
 
 ```ts
 import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core'
@@ -22,11 +22,12 @@ import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core'
 export class SaveButton {}
 ```
 
-Declare it on the components that use Helix rather than globally if you can.
-`CUSTOM_ELEMENTS_SCHEMA` switches off unknown-element checking for the whole
-template it is on, so scoping it keeps the check for your own typos.
+If you can, declare the schema only on the components that use Helix.
+`CUSTOM_ELEMENTS_SCHEMA` turns off unknown-element checking for the whole
+template it is on. A narrow scope keeps that check, which catches your own
+typos, in your other components.
 
-## Binding
+## Bind properties and events
 
 ```html
 <helix-input
@@ -35,26 +36,27 @@ template it is on, so scoping it keeps the check for your own typos.
 />
 ```
 
-`[prop]` sets a property, which is what a non-string value needs, and `(event)`
-binds with `addEventListener`, so the event name is its own.
+`[prop]` sets a property, which a value that is not a string needs. `(event)`
+binds with `addEventListener`, so use the event's own name.
 
-**Do not use `attr.` for a stateful property.** `[attr.value]="name"` writes
-the attribute, which seeds the control and is then out of date the moment a
-reader types; the property is the live channel.
+**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.
 
 ## No typings ship for Angular
 
-There is no `angular.d.ts` in the package. `CUSTOM_ELEMENTS_SCHEMA` turns off
-the checking that typings would feed, so a generated file would describe types
-Angular has already agreed not to enforce. The manifest is published as
-`@fusion.dev/helix/custom-elements.json` if you want to generate something for your
-own codebase from it.
+The package has no `angular.d.ts`. `CUSTOM_ELEMENTS_SCHEMA` turns off the
+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.
 
-The practical consequence is that a misspelled property fails silently here
-where it is a compile error in React, Vue and Svelte. Worth a note in review.
+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.
 
-## Taking a decision
+## Refuse a change
 
-`value`, `open`, `checked` and `active` are seeds: the element applies its own
-changes from there. To take one decision, listen for the `helix-before-*` event
-and call `preventDefault()`. See [State and control](./state-and-control).
+`value`, `open`, `checked`, and `active` are seeds. The element starts with the
+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).

package/content/browser-support.mdx

@@ -1,5 +1,5 @@
 ---
-description: The platform features this is built on, and what is actually tested.
+description: The browser features Helix uses, and the browser we test in.
 order: 5
 section: Getting started
 title: Browser support
@@ -7,21 +7,20 @@ title: Browser support
 
 # Browser support
 
-Helix is built on the platform rather than on a compatibility layer. There is no
-polyfill story, no transpiled fallback, and no configuration that trades
-features for reach: what the library needs is what your browser has to have.
+Helix uses browser features directly, with no compatibility layer. It has no
+polyfills, no transpiled fallback, and no setting that trades features for
+support in older browsers. Your browser needs every feature Helix uses.
 
-## What is tested
+## What we test
 
-**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 83 pixel
 baselines are captured in it, on Linux, with the network blocked.
 
-That is the honest extent of it. Everything below is a statement about which
-platform features the library uses, not a claim that we run the suite in Firefox
-and Safari. If you ship Helix to those and find something broken, that is a bug
-report we want, and it is not one we would have caught.
+We do not run the tests in Firefox or Safari. The rest of this page lists the
+browser features Helix uses. If you ship Helix to Firefox or Safari and find
+something broken, please report it. Our tests would not have caught it.
 
-## What the library uses
+## Browser features Helix uses
 
 | Feature | Where |
 |---|---|
@@ -35,55 +34,59 @@ report we want, and it is not one we would have caught.
 | `: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` |
 
-Positioning is `@floating-ui/dom` rather than CSS anchor positioning, which is a
-deliberate choice and the one place the library takes a dependency instead of
-the platform: anchor positioning is not yet available everywhere the rest of
-this list is.
-
-## What decides your floor
-
-**`light-dark()` and the Popover API.** Everything else on that list has been
-available longer. If you need to know whether a browser can run Helix, those are
-the two to check, because they are the newest things the library assumes and
-they are load-bearing: the first is how every token expresses both color modes
-in one declaration, and the second is how every overlay is drawn in the top
-layer.
-
-Chromium 132 has both and still misses two things a page's stylesheet can say
-through `::part()`, measured 15 Sep 2026: it ignores a range input's
-`::-webkit-slider-thumb` and `::-webkit-slider-runnable-track` after a part, and
-it looks for the `@keyframes` a `::part()` rule names inside the component's
-shadow root, so no animation starts; the headless examples use neither.
-
-`:state()` is the third and is deliberately not with them, because it does
-degrade: a component that cannot record a state keeps whatever its resting rule
-draws, so a checkbox is drawn unchecked rather than drawn wrong or not at all.
-It is feature-tested at the one place that records any of them.
-
-Neither degrades usefully. A browser without `light-dark()` gets no color at
-all rather than one mode; a browser without popover gets overlays that render in
-flow. This is why there is no support table with a fallback column: there is no
-partial mode to be in.
-
-## `CSS.highlights` is the one exception
-
-`Command` and `Combobox` highlight the matched substring in their filtered
-results using the CSS Custom Highlight API. It is the least widely available
-thing here, and it is the only one that degrades gracefully: without it the
-results still filter, sort and select correctly, and the match is simply not
+Positioning uses `@floating-ui/dom`. We chose this on purpose, and it is the one
+place Helix takes a dependency for something the browser could do. CSS anchor
+positioning is not yet available in every browser that has the rest of these
+features.
+
+## Which features set the minimum browser
+
+**Check for `light-dark()` and the Popover API.** They are the newest features
+Helix requires, and everything else in the table has been available longer.
+Helix depends on both. Every token uses `light-dark()` to set both color modes
+in one declaration. Every overlay uses the Popover API to draw in the top layer.
+
+Neither one has a useful fallback:
+
+- A browser without `light-dark()` shows no color at all.
+- A browser without the Popover API renders overlays in the page flow.
+
+For that reason, this page has no support table with a fallback column. Helix
+has no partial mode.
+
+Chromium 132 has both features. We measured on September 15, 2026 that it
+does not support two things your stylesheet can do through `::part()`:
+
+- It ignores a range input's `::-webkit-slider-thumb` and
+  `::-webkit-slider-runnable-track` after a part.
+- It looks for the `@keyframes` that a `::part()` rule names inside the
+  component's shadow root, so no animation starts.
+
+The headless examples use neither.
+
+`:state()` is the third newest feature. It does not set the minimum browser,
+because components still work without it. A component that cannot record a
+state keeps the look of its resting rule, so a checkbox is drawn unchecked.
+Helix tests for `:state()` support in the one place that records states.
+
+## Browsers without `CSS.highlights`
+
+`Command` and `Combobox` use the CSS Custom Highlight API to highlight the
+matched text in their filtered results. It is the least widely available
+feature Helix uses, and it is the only one that degrades gracefully. Without it,
+the results still filter, sort, and select correctly, and the match is not
 highlighted.
 
-Nothing else in the library reads it.
+Nothing else in Helix uses it.
 
-## No IE, no polyfills, no build flag
+## Older browsers
 
-There is no `browserslist` and no transpilation target, which is a decision
-rather than an oversight. A design system whose components are
-custom elements cannot be shipped to a browser without custom elements, and
-everything else on the list above arrived in the same generation of browsers
-that shipped those.
+Helix does not support Internet Explorer and uses no polyfills. It has no
+`browserslist`, no transpilation target, and no build flag for older browsers.
+We decided this on purpose. Components that are custom elements cannot run in a
+browser without custom elements, and every other feature in the table arrived in
+the same generation of browsers.
 
-If you need to support something older, the honest answer is the base layer:
-`@fusion.dev/helix-styles` is plain CSS with no JavaScript, and a page built from its
-recipes works considerably further back than the components do.
-See [Without a bundler](./without-a-bundler).
+To support an older browser, use the base layer. `@fusion.dev/helix-styles` is
+plain CSS with no JavaScript. Markup built from its recipes works in much older
+browsers than the components do. See [Without a bundler](./without-a-bundler).