@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -1,38 +1,32 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Two panes and a divider the reader can move.
+ * @summary Two panes and a divider that you can move.
  *
  * @description
- * **One axis, and nesting is how you get two.** A splitter inside a splitter
- * gives back the cross, and gives the three-pane and four-pane arrangements a
- * single divider never had.
+ * A splitter has one axis. Nest splitters to get two axes and three-pane or
+ * four-pane layouts.
  *
- * **Where two of them cross there is a corner, and it moves both.** A splitter
- * slotted into a pane of another, at right angles to it, grows a handle at the
- * crossing: `move` under the pointer, both arrow axes on the keyboard, and a
- * drag that carries the two positions at once. It appears at `firstUpdated`
- * rather than in the served markup, being an affordance rather than content,
- * and a splitter with no corner yet is a splitter with two working dividers.
+ * When a splitter is slotted into a pane of another at a right angle, a corner
+ * handle appears where the dividers cross. It shows the `move` cursor, responds
+ * to both arrow axes, and a drag moves both dividers at once. The corner is
+ * added at `firstUpdated` and is not in the server markup. Before it appears,
+ * both dividers work on their own.
  *
- * **The divider is a real `role="separator"` with `aria-valuenow`**, moved by
- * the arrow keys as well as by pointer, with `Home` and `End` taking it to its
- * bounds. A drag in progress is a state rather than `:hover`, so both dividers
- * a corner moves are lit for as long as it moves them.
+ * The divider has `role="separator"` and `aria-valuenow`. Drag it with a
+ * pointer or move it with the arrow keys, and press `Home` or `End` to move it
+ * to its bounds. A drag in progress is tracked as a state, so both dividers a
+ * corner moves stay lit for as long as they move.
  *
- * **It goes where it is put, all the way to either end.** `min` and `max` are
- * nothing and everything unless a consumer says otherwise, because a divider
- * that stops short of the edge gives a reader no way to put a pane away.
+ * By default, `min` and `max` let the divider reach either edge, so you can
+ * drag a pane fully closed. Set them to limit the range.
  *
- * **A pane can be shut, and that is not the same as a divider at the edge.**
- * The geometry is identical and the knowledge is not: only a shut pane knows
- * where to open back to. So `collapsed` is a second state rather than a reading
- * of the position, and the position it opens to is where the gesture that shut
- * it began, whichever gesture that was: a drag takes its reading on the press,
- * and every other door takes it in `settle`, nothing having been applied there
- * yet. `collapsed-size` keeps a sliver showing where a pane has a tab strip
- * worth leaving, and collapse overrides `min` and `max`, which is what those
- * are for.
+ * A pane can be collapsed, which is a separate state from a divider at the
+ * edge. `collapsed` names the shut pane, `start` or `end`, and the pane opens
+ * back to the position where the collapsing gesture began. A drag records that position
+ * on press, and every other way of collapsing records it in `settle`.
+ * `collapsed-size` keeps a sliver of the pane visible, such as a tab strip.
+ * Collapsing overrides `min` and `max`.
  *
  * @since 0.1.0
  * @status stable
@@ -40,16 +34,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases SplitPane, Resizable, SplitView
  * @documentation https://fusion.dev/helix/components/splitter
  *
- * @slot end - The pane after it.
+ * @slot end - The pane after the divider.
  * @slot start - The pane before the divider.
  *
- * @event {HelixBeforeCollapseEvent} helix-before-collapse - Fired before a pane shuts or reopens, whether or not the resize that reached it was allowed, and carrying its own position: a shut pane sits at `collapsed-size` rather than at the number the resize named. Cancelable: refusing it leaves the pane as it was and the divider where the gesture put it.
- * @event {HelixBeforeResizeEvent} helix-before-resize - Fired before the divider settles, and only where the gesture moved it: a press that moved nothing, a drag that came back, an arrow with nowhere left to go and a corner that moved the other divider are all silent on this one. Cancelable: refusing it takes the position and leaves the rest of the gesture, so a collapse the gesture reached is still announced and still yours to refuse. A drag has already drawn itself by then and holds where it was dropped until the consumer assigns their own.
+ * @event {HelixBeforeCollapseEvent} helix-before-collapse - Fired before a pane shuts or reopens, whether or not the resize that caused it was allowed. It carries its own position, because a shut pane sits at `collapsed-size`. Cancelable: canceling it leaves the pane as it was and the divider where the gesture put it.
+ * @event {HelixBeforeResizeEvent} helix-before-resize - Fired before the divider settles, and only when the gesture moved it. A press that moved nothing, a drag that came back, an arrow key with no room left, and a corner that moved only the other divider do not fire it. Cancelable: canceling it leaves the position to you and keeps the rest of the gesture, so a collapse the gesture reached still fires `helix-before-collapse`, which you can also cancel. A dragged divider stays where it was dropped until you set your own `position`.
  *
  * @csspart corner - The handle where two dividers cross, added on the client.
