@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/composition.mdx

@@ -1,64 +1,68 @@
 ---
-description: Families, parts and groups, and which to reach for.
+description: How Helix is organized into families, parts, and groups, and which one to use.
 section: Essentials
 title: Composition
 ---
 
 # Composition
 
-Helix has families, parts and groups, and they are not stylistic choices. Each
-answers a different question, and knowing which you are looking at tells you
-what to import and what to write.
+Helix components come in families, parts, and groups. Each kind has a different
+purpose. When you know which kind you are looking at, you know what to import
+and what to write.
 
-## Namespaces mean composition
+## A namespace means one component goes inside another
 
-`Tabs.Root` contains `Tabs.Tab`. The namespace says *this goes inside that*.
+`Tabs.Root` contains `Tabs.Tab`. A namespace means the part goes inside the
+family's root.
 
-It never says *this is a version of that*. An icon-only button is not a part of
-`Button`, so `IconButton` is top-level. The rule falls out of one line:
+A namespace never marks a version of a component. An icon-only button is its
+own component, so `IconButton` is top-level. One rule decides this:
 
 > Variants are props. Alternatives are separate components.
 
-A button that is filled instead of outlined is the same component with a
-different `emphasis`. A button that holds only an icon has a different
-accessible-name requirement and a different shape, so it is its own component.
+A filled button and an outlined button are the same component with a different
+`emphasis`. A button that holds only an icon has different requirements for its
+accessible name and a different shape, so it is its own component.
 
-## When a region becomes an element
+## When a region is an element and when it is a slot
 
-When it has behavior, state or API. Otherwise it is a slot.
+A region is an element when it has behavior, state, or an API. Otherwise it is a
+slot.
 
-`Card`'s header, body and footer carried none of the three, so five elements
-became one and a title became a real `<h2>` the consumer writes. `Tabs.Tab`,
-`Select.Option` and `Accordion.Item` do carry state, so they stay elements.
+`Card`'s header, body, and footer had none of the three. Five elements became
+one, and a title became a real `<h2>` that you write. `Tabs.Tab`,
+`Select.Option`, and `Accordion.Item` have state, so they stay elements.
 
-**An empty region still costs layout.** A `<slot>` is `display: contents`, so an unassigned one generates no
-box: no grid row, no flex item, no gap. A wrapper generates one either way.
-Measured on Card with identical content: wrappers present but empty rendered
-85px against an ideal of 53px. Bare slots rendered 53px with no hiding logic at
-all.
+An empty wrapper element still takes up layout space. A `<slot>` is
+`display: contents`, so an unassigned slot generates no box. It adds no grid
+row, no flex item, and no gap. A wrapper generates a box either way. We measured
+`Card` with identical content. With empty wrappers present, it rendered at 85px,
+and the ideal is 53px. With bare slots, it rendered at 53px with no hiding logic
+at all.
 
-## When a group is a part
+## When a group is a part of a family
 
-The test is whether the group reports a form value.
+A group is a part of a family when it reports a form value.
 
-**`Radio.Group` and `Toggle.Group` do.** They own the `name`, the `value` and
-the validity, and a lone radio is not a control at all: it is an answer to one.
-The group is what the family is *about*, so it is a part of it, and the member
-has nowhere else to be.
+`Radio.Group` and `Toggle.Group` report a form value. They own the `name`, the
+`value`, and the validity. A single radio is an answer, and the group is the
+control it answers. The family is about the group, so the group is a part of the
+family, and the member belongs nowhere else.
 
-**`Checkbox Group` and `Button Group` do not.** Neither calls `setFormValue`.
-Each checkbox is form-associated and submits itself; the group adds
-`role="group"`, a shared name, and one place to read the set. A button needs no
-group at all. Both are their own families, because their members are complete
-controls that the family does not need the group to explain.
+`Checkbox Group` and `Button Group` do not report a form value. Neither calls
+`setFormValue`. Each checkbox is form-associated and submits itself. The group
+adds `role="group"`, a shared name, and one place to read the set. A button
+needs no group at all. Both groups are their own families, because their members
+are complete controls without the group.
 
