@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary One measurement, with a label that names what it measures.
  *
@@ -21,6 +21,8 @@ import { type TemplateResult } from 'lit';
  * @slot - The value.
  * @slot label - What the value measures.
  * @slot unit - The unit, shown beside the value.
+ *
+ * @csspart value - The slot the value is written in. A slot draws no box, so it takes the inherited properties, such as color and font, and passes them to the value.
  */
 export declare class HelixHeadlessStat extends HelixElement {
     /**
@@ -38,6 +40,11 @@ export declare class HelixHeadlessStat extends HelixElement {
      * the value's baseline whichever way the pair goes, and only this element
      * knows which of its children the unit belongs to.
      *
+     * **`Trend` has a `direction` too, and there it means which way a number
+     * moved:** `up`, `down` or `neutral`. A Stat and a Trend are often written
+     * side by side, so watch for the mix-up. On a Stat those three words are not
+     * layouts, and the pair stays the column.
+     *
      * **Optional rather than defaulted to `column`, which is not a style
      * preference.** A reflecting property with a default writes its attribute onto
      * the host the moment the element upgrades, and the host is markup the
@@ -47,6 +54,7 @@ export declare class HelixHeadlessStat extends HelixElement {
      * carries nothing nobody wrote.
      */
     direction?: 'column-reverse' | 'row' | 'row-reverse';
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/stat/root/stat-root.js

@@ -4,13 +4,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, reportRuntime } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
+    updated(changed) {
+        super.updated(changed);
+        const given = this.direction;
+        if (changed.has('direction') && (given === 'up' || given === 'down' || given === 'neutral')) {
+            reportRuntime({
+                kind: 'misread-direction',
+                message: `<${this.localName} direction="${given}"> lays out as the column: \`${given}\` is a ` +
+                    "direction of Trend's, which says which way a number moved. Put it on the " +
+                    '`helix-trend` beside the stat.',
+                tag: this.localName,
+            });
+        }
+    }
     render() {
         return html `<slot name="label"></slot>
-      <slot></slot>
+      <slot part="value"></slot>
       <slot name="unit"></slot>`;
     }
 };

package/dist/steps/root/steps-root.js