- * @csspart end - The box holding the second.
+ * @csspart end - The box that holds the second pane.
  * @csspart separator - The divider itself.
- * @csspart start - The box holding the first pane.
+ * @csspart start - The box that holds the first pane.
  *
  * @cssproperty --splitter-corner-at - Where a nested splitter crosses this one, as a percentage.
  * @cssproperty --splitter-position - Where the divider sits, as a percentage of the box.
@@ -71,7 +65,7 @@ export declare class HelixHeadlessSplitter extends HelixElement {
     get collapsed(): 'end' | 'start' | undefined;
     set collapsed(next: 'end' | 'start' | undefined);
     /**
-     * What the divider says while a pane is shut, in place of a number.
+     * The divider's value while a pane is shut, as text in place of a number.
      *
      * **A shut pane is off the scale the divider reports**, which is `min` to
      * `max`, the sliver a drag keeps. The divider said a value outside its own
@@ -89,27 +83,27 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      */
     collapsedSize: number;
     /**
-     * Accessible name for the handle where two dividers cross.
+     * The name of the handle where two dividers cross, read by screen readers.
      */
     cornerLabel: string;
     /**
-     * Which pane starts shut, where nothing declared it.
+     * Which pane starts shut, when `collapsed` is not set.
      */
     defaultCollapsed?: 'end' | 'start';
     /**
-     * Where the divider starts, where nothing declared it.
+     * Where the divider starts, when `position` is not set.
      */
     defaultPosition: number;
     /**
-     * Accessible name for the divider.
+     * The divider's name, read by screen readers.
      */
     label: string;
     /**
-     * Nearest it may come to the end, on the same terms as `min`.
+     * How close the divider can come to the end, in the same units as `min`.
      */
     max: number | string;
     /**
-     * Nearest the divider may come to the start.
+     * How close the divider can come to the start.
      *
      * A bare number is a percentage, which is what this always took. A CSS length
      * is resolved against the splitter's own box along its axis, so `min="15rem"`
@@ -178,7 +172,7 @@ export declare class HelixHeadlessSplitter extends HelixElement {
     get position(): number;
     set position(next: number);
     /**
-     * How far one arrow press moves it, as a percentage.
+     * How far one arrow key press moves the divider, as a percentage.
      */
     step: number;
     /** The position, whoever set it, and `undefined` until somebody has. */
@@ -270,7 +264,8 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      */
     private origin;
     /**
-     * Moves the divider, and optionally says so.
+     * Moves the divider. With `settled` set, it also fires the events for a
+     * finished move.
      *
      * Public because a corner on a nested splitter has to drive the one it is
      * nested in, and that is the whole of what it needs: the pair are not
@@ -322,7 +317,8 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      */
     private watchWidth;
     /**
-     * Public because a nested splitter compares axes with the one it is in.
+     * Whether the panes are stacked. Public because a nested splitter compares
+     * its axis with the one it is in.
      *
      * The one place the axis is decided, which is why `auto` costs a single line
      * here rather than a pass over seventeen readers: the drag, the arrow keys and

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

@@ -4,9 +4,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A row of related measurements.
  *
  * @description
- * A group rather than a list, because the figures are read together and their
- * order carries no meaning: a list would announce "1 of 4" for a set where the
- * position is not information.
+ * Screen readers announce the stats as a group. The figures are read together
+ * and their order has no meaning, so the group does not announce positions such
+ * as "1 of 4".
  *
  * @since 0.1.0
  * @status stable
@@ -17,7 +17,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessStatGroup extends HelixElement {
     /**
-     * Accessible name for the set.
+     * Accessible name for the group.
      */
     label: string;
     protected willUpdate(changed: PropertyValues): void;

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

@@ -1,17 +1,16 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary One measurement, with the word for what it measures.
+ * @summary One measurement, with a label that names what it measures.
  *
  * @description
- * Label first in the markup and the value after it, which is the reading order
- * a screen reader takes and the order a caption sits above a figure. The eye
- * lands on the number either way, because the number is the loud thing; a
- * reader hearing it needs to know what it counts before hearing how many.
+ * The label comes first in the markup and the value after it, so a screen
+ * reader reads what the figure counts before the number. Visually, the number
+ * stands out either way.
  *
- * Both 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.
+ * Both are bare slots. An element that assigned itself a slot on connect would
+ * add an attribute after upgrade, which markup rendered on the server by React
+ * does not have.
  *
  * @since 0.1.0
  * @status stable
@@ -21,7 +20,7 @@ import { type TemplateResult } from 'lit';
  *
  * @slot - The value.
  * @slot label - What the value measures.
- * @slot unit - The unit, set beside the value.
+ * @slot unit - The unit, shown beside the value.
  */
 export declare class HelixHeadlessStat extends HelixElement {
     /**

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

@@ -2,19 +2,16 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
- * @summary A sequence of stages, and where the reader is in it.
+ * @summary A sequence of stages that shows which stage the user is on.
  *
  * @description
- * **`active` names where the reader is. `complete` stays on each step.** Only
- * one of them is positional: return to stage one of three and stages one and
- * two are still finished, where "everything before the active one" says only
- * the first is. So this element drives `current` and never touches `complete`.
+ * `active` sets where the user is, and `complete` stays on each step. Returning
+ * to stage one of three leaves stages one and two finished, so the root sets
+ * `current` on the steps and never changes `complete`.
  *
- * **`active` is optional, and a sequence without it still renders.** Left
- * unset, each step's own `current` stands, which is what lets the whole
- * sequence be right in the server's markup: this element would have to count
- * its slotted children to know which is third, and the server has none to
- * count.
+ * `active` is optional. Without it, each step keeps its own `current`, so the
+ * sequence is correct in the server's markup, where the root cannot count its
+ * slotted children.
  *
  * @since 0.1.0
  * @status stable
@@ -24,13 +21,13 @@ declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.
  *
  * @slot - The steps.
  *
- * @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 active step changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixSelectEvent} helix-select - Fired when a step is pressed. Dispatched by the step and listened for here, because the root is what a consumer holds. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixActivateEvent} helix-activate - Fired after the current step changes, when the element already holds the new step.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active step changes. Cancelable: cancel it to keep the current step.
+ * @event {HelixSelectEvent} helix-select - Fired when a step is pressed. The step dispatches it, and you can listen for it on the sequence. Cancelable: cancel it to keep the current step.
  */
 export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     /**
-     * Accessible name for the sequence.
+     * The sequence's name, read by screen readers.
      *
      * A list of stages is a landmark a reader arrives at out of order, so it
      * needs a name of its own rather than borrowing the heading above it.

package/dist/steps/step/step.d.ts

@@ -5,28 +5,21 @@ import '../../button/index.js';
  * @summary One stage in a sequence.
  *
  * @description
- * **The name is a button, and only the name.** The marker is `aria-hidden`
- * decoration, so wrapping it would add hit area and no meaning. It is `Button`
- * rather than a `<button>` this element resets: the hover wash, the focus ring
- * and the disabled treatment are decisions the button carries.
+ * Only the step's name is a button. The marker is `aria-hidden` decoration, so
+ * it is outside the button. The name uses `Button`, so the hover wash, the
+ * focus ring, and the disabled style come from `Button`.
  *
- * **It says nothing about where a reader may go.** Every step is pressable and
- * announces itself with `helix-select`; refusing the ones ahead is `disabled`,
- * which the consumer sets, because only they know whether a form can be
- * skipped.
+ * Every step can be pressed and fires `helix-select`. To stop the user from
+ * moving to a step, set `disabled` on it.
  *
- * **The marker is a slot whose fallback is the state.** A finished stage shows
- * a check, the current one a target, one not yet reached an empty ring. Exactly
- * one is rendered, chosen from the step's own two booleans, rather than three
- * with two hidden in CSS: the accessibility tree would otherwise carry marks
- * that are not there.
+ * The marker is a slot, and its fallback shows the step's state: a check for a
+ * finished stage, a target for the current stage, and an empty ring for a stage
+ * not reached yet. Only that one mark is rendered, so the accessibility tree
+ * has no hidden marks.
  *
- * **The two half lines either side of the mark are a sheet's, on `::before` and
- * `::after` of the step.** Both are placed entirely from properties the list
- * hands down, so there was nothing about them for a box to carry, and this tier
- * ships no CSS: a box it rendered for one to paint would be an empty child
- * costing whatever the consumer's own layout charges for a child. `ListItem`
- * measured that.
+ * The half lines on each side of the mark are drawn on the step's `::before`
+ * and `::after` from properties the list sets, so the step renders no extra
+ * element for them.
  *
  * @since 0.1.0
  * @status stable
@@ -34,38 +27,38 @@ import '../../button/index.js';
  * @documentation https://fusion.dev/helix/components/steps
  *
  * @slot - The step's name.
- * @slot content - What the stage holds. Always rendered here, a tier with no stylesheet having nothing to fold it with, so whether it is folded away is the sheet's answer and not this tier's.
- * @slot description - A line under the name, for what the stage is for.
+ * @slot content - The stage's content. The headless tier always renders it, because it has no stylesheet to collapse it with. Your stylesheet decides whether it is collapsed.
+ * @slot description - A line under the name that describes the stage.
  * @slot marker - Replaces the number, or the check a complete step shows.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the step is pressed. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the step is pressed. Cancelable: cancel it to keep the current step.
  *
  * @csspart body - The name and its description.
  * @csspart content - What the stage holds, while it is open.
- * @csspart description - The line under it.
+ * @csspart description - The line under the name.
  * @csspart label - The step's name, which is a control.
- * @csspart label-button - The inner control.
+ * @csspart label-button - The button inside the label.
  * @csspart mark - The glyph inside the marker: a tick, a dot, or an empty ring.
  * @csspart marker - The shape carrying the number or the check.
  */
 export declare class HelixHeadlessStep extends HelixElement {
     /**
-     * Whether the reader has finished this stage.
+     * Whether this stage is finished.
      */
     complete: boolean;
     /**
-     * Whether this is the stage the reader is in.
+     * Whether this is the current stage.
      */
     current: boolean;
     /**
-     * Whether the reader may go to this stage.
+     * Whether the stage is disabled, so the user cannot go to it.
      */
     disabled: boolean;
     /**
-     * What this stage is called when it announces itself.
+     * The value the step sends in `helix-select`.
      */
     value: string;
-    /** Announces the step, unless it is refusing. */
+    /** Fires `helix-select` for the step, unless the step is `disabled`. */
     select(): void;
     /**
      * The mark this stage's state calls for.

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

@@ -5,21 +5,18 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * @summary A control that turns something on or off.
  *
  * @description
- * **A switch is not a checkbox with a different shape.** A checkbox is an
- * answer to a question the form asks when it is submitted; a switch is a thing
- * happening now. That is why `role="switch"` exists and why a switch belongs
- * outside a form as often as in one: it says "on" and "off" rather than
- * "ticked" and "unticked", and a reader expects the effect immediately rather
- * than on Save.
+ * A switch turns something on or off right away, and a checkbox is an answer
+ * the form submits later. A screen reader announces `role="switch"` as "on" or
+ * "off", and people expect the change to take effect immediately. A switch is
+ * as common outside a form as inside one.
  *
- * Rendered as a real `<input type="checkbox">` carrying `role="switch"`, which
- * is the pairing ARIA describes: the input is what a form submits and what a
- * label forwards a press to, and the role is what a screen reader announces.
- * Neither half can be got from the other.
+ * It renders a real `<input type="checkbox">` with `role="switch"`, the pairing
+ * ARIA describes. The input is what a form submits and what a label forwards a
+ * press to, and the role is what a screen reader announces.
  *
- * The label sits beside it, inside the `<label>` that forwards the press, the
- * way a checkbox's does. The hint and the message go under the row, because
- * there is no above: the switch and the words naming it are one line.
+ * The label sits beside the switch, inside the `<label>` that forwards the
+ * press, the same as a checkbox. The hint and the message go below the row,
+ * because the switch and its label share one line.
  *
  * @since 0.1.0
  * @status stable
@@ -27,25 +24,24 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * @aliases Toggle switch, On/off
  * @documentation https://fusion.dev/helix/components/switch
  *
- * @slot - The words naming what this turns on.
+ * @slot - The label that names what the switch turns on.
  *
- * @event {Event} change - Relayed from the input once the state has changed.
+ * @event {Event} change - Sent from the input after the state changes.
  * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
- * @event {Event} input - Announced once the state has moved.
+ * @event {Event} input - Sent after the state changes.
  *
  * @csspart control - The input.
- * @csspart feedback - What is wrong with it.
+ * @csspart feedback - The message that says what is wrong.
  * @csspart field - The row: the track and its label.
  * @csspart hint - Help under the control, while nothing is wrong.
- * @csspart label - The words beside it.
- * @csspart track - The groove. The thumb that travels in it is drawn on the
- * groove itself, which is `::part(track)::after` from a consumer's sheet: this
- * tier ships no CSS, so a box it renders for one to paint is an empty child
- * costing whatever the consumer's own layout charges for a child. `ListItem`
- * measured that.
+ * @csspart label - The label beside the track.
+ * @csspart track - The track. Draw the thumb on the track itself, with
+ * `::part(track)::after` in your stylesheet. This tier ships no CSS, so it
+ * renders no separate thumb element, which would be an empty child that costs
+ * your layout as much as any other child. `ListItem` measured that cost.
  *
  * @cssstate checked - While it is on.
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessSwitch extends HelixHeadlessSwitch_base {
     protected readonly aria: AriaForwardController;

package/dist/table/cell/table-cell.d.ts

@@ -4,13 +4,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary One cell of a table.
  *
  * @description
- * Carries its own role, because a grid of divs is not a table to anything
- * reading it. `header` makes the cell a `columnheader`, which is what lets a
- * screen reader announce "Attribute, appearance" rather than just the value.
+ * Sets its own role, because a grid of elements has no table structure for
+ * assistive technology otherwise. `header` makes the cell a `columnheader`, so
+ * a screen reader announces the heading with the value, for example "Attribute,
+ * appearance".
  *
- * The role goes on the host rather than inside the shadow root, because the
- * cell has to be a child of its row in the flat tree for the table's structure
- * to hold together.
+ * The role is on the host so the cell stays a child of its row in the flat
+ * tree, which keeps the table structure intact.
  *
  * @since 0.1.0
  * @status stable
@@ -19,14 +19,24 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The cell's content.
  *
- * @cssproperty --table-cell-align - The edge the column this cell sits under is set to, `start`, `center` or `end`, and unset under a column that sets none. Written by the table around it, since the cell is the consumer's markup and nothing is written onto it; read by the sheet that draws the cell, where `justify-content` and `text-align` both take it as it comes and both follow the writing direction.
+ * @cssproperty --table-cell-align - The text alignment of the column above the cell: `start`, `center`, or `end`, and unset when the column sets none. The table writes it, and the stylesheet that draws the cell reads it for `justify-content` and `text-align`, which both follow the writing direction.
+ *
+ * @cssstate text - The cell holds text of its own, beside or instead of elements, so the stylesheet lets its content flow as a line of text.
  */
 export declare class HelixHeadlessTableCell extends HelixElement {
     /**
-     * Whether the cell heads its column.
+     * Whether the cell is the header cell of its column.
      */
     header: boolean;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Sets the `text` state from the cell's own content.
+     *
+     * Only text nodes count, and only ones with more than whitespace. A cell of
+     * elements alone keeps its elements laid out as they were, which is what a
+     * lone tag, button, or block of text wants.
+     */
+    private readonly handleSlotChange;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/table/cell/table-cell.js

@@ -11,13 +11,17 @@ let HelixHeadlessTableCell = class HelixHeadlessTableCell extends HelixElement {
     constructor() {
         super(...arguments);
         this.header = false;
+        this.handleSlotChange = () => {
+            const text = [...this.childNodes].some((node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '');
+            this.toggleState('text', text);
+        };
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: this.header ? 'columnheader' : 'cell' });
     }
     render() {
-        return html `<slot></slot>`;
+        return html `<slot @slotchange=${this.handleSlotChange}></slot>`;
     }
 };
 __decorate([