@fusion.dev/helix-headless 0.144.0 → 0.145.0

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import type { PropertyValues, TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../button/index.js';
 /**
  * @summary One stage in a sequence.
@@ -21,6 +21,12 @@ import '../../button/index.js';
  * and `::after` from properties the list sets, so the step renders no extra
  * element for them.
  *
+ * A finished stage says so in words: the name's button is described by
+ * `complete-label`, "Complete" unless you translate it, and a stage that
+ * becomes complete while the page is open says it once in a polite live
+ * region. The current stage's button carries `aria-current="step"`, and only
+ * the button, so the state is said once, on the control.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Stage
@@ -40,14 +46,21 @@ import '../../button/index.js';
  * @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 live - The live region that says a stage was completed, rendered from the first time one is.
  * @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.
+ * @csspart state - The words that describe a finished stage's button. Hidden.
  */
 export declare class HelixHeadlessStep extends HelixElement {
     /**
      * Whether this stage is finished.
      */
     complete: boolean;
+    /**
+     * The words that tell a screen reader the stage is finished. Translate it
+     * with the page.
+     */
+    completeLabel: string;
     /**
      * Whether this is the current stage.
      */
@@ -56,11 +69,27 @@ export declare class HelixHeadlessStep extends HelixElement {
      * Whether the stage is disabled, so the user cannot go to it.
      */
     disabled: boolean;
+    /**
+     * @internal Set by a linear sequence: whether the stage is out of reach
+     * until the ones before it are finished. A property, because the sequence
+     * writes it after the step upgrades.
+     */
+    locked: boolean;
+    /**
+     * Whether a reader may pass the stage without finishing it, in a sequence
+     * with `linear`. Ark UI's skippable step.
+     */
+    optional: boolean;
     /**
      * The value the step sends in `helix-select`.
      */
     value: string;
-    /** Fires `helix-select` for the step, unless the step is `disabled`. */
+    /** Says a stage was finished, from the first time one is. */
+    private readonly status;
+    /**
+     * Fires `helix-select` for the step, unless the step is `disabled` or a
+     * linear sequence has it out of reach.
+     */
     select(): void;
     /**
      * The mark this stage's state calls for.
@@ -85,6 +114,13 @@ export declare class HelixHeadlessStep extends HelixElement {
      */
     protected renderMarker(): TemplateResult;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Says a stage that was finished while the page is open, with its name.
+     *
+     * Only a change after the first update, so a sequence served with its done
+     * stages says nothing when it arrives.
+     */
+    protected updated(changed: PropertyValues): void;
     /**
      * The step's own label, which is a control because a step can be gone to, behind a seam the styled tier can move.
      *

package/dist/steps/step/step.js

@@ -4,8 +4,9 @@ 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, HelixSelectEvent, hostAria } from '@fusion.dev/helix-core';
+import { customElement, drawStatus, HelixElement, HelixSelectEvent, hostAria, StatusController, } from '@fusion.dev/helix-core';
 import { check, circle, record } from '@fusion.dev/helix-icons';
+import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
@@ -14,12 +15,16 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     constructor() {
         super(...arguments);
         this.complete = false;
+        this.completeLabel = 'Complete';
         this.current = false;
         this.disabled = false;
+        this.locked = false;
+        this.optional = false;
         this.value = '';
+        this.status = new StatusController(this);
     }
     select() {
-        if (this.disabled) {
+        if (this.disabled || this.locked) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
@@ -35,18 +40,26 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'listitem' });
-        this.internals.ariaCurrent = this.current ? 'step' : null;
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.get('complete') === false && this.complete) {
+            const name = (this.textContent ?? '').replace(/\s+/g, ' ').trim();
+            this.status.say(name === '' ? this.completeLabel : `${name}, ${this.completeLabel}`);
+        }
     }
     renderLabel() {
         return html `<${this.tag('button')}
       part="label"
       exportparts="button: label-button, live: label-live, text: label-text"
       emphasis="ghost"
-      ?disabled=${this.disabled}
+      aria-current=${this.current ? 'step' : nothing}
+      aria-describedby=${this.complete ? 'state' : nothing}
+      ?disabled=${this.disabled || this.locked}
       @click=${this.select}
     >
       <slot></slot>
-    </${this.tag('button')}>`;
+    </${this.tag('button')}><span id="state" part="state" hidden>${this.complete ? this.completeLabel : ''}</span>`;
     }
     render() {
         return html `<span part="marker" aria-hidden="true">
@@ -56,18 +69,27 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
         ${this.renderLabel()}
         <span part="description"><slot name="description"></slot></span>
       </span>
-      <div part="content"><slot name="content"></slot></div>`;
+      <div part="content"><slot name="content"></slot></div>${drawStatus(this.status)}`;
     }
 };
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "complete", void 0);
+__decorate([
+    property({ attribute: 'complete-label' })
+], HelixHeadlessStep.prototype, "completeLabel", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "current", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessStep.prototype, "locked", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessStep.prototype, "optional", void 0);
 __decorate([
     property()
 ], HelixHeadlessStep.prototype, "value", void 0);

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

@@ -84,6 +84,7 @@ export declare const edgeOf: (align: string | undefined) => string | undefined;
  * @slot - The heading.
  *
  * @event {HelixBeforeResizeEvent} helix-before-resize - The column is about to be resized, with the requested width. Cancelable: cancel it to keep the current width.
+ * @event {HelixResizedEvent} helix-resized - Fired after the column is resized, with the new width.
  *
  * @csspart column - The heading cell.
  * @csspart grip - The handle for moving the column, when the table allows it.
@@ -154,6 +155,16 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * replaced with the heading text.
      */
     resizeLabel: string;
+    /**
+     * Makes this column's cells the headers of their rows, in `DataTable`.
+     *
+     * A screen reader moving along a row or down a column names the row by its
+     * row header, so the cell that identifies a row, a file's name say, is the
+     * one to mark. Where no column sets it, `DataTable` makes the first column
+     * with a `field` the row header. A `Table`'s cells are your markup, so there
+     * a cell is a row header through its own `header` attribute.
+     */
+    rowHeader: boolean;
     /**
      * Whether the table can be sorted by this column.
      *

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

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessTableColumn_1;
-import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, HelixResizedEvent, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
 import { dotsThreeVertical } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -37,6 +37,7 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
         this.moveLabel = 'Move {name}';
         this.resizable = false;
         this.resizeLabel = 'Resize {name}';
+        this.rowHeader = false;
         this.sortable = false;
         this.width = '';
         this.widthLabel = '{width} pixels';
@@ -172,6 +173,7 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
         requestChange({
             apply: (value) => {
                 this.width = value;
+                this.dispatchEvent(new HelixResizedEvent({ value }));
             },
             event: (value) => new HelixBeforeResizeEvent({ value }),
             host: this,
@@ -237,6 +239,9 @@ __decorate([
 __decorate([
     property({ attribute: 'resize-label' })
 ], HelixHeadlessTableColumn.prototype, "resizeLabel", void 0);
+__decorate([
+    property({ attribute: 'row-header', type: Boolean })
+], HelixHeadlessTableColumn.prototype, "rowHeader", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessTableColumn.prototype, "sortable", void 0);

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

@@ -1,5 +1,6 @@
 import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../checkbox/index.js';
 import { type HelixHeadlessTableColumn } from '../column/table-column.js';
 declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
@@ -21,6 +22,17 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * the rows in the sorted order. `helix-sort` asks first, so you can refuse it
  * and reorder the rows yourself.
  *
+ * The `heading` slot names the table: slot a heading or a line of text into
+ * it, and the table is named by its words. An `aria-label` or `aria-labelledby` on the
+ * host wins over it.
+ *
+ * `selectable` adds a column of checkboxes. Each row is known by its `value`,
+ * and `selected` holds the chosen keys, comma separated, the same shape
+ * `DataTable` uses. The checkbox in the heading selects every row. For a grid
+ * a reader moves through with the arrow keys, with typeahead and range
+ * selection, use `DataTable`. To act on one row, put a link or a button in a
+ * cell.
+ *
  * 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
@@ -33,13 +45,29 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * @documentation https://fusion.dev/helix/components/table
  *
  * @slot - The table's rows.
+ * @slot heading - Words that name the table, shown above it, such as a heading.
  *
+ * @event {HelixSelectEvent} helix-select - The selection is about to change. The event carries every selected key, separated by commas. Cancelable: cancel it to keep the current selection.
+ * @event {HelixSelectedEvent} helix-selected - Fired after the selection changes, with every selected key, separated by commas.
  * @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.
+ * @event {HelixSortedEvent} helix-sorted - Fired after the sort order changes, with the new order.
  *
+ * @csspart checkbox - The checkbox in the heading that selects every row, in a `selectable` table.
+ * @csspart checkbox-box - The box drawn for the checkbox's input.
+ * @csspart checkbox-control - The checkbox's input.
+ * @csspart checkbox-feedback - Forwarded from the checkbox. Not shown in the table.
+ * @csspart checkbox-field - The row that holds the checkbox's box.
+ * @csspart checkbox-hint - Forwarded from the checkbox. Not shown in the table.
+ * @csspart checkbox-label - Forwarded from the checkbox. The label is read by screen readers only.
+ * @csspart checkbox-mark - The check mark, or the dash while some rows are selected.
+ * @csspart checkbox-mark-checked - Added to `checkbox-mark` while its box is checked.
+ * @csspart checkbox-mark-dash - Added to `checkbox-mark` while it draws the dash, which it keeps until its box is checked.
+ * @csspart checkbox-mark-indeterminate - Added to `checkbox-mark` while only some rows are selected.
  * @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 select-all - The heading that holds the checkbox that selects every row.
  * @csspart table - The grid.
  *
  * @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.
@@ -78,6 +106,11 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * declared in it has nowhere else to be sized from.
      */
     columns: string;
+    /**
+     * The keys selected at the start, separated by commas. Used until `selected`
+     * is set.
+     */
+    defaultSelected: string;
     /**
      * The starting sort order, used until `sort` is set.
      */
@@ -91,6 +124,32 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * wins over this.
      */
     label: string;
+    /**
+     * Adds a column of checkboxes for selecting rows. Each row is known by its
+     * `value`, and by its place among the rows as written where it has none.
+     */
+    selectable: boolean;
+    /** The name of the checkbox in the heading that selects every row. */
+    selectAllLabel: string;
+    /**
+     * The keys of the selected rows, separated by commas.
+     *
+     * A reader's press fires `helix-select` first, and refusing it leaves the
+     * selection as it was. `default-selected` seeds a selection this element
+     * then owns.
+     */
+    get selected(): string;
+    set selected(next: string);
+    /**
+     * What screen readers hear when the chosen rows change. `{count}` is how many
+     * rows are chosen.
+     */
+    selectedLabel: string;
+    /**
+     * The name of a row's checkbox. `{row}` is replaced with the words of the
+     * row's first cell.
+     */
+    selectRowLabel: string;
     /**
      * The sort order, as `field:direction`, where `field` is a sortable column's
      * `field`.
@@ -110,6 +169,9 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
     /** What screen readers hear when the table stops being sorted. */
     unsortedLabel: string;
     private sortState;
+    private selectedState;
+    /** Whether the heading names the table, so taking it away clears only this element's own name. */
+    private headed;
     /**
      * Carries a host `aria-label` and `aria-labelledby` to the grid, which is
      * the element with the `table` role.
@@ -148,6 +210,39 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * new order is said. Not on the first render, which is the table arriving.
      */
     private news;
+    /** The sort as the last render had it, so a selection said beside a sort waits. */
+    private heardSortBefore;
+    /** The selection last heard, so a render that changed nothing says nothing. */
+    private heardSelected;
+    /** The rows as written, each with the key `selected` lists it by. */
+    private get keyed();
+    /** The keys selected now. */
+    private get chosen();
+    /** Asks for a different set of selected rows, and reports whether the request stood. */
+    private requestSelected;
+    /**
+     * A checkbox this table drew asked to change: a row's, or the one in the
+     * heading. Refused, and asked of the selection instead, so a box shows only
+     * what `selected` says. A checkbox a consumer put in a cell is theirs and is
+     * left alone.
+     */
+    private readonly handleToggle;
+    /**
+     * Tells each row whether it is selected and what its checkbox is called.
+     *
+     * Pushed down for the reason the sort is: the selection is the table's, and
+     * the checkbox is drawn by the row.
+     */
+    private markSelected;
+    /**
+     * Names the table by its heading, where the host names it no other way.
+     *
+     * Through element reflection, because the heading is the consumer's markup
+     * and the table is in this shadow root, which an id cannot reach across.
+     */
+    private nameByHeading;
+    /** What the heading slot is given. */
+    private get headings();
     /**
      * Tells each column which way it is ordered, if it is the one.
      *
@@ -175,6 +270,8 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * track for one that declares neither.
      */
     private get template();
+    /** The tracks of the columns, before any checkbox column. */
+    private get tracks();
     /**
      * Tracks for the columns that set nothing, from how much text each holds.
      *
@@ -195,6 +292,8 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * after. Sampled, so a table of thousands of rows reads `SAMPLE` of them.
      */
     private fitted;
+    /** Asks for the render a hydration put off, which reads the rows. */
+    protected firstUpdated(changed: PropertyValues): void;
     private readonly handleSlotChange;
     /**
      * Watches the light DOM for rows and columns arriving, leaving and moving.
@@ -278,6 +377,8 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
     private alignCells;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The heading of the checkbox column, which selects every row. */
+    private renderSelectAll;
     protected render(): TemplateResult;
 }
 declare global {