-A container holding mixed content is a family for the same reason. `Toolbar`
-holds buttons, dropdowns and inputs, and is about none of them.
+A container that holds mixed content is its own family for the same reason.
+`Toolbar` holds buttons, dropdowns, and inputs, so it is not a part of any of
+their families.
 
-## A content property is its slot's fallback
+## A content property is the fallback for its slot
 
-Where a property carries content rather than configuration, it is the fallback
-content of a slot of the same name, never a second thing rendered beside it.
+A property that holds content, such as a tooltip's text, is the fallback content
+for a slot of the same name. Helix never renders both.
 
 ```html
 <!-- The property -->
@@ -70,21 +74,21 @@ content of a slot of the same name, never a second thing rendered beside it.
 </helix-tooltip>
 ```
 
-Text stays an attribute, because that is what most tooltips and most avatars
-hold. Anything richer replaces it by being slotted. Both can never show at once,
-and no component has to detect which you did.
+Text stays an attribute, because most tooltips and most avatars hold only text.
+To use richer content, put it in the slot, and it replaces the attribute. The
+two never show at once, so no component has to check which one you used.
 
-One trap: **a whitespace-only text node is assigned to the default slot and
-defeats its fallback.** A newline between the tags is enough. That is
-why some examples close on the same line they open.
+A text node that holds only whitespace is assigned to the default slot and hides
+its fallback. A newline between the tags is enough. For this reason, some
+examples put the closing tag on the same line as the opening tag.
 
-## Width comes from the layout
+## Set a button's width with the layout
 
-There is no `width` or `fill` property on a button, for the same reason there is
-no `size` one: how wide a control is says something about the region it is in.
+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 already stretches in a column flex or a grid, because that is what a
-stretch-aligned parent does to its children:
+A button already stretches in a column flex or a grid, because a stretch-aligned
+parent stretches its children:
 
 ```html
 <helix-flex direction="column">
@@ -95,7 +99,7 @@ stretch-aligned parent does to its children:
 </helix-flex>
 ```
 
-To make one hug its label instead, tell the layout:
+To make a button only as wide as its label, set that on the layout:
 
 ```css
 .hug {
@@ -107,13 +111,13 @@ To make one hug its label instead, tell the layout:
 <helix-button class="hug">Hugs its label</helix-button>
 ```
 
-The default surprises people: dropping a button into a column makes it full
-width, and the instinct is to look for a property that turns that off.
+This default can surprise you. A button in a column is full width, and you might
+look for a property to turn that off. The layout controls it.
 
-**A fixed width is a different question, and it belongs to your site.** A
-marketing page whose hero buttons are all the same width is a real and reusable
-practice, but the number is a fact about that page's design, not about buttons.
-Name it once where your other page constants live:
+**A fixed width belongs to your site's styles.** A marketing page whose hero
+buttons all share one width is a common and reusable practice. The number is
+part of that page's design, so it does not belong to the button component. Name
+it once, where your other page constants are defined:
 
 ```css
 :root {
@@ -125,12 +129,12 @@ Name it once where your other page constants live:
 }
 ```
 
-The same reasoning puts a hero's type size outside the component scale: a
-marketing hero is not a component, so its measurements are the site's own.
+For the same reason, a hero's type size is outside the component scale. A
+marketing hero is not a component, so its measurements belong to your site.
 
-## One property per intent
+## Name a field control with `label` or `aria-label`
 
-Every field control names itself the same way, and there are exactly two cases.
+Every field control is named the same way, and there are two cases:
 
 ```html
 <helix-input label="Files"></helix-input>       <!-- a visible label -->
@@ -138,34 +142,32 @@ Every field control names itself the same way, and there are exactly two cases.
 <helix-input></helix-input>                     <!-- unnamed. avoid -->
 ```
 