@@ -12,7 +12,7 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         super(...arguments);
         this.label = 'Steps';
         this.handleSelection = (event) => {
-            if (event.defaultPrevented) {
+            if (event.defaultPrevented || !this.steps.includes(event.target)) {
                 return;
             }
             this.requestActive(event.detail.value);

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

@@ -38,6 +38,7 @@ import '../../button/index.js';
  * @csspart description - The line under the name.
  * @csspart label - The step's name, which is a control.
  * @csspart label-button - The button inside the label.
+ * @csspart label-live - The live region inside that button, rendered only from the first time the button is pending.
  * @csspart label-text - The words on that button, trimmed to their capitals and baseline.
  * @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.

package/dist/steps/step/step.js

@@ -40,7 +40,7 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     renderLabel() {
         return html `<${this.tag('button')}
       part="label"
-      exportparts="button: label-button, text: label-text"
+      exportparts="button: label-button, live: label-live, text: label-text"
       emphasis="ghost"
       ?disabled=${this.disabled}
       @click=${this.select}

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

@@ -1,5 +1,5 @@
 import { AriaForwardController, HelixFormElement, HostClickController } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerCheckedInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A control that turns something on or off.
@@ -25,6 +25,8 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * @documentation https://fusion.dev/helix/components/switch
  *
  * @slot - The label that names what the switch turns on.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
+ * @slot hint - Help under the control, for content richer than the `hint` text.
  *
  * @event {Event} change - Sent from the input after the state changes.
  * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
@@ -38,7 +40,9 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * @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.
+ * your layout as much as any other child. `ListItem` measured that cost. A
+ * subclass that draws one returns it from `renderThumb`, as the styled switch
+ * does.
  *
  * @cssstate checked - While it is on.
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
@@ -68,6 +72,14 @@ export declare class HelixHeadlessSwitch extends HelixHeadlessSwitch_base {
      * rendered, which React reports on hydration and does not patch up.
      */
     private markEmpty;
+    /**
+     * The thumb, drawn inside the track after the input: nothing on this tier.
+     *
+     * A seam for a tier that draws the thumb as an element, so it can be a part
+     * and hold icons. An element here would be an empty child on every page that
+     * loads only this tier, which is the cost the `track` part notes.
+     */
+    protected renderThumb(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/switch/root/switch-root.js

@@ -11,6 +11,7 @@ let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerCheck
     constructor() {
         super(...arguments);
         this.aria = new AriaForwardController(this, {
+            label: true,
             target: () => this.partNamed('control'),
         });
         this.clicks = new HostClickController(this, () => this.partNamed('control'));
@@ -42,6 +43,9 @@ let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerCheck
     markEmpty() {
         markRegion(this.renderRoot, 'label', ['']);
     }
+    renderThumb() {
+        return nothing;
+    }
     render() {
         return html `<label part="field">
       <span part="track">
@@ -54,9 +58,11 @@ let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerCheck
           ?required=${this.required}
           aria-describedby=${this.describedBy ?? nothing}
           aria-invalid=${this.invalidity ?? nothing}
+          aria-readonly=${this.readOnly ? 'true' : nothing}
           @change=${this.handleChange}
+          @click=${this.holdReadOnly}
           @input=${this.stopInner}
-        />
+        />${this.renderThumb()}
       </span>
       <span part="label"><slot>${this.label}</slot></span>
     </label>

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

@@ -5,9 +5,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @description
  * 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".
+ * assistive technology otherwise. `header` makes the cell a header, so a screen
+ * reader announces it with the values it heads:
+ *
+ * - In a row that holds a cell without `header`, it is a `rowheader` and names
+ *   its row, for example "web-app" in a row of a service's values.
+ * - In a row of `header` cells alone, it is a `columnheader`, which is what a
+ *   table with no `TableColumn` heads its columns with.
  *
  * 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.
@@ -25,10 +29,26 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessTableCell extends HelixElement {
     /**
-     * Whether the cell is the header cell of its column.
+     * Whether the cell is a header: of its row in a row of values, and of its
+     * column in a row of headers alone.
      */
     header: boolean;
+    /**
+     * @internal Read by the row and by the cells beside it, to tell a header
+     * cell from a value. Not a consumer's to read or set.
+     */
+    readonly isTableCell = true;
+    /**
+     * Whether this cell, as a header, heads its row: true where the row also
+     * holds a cell that is not a header.
+     *
+     * The rule a browser applies to a `<th>` with no `scope`. Read from the
+     * siblings, which a server does not have, so a server render waits for the
+     * client to say which.
+     */
+    private get headsRow();
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     /**
      * Sets the `text` state from the cell's own content.
      *

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

@@ -11,14 +11,34 @@ let HelixHeadlessTableCell = class HelixHeadlessTableCell extends HelixElement {
     constructor() {
         super(...arguments);
         this.header = false;
+        this.isTableCell = true;
         this.handleSlotChange = () => {
             const text = [...this.childNodes].some((node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '');
             this.toggleState('text', text);
         };
     }
+    get headsRow() {
+        const siblings = [...(this.parentElement?.children ?? [])];
+        return siblings.some((sibling) => sibling !== this &&
+            'isTableCell' in sibling &&
+            !sibling.hasAttribute('header') &&
+            sibling.header !== true);
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { role: this.header ? 'columnheader' : 'cell' });
+        const header = this.headsRow ? 'rowheader' : 'columnheader';
+        hostAria(this.internals, { role: this.header ? header : 'cell' });
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('header') && changed.get('header') !== undefined) {
+            for (const sibling of this.parentElement?.children ?? []) {
+                if (sibling !== this && 'isTableCell' in sibling) {
+                    ;
+                    sibling.requestUpdate();
+                }
+            }
+        }
     }
     render() {
         return html `<slot @slotchange=${this.handleSlotChange}></slot>`;

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

@@ -68,12 +68,13 @@ export declare const edgeOf: (align: string | undefined) => string | undefined;
  * 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.
+ * A heading that does something holds a control. In a `Table` 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. In a `DataTable` the heading is a cell of the grid, reached with
+ * the arrow keys, and its controls with Enter or F2. 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
@@ -254,6 +255,21 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * on a column the table will not move is a control that does nothing.
      */
     movable: boolean;
+    /**
+     * @internal Whether the column is a cell of a grid that moves focus between
+     * its cells, written by that table. Not a consumer's to set.
+     *
+     * **The heading's box takes the role and the focus.** The column element has
+     * no box, being `display: contents`, and an element with no box cannot be
+     * focused, so in a grid the `columnheader` role, `aria-sort` and the focus all
+     * go to `[part="column"]`, and the controls on it leave the tab order.
+     */
+    gridCell: boolean;
+    /**
+     * @internal Whether the heading is the grid's one tab stop, written by the
+     * table that sets `gridCell`. Not a consumer's to set.
+     */
+    tabStop: boolean;
     /** How wide the heading drew, for the separator to report. */
     private drawn;
     /** Where a drag of the separator started, while one is running. */
@@ -300,6 +316,16 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     order(row: Readonly<Record<string, unknown>>): unknown;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * @internal The box a grid focuses for this heading, read by the table that
+     * sets `gridCell`. Not a consumer's to call.
+     */
+    get cellBox(): HTMLElement | null;
+    /**
+     * @internal The controls on the heading, in order, read by the table that
+     * sets `gridCell` to move focus into them. Not a consumer's to call.
+     */
+    get controls(): HTMLElement[];
     /** The words of the heading, for naming the controls on it. */
     private get name();
     connectedCallback(): void;

package/dist/table/column/table-column.js

@@ -43,6 +43,8 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
         this.isTableColumn = true;
         this.sorted = undefined;
         this.movable = false;
+        this.gridCell = false;
+        this.tabStop = false;
         this.drawn = 0;
         this.handleResizeStart = (event) => {
             if (event.button !== 0) {
@@ -101,11 +103,25 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { role: 'columnheader' });
-        this.internals.ariaSort = this.canSort ? (this.sorted ?? 'none') : null;
+        const named = this.movable || this.resizable;
+        const host = !this.gridCell;
+        hostAria(this.internals, {
+            label: host && named ? this.name : '',
+            role: host ? 'columnheader' : '',
+        });
+        this.internals.ariaSort = host && this.canSort ? (this.sorted ?? 'none') : null;
         this.toggleState('sorted-ascending', this.sorted === 'ascending');
         this.toggleState('sorted-descending', this.sorted === 'descending');
     }
+    get cellBox() {
+        return this.partNamed('column');
+    }
+    get controls() {
+        return ['grip', 'sort', 'resizer'].flatMap((name) => {
+            const control = this.partNamed(name);
+            return control ? [control] : [];
+        });
+    }
     get name() {
         return this.textContent?.trim() ?? '';
     }
@@ -167,19 +183,27 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
     }
     render() {
         const name = this.name;
-        return html `<span part="column">${this.movable
-            ? html `<button part="grip" type="button" aria-label=${fillTemplate(this.moveLabel, { name: name || 'column' })}>
+        const grid = this.gridCell;
+        const control = grid ? '-1' : nothing;
+        return html `<span
+      part="column"
+      role=${grid ? 'columnheader' : nothing}
+      tabindex=${grid ? (this.tabStop ? '0' : '-1') : nothing}
+      aria-sort=${grid && this.canSort ? (this.sorted ?? 'none') : nothing}
+      aria-label=${grid && (this.movable || this.resizable) && name ? name : nothing}
+    >${this.movable
+            ? html `<button part="grip" type="button" tabindex=${control} aria-label=${fillTemplate(this.moveLabel, { name: name || 'column' })}>
             <svg aria-hidden="true" fill="currentColor" part="grip-mark" viewBox=${dotsThreeVertical.viewBox}>
               ${unsafeSVG(dotsThreeVertical.content)}
             </svg>
           </button>`
             : nothing}${this.canSort
-            ? html `<button part="sort" type="button"><slot></slot></button>`
+            ? html `<button part="sort" type="button" tabindex=${control}><slot></slot></button>`
             : html `<slot></slot>`}${this.resizable
             ? html `<span
             part="resizer"
             role="separator"
-            tabindex="0"
+            tabindex=${grid ? '-1' : '0'}
             aria-label=${fillTemplate(this.resizeLabel, { name: name || 'column' })}
             aria-orientation="vertical"
             aria-valuemin=${HelixHeadlessTableColumn_1.NARROWEST}
@@ -231,6 +255,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessTableColumn.prototype, "movable", void 0);
+__decorate([
+    state()
+], HelixHeadlessTableColumn.prototype, "gridCell", void 0);
+__decorate([
+    state()
+], HelixHeadlessTableColumn.prototype, "tabStop", void 0);
 __decorate([
     state()
 ], HelixHeadlessTableColumn.prototype, "drawn", void 0);

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 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;
@@ -12,8 +12,14 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * else.
  *
  * 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.
+ * roles are set explicitly: `table`, `row`, `cell`, `columnheader`, and
+ * `rowheader` for a `header` cell in a row of values. Rows are
+ * `display: contents`, so their cells become items of the one grid.
+ *
+ * A column with `sortable` and a `field` sorts the rows by the text of its
+ * cells, numbers by their value. Your markup is not reordered: the table draws
+ * the rows in the sorted order. `helix-sort` asks first, so you can refuse it
+ * and reorder the rows yourself.
  *
  * 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
@@ -28,6 +34,8 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  *
  * @slot - The table's rows.
  *
+ * @event {HelixSortEvent} helix-sort - A different sort order was requested, as `field:direction`, or empty for the order the rows were written in. Cancelable: cancel it to keep the current order.
+ *
  * @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.
@@ -37,6 +45,8 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * @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 {
+    /** The word for an ascending sort, in `sorted-label`. */
+    ascendingLabel: string;
     /**
      * The column widths as one track list, written once on the table.
      *
@@ -68,10 +78,90 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * declared in it has nowhere else to be sized from.
      */
     columns: string;
+    /**
+     * The starting sort order, used until `sort` is set.
+     */
+    defaultSort: string;
+    /** The word for a descending sort, in `sorted-label`. */
+    descendingLabel: string;
     /**
      * Accessible name for the table.
+     *
+     * An `aria-label` or `aria-labelledby` on the host names the table too, and
+     * wins over this.
      */
     label: string;
+    /**
+     * The sort order, as `field:direction`, where `field` is a sortable column's
+     * `field`.
+     *
+     * The rows are compared by the text of their cells in that column, numbers by
+     * their value. A reader's click on a sortable heading fires `helix-sort`
+     * first, and refusing it leaves the order as it was. `default-sort` seeds an
+     * order this element then owns.
+     */
+    get sort(): string;
+    set sort(next: string);
+    /**
+     * What screen readers hear when the table is sorted. `{column}` is the
+     * column's heading and `{order}` is `ascending-label` or `descending-label`.
+     */
+    sortedLabel: string;
+    /** What screen readers hear when the table stops being sorted. */
+    unsortedLabel: string;
+    private sortState;
+    /**
+     * Carries a host `aria-label` and `aria-labelledby` to the grid, which is
+     * the element with the `table` role.
+     *
+     * A heading the table is named by is the consumer's markup, beside the
+     * host, and an IDREF on the host named a generic wrapper while the table
+     * itself kept its default name.
+     */
+    protected readonly aria: AriaForwardController;
+    /**
+     * Asks for a different order, and reports whether the request stood.
+     */
+    private requestSort;
+    /**
+     * Cycles the sort order of one column, as a click on its heading does.
+     *
+     * Ascending, descending, then the order the rows were written in.
+     */
+    toggleSort(field: string): boolean;
+    /**
+     * The rows in the order they are drawn: sorted by `sort`, and as written
+     * where there is no sort.
+     *
+     * **Drawn in order by assignment.** A manually assigned slot draws its nodes
+     * in the order they were assigned, so the rows move on screen and in the
+     * accessibility tree while the consumer's markup stays as it was written,
+     * which is what a framework holding those rows needs.
+     */
+    private get arrangedRows();
+    /** The sort last heard, so a render that changed nothing says nothing. */
+    private heardSort;
+    /**
+     * What the table says after a sort, once, in the collection's live region.
+     *
+     * A reader on a heading's button is not told that `aria-sort` moved, so the
+     * new order is said. Not on the first render, which is the table arriving.
+     */
+    private news;
+    /**
+     * Tells each column which way it is ordered, if it is the one.
+     *
+     * The table owns the sort and the column carries `aria-sort`, the same
+     * arrangement `DataTable` has.
+     */
+    private markSorted;
+    /**
+     * A click on a sortable heading's button.
+     *
+     * Enter and Space arrive here too, as the click the button makes of them.
+     * Only the button sorts: a click on a column's separator is a resize.
+     */
+    private readonly handleHeadClick;
     /** The columns declared as children, in the order they are written. */
     get tableColumns(): HelixHeadlessTableColumn[];
     /**
@@ -186,6 +276,7 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * take the outer column's edge for columns of its own that set none.
      */
     private alignCells;
+    protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }