@fusion.dev/helix 0.105.0 → 0.106.0

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

@@ -1,12 +1,11 @@
 import { HelixHeadlessTag } from '@fusion.dev/helix-headless/tag';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary Labels content with a short piece of metadata.
+ * @summary A short label that adds metadata to content.
  *
  * @description
- * Seven tones. The fill is a tint of the status color, mixed with
- * `color-mix` rather than held as a token per status, so a theme that changes
- * the status colors gets the tints with them.
+ * Seven tones. The fill is a tint of the status color made with `color-mix`, so
+ * when a theme changes its status colors, the tints change with them.
  *
  * @since 0.1.0
  * @status stable
@@ -16,18 +15,18 @@ import type { CSSResultGroup } from 'lit';
  *
  * @slot - The tag's label.
  *
- * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the tag. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixDismissEvent} helix-dismiss - The remove button was pressed. The tag does not remove itself, so remove it in response. Cancelable.
  *
  * @csspart dismiss - The remove button, when `dismissible`.
  *
- * @cssproperty --tag-background-color - Fill behind the tag.
- * @cssproperty --tag-border-color - Color of the edge, for a chip that separates by fill alone.
- * @cssproperty --tag-foreground-color - Label color.
- * @cssproperty --tag-radius - Corner radius of the tag.
+ * @cssproperty --tag-background-color - The fill behind the tag.
+ * @cssproperty --tag-border-color - The color of the tag's edge.
+ * @cssproperty --tag-foreground-color - The label color.
+ * @cssproperty --tag-radius - The corner radius of the tag.
  */
 export declare class HelixTag extends HelixHeadlessTag {
     /**
-     * How much of the tone the tag wears.
+     * How strongly the tag shows its tone: `subtle`, `solid`, or `outlined`.
      *
      * - `subtle` is the default: a wash of the tone with the label in it, for a
      *   tag that labels something rather than warning about it.
@@ -42,7 +41,7 @@ export declare class HelixTag extends HelixHeadlessTag {
      */
     emphasis?: 'outlined' | 'solid' | 'subtle';
     /**
-     * Which status the tag reports.
+     * The meaning the tag's color shows, such as `success` or `danger`.
      *
      * `tone` is semantic color, which is what these are and what `helix-text`
      * already calls them. `helix component`'s `axes` holds the vocabulary.

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

@@ -1,36 +1,29 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A run of text, with the element and the look chosen separately.
+ * @summary Text, with its HTML element and its type style set separately.
  *
  * @description
- * Two properties, and they answer different questions. `as` is the element,
- * which decides the document outline and what a screen reader announces.
- * `variant` is the ramp, which decides size, weight, leading, and tracking
- * together.
+ * `as` sets the element, which decides the document outline and what a screen
+ * reader announces. `variant` sets the type ramp, which decides size, weight,
+ * leading, and tracking together.
  *
- * They are separate because they genuinely come apart: a section's second
- * heading sometimes has to look smaller without lying about the outline, and a
- * `<p>` sometimes has to read as a caption. They default to matching, so the
- * common case is `as="h2"` and nothing else.
+ * The two match by default, so usually you set only `as`, such as `as="h2"`.
+ * Set `variant` when the look and the element differ, such as a heading that
+ * looks smaller or a `<p>` styled as a caption.
  *
- * The pairing is resolved in CSS rather than by computing an attribute, so the
- * element writes nothing to its own host: `as="h2"` picks up the heading ramp
- * through a selector, and setting `variant` takes the pairing rule out of play.
- * Deriving it in `willUpdate` works and must not be done: it puts an attribute
- * on the host that the server's markup does not have, which is a hydration
- * mismatch in every React consumer.
+ * The pairing is resolved in CSS, so the element writes nothing to its host.
+ * `as="h2"` picks up the heading ramp through a selector, and setting `variant`
+ * overrides the pairing. Do not derive it in `willUpdate`, because that adds a
+ * host attribute the server markup does not have, which causes a hydration
+ * mismatch in React.
  *
- * **Size, weight, and leading are not properties.** Exposing them separately
- * offers a few hundred combinations of which a handful are right, and every
- * caller then picks one. A ramp is a decision the system already made:
- * the ramp is named, and a page built from it is consistent because there was
- * nothing else to choose.
+ * Size, weight, and leading are not separate properties. Choose a named ramp
+ * with `variant`.
  *
- * `tone` and `emphasis` stay separate, because color carries state rather than
- * typography, and what a line means is not how loudly it says it. Folding
- * either in would mean `caption-danger` and `label-muted` and the rest of the
- * cross product, which is the explosion a named ramp exists to prevent.
+ * `tone` and `emphasis` are separate from `variant`, because color carries
+ * state. Combining them would need a variant for every pair, such as
+ * `caption-danger` and `label-muted`.
  *
  * @since 0.1.0
  * @status stable
@@ -44,13 +37,13 @@ import type { CSSResultGroup } from 'lit';
  */
 export declare class HelixText extends HelixElement {
     /**
-     * Which element to render.
+     * The HTML element to render.
      *
      * Decides the outline and the semantics.
      */
     as?: 'span' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'strong' | 'em' | 'code' | 'label';
     /**
-     * How loud the text is, beside what it means.
+     * Makes the text quieter: `muted`, or the quieter `subtle`.
      *
      * `muted` is the quiet ink that still has to be read, and `subtle` the
      * quieter one below it. Two axes because the test says so: a line can be a
@@ -67,9 +60,8 @@ export declare class HelixText extends HelixElement {
      */
     emphasis?: 'muted' | 'subtle';
     /**
-     * What the text means. A separate axis from the type ramp, because color
-     * carries state: folding it in would mean `caption-danger` and the rest of the
-     * cross product.
+     * The meaning of the text, shown by its color, such as `danger` or `success`.
+     * It is set separately from `variant`.
      *
      * **There is no `default` value**, and one must not be added: it would match
      * no rule and fall through to the inherited ink, reading as working while
@@ -80,7 +72,7 @@ export declare class HelixText extends HelixElement {
      */
     tone?: 'accent' | 'danger' | 'info' | 'primary' | 'success' | 'warning';
     /**
-     * Type treatment.
+     * The type style, which sets the size, weight, leading, and tracking.
      *
      * Defaults to the one that matches `as`.
      */

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

@@ -1,13 +1,12 @@
 import { HelixHeadlessTextarea } from '@fusion.dev/helix-headless/textarea';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary Several lines of text a reader types into.
+ * @summary A multi-line text field.
  *
  * @description
- * The same frame an `Input` wears, so a form of mixed fields reads as one set
- * rather than as two kinds of box. What differs is the resize handle, which is
- * the platform's and is left alone on the block axis only: a field that can be
- * dragged wider than the form holding it is a field that breaks the layout.
+ * Uses the same frame as `Input`, so mixed fields in a form match. The
+ * platform's resize handle is kept on the block axis only, so the field cannot
+ * be dragged wider than its form.
  *
  * @since 0.1.0
  * @status stable

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

@@ -4,18 +4,16 @@ import '../../icon/index.js';
 import '../../tag/index.js';
 import '../../time-picker/index.js';
 /**
- * @summary A time, typed or picked from a list.
+ * @summary A field for a time, typed or picked from a list.
  *
  * @description
- * The frame is the field rather than the input, so the trigger sits inside the
- * same box as the text and the focus ring is drawn once around the whole
- * control. The trigger is a mark within that box rather than a button beside it,
- * the arrangement Date Input settled on.
+ * The frame wraps the whole field, so the trigger sits in the same box as the
+ * text and the focus ring goes around the whole control. The trigger is drawn
+ * inside that box, as in Date Input.
  *
- * The panel is the field's width, which is the one place this differs from Input
- * Date: a calendar is seven columns with a width of its own, and a list of times
- * is a column of one line each, so it should be as wide as the control it
- * belongs to. That is the same reasoning Select gives for its own list.
+ * The panel is as wide as the field. This is the one difference from Input
+ * Date, whose calendar has seven columns and a width of its own. A list of
+ * times is one column, so it matches the control, as Select's list does.
  *
  * @since 0.1.0
  * @status stable
@@ -25,11 +23,11 @@ import '../../time-picker/index.js';
  *
  * @cssproperty --time-input-background-color - Fill behind the field.
  * @cssproperty --time-input-border-color - Color of the panel's edge.
- * @cssproperty --time-input-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
- * @cssproperty --time-input-shadow - Lift under the panel. Follows `--helix-shadow-floating`:
- *   a floating surface sits over content nobody can predict, so it keeps a lift by default.
+ * @cssproperty --time-input-border-width - Width of the panel's edge. Defaults to
+ *   `--helix-border-floating`, which is `0`, so the panel stands out by its shadow unless
+ *   your theme sets a width.
+ * @cssproperty --time-input-shadow - Shadow under the panel. Defaults to
+ *   `--helix-shadow-floating`, because the panel can sit over any content.
  */
 export declare class HelixTimeInput extends HelixHeadlessTimeInput {
     static tier: string;

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

@@ -3,17 +3,15 @@ import type { CSSResultGroup } from 'lit';
 import '../../listbox/index.js';
 import '../../option/index.js';
 /**
- * @summary Picks a time, from a list of them.
+ * @summary A control for choosing a time from a list or from wheels.
  *
  * @description
- * A bounded list on a surface of its own, because ninety-six rows is taller than
- * anywhere it will be put. `--time-picker-list-block-size` is the bound and it is a height
- * rather than a count of rows: what a panel has is room, and a row count would
- * have to be recomputed every time the density changed.
+ * The list has a bounded height on a surface of its own, because 96 rows are
+ * taller than any place it is used. `--time-picker-list-block-size` sets the
+ * bound as a height, so it does not need recomputing when the density changes.
  *
- * No border and no fill of its own. Flat on a page it takes what it is given,
- * and in Time Input's panel the panel supplies both: a list that brought its own
- * card would be a card inside a card there.
+ * The picker has no border or fill of its own. On a page it takes the space it
+ * is given, and inside Time Input the panel supplies both.
  *
  * @since 0.1.0
  * @status stable
@@ -22,8 +20,8 @@ import '../../option/index.js';
  * @documentation https://fusion.dev/helix/components/time-picker
  *
  * @cssproperty --time-picker-list-block-size - How tall the list is before it scrolls.
- * @cssproperty --time-picker-range-color - Wash behind the times inside a range.
- * @cssproperty --time-picker-row-size - Height and least width of one row in a wheel.
+ * @cssproperty --time-picker-range-color - Fill behind the times inside a range.
+ * @cssproperty --time-picker-row-size - Height and minimum width of one row in a wheel.
  * @cssproperty --time-picker-selected-color - Fill on the chosen row of a wheel.
  * @cssproperty --time-picker-wheel-block-size - How tall a wheel is. Five rows by default.
  */

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

@@ -4,8 +4,8 @@ import type { CSSResultGroup } from 'lit';
  * @summary One event on a timeline: when it happened, and what it was.
  *
  * @description
- * Presentation only: the rail down the side, the mark on it, and the line that
- * arrives at this entry from the one before.
+ * Draws the rail down the side, the mark on it, and the line that arrives from
+ * the previous entry.
  *
  * @since 0.1.0
  * @status stable

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

@@ -1,11 +1,11 @@
 import { HelixHeadlessTimeline } from '@fusion.dev/helix-headless/timeline';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A record of what happened, in the order it happened.
+ * @summary A list of events, in the order they happened.
  *
  * @description
- * Presentation only: the direction time runs in, and the spacing between one
- * event and the next. Every entry draws its own mark and its own line.
+ * Sets the direction time runs in and the spacing between events. Each entry
+ * draws its own mark and line.
  *
  * @since 0.1.0
  * @status stable

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

@@ -4,10 +4,9 @@ import type { CSSResultGroup } from 'lit';
  * @summary One message in the toast region.
  *
  * @description
- * A surface with a shadow, because a toast sits over whatever the reader was
- * looking at rather than in it. The severity is a bar down the leading edge and
- * not a fill: a message is text to be read, and a colored panel behind it
- * costs contrast for something the mark already says.
+ * A surface with a shadow, because a toast sits over the page content. The
+ * severity is a bar along the leading edge, so the message text keeps full
+ * contrast on the surface.
  *
  * @since 0.1.0
  * @status stable
@@ -15,11 +14,11 @@ import type { CSSResultGroup } from 'lit';
  *
  * @cssproperty --toast-border-color - Color of the panel's edge.
  * @cssproperty --toast-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
+ *   `--helix-border-floating`, which is `0`, so the panel stands out by its shadow unless your
+ *   theme sets a border.
  * @cssproperty --toast-item-padding - Space between the message's edge and its contents.
- * @cssproperty --toast-shadow - Lift under the panel. Follows `--helix-shadow-floating`: a
- *   floating surface sits over content nobody can predict, so it keeps a lift by default.
+ * @cssproperty --toast-shadow - Shadow under the panel. Follows `--helix-shadow-floating`. A
+ *   floating surface can sit over any content, so it has a shadow by default.
  */
 export declare class HelixToastItem extends HelixHeadlessToastItem {
     static styles: CSSResultGroup;

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

@@ -1,21 +1,19 @@
 import { HelixHeadlessToast } from '@fusion.dev/helix-headless/toast';
 import type { CSSResultGroup } 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
- * Fixed to the window, and it catches nothing: the region spans a whole edge,
- * so a stack of one message in a corner would otherwise put an invisible bar
- * across everything beside it. The region is transparent to a pointer and the
- * messages take it back.
+ * Fixed to the window. The region spans a whole edge, so it ignores the pointer
+ * and only the messages receive clicks. Content beside a message stays
+ * clickable.
  *
- * **It belongs at the root of the application.** `position: fixed` is
- * positioned against the viewport only while no ancestor carries `transform`,
- * `filter`, `perspective` or `contain`, any of which makes that ancestor the
- * containing block instead, and it is still clipped by an ancestor with
- * `overflow: hidden`. That is a real constraint rather than a style note, and
- * it is the same fact that put every other floating surface in this library
- * into the top layer.
+ * **Place the region at the root of your application.** `position: fixed`
+ * positions against the viewport only while no ancestor has `transform`,
+ * `filter`, `perspective`, or `contain`. Any of these makes that ancestor the
+ * containing block, and an ancestor with `overflow: hidden` still clips the
+ * region. The other floating surfaces in Helix use the top layer for the same
+ * reason.
  *
  * @since 0.1.0
  * @status stable

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

@@ -4,15 +4,13 @@ import type { CSSResultGroup } from 'lit';
  * @summary A row of options with the selection marked by a moving indicator.
  *
  * @description
- * The indicator travels between items rather than the fill swapping. A fill
- * that appears on one item as it disappears from another is two changes at once
- * and reads as a flicker; one object moving is something the eye follows, and
- * it says where the selection came from as well as where it went.
+ * The indicator moves between items, so a change of selection is one moving
+ * object the eye can follow.
  *
- * It animates `translate` and `inline-size`. Width is a layout property and the
- * rule is transform and opacity only, but the indicator is out of flow, so
- * animating its width reflows nothing else. Scaling instead would distort the
- * corner radius, which is worse than the exception.
+ * It animates `translate` and `inline-size`. Animating width is an exception to
+ * the transform and opacity rule, and it is safe because the indicator is out
+ * of flow and its width reflows nothing else. Scaling would distort the corner
+ * radius.
  *
  * @since 0.1.0
  * @status stable
@@ -20,16 +18,16 @@ import type { CSSResultGroup } from 'lit';
  * @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.
  *
  * @csspart indicator - The moving marker behind the selected item.
  *
- * @cssproperty --toggle-group-indicator-color - Fill of the moving marker.
+ * @cssproperty --toggle-group-indicator-color - The fill of the moving marker.
  */
 export declare class HelixToggleGroup extends HelixHeadlessToggleGroup {
     /**
-     * How the group separates itself from the page.
+     * How the group is set apart from the page.
      *
      * Separation rather than emphasis, because what `plain` drops is the
      * background *and* the border: the question is where the group ends, not how

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

@@ -4,9 +4,8 @@ import type { CSSResultGroup } from 'lit';
  * @summary One option in a toggle group.
  *
  * @description
- * Carries no background of its own. The selected look comes from the group's
- * indicator sitting behind it, which is what lets that marker travel instead of
- * one fill appearing as another disappears.
+ * Has no background of its own. The selected look comes from the group's
+ * indicator behind it, which moves between items.
  *
  * @since 0.1.0
  * @status stable

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

@@ -4,8 +4,8 @@ import type { CSSResultGroup } from 'lit';
  * @summary A group of controls that share one tab stop.
  *
  * @description
- * No chrome of its own: a toolbar is a place controls sit, and a border around
- * them would be a second frame inside whatever already frames the bar.
+ * The toolbar draws no frame of its own, so it does not add a second frame
+ * inside whatever already frames the bar.
  *
  * @since 0.1.0
  * @status stable
@@ -17,7 +17,7 @@ import type { CSSResultGroup } from 'lit';
  *
  * @csspart toolbar - The toolbar container.
  *
- * @cssproperty --toolbar-gap - Space between controls.
+ * @cssproperty --toolbar-gap - The space between controls.
  */
 export declare class HelixToolbar extends HelixHeadlessToolbar {
     static styles: CSSResultGroup;

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

@@ -1,14 +1,14 @@
 import { HelixHeadlessTooltip } from '@fusion.dev/helix-headless/tooltip';
 import type { CSSResultGroup } from 'lit';
 /**
- * @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 bubble is in the top layer, so it needs no `z-index` and cannot be
- * clipped by whatever it sits inside.
+ * The bubble is in the top layer, so it needs no `z-index` and no container
+ * clips it.
  *
- * The arrow is positioned by the same pass that positions the bubble, so it
- * still points at the trigger after the bubble has slid along to stay in view.
+ * The arrow is positioned in the same pass as the bubble, so it still points at
+ * the trigger after the bubble shifts to stay in view.
  *
  * @since 0.1.0
  * @status stable
@@ -17,14 +17,14 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Hint, Popup label
  * @documentation https://fusion.dev/helix/components/tooltip
  *
- * @cssproperty --tooltip-arrow-size - Size of the point at the bubble's edge.
- * @cssproperty --tooltip-backdrop - Blur behind a `frosted` or `glass` bubble.
- * @cssproperty --tooltip-background-color - Fill of the bubble.
- * @cssproperty --tooltip-max-inline-size - Widest the bubble grows before wrapping.
+ * @cssproperty --tooltip-arrow-size - The size of the arrow on the bubble's edge.
+ * @cssproperty --tooltip-backdrop - The blur behind a `frosted` or `glass` bubble.
+ * @cssproperty --tooltip-background-color - The fill of the bubble.
+ * @cssproperty --tooltip-max-inline-size - The widest the bubble grows before its text wraps.
  */
 export declare class HelixTooltip extends HelixHeadlessTooltip {
     /**
-     * What the bubble is made of.
+     * The bubble's surface: `frosted` or `glass`.
      *
      * Absent is the inverse bubble, a dark surface over a light page, which is
      * what a hint over content the theme cannot know has always been here. `glass`

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

@@ -1,20 +1,19 @@
 import { HelixHeadlessTour } from '@fusion.dev/helix-headless/tour';
 import type { CSSResultGroup } from 'lit';
 /**
- * @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
- * It draws the light and nothing else: the scrim's color and the lit box's
- * corners are this tier's, and the order, the stops and the measuring stay
- * below.
+ * Draws the spotlight: the scrim's color and the corners of the lit box. The
+ * order, the stops, and the measuring are in the headless tier.
  *
  * @since 0.1.0
  * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *
- * @cssproperty --tour-scrim-color - The darkness outside the lit box.
- * @cssproperty --tour-spotlight-radius - Corner radius of the lit box.
+ * @cssproperty --tour-scrim-color - The color of the dimmed area outside the spotlight.
+ * @cssproperty --tour-spotlight-radius - The corner radius of the spotlight.
  */
 export declare class HelixTour extends HelixHeadlessTour {
     static styles: CSSResultGroup;

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

@@ -2,28 +2,28 @@ import { HelixHeadlessTourStop } from '@fusion.dev/helix-headless/tour';
 import type { CSSResultGroup } 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
- * The panel is `Popover`'s panel by another name, on purpose: a surface, an
- * inset and a lift, so a stop and a flyout on the same page are the same
- * object. What this tier adds beyond that is the point, which no other surface
- * here draws.
+ * The panel uses the same styles as `Popover`'s panel, with a surface, an
+ * inset, and a shadow, so a stop matches a popover on the same page. The styled
+ * tier adds the pointer toward the target, which no other Helix surface draws.
  *
  * @since 0.1.0
  * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *
- * @cssproperty --tour-arrow-size - The point's box, before it is rotated.
- * @cssproperty --tour-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
- * @cssproperty --tour-bubble-size - How wide the panel may grow.
- * @cssproperty --tour-padding - Inset inside the panel.
- * @cssproperty --tour-shadow - Lift under the panel. Follows `--helix-shadow-floating`: a
- *   floating surface sits over content nobody can predict, so it keeps a lift by default.
- * @cssproperty --tour-surface-color - The panel's own surface.
+ * @cssproperty --tour-arrow-size - The size of the arrow's box, before it is rotated.
+ * @cssproperty --tour-border-width - The width of the panel's border. It follows
+ *   `--helix-border-floating`, which is `0`, so the panel stands out by its
+ *   shadow unless a theme sets a border.
+ * @cssproperty --tour-bubble-size - The widest the panel can grow.
+ * @cssproperty --tour-padding - The padding inside the panel.
+ * @cssproperty --tour-shadow - The shadow under the panel. It follows
+ *   `--helix-shadow-floating`. The panel can sit over any content, so it has a
+ *   shadow by default.
+ * @cssproperty --tour-surface-color - The color of the panel's surface.
  */
 export declare class HelixTourStop extends HelixHeadlessTourStop {
     static tier: string;

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

@@ -4,14 +4,11 @@ import type { CSSResultGroup } from 'lit';
  * @summary One node in a tree.
  *
  * @description
- * Indent comes from the `level` the tree sets, as a multiple of one hook, so a
- * node moved to another depth re-indents without any nested selector. Nesting
- * selectors by depth is the usual approach and stops working at whatever depth
- * nobody wrote a rule for.
+ * Indentation is a multiple of one hook, set from the `level` the tree assigns,
+ * so an item moved to another depth re-indents with no nested selectors, at any
+ * depth.
  *
- * The twisty rotates rather than swapping glyphs, so opening a branch is a
- * short movement instead of a substitution. Motion carries the state change;
- * the row itself stays flat.
+ * The twisty rotates when a branch opens. The row itself stays flat.
  *
  * @since 0.1.0
  * @status stable
@@ -21,7 +18,7 @@ import type { CSSResultGroup } from 'lit';
  * @slot - The item's label.
  * @slot children - Nested items, which make this a branch.
  *
- * @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, and cancelable. Canceling it changes nothing.
  *
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target.
@@ -32,7 +29,7 @@ import type { CSSResultGroup } from 'lit';
  * @cssproperty --tree-chevron-size - Size of the chevron, and the gutter a leaf reserves.
  * @cssproperty --tree-gap - Space between rows.
  * @cssproperty --tree-indent - Indent added per level.
- * @cssproperty --tree-row-size - Least height of a row, so rows with and without an icon match.
+ * @cssproperty --tree-row-size - Minimum height of a row, so rows with and without an icon match.
  */
 export declare class HelixTreeItem extends HelixHeadlessTreeItem {
     static styles: CSSResultGroup;

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

@@ -1,12 +1,11 @@
 import { HelixHeadlessTree } from '@fusion.dev/helix-headless/tree';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A tree of items, navigable entirely from the keyboard.
+ * @summary A hierarchy of items, with branches that open and close.
  *
  * @description
  * Quiet by default: no rules between rows and no fill except on the selected
- * item. A navigation tree is read by scanning, and every line of chrome added
- * to it is one more thing between the reader and the label.
+ * item, so the labels are easy to scan.
  *
  * @since 0.1.0
  * @status stable
@@ -16,17 +15,17 @@ import type { CSSResultGroup } from 'lit';
  *
  * @slot - The tree's items.
  *
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here, because the tree is what a consumer holds a reference to. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. The item sends it, and you can listen for it on the tree. Cancelable: canceling it changes nothing.
  *
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
+ * @csspart live - A copy of the empty and loading messages, in a live region that announces them when they change. Visually hidden in the styled tier.
  * @csspart tree - The tree container.
  *
- * @cssproperty --tree-chevron-gap - Set from `chevron-placement`; the space before the chevron.
- * @cssproperty --tree-chevron-order - Set from `chevron-placement`; read by each item.
+ * @cssproperty --tree-chevron-gap - The space before the chevron. Set from `chevron-placement`.
+ * @cssproperty --tree-chevron-order - The chevron's order in the row. Set from `chevron-placement` and read by each item.
  * @cssproperty --tree-chevron-size - Size of the chevron, and the gutter a leaf reserves.
  * @cssproperty --tree-gap - Space between rows.
  * @cssproperty --tree-indent - Indent added per level.
- * @cssproperty --tree-row-size - Least height of a row, so rows with and without an icon match.
+ * @cssproperty --tree-row-size - Minimum height of a row, so rows with and without an icon match.
  */
 export declare class HelixTree extends HelixHeadlessTree {
     /**