-`label` means a label. `aria-label` means a name. Neither means a control a
-screen reader announces as "edit text", which is almost never what you want.
-If the page already makes the purpose plain, that is the `aria-label` case, not
-the empty case.
+`label` gives the control a visible label. `aria-label` gives it a name and
+draws nothing. With neither, a screen reader announces the control as "edit
+text", which is almost never what you want. If the page already makes the
+purpose plain, use `aria-label`. Do not leave the control unnamed.
 
-**`aria-label` works here because the component forwards it**, which is not true
-of custom elements in general. A custom element
-cannot delegate a label to the control inside its shadow root: an `aria-label`
-you write on the host sits on a wrapper and never reaches the `<input>` that
-actually takes focus. Measured on this library before it was fixed, the inner
-input came back with no label and no name at all.
+`aria-label` works on a Helix field because the component forwards it. Most
+custom elements do not. A custom element cannot delegate a label to the control
+inside its shadow root. An `aria-label` you write on the host stays on a wrapper
+and never reaches the `<input>` that takes focus. We measured this in Helix
+before we fixed it: the inner input had no label and no name at all.
 
-So the field renders the label and clips it, and the name arrives through the
-same `<label for>` a visible one does.
+The field renders the label and clips it. The name then reaches the input
+through the same `<label for>` that a visible label uses.
 
-There used to be a `hide-label` boolean beside `label`. It is gone: one
-attribute supplying a label and a second saying not to show it is the absence of
-the first, spelled twice.
+`hide-label` was a boolean beside `label`, and we removed it. Setting a label
+and then a second attribute to hide it is the same as having no visible label.
 
-## Shared behavior becomes its own family
+## Shared behavior is its own family
 
