@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

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

@@ -4,15 +4,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A group of controls that share one tab stop.
  *
  * @description
- * Separate from a button group, and the difference is what it holds: a group is
- * homogeneous, a toolbar is not. A toolbar mixes buttons, toggles, and menus,
- * which is why it is its own component rather than a variant of something.
+ * A toolbar holds a mix of controls, such as buttons, toggles, and menus. A
+ * button group holds one kind, so the two are separate components.
  *
- * The whole toolbar is one tab stop and the arrows move between controls, so a
- * page with three toolbars costs three presses of Tab to get past rather than
- * thirty. Controls are found by asking the browser what is focusable rather
- * than by matching tag names, so a toolbar works with anything put in it,
- * including a consumer's own elements.
+ * The toolbar is one tab stop, and the arrow keys move between its controls, so
+ * three toolbars take three presses of Tab to pass. Any element the browser can
+ * focus counts as a control, including your own elements.
  *
  * @since 0.1.0
  * @status stable
@@ -26,11 +23,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessToolbar extends HelixElement {
     /**
-     * Accessible name for the toolbar.
+     * The toolbar's name, read by screen readers.
      */
     label: string;
     /**
-     * Which way the arrow keys move.
+     * The direction the arrow keys move focus in.
      */
     orientation?: 'horizontal' | 'vertical';
     private watcher;

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

@@ -2,40 +2,32 @@ import { HelixElement, type Placement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A short description that appears beside what it describes.
+ * @summary A short text that appears next to an element on hover and focus.
  *
  * @description
- * The trigger is slotted and stays the consumer's own element. The bubble is
- * rendered here, in the top layer through the popover API, so it clears any
- * ancestor with `overflow: hidden` without a `z-index` anywhere. Position comes
- * from `FloatingController`, which flips to another side when the preferred one
- * does not fit.
+ * The trigger is slotted and stays your own element. The bubble renders in the
+ * top layer through the popover API, so an ancestor with `overflow: hidden`
+ * does not clip it and no `z-index` is needed. `FloatingController` positions
+ * it and flips it to another side when the preferred side does not fit.
  *
- * **Two forms, and they are not equivalent for a screen reader.** Wrapping is
- * the convenience form and is right where the bubble decorates a control that
- * already says what it is: nothing here can describe a slotted trigger, an
- * IDREF being unable to cross a shadow boundary.
+ * Wrapping the trigger is the convenient form. Use it where the trigger already
+ * has an accessible name, because the tooltip cannot describe a slotted
+ * trigger: an IDREF cannot cross a shadow boundary.
  *
- * `for` is the form that works. The tooltip sits *beside* the trigger in the
- * consumer's own tree and names it by id, so an IDREF between them is legal in
- * the ordinary way:
+ * To add a description, place the tooltip beside the trigger and name the
+ * trigger with `for`:
  *
  * ```html
  * <helix-headless-button id="save" aria-describedby="save-tip">Save</helix-headless-button>
  * <helix-headless-tooltip id="save-tip" for="save" content="Save your work"></helix-headless-tooltip>
  * ```
  *
- * The reference points at *this host*, not at the bubble in its shadow root:
- * the description is computed from the flat tree, which descends into shadow
- * content on its own.
+ * Write the `aria-describedby` yourself, pointing at the tooltip host. Setting
+ * it at runtime causes a hydration mismatch that React does not fix. With
+ * `for`, the tooltip warns once on first open if the attribute is missing.
  *
- * **The consumer writes that `aria-describedby`, and nothing here writes it for
- * them.** Setting it at runtime is a hydration mismatch React will not patch
- * up. `for` audits itself on first open and warns once where it is missing.
- *
- * It shows on hover and on focus, and hides on leave, on blur, on Escape, and
- * once the trigger has been activated: the hint is spent when the control has
- * been used.
+ * The tooltip shows on hover and on focus. It hides on pointer leave, on blur,
+ * on Escape, and when the trigger is activated.
  *
  * @since 0.1.0
  * @status stable
@@ -43,24 +35,24 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * @aliases Hint, Popup label
  * @documentation https://fusion.dev/helix/components/tooltip
  *
- * @slot - The trigger.
- * @slot content - The bubble's content, when `content` is not enough. Anything
- * slotted here replaces the property, which is this slot's fallback.
+ * @slot - The trigger: the element the tooltip describes.
+ * @slot content - Rich content for the bubble. It replaces the `content`
+ * property.
  *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it hides, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the bubble shows, and cancelable.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The bubble is about to hide. Cancelable: cancel it to keep it shown.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The bubble is about to show. Cancelable: cancel it to keep it hidden.
+ * @event {Event} toggle - The bubble opened or closed. The event carries `newState` and `oldState`.
  *
- * @csspart arrow - The point, resting against the trigger.
- * @csspart arrow-bottom - The point while the bubble is below its trigger, so on the bubble's top edge, beside `arrow`.
- * @csspart arrow-left - The point while the bubble is left of its trigger, so on the bubble's right edge, beside `arrow`.
- * @csspart arrow-right - The point while the bubble is right of its trigger, so on the bubble's left edge, beside `arrow`.
- * @csspart arrow-top - The point while the bubble is above its trigger, so on the bubble's bottom edge, beside `arrow`.
+ * @csspart arrow - The arrow that points at the trigger.
+ * @csspart arrow-bottom - Added to `arrow` while the bubble is below its trigger, with the arrow on the bubble's top edge.
+ * @csspart arrow-left - Added to `arrow` while the bubble is left of its trigger, with the arrow on the bubble's right edge.
+ * @csspart arrow-right - Added to `arrow` while the bubble is right of its trigger, with the arrow on the bubble's left edge.
+ * @csspart arrow-top - Added to `arrow` while the bubble is above its trigger, with the arrow on the bubble's bottom edge.
  * @csspart tooltip - The bubble.
- * @csspart tooltip-bottom - The bubble while it is below its trigger, beside `tooltip`.
- * @csspart tooltip-left - The bubble while it is left of its trigger, beside `tooltip`.
- * @csspart tooltip-right - The bubble while it is right of its trigger, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above its trigger, beside `tooltip`.
+ * @csspart tooltip-bottom - Added to `tooltip` while the bubble is below its trigger.
+ * @csspart tooltip-left - Added to `tooltip` while the bubble is left of its trigger.
+ * @csspart tooltip-right - Added to `tooltip` while the bubble is right of its trigger.
+ * @csspart tooltip-top - Added to `tooltip` while the bubble is above its trigger.
  *
  * @cssstate open - While the tooltip shows.
  * @cssstate placed-bottom - While the bubble sits below its trigger.
@@ -90,11 +82,12 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      */
     delayOut: number;
     /**
-     * Whether the tooltip never shows.
+     * Stops the tooltip from showing.
      */
     disabled: boolean;
     /**
-     * The id of the element this describes, in this tooltip's own tree.
+     * The id of the element the tooltip describes, in the same document or shadow
+     * root as the tooltip.
      *
      * Set it and the tooltip stops wrapping: it renders no trigger, listens on
      * the element it names, and points its bubble there. Leave it unset and the
@@ -114,7 +107,7 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      */
     for: string;
     /**
-     * Space between the trigger and the point of the bubble, in pixels.
+     * The space between the trigger and the tip of the bubble, in pixels.
      *
      * **Measured from the point, which is what the arrow being back changed.**
      * The arrow is drawn half outside the bubble, so a gap measured to the
@@ -126,7 +119,8 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      */
     offset: number;
     /**
-     * Whether the bubble survives the trigger being used.
+     * Keeps the bubble open when the trigger is used, such as a copy button whose
+     * tooltip changes to "Copied".
      *
      * **Activation takes a tooltip down, because a hint about what a control will
      * do is spent once the control has done it.** That is right for a gear that
@@ -143,13 +137,13 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      */
     persist: boolean;
     /**
-     * Preferred side.
+     * The side to show the bubble on.
      *
      * It moves if that side does not fit.
      */
     placement: Placement;
     /**
-     * The id of a box to keep the bubble inside, instead of the viewport.
+     * The id of a box to keep the bubble inside. Defaults to the viewport.
      *
      * Resolved the way `for` is, so an id in the same tree, which is what lets a
      * component name a box in its own shadow root. A chart does: its bubble is
@@ -190,7 +184,7 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      */
     private get trigger();
     /**
-     * Places the bubble again, for an anchor that moved without the page moving.
+     * Positions the bubble again, for a trigger that moved while the page did not.
      *
      * Public because a chart needs it. Its mark walks from reading to reading
      * while the page holds still, and `autoUpdate` watches scrolling, resizing
@@ -245,10 +239,10 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * a framework does, would leave the trigger describing nothing.
      */
     private readonly handleContentChange;
-    /** Shows the bubble, unless there is nothing to show. */
+    /** Shows the bubble, if it has content. */
     show(): void;
     /**
-     * Closes the bubble, and cancels a show that had not happened yet.
+     * Hides the bubble, and cancels a pending show.
      *
      * The timer matters as much as the state: a pointer that arrives and leaves
      * inside the delay left one queued, and the tooltip appeared over whatever

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

@@ -2,22 +2,20 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
 /**
- * @summary A guided run through an interface, one stop at a time.
+ * @summary A guided tour of an interface, one stop at a time.
  *
  * @description
- * The root owns the order and nothing else. Which stop is current, what Next
- * and Back mean, when the run is finished; the stops own where they point, and
- * the consumer owns every word.
+ * The root holds the order of the stops: which stop is current, what Next and
+ * Back do, and when the tour is finished. Each stop holds its target, and you
+ * write all the text.
  *
- * **The spotlight is a shadow, not a hole.** The scrim is a box the size of the
- * current target with an enormous spread on its `box-shadow`, so the darkness
- * is what the shadow paints. A `clip-path` on a full-screen scrim needs the
- * viewport in the same coordinate space as the cut, which stops being true the
- * moment anything between them is transformed.
+ * **The spotlight is a shadow.** The scrim is a box the size of the current
+ * target with a very large `box-shadow` spread, and the shadow paints the
+ * darkness. A `clip-path` on a full-screen scrim breaks as soon as an element
+ * between the scrim and the viewport is transformed.
  *
- * **It measures, and the target is an element elsewhere on the page whose
- * position nothing can know statically.** Nothing is measured on the server and
- * nothing needs to be: a tour starts when a reader asks for it.
+ * The root measures the target's position in the browser. Nothing is measured
+ * on the server, because a tour starts only on request.
  *
  * @since 0.1.0
  * @status stable
@@ -25,23 +23,23 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  * @aliases Coachmark, Product tour, Walkthrough, Onboarding
  * @documentation https://fusion.dev/helix/components/tour
  *
- * @slot - The stops, in the order they should be visited.
+ * @slot - The stops, in the order they are shown.
  *
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current stop moves, carrying the new index. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the reader leaves early. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current stop changes, with the new index. Cancelable: call `preventDefault()` to stay on the current stop.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the user ends the tour early. Cancelable: call `preventDefault()` to keep the tour open.
  * @event {HelixCompleteEvent} helix-complete - Fired when the last stop is
  * finished.
- * @event {HelixTourAskEvent} helix-tour-ask - A stop's own controls asking the tour to move, dispatched by the stop and heard here because the tour is what moves.
+ * @event {HelixTourAskEvent} helix-tour-ask - Fired when a stop's control is pressed to move the tour. The stop sends it, and the tour handles it.
  *
- * @csspart spotlight - The box over the current target, which paints the scrim.
+ * @csspart spotlight - The box over the current target. It also draws the dimmed area around the target.
  */
 export declare class HelixHeadlessTour extends HelixElement {
     /**
-     * Label for the control that goes back, handed to every stop.
+     * Label for the control that goes back, passed to every stop.
      */
     backLabel: string;
     /**
-     * Stop to start on, where nothing declared one.
+     * The stop to start on, when nothing else sets one.
      */
     defaultIndex: number;
     /**
@@ -51,7 +49,7 @@ export declare class HelixHeadlessTour extends HelixElement {
     /** The stop being shown, whoever set it, and `undefined` until somebody has. */
     private indexState;
     /**
-     * Which stop the reader is on.
+     * The index of the stop being shown.
      *
      * **Moved through `requestChange`, never by assignment from `move`.** That
      * announces first and applies only if nobody refused, and refusing is how a
@@ -65,7 +63,7 @@ export declare class HelixHeadlessTour extends HelixElement {
     get index(): number;
     set index(next: number);
     /**
-     * Accessible name for the run, such as "Getting started".
+     * The tour's name, read by screen readers, such as "Getting started".
      */
     label: string;
     /**
@@ -81,7 +79,7 @@ export declare class HelixHeadlessTour extends HelixElement {
      */
     skipLabel: string;
     /**
-     * Space left around the target when it is lit, in pixels.
+     * The space around the target inside the spotlight, in pixels.
      */
     spotlightPadding: number;
     private assigned;
@@ -98,16 +96,16 @@ export declare class HelixHeadlessTour extends HelixElement {
     private sizer;
     /** What `sizer` is watching, so a render that changed nothing re-observes nothing. */
     private sized;
-    /** The stops, in the order they were written. */
+    /** The stops, in source order. */
     get stops(): HelixHeadlessTourStop[];
     /** How many stops there are. */
     get length(): number;
-    /** Goes on, and finishes the run on the last stop. */
+    /** Goes to the next stop, and finishes the tour on the last stop. */
     next(): void;
-    /** Goes back, and does nothing on the first stop. */
+    /** Goes to the previous stop. It does nothing on the first stop. */
     back(): void;
     /**
-     * Leaves the run early, which is a close rather than a completion.
+     * Ends the tour early, as a close. `helix-complete` is not fired.
      *
      * Announced before it is applied, and cancelable because of it: writing
      * `open` first and dispatching after leaves a consumer calling