@fusion.dev/helix-headless 0.105.0 → 0.106.0

package/dist/time-picker/root/time-picker-root.d.ts

@@ -4,40 +4,31 @@ import '../../listbox/index.js';
 import '../../option/index.js';
 declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
- * @summary Picks a time, from a list of them.
+ * @summary A control for choosing a time from a list or from wheels.
  *
  * @description
- * **A list rather than three wheels**, and the reason is what a list already
- * is. `Listbox` brings the keyboard, the typeahead, the scroll into view and
- * the announcement of a set of options, and a time at a step is a set of
- * options. Three little wheels for hours, minutes and a meridiem are three
- * controls to build, three to test, and a tab stop each for something a reader
- * answers once.
+ * Shows the times at each `step` as a `Listbox`, which provides the keyboard
+ * behavior, typeahead, scrolling into view, and announcements for a set of
+ * options. `variant="wheels"` shows a column each for the hour, the minute, and
+ * the meridiem.
  *
- * **A step is what makes it a list at all.** Fifteen minutes is ninety-six rows,
- * which a reader scrolls or types into; one minute is one thousand four hundred
- * and forty, which is a listbox in name only. So the list is for the times a
- * product actually offers, and arbitrary times are the field's job in Input
- * Time, the same division Date Input draws between typing a date and using the
- * calendar.
+ * The step keeps the list usable. At the default of 15 minutes a day is 96
+ * rows, which people can scroll or type into. At 1 minute it is 1,440. Use the
+ * list for the times your product offers, and Time Input for any time, the same
+ * way Date Input separates typing a date from picking one on the calendar.
  *
- * **The value is `HH:mm` on a twenty-four hour clock, always.** That is what a
- * form submits and what `min` and `max` compare against, and it sorts as a
- * string, which is the whole reason the shape is that one. What each row *says*
- * is the reader's own convention, from `Intl`.
+ * The value is always `HH:mm` on a 24-hour clock. A form submits that shape,
+ * `min` and `max` compare against it, and it sorts as a string. Each row's text
+ * follows the person's own conventions, from `Intl`.
  *
- * **The chosen row is marked in the markup, not worked out on upgrade.** The
- * listbox is handed the answer as `.value`, and lit-ssr serializes no property
- * binding, so a served `value="09:30"` shipped ninety-six rows with nothing on
- * any of them saying which one it was: the mark arrived when the listbox
- * upgraded and ran `place`. So each option is given `selected` as well, which
- * is an attribute binding and does serve, and which the listbox then agrees
- * with rather than fights, `place` writing the same answer from the same value.
- * `selected` is the declaration a consumer writes on `Option` anywhere else in
- * the library, and Date Picker expresses its own choice as markup for the same
- * reason: a picker whose answer is invisible until a script runs is a picker
- * whose answer is not served at all. Both readings do it, the list and the
- * wheels, a wheel being a listbox like the list is.
+ * The chosen row is marked in the served markup. The listbox gets the answer as
+ * `.value`, and Lit SSR serializes no property binding, so without more the 96
+ * served rows would carry no mark until the listbox upgrades and runs `place`.
+ * Each option also gets `selected`, an attribute binding that does serialize,
+ * and `place` then writes the same answer from the same value. This is the same
+ * `selected` you write on `Option` elsewhere in Helix, and Date Picker marks
+ * its choice in markup for the same reason. The list and the wheels both do
+ * this, because each wheel is also a listbox.
  *
  * @since 0.1.0
  * @status stable
@@ -45,47 +36,47 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * @aliases Time, TimeList
  * @documentation https://fusion.dev/helix/components/time-picker
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes, and cancelable. Canceling it keeps the current time.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart column - One of them.
- * @csspart column-empty - Shown when a filter has hidden everything.
- * @csspart column-feedback - What is wrong with it.
- * @csspart column-filter-icon - The mark beside that field.
- * @csspart column-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart column - One column of the wheels.
+ * @csspart column-empty - The text shown when the filter hides every option.
+ * @csspart column-feedback - The message that says what is wrong with the value.
+ * @csspart column-filter-icon - The icon beside the filter field.
+ * @csspart column-filter-mark - The default icon beside the filter field, shown when none is slotted.
  * @csspart column-hint - Help under the list.