-`Option`, `Listbox` and `Select` are three families rather than one because the
-keyboard, the filtering, the multi-select rules and the active-item tracking
-should be written once. `Select` renders a `Listbox` internally; a future
-combobox will; a command palette would.
+`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.
 
-The same reasoning made `DrilldownController`: `Menu` had held a page stack and
-derived its rows since it was written, and none of that was about menus. `Menu`
-and `Drilldown` share it now.
+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
+was specific to menus. `Menu` and `Drilldown` now share it.
 
-If you are about to write the second copy of something, that is the signal.
+If you are about to write a second copy of some behavior, make it shared.

package/content/elevation-and-material.mdx

@@ -1,5 +1,5 @@
 ---
-description: Five layers, four shadows, and the glass the material tokens make possible.
+description: The layer, shadow, and material tokens for stacking, lifting, and translucent surfaces.
 section: Foundations
 title: Elevation and material
 ---
@@ -21,9 +21,9 @@ title: Elevation and material
 
 [//]: # (/tokens)
 
-Five, named after what lives at each rather than numbered. A numbered scale
-invites `z-index: 1001`, and the number nobody can justify is how stacking
-context bugs start.
+The five main layers are named after what sits at each one. A numbered scale
+leads to values such as `z-index: 1001` that nobody can explain, and those
+values cause stacking context bugs.
 
 | Layer | What is at it |
 |---|---|
@@ -33,10 +33,13 @@ context bugs start.
 | `overlay` | Menus, dialogs, popovers, tooltips |
 | `toast` | Above everything, including a modal |
 
-**Most overlays do not need these**, because they use the popover API and render
-in the browser's top layer, which is above every z-index by construction. The
-tokens are for the cases the top layer does not cover: your own sticky header,
-your own dragged element, and anything that has to sit between two of ours.
+**Most overlays do not need these tokens.** They use the popover API and render
+in the browser's top layer, which is always above every z-index. Use the tokens
+for the cases the top layer does not cover:
+
+- your own sticky header
+- your own dragged element
+- anything that has to sit between two of our layers
 
 ## Shadows
 
@@ -53,41 +56,41 @@ your own dragged element, and anything that has to sit between two of ours.
 
 [//]: # (/tokens)
 
-The first four are the values. The last two are the *decision*, and they are
-what a theme sets to make the system shadow-first or border-first. See [Surfaces
-and separation](./surfaces-and-separation).
+The first four are the values. The last two are policy tokens. A theme sets
+them to make your interface shadow-first or border-first. See [Surfaces and
+separation](./surfaces-and-separation).
 
 ## Material
 
-Eight tokens describing translucency rather than color:
+Eight tokens describe translucency:
 
 [//]: # (tokens:material)
 
 | Token | Value | For |
 | --- | --- | --- |
-| `--helix-material-backdrop` | `blur(var(--helix-material-blur-md)) saturate(1.5)` | The wash behind a modal. |
+| `--helix-material-backdrop` | `blur(var(--helix-material-blur-md)) saturate(1.5)` | The tint behind a modal. |
 | `--helix-material-opacity` | `1` | How opaque a translucent surface is. |
 | `--helix-material-blur-sm` | `8px` | The lightest backdrop blur. |
-| `--helix-material-blur-md` | `16px` | The backdrop blur a modal takes. |
+| `--helix-material-blur-md` | `16px` | The backdrop blur behind a modal. |
 | `--helix-material-blur-lg` | `32px` | The heaviest backdrop blur. |
-| `--helix-material-translucent` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 30%, transparent)` | The translucent ground, for a surface that admits what is behind it. |
-| `--helix-material-translucent-strong` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 88%, transparent)` | The heavier translucent ground, for one that admits less. |
-| `--helix-material-border` | `light-dark(color-mix(in oklab, oklch(0.15 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258)) 14%, transparent), color-mix(in oklab, oklch(1 0 0) 12%, transparent))` | The edge a translucent surface needs to have any at all. |
+| `--helix-material-translucent` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 30%, transparent)` | The translucent background, for a surface that shows what is behind it. |
+| `--helix-material-translucent-strong` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 88%, transparent)` | The stronger translucent background, for a surface that shows less of what is behind it. |
+| `--helix-material-border` | `light-dark(color-mix(in oklab, oklch(0.15 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258)) 14%, transparent), color-mix(in oklab, oklch(1 0 0) 12%, transparent))` | The border a translucent surface needs to keep a visible edge. |
 
 [//]: # (/tokens)
 
-These are what the `material` axis renders: `frosted`, `glass` and `transparent`
-are three points of one optical language, and they are an axis of their own
-rather than values of `emphasis`, because a panel can be glass *and* outlined
-and two things that can be true at once are two axes. See [Visual
+The `material` axis draws its three values, `frosted`, `glass`, and
+`transparent`, with these tokens. Material is an axis of its own, separate from
+`emphasis`, because a panel can be glass and outlined at the same time. Two
+properties that can apply at once belong on two axes. See [Visual
 axes](./visual-axes).
 
-**Blur is expensive and is the one thing here worth being deliberate about.** A
-`backdrop-filter` forces the compositor to re-read what is behind the element on
-every frame it moves. A frosted header that is always on screen pays that
-continuously. Reach for `translucent` without the blur when the effect is about
-depth rather than about the texture.
+**Use blur with care, because it is expensive.** A `backdrop-filter` makes the
+compositor read what is behind the element again on every frame the element
+moves. A frosted header that is always on screen pays that cost all the time.
+When you want depth without the frosted texture, use `translucent` without the
+blur.
 
-**`material-border` is not decoration.** A translucent surface takes its color
-from what is behind it, so on a busy background it has no edge at all. The
-border token is what keeps it a shape.
+A translucent surface takes its color from what is behind it, so on a busy
+background it has no visible edge. `material-border` gives it one, so it keeps
+its shape.

package/content/events.mdx

@@ -1,12 +1,13 @@
 ---
-description: The request and the notification, why one name is prefixed and the other is not.
+description: The two events each state change sends, and why one name has a prefix and the other does not.
 section: Essentials
 title: Events
 ---
 
 # Events
 
-**Every state change is announced twice, and the two are for different people.**
+Each state change sends two events. The first is a request that you can cancel.
+The second is a notification that the change happened.
 
 ```ts
 // The request. Cancelable, carries what is being proposed, and fires before
