@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

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

@@ -2,16 +2,16 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
- * @summary A tree of items, navigable entirely from the keyboard.
+ * @summary A hierarchy of items, with branches that open and close.
  *
  * @description
- * Focus is a single tab stop, moved with the arrow keys, which is what the tree
- * pattern requires: a sidebar of forty items should not be forty presses of Tab
- * to get past. The tree owns which item is the tab stop and moves it as focus
- * moves, so the browser's own focus order is never fought with.
+ * The tree is a single tab stop, and arrow keys move focus between items, as
+ * the tree pattern requires, so Tab moves past a long sidebar in one press. The
+ * tree moves the tab stop to the focused item, so the browser's focus order
+ * stays intact.
  *
  * Items are found with `instanceof`, never by tag name, so the headless tier
- * does not learn about the styled one.
+ * does not depend on the styled one.
  *
  * @since 0.1.0
  * @status stable
@@ -21,13 +21,13 @@ declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.d
  *
  * @slot - The tree's items.
  *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current node 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, because the tree is what a consumer holds a reference to. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixActivateEvent} helix-activate - Fired after the current node changes, so the tree already holds the new one.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current node changes, and cancelable. Canceling it is the only way to stop the change.
+ * @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 empty - Shown when there are no rows to show.
- * @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 loading - Shown while the rows are still on their way.
+ * @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 loading - Shown while the rows load.
  * @csspart tree - The tree container.
  */
 export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
@@ -36,7 +36,8 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
      */
     label: string;
     /**
-     * What a step inward means: nothing, a rank, or a heading over what follows.
+     * What a deeper level means: `peer` for no change, `subordinate` for a lower
+     * rank, or `heading` for a parent that heads the items under it.
      *
      * All three answers are right, for different trees, which is why this is
      * asked rather than decided. `peer` is a file explorer: every row is the same

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

@@ -1,27 +1,26 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Which way a measurement moved, and whether that is good news.
+ * @summary An indicator that shows which way a measurement moved, and whether the change is good.
  *
  * @description
- * Three parts: a direction that is up, down or neutral, the metric that moved,
- * and a label saying over what. The arrow carries the direction and its color
- * carries the judgment, and the two are separate properties because they are
- * separate facts.
+ * A trend has three parts: a direction of up, down, or neutral, the metric that
+ * moved, and a label for the period it moved over. The arrow shows the
+ * direction and its color shows whether the change is good. Direction and
+ * judgment are separate properties because they are separate facts.
  *
- * **`good` is absent by default, so an unjudged trend is gray.** Every
- * dashboard convention says up is green, and for churn, latency, error rate,
- * cost and bounce rate that convention is a lie told in the most legible color
- * on the page. State the metric's polarity once and the component does the part
- * that varies.
+ * `good` is unset by default, so a trend with no judgment is gray. For churn,
+ * latency, error rate, cost, and bounce rate, up is bad. Set the metric's
+ * polarity once with `good`, and the component picks the color from the
+ * direction.
  *
- * The direction is also written as a word, because a colored arrow says
- * nothing to a reader who is not looking at it. `part="direction"` is what the
- * styled tier clips out of sight and leaves in the accessibility tree.
+ * The direction is also written as a word, so a screen reader reads it. The
+ * styled tier hides `part="direction"` visually and keeps it in the
+ * accessibility tree.
  *
- * Both the metric and the label are bare slots. An element whose only job is to
- * assign itself a slot on connect gives its own host an attribute after
- * upgrade, which a React consumer's server markup never had.
+ * The metric and the label are bare slots. An element that assigned its own
+ * slot on connect would add an attribute to its host after upgrade, which the
+ * React server markup did not have.
  *
  * @since 0.1.0
  * @status stable
@@ -30,9 +29,9 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/trend
  *
  * @slot - The metric that moved.
- * @slot label - What it moved over.
+ * @slot label - The period the metric moved over.
  *
- * @csspart direction - The direction as a word, for readers who are not looking.
+ * @csspart direction - The direction as a word, for people who cannot see the arrow.
  * @csspart icon - The arrow.
  */
 export declare class HelixHeadlessTrend extends HelixElement {
@@ -48,7 +47,7 @@ export declare class HelixHeadlessTrend extends HelixElement {
      */
     direction?: 'down' | 'neutral' | 'up';
     /**
-     * Which direction is the improvement, for this metric.
+     * Which direction counts as an improvement for this metric.
      *
      * Absent states the movement without judging it, which is the honest default:
      * revenue up is good news and latency up is bad news, and only the consumer