- * @csspart column-items - The list itself.
- * @csspart column-label - The question, over the list.
- * @csspart column-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart column-loading - Shown while the options are still on their way.
- * @csspart column-search - The region holding the field that narrows the list.
- * @csspart column-search-field - The field itself.
+ * @csspart column-items - The list of options.
+ * @csspart column-label - The label above the list.
+ * @csspart column-live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart column-loading - The text shown while the options load.
+ * @csspart column-search - The region that holds the filter field.
+ * @csspart column-search-field - The filter field.
  * @csspart columns - The row of columns, in `wheels`.
  * @csspart list - The listbox holding the times, in `list`.
- * @csspart list-empty - Shown when a filter has hidden everything.
- * @csspart list-feedback - What is wrong with it.
- * @csspart list-filter-icon - The mark beside that field.
- * @csspart list-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart list-empty - The text shown when the filter hides every option.
+ * @csspart list-feedback - The message that says what is wrong with the value.
+ * @csspart list-filter-icon - The icon beside the filter field.
+ * @csspart list-filter-mark - The default icon beside the filter field, shown when none is slotted.
  * @csspart list-hint - Help under the list.
- * @csspart list-items - The list itself.
- * @csspart list-label - The question, over the list.
- * @csspart list-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart list-loading - Shown while the options are still on their way.
- * @csspart list-search - The region holding the field that narrows the list.
- * @csspart list-search-field - The field itself.
- * @csspart option - One time in it. Carries `data-between` inside a range.
- * @csspart option-between - A time inside a chosen range, short of either end, beside `option`.
- * @csspart option-description - The caption under the words, when there is one.
+ * @csspart list-items - The list of options.
+ * @csspart list-label - The label above the list.
+ * @csspart list-live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart list-loading - The text shown while the options load.
+ * @csspart list-search - The region that holds the filter field.
+ * @csspart list-search-field - The filter field.
+ * @csspart option - One time in the list. It carries `data-between` inside a range.
+ * @csspart option-between - A time inside a chosen range, excluding its ends, beside `option`.
+ * @csspart option-description - The caption under the time's label, when there is one.
  * @csspart option-item - The row.
  * @csspart option-item-active - The row the keyboard is on.
  * @csspart option-item-selected - The row of a chosen time: the one time, or either end of a range.