@@ -24,59 +25,67 @@ element.addEventListener('change', (event) => {
 })
 ```
 
-Most consumers want the second. Bind `onChange` in React or `onchange=` in HTML
-and read the target, exactly as you would from an `<input>`. Reach for the
-prefixed one when you mean to refuse.
+Most of the time you need the notification. Bind `onChange` in React or
+`onchange=` in HTML and read the target, as you would for an `<input>`. Use the
+prefixed event when you want to cancel the change.
 
-The class exists rather than a bare `CustomEvent` for three reasons, all about
-the type reaching you: the class name is in the manifest, which is what lets the
-framework typings emit a typed callback instead of `(detail: unknown)`; the
-package augments `HTMLElementEventMap`, which types `addEventListener` for
-people writing plain HTML; and the name lives on the class, so a dispatch and a
-listener cannot disagree about the string.
+Each event has its own class. The class gets the event's type to you in three
+ways:
 
-## Why the request is prefixed and the notification is not
+- The class name is in the manifest, so the framework typings can emit a typed
+  callback. A bare `CustomEvent` would give `(detail: unknown)`.
+- The package augments `HTMLElementEventMap`, which types `addEventListener`
+  when you write plain HTML.
+- The name is defined on the class, so a dispatch and a listener always use the
+  same string.
 
-**Retargeting.** An event dispatched inside a shadow root is retargeted to look
-like it came from the host, so a bare `input` from a `<helix-input>` is
-indistinguishable from the inner control's own. Prefixed, it cannot be mistaken
-for either.
+## Why the request has a prefix and the notification does not
 
-**React's claimed verbs.** React's synthetic system owns `change`, `input`,
-`submit`, `copy`, `focus` and the rest, and a prop matching one of those is
-wired to the native event instead. `onhelix-before-change` matches none of them
-and reaches us, which is exactly what a request needs.
+### Retargeting
 
-**And the notification wants the opposite.** It is not prefixed precisely
-because React claims the verb: `onChange` on a Helix element goes through the
-synthetic system to the native `change` the element sends, which is why the
-ordinary path costs a consumer nothing to learn.
+An event dispatched inside a shadow root is retargeted so that it appears to
+come from the host. A bare `input` from a `<helix-input>` would look the same
+as the `input` from the control inside it. A prefixed event cannot be mistaken
+for either one.
 
-**The type map is global.** `HTMLElementEventMap` is shared with every element
-in your application. Our classes extend `Event`, so an entry named `select`
-would not fail to compile: it would silently retype
-`textarea.addEventListener('select', …)` as carrying our detail, which at
-runtime is `undefined`. Measured. An unprefixed name is not a collision we would
-notice, it is one you would.
+### React's event names
 
-## Propagation follows the event's role
+React's synthetic event system handles `change`, `input`, `submit`, `copy`,
+`focus`, and its other event names. A prop that matches one of those names is
+connected to the native event of that name. `onhelix-before-change` matches none
+of them, so it reaches our event. A request needs exactly that.
 
-**Lifecycle does not bubble and is not composed.** `helix-before-open` and
-`helix-before-close`. Overlays nest, and an inner one's lifecycle must never reach the
-outer one that contains it: a menu closing inside a dialog is not the dialog
-closing.
+### The notification uses the native name
 
-**Coordination bubbles and is composed.** `helix-select`, `helix-dismiss`,
-`helix-before-change`. A parent, or a router, can intercept one across a shadow
-boundary, which is what makes a `Tree` usable as navigation.
+The notification has no prefix for the same reason. `onChange` on a Helix
+element goes through React's synthetic system to the native `change` event the
+element sends. You use it the way you already use it on any input.
 
-If you are listening on a container and hearing nothing, the event is probably a
-lifecycle one and the listener belongs on the element itself.
+### The type map is global
 
-## Canceling
+`HTMLElementEventMap` is shared by every element in your application. Our event
+classes extend `Event`, so an entry named `select` would still compile. It would
+silently retype `textarea.addEventListener('select', …)` as carrying our detail,
+which is `undefined` at runtime. We measured this. We would not see a collision
+from an unprefixed name, and you would.
 
-The events that precede a state change are cancelable, and that is the only way
-to refuse one:
+## Which events bubble
+
+- **Lifecycle events** do not bubble and are not composed. These are
+  `helix-before-open` and `helix-before-close`. Overlays nest, and an inner
+  overlay's lifecycle must never reach the outer overlay that contains it. A
+  menu that closes inside a dialog does not close the dialog.
+- **Coordination events** bubble and are composed. These are `helix-select`,
+  `helix-dismiss`, and `helix-before-change`. A parent or a router can intercept
+  them across a shadow boundary, so you can use a `Tree` as navigation.
+
+If you listen on a container and receive nothing, the event is probably a
+lifecycle event. Add the listener to the element itself.
+
+## Cancel a change
+
+You can cancel the events sent before a state change. Canceling is the only way
+to stop the change:
 
 ```ts
 dialog.addEventListener('helix-before-close', (event) => {
@@ -86,18 +95,18 @@ dialog.addEventListener('helix-before-close', (event) => {
 })
 ```
 
-Every dispatched event is held to a declaration and every declaration to a
-dispatch, so an event you can listen for is an event that is documented.
+Every dispatched event is checked against a declaration, and every declaration
+against a dispatch, so every event you can listen for is documented.
 
-## The set
+## Helix events
 
-| Event | Roughly |
+| Event | Meaning |
 |---|---|
-| `helix-before-change` | A value about to move, refusable |
-| `helix-before-toggle` | A checked state about to flip, refusable |
-| `helix-before-open`, `helix-before-close` | An open state about to move, refusable |
-| `helix-select` | An item chosen from a set |
-| `helix-dismiss` | The reader asked for something to go away |
+| `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-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 |
 | `helix-filter` | A query changed in a filtering control |
 | `helix-navigate` | A component is about to navigate |
@@ -105,21 +114,24 @@ dispatch, so an event you can listen for is an event that is documented.
 | `helix-caret` | The cursor moved in a text control |
 | `helix-complete` | A control that fills up has filled |
 | `helix-create` | A new item was made from a query |
-| `helix-console` | The sandbox relaying a log |
+| `helix-console` | The sandbox passes on a log message |
 | `helix-tour-ask`, `helix-sample-start`, `helix-sample-end` | Tour and color sampling |
 
-And the native ones every stateful component sends once the change has landed:
-`input` and `change` on a value control, `toggle` on anything that opens,
-carrying `newState` and `oldState` the way `<details>` does, `close` on a dialog,
-and `load` and `error` on an image.
+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
+- `close` on a dialog
+- `load` and `error` on an image
 
-Each component's page lists the events it actually dispatches, with the class
-and the detail.
+Each component's page lists the events it dispatches, with the class and the
+detail.
 
-## In a framework
+## Events in a framework
 
-A native event is `onChange`, `onInput` or `onToggle`, which is what React and
-every framework already understand. A prefixed one is `on` and the name,
-verbatim: `onhelix-before-change`. Nothing strips the prefix and nothing
-camel-cases it, which is React's own behavior rather than a convention here. See [React](./react), [Vue](./vue) and
-[Svelte](./svelte).
+Native events use their usual props, such as `onChange`, `onInput`, and
+`onToggle`, which every framework already understands. A prefixed event uses
+`on` followed by the exact name, such as `onhelix-before-change`. Nothing
+removes the prefix or converts it to camel case. That is React's own behavior.
+See [React](./react), [Vue](./vue), and [Svelte](./svelte).