@fusion.dev/helix-headless 0.105.0 → 0.106.0

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

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

@@ -2,67 +2,58 @@ import { HelixElement, type Placement } from '@fusion.dev/helix-core';
 import type { PropertyValues, TemplateResult } from 'lit';
 import '../../button/index.js';
 /**
- * @summary One stop on a tour: what it points at, and a panel to say it in.
+ * @summary One stop on a tour: the element it points at, and a panel of content about it.
  *
  * @description
- * A stop names a target with `for` and holds whatever the consumer puts in it.
- * It owns no content of its own, which is the whole shape of this family: the
- * tour abstracts the three things that are genuinely hard, and the words are
- * the consumer's.
+ * A stop names its target with `for` and holds the content you put in it. The
+ * stop handles three things:
  *
- * What it does own:
+ * - **Placement.** The panel is anchored to the target by the same floating
+ *   positioning as the other Helix overlays.
+ * - **Stacking.** The panel is a popover, so it is in the top layer and shows
+ *   above dialogs, scrolling regions, and other stacking contexts.
+ * - **Visibility.** The stop shows when it is `current`, which the root sets.
  *
- * - **Where the panel goes.** Anchored to the target through the same floating
- *   pass every other overlay here uses.
- * - **That it is on top.** A popover, so it is in the top layer. A tour points
- *   at things inside dialogs, inside scrollers, inside anything with a stacking
- *   context, and a panel in the ordinary flow loses to all three.
- * - **When it shows.** Which is `current`, and which the root decides.
+ * Put any content in the stop, such as a `Card`, or a heading and a line of
+ * text. There are no fixed title or body parts.
  *
- * What it does not own is the heading, the paragraph, the picture and the
- * layout. Slot a `Card`, or a heading and a line of prose, or anything else.
- * Fixed `title` and `body` parts would be a component deciding what a tour is
- * allowed to say.
+ * **The buttons are slot fallback.** With nothing in the `actions` slot, you
+ * get Back, Next, and Skip, already wired. Slot your own `actions` and drive
+ * them with `next()`, `back()`, and `skip()` on the root.
  *
- * **The buttons are slot fallback, so the common case costs nothing and the
- * uncommon one is possible.** Write nothing and get Back, Next and Skip already
- * wired. Slot `actions` and they are yours, driven by `next()`, `back()` and
- * `skip()` on the root, which are public for exactly that.
- *
- * **`for` is an id, the same as `Tooltip`'s.** The target is elsewhere on the
- * page, and an id is the one reference a consumer can write in markup without
- * holding an element. Resolved against the root node, so a stop inside a shadow
- * tree points at a target in that tree.
+ * **`for` is an id, as with `Tooltip`**, so you can point at a target elsewhere
+ * on the page from markup. It resolves against the stop's root node, so a stop
+ * inside a shadow tree points at a target in that tree.
  *
  * @since 0.1.0
  * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *
- * @slot - What this stop says. A card, a heading and a line, anything.
- * @slot actions - Replaces the controls, which are Back, Next and Skip.
+ * @slot - The stop's content. Any content works, such as a card, or a heading and a line.
+ * @slot actions - Replaces the controls, which are Back, Next, and Skip.
  *
- * @event {HelixTourAskEvent} helix-tour-ask - A stop asking the tour to move, from its own controls.
+ * @event {HelixTourAskEvent} helix-tour-ask - Fired when one of the stop's controls is pressed, to move the tour.
  *
  * @csspart actions - The row the controls sit in.
- * @csspart arrow - The point, which the floating pass places against the target.
- * @csspart arrow-bottom - The point while the panel is below its target, so on the panel's top edge, beside `arrow`.
- * @csspart arrow-left - The point while the panel is left of its target, so on the panel's right edge, beside `arrow`.
- * @csspart arrow-right - The point while the panel is right of its target, so on the panel's left edge, beside `arrow`.
- * @csspart arrow-top - The point while the panel is above its target, so on the panel's bottom edge, beside `arrow`.
+ * @csspart arrow - The arrow that points at the target.
+ * @csspart arrow-bottom - The arrow while the panel is below its target, on the panel's top edge. Applied with `arrow`.
+ * @csspart arrow-left - The arrow while the panel is left of its target, on the panel's right edge. Applied with `arrow`.
+ * @csspart arrow-right - The arrow while the panel is right of its target, on the panel's left edge. Applied with `arrow`.
+ * @csspart arrow-top - The arrow while the panel is above its target, on the panel's bottom edge. Applied with `arrow`.
  * @csspart back - The control that goes to the previous stop.
- * @csspart back-button - The inner control.
+ * @csspart back-button - The button inside `back`.
  * @csspart bubble - The panel that points at the target.
  * @csspart content - The region holding the slotted content.
- * @csspart next - The control that goes on, and finishes on the last stop.
- * @csspart next-button - The inner control.
- * @csspart skip - The control that leaves the tour.
- * @csspart skip-button - The inner control.
+ * @csspart next - The control that goes to the next stop, and finishes the tour on the last stop.
+ * @csspart next-button - The button inside `next`.
+ * @csspart skip - The control that ends the tour early.
+ * @csspart skip-button - The button inside `skip`.
  *
- * @cssstate placed-bottom - While the panel sits below its target.
- * @cssstate placed-left - While the panel sits to the left of its target.
- * @cssstate placed-right - While the panel sits to the right of its target.
- * @cssstate placed-top - While the panel sits above its target.
+ * @cssstate placed-bottom - The panel sits below its target.
+ * @cssstate placed-left - The panel sits to the left of its target.
+ * @cssstate placed-right - The panel sits to the right of its target.
+ * @cssstate placed-top - The panel sits above its target.
  */
 export declare class HelixHeadlessTourStop extends HelixElement {
     /**
@@ -70,7 +61,7 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      */
     backLabel: string;
     /**
-     * Whether this is the stop the reader is on.
+     * Whether the stop is the one being shown.
      *
      * Written by the root rather than by a consumer, which is the one place this
      * family writes onto markup it does not own. It is acceptable here for a
@@ -84,15 +75,15 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      */
     doneLabel: string;
     /**
-     * Whether this is the first stop, so there is nowhere back to.
+     * Whether the stop is the first one, with no stop before it.
      */
     first: boolean;
     /**
-     * The id of the element this stop is about.
+     * The id of the element the stop points at.
      */
     for: string;
     /**
-     * Whether this is the last stop, so the control says Done.
+     * Whether the stop is the last one. Its next control then shows `doneLabel`.
      */
     last: boolean;
     /**
@@ -100,7 +91,7 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      */
     nextLabel: string;
     /**
-     * Which side of the target the panel prefers.
+     * The side of the target the panel is placed on when there is room.
      */
     placement: Placement;
     /**
@@ -113,7 +104,7 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      * makes.
      */
     private side?;
-    /** The element this stop is about, or null where the id resolves to nothing. */
+    /** The element the stop points at, or `null` when no element has the `for` id. */
     get target(): HTMLElement | null;
     private readonly floating;
     protected willUpdate(changed: PropertyValues): void;

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

@@ -5,23 +5,19 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * @summary One node in a tree.
  *
  * @description
- * **`open`, on `MixinControllerOpen`, rather than a bare boolean of its own.**
- * A branch showing its children is the same state a disclosure holds. A
- * hand-written toggle announces nothing, so a consumer could neither know a
- * branch opened nor own the state. `aria-expanded` is still what the row
- * renders: the property differs, not the semantics.
+ * `open` comes from `MixinControllerOpen`, the same state a disclosure holds,
+ * so you can respond to a branch opening and control the state yourself. The
+ * row renders `aria-expanded`.
  *
- * An element rather than a slot, because it owns state: whether it is open,
- * selected, and whether it holds focus.
+ * Each item is an element because it holds state: whether it is open, selected,
+ * and focused.
  *
- * A branch is any item with something slotted into `children`, detected on the
- * client because the server cannot inspect children. The server renders the
- * node as a leaf and the twisty appears on hydration, which is the harmless
- * direction.
+ * An item is a branch when something is slotted into `children`. This is
+ * detected on the client, so server-rendered markup shows a leaf and the twisty
+ * appears on hydration.
  *
- * **`href` makes the row itself the link.** With the anchor slotted into the
- * name instead, everything outside the words is dead: no Enter, no middle
- * click, no status bar. Given an `href` the row *is* an `<a>`.
+ * **`href` makes the whole row a link**, rendered as an `<a>`. Enter, middle
+ * click, and the status bar then work anywhere on the row.
  *
  * @since 0.1.0
  * @status stable
@@ -30,13 +26,13 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  *
  * @slot - The item's label.
  * @slot children - Nested items, which make this a branch.
- * @slot end - After the label, at the row's far side. A count, or a state.
- * @slot start - Before the label, after the chevron. A mark about the item.
+ * @slot end - Content after the label, at the far side of the row, such as a count or a state.
+ * @slot start - Content before the label and after the chevron, such as a mark for the item.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before a branch closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before a branch opens, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixSelectEvent} helix-select - Fired when the item is chosen, and cancelable. Canceling it changes nothing.
+ * @event {Event} toggle - Sent when the branch opens or closes, with `newState` and `oldState`.
  *
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target unless `href` moves it to the row.
@@ -51,7 +47,7 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  */
 export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
     /**
-     * Where this node goes, which makes its row a real link.
+     * The URL this node links to. Setting it makes the row a link.
      *
      * Unset by default, and unreflected: a tree of choosable nodes is not a tree
      * of links, and an empty `href` written onto every row would be a link to the
@@ -59,7 +55,8 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      */
     href: string;
     /**
-     * Depth from the root, counted by the tree so indentation needs no CSS nesting.
+     * The node's depth from the root. The tree counts it, so indentation needs no
+     * nested CSS.
      *
      * **Read rather than written, and no attribute at all.** The tree counts the
      * items a row sits inside and assigns this on every sync, so a value declared
@@ -79,7 +76,8 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      */
     level?: number;
     /**
-     * What the link declares about where it goes.
+     * The link's `rel` value, which describes how the linked page relates to this
+     * one.
      *
      * Set by the consumer rather than derived from `target`: `noreferrer` is a
      * decision about their own analytics and a component should not make it for
@@ -100,11 +98,11 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      */
     selected: boolean;
     /**
-     * Where the link opens, for the rare row that leaves the site.
+     * Where the link opens. Use it for a row that leaves the site.
      */
     target: string;
     /**
-     * Identifies the item to the consumer, carried in `helix-select`.
+     * Identifies the item to your code. It is sent in `helix-select`.
      */
     value: string;
     /**
@@ -137,10 +135,10 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * row rather than the wrapper around it.
      */
     focusItem(): void;
-    /** Selects this node and announces it. */
+    /** Selects this node and sends `helix-select`. */
     select(): void;
     /**
-     * Chooses this node the way a reader does, from a press or from Enter.
+     * Chooses this node, as a press or Enter does.
      *
      * Selecting and following are two things and this is where they meet, so the
      * pointer and the keyboard take one path to the same end. The tree calls this