@fusion.dev/helix-headless 0.105.0 → 0.107.0

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([

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

@@ -31,51 +31,49 @@ export declare const at: (row: Readonly<Record<string, unknown>>, path: string)
  */
 export declare const edgeOf: (align: string | undefined) => string | undefined;
 /**
- * @summary One column of a table: its heading, how wide it is, and what it reads.
+ * @summary One column of a table: its heading, its width, and the field it reads from each row.
  *
  * @description
- * **The column is the source of both its heading and its track.** Add one and
- * the table has another track; remove one and it does not. That is what ties
- * the two together, and a table-level track list on its own does not: a list
- * that is accidentally the headings is invalid CSS a grid ignores in silence,
- * drawing the whole table as one column. `Table`'s `columns` is dealt out a
- * track at a time against the columns declared under it, so a heading among the
- * widths costs its own column a width and no more, and a list longer or shorter
- * than the columns is trimmed or shared rather than being a second count of
- * them. A column's own `width` wins over the track in its place.
+ * Each column provides both its heading and its grid track. Adding a column
+ * adds a track, and removing one removes it. `Table`'s `columns` is applied one
+ * track at a time to the columns declared under it:
  *
- * **It is also where every per-column fact goes**, which is the reason
- * `DataTable` needs no column config object. `field` names the key the cell
- * reads, `sortable` says a reader may reorder by it, `text-align` says which edge
- * the values line up against, and `cell` takes a function for anything the
- * field alone cannot express. The schema is markup and the data is a property:
- * a schema is small, declarative, and something a reader should be able to see
- * in the HTML, and data is large and windowed.
+ * - A heading name in the list affects only its own column's width.
+ * - A list longer or shorter than the columns is trimmed or shared.
+ * - A column's own `width` overrides the track in its place.
  *
- * **The same element serves both tables**, the markup one and the data one. It
- * is identified by a flag rather than by `instanceof`, so a `TableColumn` works
- * inside either without the two roots sharing anything else.
+ * This protects the table from a track list that contains the headings by
+ * mistake, which is invalid CSS that the grid ignores silently, drawing the
+ * whole table as one column.
  *
- * **It generates no box of its own**, the same as a row: the heading is a grid
- * item of the table, so it lines up with the cells under it rather than sitting
- * in a wrapper that has to be kept the same width.
+ * Every per-column setting goes on the column, so `DataTable` needs no column
+ * configuration object:
  *
- * **`hidden` takes the column out of the grid**, its heading and its track
- * both, so the columns after it keep their own widths and every row keeps its
- * cells under their headings. `hidden="until-found"` keeps its track, the
- * heading being left drawn, as every Helix element leaves one with that value.
- * `DataTable` draws the cells, so it leaves out the ones under a hidden column.
- * A `Table`'s cells are markup the consumer wrote, so hide them with the
- * column, as removing a column means removing its cells: a row with a cell more
- * than the table has tracks wraps into the next.
+ * - `field` names the key the cell reads.
+ * - `sortable` lets people sort by the column.
+ * - `text-align` sets which edge the values line up against.
+ * - `cell` takes a function for anything `field` alone cannot express.
  *
- * **A heading that does something holds a control that does it.** The host is
- * the column header, and a header is not focusable, so a sortable heading is a
- * `<button>` inside it: the pattern for a sortable table, and the only way a
- * reader on a keyboard reaches the sort at all. A column a reader may resize
- * carries a `separator` on its end edge, moved by dragging it or with the arrow
- * keys, and a column in a table that lets a reader reorder its columns carries
- * a grip the table moves.
+ * The same element works in both `Table` and `DataTable`. It is identified by a
+ * flag, so the two roots share nothing else.
+ *
+ * The column generates no box of its own, the same as a row. The heading is a
+ * grid item of the table, so it lines up with the cells below it.
+ *
+ * `hidden` takes the column out of the grid, both its heading and its track, so
+ * the other columns keep their widths and every row keeps its cells under their
+ * headings. `hidden="until-found"` keeps the track and leaves the heading
+ * drawn, as it does on every Helix element. `DataTable` leaves out the cells
+ * under a hidden column. In a `Table` the cells are markup you wrote, so hide
+ * them with the column: a row with more cells than the table has tracks wraps
+ * onto the next line.
+ *
+ * A heading that does something holds a control. A column header is not
+ * focusable, so a sortable heading contains a `<button>`, which is the pattern
+ * for a sortable table and the only way to reach the sort by keyboard. A
+ * resizable column has a `separator` on its end edge, moved by dragging or with
+ * the arrow keys. In a table with reorderable columns, each column has a grip
+ * that the table moves.
  *
  * @since 0.1.0
  * @status stable
@@ -84,20 +82,21 @@ export declare const edgeOf: (align: string | undefined) => string | undefined;
  *
  * @slot - The heading.
  *
- * @event {HelixBeforeResizeEvent} helix-before-resize - Fired as a reader resizes the column, with the width asked for, and cancelable.
+ * @event {HelixBeforeResizeEvent} helix-before-resize - The column is about to be resized, with the requested width. Cancelable: cancel it to keep the current width.
  *
  * @csspart column - The heading cell.
- * @csspart grip - The handle a reader moves the column by, where the table allows it.
- * @csspart grip-mark - The glyph on it.
- * @csspart resizer - The edge a reader drags to change the width, where the column allows it.
- * @csspart sort - The button a sortable heading is.
+ * @csspart grip - The handle for moving the column, when the table allows it.
+ * @csspart grip-mark - The icon on the grip.
+ * @csspart resizer - The edge that is dragged to change the width, when the column is resizable.
+ * @csspart sort - The button that a sortable heading renders as.
  *
  * @cssstate sorted-ascending - While the table is sorted by this column, smallest first.
  * @cssstate sorted-descending - While the table is sorted by this column, largest first.
  */
 export declare class HelixHeadlessTableColumn extends HelixElement {
     /**
-     * How to read the cell, where the field alone will not do.
+     * A function that reads the cell's content from a row, for cells that `field`
+     * alone cannot read.
      *
      * A property and not an attribute, because it is a function. Set it from a Lit
      * template with `.cell=${...}`, or assign it in script. A column with neither
@@ -106,7 +105,8 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     cell: CellReader | undefined;
     /**
-     * How to read the value that gets sorted and filtered, where it is not the cell.
+     * A function that reads the value used for sorting and filtering, when it
+     * differs from the cell.
      *
      * **The one that is easy to leave out and expensive to add later.** A cell
      * showing `2.4 MB` sorts as a string unless something says the underlying value
@@ -132,15 +132,15 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     field: string;
     /**
-     * What the grip that moves the column is called, with the heading's words as
-     * `{name}`.
+     * The accessible name of the grip that moves the column. `{name}` is replaced
+     * with the heading text.
      *
      * **Every word a column speaks is a property**, so a table in another
      * language hears its own rather than English around its own headings.
      */
     moveLabel: string;
     /**
-     * Whether a reader may change this column's width.
+     * Whether the column can be resized.
      *
      * By dragging the edge at the end of the heading, or with the arrow keys once
      * it has focus, a step at a time and four with Shift. The width lands in
@@ -149,12 +149,12 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     resizable: boolean;
     /**
-     * What the separator that resizes the column is called, with the heading's
-     * words as `{name}`.
+     * The accessible name of the separator that resizes the column. `{name}` is
+     * replaced with the heading text.
      */
     resizeLabel: string;
     /**
-     * Whether a reader may reorder the set by this column.
+     * Whether the table can be sorted by this column.
      *
      * Ignored without a `field`, and silently: a column with nothing to sort by
      * has no order to offer, and refusing loudly would mean an actions column
@@ -226,7 +226,8 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     width: string;
     /**
-     * How the separator reads out the column's width, with `{width}` filled in.
+     * The text screen readers announce for the column's width. `{width}` is
+     * replaced with the width.
      */
     widthLabel: string;
     /**
@@ -257,7 +258,7 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
     /** Watches `hidden`, which is the platform's attribute and no property of this element's. */
     private hiding;
     /**
-     * The narrowest a reader can drag a column, in pixels.
+     * The narrowest width a column can be dragged to, in pixels.
      *
      * Three characters and the inset around them. Narrower and the heading has
      * nothing left to be read by, and the separator is a grab target with no
@@ -275,7 +276,10 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * exactly when the heading stops being drawn.
      */
     get shown(): boolean;
-    /** Whether a reader can actually reorder by this column. */
+    /**
+     * Whether the table can be sorted by this column, which needs `sortable` and
+     * a `field`.
+     */
     get canSort(): boolean;
     /**
      * The value this column shows for a row.
@@ -285,7 +289,10 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * default back for the rows it has nothing to say about.
      */
     read(row: Readonly<Record<string, unknown>>): unknown;
-    /** The value this column sorts and filters by, which is not always what it shows. */
+    /**
+     * The value this column sorts and filters by for a row, which can differ from
+     * what it shows.
+     */
     order(row: Readonly<Record<string, unknown>>): unknown;
     protected willUpdate(changed: PropertyValues): void;
     /** The words of the heading, for naming the controls on it. */

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

@@ -3,23 +3,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import { type HelixHeadlessTableColumn } from '../column/table-column.js';
 declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
- * @summary Tabular data laid out on a grid.
+ * @summary A table of data, laid out on a grid.
  *
  * @description
- * A grid rather than a `<table>`, so every column lines up across rows while
+ * Lays out the rows on a CSS grid, so every column lines up across rows and
  * each row stays a real element that can be styled, hidden, or made
- * interactive. Table layout gives column alignment and takes away almost
- * everything else; grid gives both.
+ * interactive. A `<table>` layout aligns columns but limits almost everything
+ * else.
  *
- * The cost is that the roles have to be declared, since a grid of divs is not a
- * table to anyone reading it. `table`, `row`, `cell`, and `columnheader` are
- * all set explicitly, and rows are `display: contents` so their cells become
- * items of the one grid that does the aligning.
+ * A grid of elements has no table structure for assistive technology, so the
+ * roles are set explicitly: `table`, `row`, `cell`, and `columnheader`. Rows
+ * are `display: contents`, so their cells become items of the one grid.
  *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * The CSS custom properties listed for this component are written by it and
+ * read by the stylesheet that draws it. Do not set them. Each holds a number
+ * the component computes and CSS cannot, so the stylesheet can draw the table
+ * without measuring anything.
  *
  * @since 0.1.0
  * @status stable
@@ -29,13 +28,13 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  *
  * @slot - The table's rows.
  *
- * @csspart empty - Shown when there are no rows to show.
- * @csspart head - The row the column headings sit in. `display: contents`, so it takes no space.
- * @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 empty - The text shown when there are no rows.
+ * @csspart head - The row that holds the column headings. It has `display: contents`, so it takes no space of its own.
+ * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart loading - The text shown while the rows are loading.
  * @csspart table - The grid.
  *
- * @cssproperty --table-template - The column track list this element worked out from the columns declared in it. Written by the component, read by the sheet that paints: a stylesheet takes it to lay the grid out, and setting it does nothing, because the component writes it inline on the very element that reads it and an inline declaration beats any sheet. `columns` is the one to set.
+ * @cssproperty --table-template - The column track list the table works out from its columns. The component writes it inline on the element that reads it, so setting it has no effect. Set `columns` to change the tracks.
  */
 export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
     /**

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

@@ -5,9 +5,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @description
  * The row renders its cells straight through and lays out none of them, so a
- * sheet can take them into the table's own grid and every column lines up
- * across every row. The row still exists as an element, which is what a
- * `<table>` gives away when its cells are laid out by the table algorithm.
+ * stylesheet can place them in the table's grid and every column lines up
+ * across rows. The row still exists as an element, so you can style it, hide
+ * it, or make it interactive.
  *
  * @since 0.1.0
  * @status stable

package/dist/tabs/panel/tab-panel.d.ts

@@ -4,9 +4,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary The content shown for one tab.
  *
  * @description
- * Hidden rather than unmounted when inactive, so anything typed into a panel is
- * still there when the reader comes back to it, and so the content is in the
- * server's markup for a crawler regardless of which tab is open.
+ * An inactive panel is hidden and stays mounted. Anything typed into it is
+ * still there when the person comes back, and the content of every panel is in
+ * the server-rendered markup for crawlers, whichever tab is open.
  *
  * @since 0.1.0
  * @status stable