- * @csspart option-label - The words.
- * @csspart option-text - The words and the caption, as one column.
+ * @csspart option-label - The time's label.
+ * @csspart option-text - The label and the caption, as one column.
  */
 export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_base {
     /**
-     * What a reader is told when the value holds something that is not a time.
+     * The validation message for a value that is not a time.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
@@ -154,7 +145,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      */
     mode?: 'multiple' | 'range';
     /**
-     * Whether the control refuses changes while still submitting its value.
+     * Blocks changes to the time. The value is still submitted with the form.
      *
      * **Enforced by refusing every request in one place**, which is the seam this
      * component already has: `requestValue` is what every path here comes through,
@@ -168,7 +159,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      */
     readOnly: boolean;
     /**
-     * Whether the form refuses to submit while nothing is chosen.
+     * Stops the form from submitting while no time is chosen.
      */
     required: boolean;
     /**
@@ -235,8 +226,8 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     /** Every minute offered within the hour currently shown. */
     private get minutes();
     /**
-     * Each wheel comes to rest on its own answer, and the list on the time it
-     * holds.
+     * Scrolls each wheel to its selected value, and the list to its selected
+     * time.
      *
      * A dial that opens at midnight when it holds ten in the evening is a dial
      * showing the wrong thing, and CSS cannot fix it: `scroll-snap-type` chooses a
@@ -272,11 +263,12 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     /** Refuses every change while read-only. See `readOnly`. */
     requestValue(next: string): boolean;
     /**
-     * What a reader is told when a time is required and none is chosen.
+     * The validation message for a required time picker with no time chosen.
      */
     valueMissingMessage?: string;
     /**
-     * Whether the times are one list or a column each.
+     * Shows the times as one `list`, or as `wheels` with a column for each part
+     * of the time.
      *
      * `list` is the default and offers whole times, which is what a product with
      * opening hours or slots actually has. `wheels` splits them into an hour, a
@@ -356,7 +348,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     private listRevealed;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    /** Puts the keyboard on the list, which is the only control here. */
+    /** Moves focus to the list, which is the only control in the picker. */
     focus(options?: FocusOptions): void;
     /**
      * One wheel, which is a listbox like the whole list is.

package/dist/timeline/item/timeline-item.d.ts

@@ -4,20 +4,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary One event on a timeline: when it happened, and what it was.
  *
  * @description
- * **The time is a `<time>`, and only when there is a time to put in it.** Given
- * `datetime`, the label a consumer wrote is wrapped in the element the platform
- * has for exactly this, so the machine-readable instant travels with the human
- * one: a crawler, a reader's own tooling and a copy-paste all get "2026-08-19",
- * where "yesterday" on its own is a word. Given no `datetime`, it stays a span,
- * because a `<time>` with nothing to be precise about is markup pretending.
+ * Given `datetime`, the label you write is wrapped in a `<time>` element, so a
+ * machine-readable value such as "2026-08-19" travels with a label such as
+ * "yesterday". Without `datetime`, the label is a `<span>`.
  *
- * **The connector is this element's, not the list's.** Each entry draws the line
- * that arrives at it and hides it when it is first, which `:host(:first-child)`
- * settles with no index, no counting parent and no script. `Steps` and
- * `Breadcrumbs` both do it this way and for the same reason.
+ * Each entry draws the connector line that arrives at it and hides it when it
+ * is the first entry, using `:host(:first-child)`. This needs no index, no
+ * counting parent, and no script. `Steps` and `Breadcrumbs` work the same way.
  *
- * `tone` says what kind of event it was, and it is the only thing that colors
- * the mark. It takes `Announcement`'s vocabulary rather than a second one.
+ * `tone` sets the kind of event and is the only thing that colors the mark. It
+ * uses the same values as `Announcement`.
  *
  * @since 0.1.0
  * @status stable
@@ -26,24 +22,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/timeline
  *
  * @slot - What happened.
- * @slot marker - The mark on the line. Falls back to a dot, which is the slot's
- * own fallback content: whether a consumer slotted a mark is a question only the
- * platform can answer, and it answers it at assignment time.
- * @slot time - When it happened, as a reader should see it written.
+ * @slot marker - The mark on the line. Defaults to a dot, which is the slot's fallback
+ * content.
+ * @slot time - When it happened, written the way you want it shown.
  *
  * @csspart content - What happened, and the time above it.
- * @csspart dot - The mark drawn where nothing was slotted for one.
+ * @csspart dot - The dot drawn when no marker is slotted.
  * @csspart marker - The mark on the line.
- * @csspart rail - The column holding the mark and the line. Both halves of the
- * line are drawn on the rail, which is `::part(rail)::before` and `::after` from
- * a consumer's sheet: this tier ships no CSS, so a box it renders for one to
- * paint is an empty child costing whatever the consumer's own layout charges for
- * a child. `ListItem` measured that.
+ * @csspart rail - The column that holds the mark and the line. Draw the two halves of the
+ * line with `::part(rail)::before` and `::part(rail)::after` in your stylesheet. This
+ * tier ships no CSS and renders no extra box for the line.
  * @csspart time - When it happened.
  */
 export declare class HelixHeadlessTimelineItem extends HelixElement {
     /**
-     * When it happened, machine-readable.
+     * When it happened, in machine-readable form. Setting it wraps the time in a
+     * `<time>` element.
      *
      * Whatever `<time>` accepts, which is a date, a time, both, a duration or a
      * week. Unset, the label is written as it was given and nothing claims to
@@ -51,7 +45,7 @@ export declare class HelixHeadlessTimelineItem extends HelixElement {
      */
     datetime: string;
     /**
-     * What kind of event it was, which decides the mark's color and nothing else.
+     * The kind of event. It sets the color of the mark and nothing else.
      */
     tone?: 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
     protected willUpdate(changed: PropertyValues): void;

package/dist/timeline/root/timeline-root.d.ts

@@ -1,31 +1,23 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A record of what happened, in the order it happened.
+ * @summary A list of events, in the order they happened.
  *
  * @description
- * **Not `Steps`, and the difference is what the thing is for.** A stepper is a
- * process a reader is moving through: it has a stage they are on, stages they
- * have finished, and stages ahead, so it carries `active` and `complete` and
- * numbers itself. A timeline is a record of events that already happened, or are
- * scheduled to. Nothing is current, nothing is complete, and what each entry
- * carries instead is a time. Building this as an appearance of `Steps` would
- * have meant a stepper with no step you are on.
+ * A timeline is a record of events that happened or are scheduled. Each entry
+ * carries a time, and no entry is current or complete. For a process you move
+ * through, with a current stage and `active` and `complete` states, use
+ * `Steps`.
  *
- * What it does take from `Steps` is the connector. Each entry draws the line
- * that arrives at it and hides it when it is first, which needs neither an index
- * nor a parent that counts: `:host(:first-child)` is the whole of it, resolved
- * at layout with no script, so a server's markup is right before anything runs.
+ * Each entry draws the connector line that arrives at it and hides it when it
+ * is first, using `:host(:first-child)`. This resolves at layout with no
+ * script, so the server markup is correct before anything runs.
  *
- * `role="list"` on the host rather than an `<ol>` in the shadow root, for the
- * reason `Steps` gives: the entries are the consumer's elements in the light
- * DOM, so a list element here would be a list whose items are somewhere else.
+ * The host has `role="list"`, because the entries are your elements in the
+ * light DOM. `Steps` does the same.
  *
- * **It runs down the page and has no horizontal form.** Laid along a line there
- * is no room for the time or the sentence that are the whole reason to reach for
- * a timeline, so what survives is a mark and a short label, and that is a
- * stepper. `Steps` is already horizontal by default and already draws it. A run
- * of stages along a page is `Steps`.
+ * A timeline runs down the page and has no horizontal layout. For stages laid
+ * out horizontally, use `Steps`, which is horizontal by default.
  *
  * @since 0.1.0
  * @status stable
@@ -37,7 +29,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessTimeline extends HelixElement {
     /**
-     * Names the record, for a reader arriving at it out of context.
+     * Accessible name for the timeline, for people who reach it out of context.
      */
     label: string;
     protected render(): TemplateResult;

package/dist/toast/item/toast-item.d.ts

@@ -5,35 +5,33 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * @summary One message in the toast region.
  *
  * @description
- * An element rather than a slot, because it carries a timeout, a tone, a
- * dismiss control and a lifetime that pauses: behavior, state and API.
+ * Each message is an element because it has a timeout, a tone, a dismiss
+ * control, and a lifetime that pauses.
  *
- * **The timer is the item's own.** Held by the region, one message arriving
- * would restart another's, so a stack of three would go from three seconds each
- * to nine for the last.
+ * **Each item runs its own timer.** A timer held by the region would restart
+ * with each new message, and the last of three messages would stay for nine
+ * seconds.
  *
- * **A message is the opposite of the page it is over.** Inverted by default, so
- * a thing arriving in a corner is told apart from the page before it is read,
- * and by a flip of `color-scheme` rather than by spending a color that means
- * something.
+ * **Messages are inverted by default.** The item flips `color-scheme`, so a new
+ * message stands out from the page without using a color that carries meaning.
  *
  * @since 0.1.0
  * @status stable
  * @documentation https://fusion.dev/helix/components/toast
  *
  * @slot - The message.
- * @slot actions - What to do about it, usually a button or a link.
+ * @slot actions - Actions for the message, usually a button or a link.
  * @slot dismiss-icon - Replaces the glyph inside the dismiss control.
- * @slot icon - Replaces the tone mark. Matches `Callout`, which is why the
- *   dismiss control's own glyph is `dismiss-icon` rather than this: two slots
- *   cannot share a name, assignment goes to whichever comes first in the tree,
- *   and the tone mark is the one a consumer reaches for.
+ * @slot icon - Replaces the tone mark. The name matches `Callout`. The dismiss
+ *   control's glyph uses `dismiss-icon`, because two slots cannot share a name:
+ *   content goes to whichever slot comes first in the tree, and the tone mark is
+ *   the one you are more likely to replace.
  *
- * @event {HelixDismissEvent} helix-dismiss - Fired when it asks to go, whether by the control or by its timer. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the message is dismissed, by the control or by its timer, and cancelable. Canceling it keeps the message.
  *
- * @csspart actions - The region holding what to do about it.
+ * @csspart actions - The region that holds the actions.
  * @csspart content - The message.
- * @csspart dismiss - The control that asks to close.
+ * @csspart dismiss - The control that dismisses the message.
  * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
  * @csspart icon - The tone mark, where the message has one.
  * @csspart icon-mark - The tone glyph, where none is slotted.
@@ -44,7 +42,8 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  */
 export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base {
     /**
-     * How long it stays, in milliseconds. Absent means until it is dismissed.
+     * How long the message stays, in milliseconds. When it is not set, the
+     * message stays until it is dismissed.
      *
      * Read once when the item is first rendered. Changing it afterwards does not
      * restart a message the reader is already partway through.
@@ -71,7 +70,7 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     private remaining;
     private timer;
     /**
-     * What kind of message it is, which picks the mark and its name.
+     * The kind of message, which sets its mark and the mark's accessible name.
      *
      * A subset of the tone axis: a toast reports a status and never a brand role.
      */
@@ -79,7 +78,7 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     /** Whether it is showing, whoever said so, and `undefined` until somebody has. */
     private openState;
     /**
-     * Asks to be taken away, and reports whether the request stood.
+     * Dismisses the message, and returns whether the dismissal went ahead.
      *
      * Announced before anything happens, so `preventDefault()` is a refusal and
      * the message stays. The event still carries the label, because a consumer
@@ -87,9 +86,9 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
      * true whether or not the item hid itself first.
      */
     dismiss(): boolean;
-    /** Stops the clock, leaving whatever is left of it. */
+    /** Pauses the dismiss timer and keeps the time that is left. */
     pause(): void;
-    /** Starts it again from where it stopped. */
+    /** Restarts the dismiss timer from where it paused. */
     resume(): void;
     /**
      * How many reasons there are to hold the clock, rather than whether there is

package/dist/toast/root/toast-root.d.ts

@@ -1,32 +1,27 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary The region messages arrive in, and the only thing that announces them.
+ * @summary The region that holds toast messages, and the only element that announces them.
  *
  * @description
- * **The region is why this is one family rather than two.** A live region has
- * to be in the document *before* a message is put into it: assistive technology
- * subscribes to the region, and a region that arrives already holding its
- * message is frequently not announced at all. So the container is a part of the
- * family and not an arranger of complete things, which is the same reasoning
- * that puts `Radio.Group` inside its own family.
+ * The region and its items are one family because a live region must be in the
+ * document before a message is added to it. Assistive technology often does not
+ * announce a region that arrives already holding its message. `Radio.Group` is
+ * part of its family for the same reason.
  *
- * **Polite, never assertive.** `role="alert"` interrupts whatever a reader is
- * being told, and almost nothing that arrives in a corner of the screen has
- * earned that. Something that genuinely cannot wait is a `Dialog`, which stops
- * the page for everyone rather than only for the people who cannot see it.
+ * **The region is polite, never assertive.** `role="alert"` interrupts whatever
+ * a screen reader is reading. For something that cannot wait, use a `Dialog`,
+ * which stops the page for every user.
  *
- * **It never creates or destroys anything.** The consumer renders items and
- * removes them; asking to go is a cancelable `helix-dismiss` from the item. An
- * item that has gone hides itself and stays in the tree, so a consumer whose
- * state still lists it does not have their framework fighting a node this
- * component took away. It hides without waiting to be told, unless the consumer
- * declared `open` and said the state is theirs.
- * There is no `toast.show()`, because an imperative queue inside a component is
- * a second copy of the application's state that nothing can render from: an app
- * that wants a `toast()` function writes a thin one over the state it already
- * has, and keeps the ability to render the same messages on the server, in a
- * test, or twice.
+ * **The region never creates or removes items.** You render items and remove
+ * them. An item requests closing with a cancelable `helix-dismiss` event. A
+ * dismissed item hides itself and stays in the DOM, so your framework's state
+ * and the DOM stay in sync. It hides on its own unless you set `open`, which
+ * makes the state yours.
+ *
+ * There is no `toast.show()`. For a `toast()` function, write a small one over
+ * your app's state, which also lets you render the same messages on the server,
+ * in a test, or more than once.
  *
  * @since 0.1.0
  * @status stable
@@ -36,7 +31,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The messages.
  *
- * @event {HelixDismissEvent} helix-dismiss - A message asking to go, by its control or by its timer, dispatched by the message and heard here because the stack is what a consumer holds. Cancelable: refusing it takes the decision and the message stays.
+ * @event {HelixDismissEvent} helix-dismiss - A message is being dismissed, by its control or by its timer. The message sends it, and you can listen for it on the region. Cancelable: canceling it keeps the message.
  *
  * @csspart region - The stack the messages are in.
  */

package/dist/toggle/group/toggle-group.d.ts

@@ -5,15 +5,14 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * @summary A row of options with the selection marked by a moving indicator.
  *
  * @description
- * The indicator is one element that travels, not a background that appears on
- * whichever item is current. A fill that swaps is two things changing at once
- * and reads as a flicker; one that moves is a single object the eye follows,
- * and it says where the selection came from as well as where it went.
+ * The indicator is one element that moves to the selected item. A single moving
+ * object is easier to follow than a fill that swaps, and it shows where the
+ * selection came from.
  *
- * Its box is measured from the selected item and written onto the indicator as
- * custom properties, labels being different lengths. Measurement is client-side
- * by necessity, so the server renders the indicator hidden and it fades in once
- * it has somewhere to be, which is the harmless direction.
+ * Its size and position are measured from the selected item and written to the
+ * indicator as custom properties, because labels have different lengths.
+ * Measurement happens on the client, so the server renders the indicator hidden
+ * and it fades in once measured.
  *
  * @since 0.1.0
  * @status stable
@@ -21,26 +20,25 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * @documentation https://fusion.dev/helix/components/toggle
  *
  * @slot - The group's items.
- * @slot end - Whatever sits after the track on its own line, such as a count or a reset.
- * @slot start - Whatever sits before the track on its own line, such as an icon or a caption.
+ * @slot end - Content after the track, on the same line, such as a count or a reset.
+ * @slot start - Content before the track, on the same line, such as an icon or a caption.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the answer moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the choice changes. Cancelable: call `preventDefault()` to keep the current choice. It is the only way to block a change.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. The item sends it, and you listen for it on the group. Cancelable: call `preventDefault()` to keep the current choice.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart feedback - What is wrong with it.
- * @csspart hint - Help under the row, while nothing is wrong.
+ * @csspart feedback - The error message under the row.
+ * @csspart hint - The help text under the row, shown while there is no error.
  * @csspart indicator - The moving marker behind the selected item.
- * @csspart label - The question, over the row.
- * @csspart row - The line the track sits on, with whatever flanks it.
- * @csspart track - The bar the items sit in. The rule after an inline label,
- * separating it from the items, is drawn on the bar, which is
- * `::part(track)::before` from a consumer's sheet: this tier ships no CSS, so a
- * box it renders for one to paint is an empty child costing whatever the
- * consumer's own layout charges for a child. `ListItem` measured that.
+ * @csspart label - The label above the row.
+ * @csspart row - The line that holds the track and the content on either side of it.
+ * @csspart track - The bar the items sit in. Draw the line between an inline
+ * label and the items with `::part(track)::before` in your stylesheet. This tier
+ * ships no CSS, so it renders no separate element for the line, which would add
+ * an empty child to your layout.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The group has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_base {
     /**
@@ -110,7 +108,7 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      */
     private validate;
     /**
-     * Where the group's label sits, `start` putting it on the track's line.
+     * Where the group's label sits. `start` puts it on the track's line.
      *
      * Absent is above, which is what a field looks like and what almost every
      * group wants. `start` is for a row of controls that are labeled rather than

package/dist/toggle/root/toggle-root.d.ts

@@ -5,11 +5,11 @@ declare const HelixHeadlessToggle_base: (new (...args: any[]) => import("@fusion
  * @summary One option in a toggle group.
  *
  * @description
- * Renders a `<button role="radio">`. This is a form control and nothing else.
+ * Renders a `<button role="radio">` for use as a form control.
  *
- * Navigation is not this. It is links marked with `aria-current` and styled by
- * the `data-navigation-item` recipe in the base layer, which carries the same look
- * without radio semantics announcing destinations as choices.
+ * Do not use it for navigation. For navigation, use links marked with
+ * `aria-current` and styled by the `data-navigation-item` recipe in the base
+ * layer. The recipe has the same look, and links are not announced as choices.
  *
  * @since 0.1.0
  * @status stable
@@ -19,15 +19,15 @@ declare const HelixHeadlessToggle_base: (new (...args: any[]) => import("@fusion
  *
  * @slot - The item's label.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: call `preventDefault()` to keep the current choice.
  *
  * @csspart item - The radio button.
  *
- * @cssstate selected - While it is on.
+ * @cssstate selected - The item is chosen.
  */
 export declare class HelixHeadlessToggle extends HelixHeadlessToggle_base {
     /**
-     * Whether the markup declared this one chosen, which is what a reset returns to.
+     * Whether the markup declares the item chosen. A form reset returns to it.
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
@@ -56,7 +56,7 @@ export declare class HelixHeadlessToggle extends HelixHeadlessToggle_base {
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
     /**
-     * Whether this item holds the group's tab stop while nothing is chosen.
+     * Whether the item holds the group's tab stop while nothing is chosen.
      *
      * The stop normally rides on the selection, and an unanswered group has no
      * selection, so without this the keyboard cannot reach it. Written by the