@fusion.dev/helix-headless 0.143.0 → 0.145.0

package/dist/list/item/list-item.js

@@ -4,19 +4,50 @@ 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, hostAria } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, hostAria, slottedWords } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+const CONTROL = 'a[href], button, input, select, textarea, [tabindex]';
 let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
     constructor() {
         super(...arguments);
+        this.disabled = false;
         this.href = '';
         this.rel = '';
         this.target = '';
+        this.value = '';
+    }
+    get words() {
+        return this.childrenKnown ? slottedWords(this, ['']) : '';
+    }
+    get grouped() {
+        return this.focusable !== undefined;
+    }
+    get cell() {
+        return this.renderRoot?.querySelector?.('[part~="row"]') ?? null;
+    }
+    get controls() {
+        const slot = this.renderRoot?.querySelector?.('slot[name="end"]');
+        return (slot?.assignedElements({ flatten: true }) ?? [])
+            .flatMap((element) => [element, ...element.querySelectorAll('*')])
+            .filter((element) => element instanceof HTMLElement &&
+            element.matches(CONTROL) &&
+            !element.matches(':disabled'));
+    }
+    focusItem() {
+        this.cell?.focus();
+    }
+    follow() {
+        this.renderRoot?.querySelector('[part~="link"]')?.click();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { role: 'listitem' });
+        hostAria(this.internals, { role: this.grouped ? 'row' : 'listitem' });
+        this.internals.ariaSelected = this.selected === undefined ? null : String(this.selected);
+        this.internals.ariaDisabled = this.grouped && this.disabled ? 'true' : null;
+        this.internals.ariaCurrent =
+            this.current !== undefined && this.href === '' ? this.current : null;
+        this.toggleState('selected', this.selected === true);
     }
     renderRail() {
         return nothing;
@@ -25,26 +56,57 @@ let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
         const content = html `${this.renderRail()}<slot name="start"></slot>
       <slot></slot>
       <slot name="description"></slot>`;
+        const role = this.grouped ? 'gridcell' : nothing;
+        const tabindex = this.grouped ? (this.focusable ? '0' : '-1') : nothing;
         return this.href === ''
-            ? html `<div part="row">${content}<slot name="end"></slot></div>`
-            : html `<div part="row"><a
+            ? html `<div
+          part="row${this.current === undefined ? '' : ' row-current'}"
+          role=${role}
+          tabindex=${tabindex}
+        >${content}<slot name="end"></slot></div>`
+            : html `<div
+          part="row${this.current === undefined ? '' : ' row-current'}"
+          role=${role}
+          tabindex=${tabindex}
+        ><a
           part="link"
           href=${this.href}
           target=${this.target || nothing}
           rel=${this.rel || nothing}
+          aria-current=${this.current ?? nothing}
+          tabindex=${this.grouped ? '-1' : nothing}
           >${content}</a
         ><slot name="end"></slot></div>`;
     }
 };
+__decorate([
+    property({
+        converter: {
+            fromAttribute: (value) => value === null || value === 'false' ? undefined : (value || 'true'),
+        },
+    })
+], HelixHeadlessListItem.prototype, "current", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessListItem.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessListItem.prototype, "focusable", void 0);
 __decorate([
     property()
 ], HelixHeadlessListItem.prototype, "href", void 0);
 __decorate([
     property()
 ], HelixHeadlessListItem.prototype, "rel", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessListItem.prototype, "selected", void 0);
 __decorate([
     property()
 ], HelixHeadlessListItem.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessListItem.prototype, "value", void 0);
 HelixHeadlessListItem = __decorate([
     customElement('helix-headless-list-item')
 ], HelixHeadlessListItem);

package/dist/list/numbering.d.ts

@@ -0,0 +1,14 @@
+/** The first row's number, and what each row after it adds. */
+export interface Numbering {
+    first: number;
+    step: -1 | 1;
+}
+/**
+ * The numbering `start` and `reversed` ask for, as `<ol>` reads them, or
+ * nothing where they ask for the ordinary count from one.
+ *
+ * Reversed without a start counts down from the number of rows, which is
+ * unknown until the rows are: `count` is `undefined` on a server and while
+ * hydrating, and the list counts from one until it knows.
+ */
+export declare const numbering: (start: number | undefined, reversed: boolean, count: number | undefined) => Numbering | undefined;

package/dist/list/numbering.js

@@ -0,0 +1,8 @@
+export const numbering = (start, reversed, count) => {
+    const from = start !== undefined && Number.isFinite(start) ? Math.trunc(start) : undefined;
+    if (!reversed) {
+        return from === undefined ? undefined : { first: from, step: 1 };
+    }
+    const first = from ?? count;
+    return first === undefined ? undefined : { first, step: -1 };
+};

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

@@ -1,5 +1,7 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixHeadlessListItem } from '../item/list-item.js';
+import { type ListSelectionMode } from '../selection.js';
 /**
  * @summary A set of rows, announced as a list.
  *
@@ -7,6 +9,29 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * Sets `role="list"` on the host, so a screen reader counts the rows and
  * announces each one's position, such as "1 of 7".
  *
+ * **`selection-mode` makes the list interactive**, in the way of a grid list:
+ * a grid of rows that is one tab stop. Up and Down move between rows, Home
+ * and End go to the first and the last, and a typed letter goes to the next
+ * row starting with it. Left and Right move between the row and the controls
+ * in its `end` slot. `single` selects one row at a time and `multiple` any
+ * number, with Space or a press, and `value` holds the selected rows' values,
+ * separated by commas. A change asks with `helix-before-change` and tells
+ * with `change`. Enter acts on the row: it follows the row's link, or sends
+ * `helix-action` from the row. `none` selects nothing, so a press acts too. A
+ * `disabled` row is passed over.
+ *
+ * **Leave `selection-mode` unset for a list a reader reads**, and set it for
+ * one a reader chooses from or acts on. The rows of an interactive list are
+ * grid rows, which hold controls as a list box option cannot. Give a control
+ * in `end` `tabindex="-1"` to leave it to the arrow keys and out of the tab
+ * order.
+ *
+ * `start` and `reversed` number an ordered list as `<ol>` does. The list
+ * writes where the numbers start and which way they run as `--list-first` and
+ * `--list-step` on its slot, which the styled tier counts from. Reversed with
+ * no `start` counts down from the number of rows, which a server cannot know,
+ * so served markup counts from one until the list runs.
+ *
  * @since 0.1.0
  * @status stable
  * @category data
@@ -14,6 +39,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/list
  *
  * @slot - The rows.
+ *
+ * @event {Event} change - Fired once a press has changed which rows are selected.
+ * @event {HelixActionEvent} helix-action - Sent from a row when the reader acts on it: Enter, or a press in a list that selects nothing. Read the row from `target`. A row with `href` follows its link instead.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before a press changes which rows are selected, with the `value` it would leave. Cancelable.
+ *
+ * @cssproperty --list-first - The number of the first row, written where `start` or `reversed` moves it.
+ * @cssproperty --list-step - What each row adds to the number before it: `1`, or `-1` where `reversed`.
  */
 export declare class HelixHeadlessList extends HelixElement {
     /**
@@ -43,6 +75,22 @@ export declare class HelixHeadlessList extends HelixElement {
      * The list's name, read by screen readers.
      */
     label: string;
+    /**
+     * Numbers an ordered list downward, so the count falls row by row and ends at
+     * its last row, as `<ol reversed>` does.
+     */
+    reversed: boolean;
+    /**
+     * Makes the list interactive: `single` selects one row, `multiple` any
+     * number, and `none` moves and acts without selecting. Unset is a list a
+     * reader reads, with no tab stop of its own.
+     */
+    selectionMode?: ListSelectionMode;
+    /**
+     * The number of an ordered list's first row, as `<ol start>` is. Unset counts
+     * from one, or down from the number of rows where `reversed`.
+     */
+    start?: number;
     /**
      * The markers an ordered list draws. It takes the five values of `<ol type>`.
      *
@@ -51,18 +99,67 @@ export declare class HelixHeadlessList extends HelixElement {
      * the CSS ones, so `<helix-headless-list kind="ordered" type="i">` is what a
      * consumer would have written on an `<ol>`.
      *
-     * **`start` and `reversed` are both absent and neither can be done here.**
-     * This renders no `<ol>`: the rows are slotted and numbered by the CSS
-     * `list-item` counter, and that counter is not author-resettable. Measured in
-     * Chrome 148, `counter-reset: list-item 4` moves nothing on a `<div>`, on a
-     * `<ul>`, or even on a real `<ol>`, while `<ol start="5">` does and a *named*
-     * counter with explicit `::before` content does. So the markers would have to
-     * be rebuilt out of generated content to gain a start, which is a different
-     * component. `type` is only `list-style-type` and works.
+     * `type` is only `list-style-type`. `start` and `reversed` move the count
+     * itself.
      */
     type?: '1' | 'a' | 'A' | 'i' | 'I';
+    /**
+     * The selected rows' values, separated by commas, in a list that selects.
+     *
+     * Set it to start with rows selected. A row's value is its `value`, or its
+     * words where it has none.
+     */
+    value: string;
+    /** The row the reader was last on, which keeps the tab stop. */
+    private last;
+    /**
+     * Up, Down, Home, End and typed letters, moving focus and choosing nothing,
+     * from the focused row and without wrapping. Left and Right are the row's.
+     */
+    protected readonly keys: KeyboardNavigationController;
+    /** Whether the list is a grid a reader moves through. */
+    private get interactive();
+    /** The rows the list holds, in order. */
+    get rows(): HelixHeadlessListItem[];
+    /** The rows a key can land on, in an interactive list. */
+    private get reachable();
+    /** A row as the keyboard controller sees it: an item it moves focus to and never chooses. */
+    private navigable;
+    /** What a row stands for in `value`: its own `value`, or its words. */
+    private valueFor;
+    /**
+     * Tells every row its place: whether it holds the one tab stop and whether
+     * it is selected, or that it is a plain row. Through `whenHydrated`, so a
+     * row a server rendered draws its served markup first.
+     */
+    private sync;
+    /** The row a press or a key came from, read off the event's path. */
+    private rowOf;
+    /**
+     * Selects the row, or lets it go, asking first. `helix-before-change`
+     * carries the `value` the press would leave, and `change` follows once it
+     * has moved.
+     */
+    protected press(row: HelixHeadlessListItem): void;
+    /** Acts on the row: follows its link, or says it was acted on. */
+    protected act(row: HelixHeadlessListItem): void;
+    /** Left and Right inside a row: the cell, then each control in `end`, and back. */
+    private moveInRow;
+    private readonly handleKeydown;
+    private readonly handleClick;
+    private readonly handleFocusin;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Where the numbers start and which way they run, as custom properties on
+     * the slot the rows inherit from, or nothing where they count up from one.
+     */
+    private get numbers();
     protected render(): TemplateResult;
+    private readonly handleSlotChange;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/list/root/list-root.js

@@ -4,20 +4,193 @@ 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, hostAria } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { commaList, customElement, HelixActionEvent, HelixBeforeChangeEvent, HelixElement, hostAria, inlineStep, KeyboardNavigationController, requestChange, rovingStop, whenHydrated, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { HelixHeadlessListItem } from '../item/list-item.js';
+import { numbering } from '../numbering.js';
+import { pressedValue, rowStop } from '../selection.js';
+const PRESSABLE = 'a[href], button, input, label, select, textarea, [tabindex]';
 let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.reversed = false;
+        this.value = '';
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => this.reachable.map((row) => this.navigable(row)),
+            origin: 'focus',
+            reserved: () => ['ArrowLeft', 'ArrowRight'],
+            selects: () => false,
+            typeahead: (item) => item.words,
+            wrap: false,
+        });
+        this.handleKeydown = (event) => {
+            const row = this.interactive ? this.rowOf(event) : undefined;
+            if (!row || row.disabled || event.altKey || event.ctrlKey || event.metaKey) {
+                return;
+            }
+            if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+                this.moveInRow(row, event);
+                return;
+            }
+            if (event.composedPath()[0] !== row.cell) {
+                return;
+            }
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                this.act(row);
+            }
+            else if (event.key === ' ') {
+                event.preventDefault();
+                this.press(row);
+            }
+        };
+        this.handleClick = (event) => {
+            const row = this.interactive ? this.rowOf(event) : undefined;
+            if (!row) {
+                return;
+            }
+            const path = event.composedPath();
+            const cell = row.cell;
+            const end = cell && path.includes(cell) ? path.indexOf(cell) : path.indexOf(row);
+            const inner = path.slice(0, Math.max(0, end));
+            if (inner.some((node) => node instanceof HTMLElement && node.matches(PRESSABLE))) {
+                return;
+            }
+            if (this.selectionMode === 'none') {
+                this.act(row);
+            }
+            else {
+                this.press(row);
+            }
+        };
+        this.handleFocusin = (event) => {
+            const row = this.interactive ? this.rowOf(event) : undefined;
+            if (row && row !== this.last) {
+                this.last = row;
+                this.sync();
+            }
+        };
+        this.handleSlotChange = () => {
+            this.requestUpdate();
+        };
+    }
+    get interactive() {
+        return this.selectionMode !== undefined;
+    }
+    get rows() {
+        return this.knownChildren.filter((child) => child instanceof HelixHeadlessListItem);
+    }
+    get reachable() {
+        return this.interactive ? this.rows.filter((row) => !row.disabled) : [];
+    }
+    navigable(row) {
+        return {
+            contains: (node) => row.contains(node),
+            disabled: row.disabled,
+            focusItem: () => row.focusItem(),
+            select: () => { },
+            selected: false,
+            words: row.words,
+        };
+    }
+    valueFor(row) {
+        return row.value || row.words;
+    }
+    sync() {
+        const mode = this.selectionMode;
+        const chosen = new Set(commaList(this.value));
+        const rows = this.rows;
+        const holder = mode
+            ? rovingStop(rows, this.last, {
+                disabled: (row) => row.disabled,
+                selected: (row) => chosen.has(this.valueFor(row)),
+            })
+            : undefined;
+        for (const row of rows) {
+            whenHydrated(row, () => {
+                row.focusable = mode ? row === holder : undefined;
+                row.selected =
+                    mode === undefined || mode === 'none' ? undefined : chosen.has(this.valueFor(row));
+            });
+        }
+    }
+    rowOf(event) {
+        return event
+            .composedPath()
+            .find((node) => node instanceof HelixHeadlessListItem && node.parentElement === this);
+    }
+    press(row) {
+        const mode = this.selectionMode;
+        if (mode === undefined || mode === 'none' || row.disabled) {
+            return;
+        }
+        requestChange({
+            apply: (value) => {
+                this.value = value;
+                this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+            },
+            event: (value) => new HelixBeforeChangeEvent({ value }),
+            host: this,
+            next: pressedValue(mode, this.value, this.valueFor(row)),
+        });
+    }
+    act(row) {
+        if (row.disabled) {
+            return;
+        }
+        if (row.href !== '') {
+            row.follow();
+            return;
+        }
+        row.dispatchEvent(new HelixActionEvent());
+    }
+    moveInRow(row, event) {
+        const step = inlineStep(this, event.key);
+        const cell = row.cell;
+        if (step === 0 || !cell) {
+            return;
+        }
+        const stops = [cell, ...row.controls];
+        const on = event.composedPath().find((node) => stops.includes(node));
+        const at = Math.max(0, stops.indexOf(on));
+        event.preventDefault();
+        stops[rowStop(stops.length, at, step)]?.focus();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('keydown', this.handleKeydown);
+        this.addEventListener('click', this.handleClick);
+        this.addEventListener('focusin', this.handleFocusin);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('click', this.handleClick);
+        this.removeEventListener('focusin', this.handleFocusin);
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (this.interactive || changed.get('selectionMode') !== undefined) {
+            this.sync();
+        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'list' });
+        hostAria(this.internals, { label: this.label, role: this.interactive ? 'grid' : 'list' });
+        this.internals.ariaMultiSelectable = this.selectionMode === 'multiple' ? 'true' : null;
+    }
+    get numbers() {
+        const counted = numbering(this.start, this.reversed, this.childrenKnown ? this.knownChildren.length : undefined);
+        return counted ? `--list-first: ${counted.first}; --list-step: ${counted.step}` : nothing;
     }
     render() {
-        return html `<slot></slot>`;
+        return html `<slot style=${this.numbers} @slotchange=${this.handleSlotChange}></slot>`;
     }
 };
 __decorate([
@@ -26,9 +199,21 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessList.prototype, "label", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessList.prototype, "reversed", void 0);
+__decorate([
+    property({ attribute: 'selection-mode' })
+], HelixHeadlessList.prototype, "selectionMode", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessList.prototype, "start", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessList.prototype, "type", void 0);
+__decorate([
+    property()
+], HelixHeadlessList.prototype, "value", void 0);
 HelixHeadlessList = __decorate([
     customElement('helix-headless-list')
 ], HelixHeadlessList);

package/dist/list/selection.d.ts

@@ -0,0 +1,19 @@
+/** How many rows a reader can select in an interactive list. */
+export type ListSelectionMode = 'multiple' | 'none' | 'single';
+/**
+ * The `value` a press on the row carrying `pressed` leaves.
+ *
+ * `single` selects that row alone, or none where it was the one selected.
+ * `multiple` adds it, or takes it out. `none` selects nothing and leaves the
+ * value as it was. Tag Group answers the same question for its tags.
+ */
+export declare const pressedValue: (mode: ListSelectionMode, value: string, pressed: string) => string;
+/**
+ * Where Left or Right goes inside a row: `at` is the row's place among its
+ * `count` stops, the cell first and its controls after it, and `step` is the
+ * way the key points along the line.
+ *
+ * Past either end it comes back to the cell, so the keys never leave the row,
+ * and from the cell going back reaches the last control.
+ */
+export declare const rowStop: (count: number, at: number, step: -1 | 1) => number;

package/dist/list/selection.js

@@ -0,0 +1,21 @@
+import { commaList, toggleValue } from '@fusion.dev/helix-core';
+export const pressedValue = (mode, value, pressed) => {
+    const now = commaList(value);
+    if (mode === 'single') {
+        return now.includes(pressed) ? '' : pressed;
+    }
+    if (mode === 'multiple') {
+        return toggleValue(now, pressed).join(', ');
+    }
+    return value;
+};
+export const rowStop = (count, at, step) => {
+    if (count <= 1) {
+        return 0;
+    }
+    const next = at + step;
+    if (next >= count) {
+        return 0;
+    }
+    return next < 0 ? count - 1 : next;
+};