@fusion.dev/helix-headless 0.145.0 → 0.146.0

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

@@ -46,21 +46,48 @@ export interface VirtualListRange {
  *
  * Rows are your markup in the light DOM, so your stylesheet styles them.
  *
- * **Keyboard.** The list is one tab stop. Up and Down move between items, Home
- * and End go to the first and the last, and Page Up and Page Down move by a
- * screen. An item that is not drawn is scrolled into view and focused, so a
- * keyboard reaches the whole set. Tab moves on into the focused row's own links
- * and buttons. When the row holding the tab stop scrolls away, the stop moves
- * to the first row on screen.
+ * **Keyboard.** The list is one tab stop.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Down, Up | Moves to the next or the previous item. |
+ * | Home, End | Moves to the first or the last item. |
+ * | Page Down, Page Up | Moves by the number of items on screen. |
+ * | A letter or a word | Moves to the next item whose text starts with what you typed. |
+ * | Tab | Moves into the focused row's own links and buttons, then out of the list. |
+ *
+ * An item that is not drawn is scrolled into view and focused, so a keyboard
+ * reaches the whole set. When the row holding the tab stop scrolls away, the
+ * stop moves to the first row on screen. Typing matches each item's
+ * `text-field`, which is the first `data-field` of the row template by default,
+ * or the item itself when it is a string or a number.
  *
  * Each row says its place in the whole set with `aria-posinset` and
  * `aria-setsize`, so a screen reader says "4,000 of 10,000". The row holding
  * focus stays drawn when it scrolls out.
  *
+ * **Selecting.** `selection-mode` makes the list a list box a reader chooses
+ * from: `single` selects one item and `multiple` any number. Space or a press
+ * selects an item, Shift with Space, Up, Down, Home, End or a press takes in
+ * the items from the last one chosen, and Control or Command with A selects
+ * them all, in `multiple`. `value` holds the chosen items' keys, separated by
+ * commas, in the order of the set: `key-field` names each item's key, and a
+ * string or a number item is its own key. A change asks with
+ * `helix-before-change` and tells with `change`. Each row is an `option`
+ * marked `aria-selected`, so a row's own links and buttons are not reached
+ * there: keep those to a list without `selection-mode`.
+ *
  * **Loading more.** `helix-range-change` fires as the items on screen change,
  * and `range` holds them. `helix-load-more` fires once a reader is within one
  * screen of the end, once for each length of the set: add to `items` and it can
- * fire again. `scrollToIndex` takes a reader to an item.
+ * fire again. While you fetch, set `loading`: the list is busy, and a row after
+ * the last item says "Loading more" (`loading-label`, or your own content in
+ * the `loading` slot). `scrollToIndex` takes a reader to an item.
+ *
+ * **Row height.** Rows are placed by `estimate` until they are drawn. Then the
+ * list reads the drawn rows' height once and places every row by it, so a
+ * wrong estimate still reaches the last item. Set `measured` for rows of
+ * different heights.
  *
  * The list follows its source. A new `items` array, an edit to the script's
  * text, or a script replaced under the same id draws the new rows. A row that
@@ -76,12 +103,16 @@ export interface VirtualListRange {
  * @documentation https://fusion.dev/helix/components/virtual-list
  *
  * @slot - The `<template>` that defines one row. The list writes the rows it renders beside it, and this slot shows them between the two spacers.
+ * @slot loading - Content for the row after the last item while `loading` is set. Falls back to `loading-label`.
  *
+ * @event {Event} change - Fired once a press or a key has changed which items are selected, in a list with `selection-mode`.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before a press or a key changes which items are selected, with the `value` it would leave. Cancelable.
  * @event {HelixLoadMoreEvent} helix-load-more - Fired when a reader comes within one screen of the last item, once for each length of the set.
  * @event {HelixRangeChangeEvent} helix-range-change - Fired when the items on screen change, with the new `first` and `last`, which `range` also holds.
  *
  * @csspart after - The space that stands in for the rows below the rendered ones.
  * @csspart before - The space that stands in for the rows above the rendered ones.
+ * @csspart loading - The row after the last item while `loading` is set.
  * @csspart viewport - The scrolling box. On this tier, it needs only a block size.
  */
 export declare class HelixHeadlessVirtualList extends HelixElement {
@@ -105,6 +136,12 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * Left unset, the list reads the script that `for` names.
      */
     items: readonly unknown[] | undefined;
+    /**
+     * The field of each item that is its key in `value`, as a key or a path of
+     * keys. Empty reads a string or a number item as its own key, and any
+     * other item by its place in the set.
+     */
+    keyField: string;
     /**
      * The list's name, read by screen readers, because only some of its rows
      * are rendered at a time.
@@ -114,11 +151,22 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      */
     label: string;
     /**
-     * Places rows by their measured height. Without it, every row is placed by
-     * `estimate`.
+     * Marks the list as busy fetching more items, and draws a row after the last
+     * item that says so.
+     *
+     * Set it when `helix-load-more` starts a fetch, and clear it when the items
+     * arrive. The list does not ask for more while it is set.
+     */
+    loading: boolean;
+    /** The text of the row drawn while `loading` is set, where the `loading` slot is empty. */
+    loadingLabel: string;
+    /**
+     * Places each row by its own measured height. Without it, rows are placed
+     * by one height: `estimate` until rows are drawn, then the drawn rows' height,
+     * read once.
      *
      * **Off by default, because the straight line is better when it holds.** One
-     * estimate makes offset and index convert by division, which can never
+     * height makes offset and index convert by division, which can never
      * disagree with itself; measuring is what a set of genuinely different
      * heights needs and costs a read of each row as it renders. A list of
      * one-line rows should leave this alone.
@@ -133,6 +181,24 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * and place in the set. Where it is unset, the row `<template>` is used.
      */
     renderItem: VirtualListRenderer | undefined;
+    /**
+     * Makes the list a list box a reader chooses from: `single` selects one
+     * item, and `multiple` any number. Unset is a list a reader reads.
+     */
+    selectionMode?: 'multiple' | 'single';
+    /**
+     * The field of each item that typing matches, as a key or a path of keys
+     * (`author.name`).
+     *
+     * Empty by default, which matches the first `data-field` of the row
+     * template, or the item itself where it is a string or a number.
+     */
+    textField: string;
+    /**
+     * The keys of the chosen items, separated by commas, in a list with
+     * `selection-mode`. Set it to start with items chosen.
+     */
+    value: string;
     /**
      * The parsed script.
      *
@@ -158,8 +224,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private released;
     /** The range last reported, so `helix-range-change` fires only on a change. */
     private said;
-    /** The length of the set when `helix-load-more` last fired. */
-    private askedAt;
+    /** The letters typed at the list, which move to the item they start. */
+    private readonly typeahead;
+    /** The key of the item a Shift range runs from: the last one chosen. */
+    private anchor;
     /**
      * Watches the source and the tree around it.
      *
@@ -235,6 +303,11 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * has not been laid out yet asks for nothing.
      */
     private report;
+    /**
+     * The text typing matches for each item: `text-field`, the template's first
+     * `data-field`, or a string or number item itself.
+     */
+    private texts;
     /** The item a row element drew, for an element that is one of the rows. */
     private indexOf;
     /** The row that holds the tab stop for item `index`, where it is drawn. */
@@ -246,6 +319,28 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * is that control's, so a field in a row keeps its arrows.
      */
     private readonly handleKeydown;
+    /** The key of item `at` in `value`. See `keyField`. */
+    private keyAt;
+    /** Every item's key, in the order of the set. */
+    private keys;
+    /** The keys chosen now. */
+    private get chosen();
+    /**
+     * Selects item `at`, or lets it go, asking first. With `extend`, in
+     * `multiple`, the items from the anchor to it are taken in, as Data Table
+     * and List take in a range. Otherwise the item is where the next range runs
+     * from.
+     */
+    private press;
+    /** Keys in the order of the set, a key it no longer holds kept after them. */
+    private inOrder;
+    /** Asks for a new `value`, and says so once it has moved. */
+    private choose;
+    /**
+     * A press on a row selects it, in a list with `selection-mode`, except on a
+     * control of its own. Shift takes in a range.
+     */
+    private readonly handleClick;
     /**
      * Focuses the row for item `index`, scrolling it into view and drawing it
      * first when it is not drawn.
@@ -266,7 +361,13 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private focusing;
     /** The item drawn outside the window to keep focus, or to take it, if there is one. */
     private keptIndex;
-    /** Writes a row's role and its place in the set. */
+    /**
+     * Writes a row's role, and whether it is chosen in a list that selects:
+     * `option` with `aria-selected` there, and `listitem` otherwise. Every pass,
+     * since a choice changes no row's content.
+     */
+    private mark;
+    /** Writes a row's place in the set. */
     private stamp;
     /** Fills a drawn row from its item, by `renderItem` or by the template's holes. */
     private fill;

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

@@ -4,24 +4,30 @@ 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 { AriaForwardController, customElement, elementById, HelixElement, HelixLoadMoreEvent, HelixRangeChangeEvent, searchableById, VirtualizeController, } from '@fusion.dev/helix-core';
-import { html, render } from 'lit';
+import { AriaForwardController, commaList, customElement, elementById, HelixBeforeChangeEvent, HelixElement, HelixLoadMoreEvent, HelixRangeChangeEvent, rangeAdd, requestChange, searchableById, Typeahead, toggleValue, typesCharacter, VirtualizeController, valueAt, } from '@fusion.dev/helix-core';
+import { html, nothing, render } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { holdControls, releaseControls } from '../controls.js';
-import { fillHoles } from '../fill.js';
+import { fillHoles, textOf } from '../fill.js';
 import { stepIndex } from '../keys.js';
+import { drawPlan, stopAfter } from '../plan.js';
 let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixElement {
     constructor() {
         super(...arguments);
         this.estimate = 32;
         this.for = '';
+        this.keyField = '';
         this.label = '';
+        this.loading = false;
+        this.loadingLabel = 'Loading more';
         this.measured = false;
+        this.textField = '';
+        this.value = '';
         this.rows = [];
         this.source = null;
         this.active = 0;
         this.said = { first: 0, last: 0 };
-        this.askedAt = -1;
+        this.typeahead = new Typeahead();
         this.aria = new AriaForwardController(this, {
             label: true,
             target: () => this.partNamed('viewport'),
@@ -34,17 +40,38 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             rows: () => this.drawn(),
         });
         this.handleKeydown = (event) => {
-            if (event.defaultPrevented ||
-                event.altKey ||
-                event.ctrlKey ||
-                event.metaKey ||
-                event.shiftKey) {
+            if (event.defaultPrevented) {
                 return;
             }
             const at = this.indexOf(event.target);
             if (at === undefined) {
                 return;
             }
+            if (typesCharacter(event) && (event.key !== ' ' || this.typeahead.typing())) {
+                const found = this.typeahead.match(event.key, this.texts(), at);
+                event.preventDefault();
+                if (found >= 0 && found !== at) {
+                    void this.focusIndex(found);
+                }
+                return;
+            }
+            const toggle = event.ctrlKey || event.metaKey;
+            if (this.selectionMode && !event.altKey) {
+                if (toggle && event.key.toLowerCase() === 'a' && this.selectionMode === 'multiple') {
+                    event.preventDefault();
+                    this.choose(this.keys().join(','));
+                    return;
+                }
+                if (event.key === ' ' && !toggle) {
+                    event.preventDefault();
+                    this.press(at, event.shiftKey);
+                    return;
+                }
+            }
+            const extend = event.shiftKey && this.selectionMode === 'multiple';
+            if (event.altKey || toggle || (event.shiftKey && !extend)) {
+                return;
+            }
             const { first, last } = this.virtualize.visible();
             const next = stepIndex(event.key, at, this.data.length, last - first - 1);
             if (next === undefined) {
@@ -52,6 +79,27 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             event.preventDefault();
             void this.focusIndex(next);
+            if (extend) {
+                this.anchor ??= this.keyAt(at);
+                this.press(next, true);
+            }
+        };
+        this.handleClick = (event) => {
+            if (!this.selectionMode) {
+                return;
+            }
+            const path = event.composedPath();
+            const row = path.find((node) => node instanceof HTMLElement && node.parentElement === this);
+            const at = this.indexOf(row ?? null);
+            if (at === undefined) {
+                return;
+            }
+            const inner = path.slice(0, path.indexOf(row));
+            if (inner.some((node) => node instanceof HTMLElement &&
+                node.matches('a[href], button, input, select, textarea, label'))) {
+                return;
+            }
+            this.press(at, event.shiftKey && this.selectionMode === 'multiple');
         };
         this.handleFocusOut = () => {
             this.requestUpdate();
@@ -98,6 +146,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('keydown', this.handleKeydown);
+        this.addEventListener('click', this.handleClick);
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('focusout', this.handleFocusOut);
         if (typeof MutationObserver === 'undefined') {
@@ -113,6 +162,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('click', this.handleClick);
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('focusout', this.handleFocusOut);
         this.watcher?.disconnect();
@@ -160,17 +210,20 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             this.said = { first, last };
             this.dispatchEvent(new HelixRangeChangeEvent({ first, last }));
         }
-        const box = this.partNamed('viewport');
-        const count = this.data.length;
-        const screen = box?.clientHeight ?? 0;
-        if (count > 0 &&
-            screen > 0 &&
-            this.askedAt !== count &&
-            this.virtualize.remaining() <= screen) {
-            this.askedAt = count;
+        if (!this.loading && this.virtualize.endInSight()) {
             this.dispatchEvent(new HelixLoadMoreEvent());
         }
     }
+    texts() {
+        const field = this.textField ||
+            this.querySelector(':scope > template')
+                ?.content.querySelector('[data-field]')
+                ?.getAttribute('data-field') ||
+            '';
+        return this.data.map((item) => field === '' || item === null || typeof item !== 'object'
+            ? textOf(item)
+            : textOf(valueAt(item, field)));
+    }
     indexOf(node) {
         if (!(node instanceof HTMLElement) || node.parentElement !== this) {
             return undefined;
@@ -181,6 +234,62 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     rowFor(index) {
         return this.querySelector(`:scope > [data-index="${index}"]`);
     }
+    keyAt(at) {
+        const item = this.data[at];
+        if (this.keyField !== '' && item !== null && typeof item === 'object') {
+            return textOf(valueAt(item, this.keyField));
+        }
+        return typeof item === 'string' || typeof item === 'number' ? String(item) : String(at);
+    }
+    keys() {
+        return this.data.map((_, at) => this.keyAt(at));
+    }
+    get chosen() {
+        return new Set(commaList(this.value));
+    }
+    press(at, extend = false) {
+        const mode = this.selectionMode;
+        const key = this.keyAt(at);
+        if (!mode || at < 0 || at >= this.data.length) {
+            return;
+        }
+        const now = commaList(this.value);
+        if (extend && mode === 'multiple') {
+            const keys = this.keys();
+            const from = this.anchor === undefined ? -1 : keys.indexOf(this.anchor);
+            const range = rangeAdd(now, keys, from, at);
+            if (range) {
+                this.choose(this.inOrder(range));
+            }
+            return;
+        }
+        this.anchor = key;
+        if (mode === 'single') {
+            this.choose(now.length === 1 && now[0] === key ? '' : key);
+            return;
+        }
+        this.choose(this.inOrder(toggleValue(now, key)));
+    }
+    inOrder(keys) {
+        const wanted = new Set(keys);
+        const ordered = this.keys().filter((key) => wanted.has(key));
+        const placed = new Set(ordered);
+        return [...ordered, ...keys.filter((key) => !placed.has(key))].join(',');
+    }
+    choose(next) {
+        if (next === this.value) {
+            return;
+        }
+        requestChange({
+            apply: (value) => {
+                this.value = value;
+                this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+            },
+            event: (value) => new HelixBeforeChangeEvent({ value }),
+            host: this,
+            next,
+        });
+    }
     async focusIndex(index) {
         this.active = index;
         this.focusing = index;
@@ -211,8 +320,16 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             ? index
             : undefined;
     }
+    mark(element, at, chosen) {
+        element.setAttribute('role', this.selectionMode ? 'option' : 'listitem');
+        if (this.selectionMode) {
+            element.setAttribute('aria-selected', String(chosen.has(this.keyAt(at))));
+        }
+        else {
+            element.removeAttribute('aria-selected');
+        }
+    }
     stamp(element, at) {
-        element.setAttribute('role', 'listitem');
         element.setAttribute('aria-posinset', String(at + 1));
         element.setAttribute('aria-setsize', String(this.data.length));
         element.setAttribute('data-index', String(at));
@@ -247,24 +364,19 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         }
         const count = this.data.length;
         const { first, last } = this.virtualize.window;
-        const kept = this.keptIndex();
-        const wanted = [];
-        for (let at = first; at < Math.min(last, count); at += 1) {
-            wanted.push(at);
-        }
-        if (kept !== undefined) {
-            wanted.push(kept);
-            wanted.sort((a, b) => a - b);
-        }
-        const keep = new Set(wanted);
-        const redraw = (this.filledBy === undefined) !== (this.renderItem === undefined);
+        const children = [...this.children].filter((child) => child !== template && child instanceof HTMLElement && !child.hasAttribute('slot'));
+        const plan = drawPlan({
+            count,
+            drawn: children.map((child) => Number(child.dataset.index)),
+            first,
+            kept: this.keptIndex(),
+            last,
+            redraw: (this.filledBy === undefined) !== (this.renderItem === undefined),
+        });
         const drawn = new Map();
-        for (const child of [...this.children]) {
-            if (child === template) {
-                continue;
-            }
+        for (const child of children) {
             const index = Number(child.dataset.index);
-            if (redraw || !Number.isInteger(index) || !keep.has(index)) {
+            if (plan.remove.has(index)) {
                 child.remove();
                 continue;
             }
@@ -275,7 +387,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.filledBy = this.renderItem;
         const fresh = new Set();
         let anchor = drawn.values().next().value?.[0] ?? null;
-        for (const at of wanted) {
+        for (const at of plan.wanted) {
             const group = drawn.get(at);
             if (group) {
                 if (refill) {
@@ -290,11 +402,17 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             fresh.add(at);
             this.insertBefore(fragment, anchor);
         }
-        if (!keep.has(this.active)) {
-            const onScreen = this.virtualize.visible().first;
-            this.active = Math.max(Math.min(onScreen, Math.min(last, count) - 1), first, 0);
-        }
+        this.active = stopAfter(this.active, plan.wanted, {
+            count,
+            first,
+            last,
+            onScreen: this.virtualize.visible().first,
+        });
+        const chosen = this.chosen;
         for (const [at, group] of drawn) {
+            for (const element of group) {
+                this.mark(element, at, chosen);
+            }
             const stop = at === this.active;
             group[0]?.setAttribute('tabindex', stop ? '0' : '-1');
             if (stop && (fresh.has(at) || this.released !== at)) {
@@ -311,7 +429,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         return html `<div
       data-scroller
       part="viewport"
-      role="list"
+      role=${this.selectionMode ? 'listbox' : 'list'}
+      aria-multiselectable=${this.selectionMode === 'multiple' ? 'true' : nothing}
+      aria-busy=${this.loading ? 'true' : nothing}
       aria-label=${this.label}
       @scroll=${() => {
             this.virtualize.measure();
@@ -321,6 +441,11 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
       <div part="before" style="block-size: ${before}px"></div>
       <slot></slot>
       <div part="after" style="block-size: ${after}px"></div>
+      ${this.loading
+            ? html `<div part="loading" role=${this.selectionMode ? 'option' : 'listitem'}>
+              <slot name="loading">${this.loadingLabel}</slot>
+            </div>`
+            : nothing}
     </div>`;
     }
 };
@@ -333,15 +458,33 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessVirtualList.prototype, "items", void 0);
+__decorate([
+    property({ attribute: 'key-field' })
+], HelixHeadlessVirtualList.prototype, "keyField", void 0);
 __decorate([
     property()
 ], HelixHeadlessVirtualList.prototype, "label", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessVirtualList.prototype, "loading", void 0);
+__decorate([
+    property({ attribute: 'loading-label' })
+], HelixHeadlessVirtualList.prototype, "loadingLabel", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessVirtualList.prototype, "measured", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessVirtualList.prototype, "renderItem", void 0);
+__decorate([
+    property({ attribute: 'selection-mode' })
+], HelixHeadlessVirtualList.prototype, "selectionMode", void 0);
+__decorate([
+    property({ attribute: 'text-field' })
+], HelixHeadlessVirtualList.prototype, "textField", void 0);
+__decorate([
+    property()
+], HelixHeadlessVirtualList.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessVirtualList.prototype, "rows", void 0);