@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -1,30 +1,97 @@
 import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * Draws one item into its row, for a list given `renderItem`.
+ *
+ * Returns anything Lit renders: a template from `html`, a string, or a DOM
+ * node the function built.
+ */
+export type VirtualListRenderer = (item: unknown, index: number) => unknown;
+/** Where `scrollToIndex` puts an item, and how it gets there. */
+export interface VirtualListScrollOptions {
+    /**
+     * Where the item lands: the least distance that shows it whole (`nearest`,
+     * the default), or at the box's `start`, `center` or `end`.
+     */
+    align?: 'center' | 'end' | 'nearest' | 'start';
+    /** The platform's scroll behavior. Instant when left out. */
+    behavior?: ScrollBehavior;
+}
+/** The items on screen: `items.slice(first, last)`. */
+export interface VirtualListRange {
+    /** The index of the first item on screen. */
+    first: number;
+    /** One past the index of the last item on screen. */
+    last: number;
+}
 /**
  * @summary A list that renders only the rows of a long set that are on screen.
  *
  * @description
- * The items arrive as data:
+ * The items arrive as data, in one of two ways:
+ *
+ * - `items` takes an array. A framework sets it as a property, and React
+ *   hydration keeps it.
+ * - `for` names a `<script type="application/json">` that holds an array, which
+ *   a server sends as markup.
+ *
+ * Each item is drawn into a row in one of two ways:
+ *
+ * - `renderItem` is a function from an item and its index to the row's
+ *   content: a Lit template, a string, or a DOM node.
+ * - A `<template>` child defines one row. `data-field="name"` fills an element
+ *   with the item's `name` as text, and `data-field-href="url"` writes the
+ *   item's `url` into `href`, the same for any attribute. A field may be a path
+ *   of keys, such as `author.name`.
+ *
+ * Rows are your markup in the light DOM, so your stylesheet styles them.
+ *
+ * **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.
  *
- * - `for` names a `<script type="application/json">` that holds an array of
- *   objects.
- * - A `<template>` child defines one row. Elements with `data-field="name"` are
- *   filled with that field of the item.
+ * **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`.
  *
- * Both are markup. React hydration skips every property it would have to set
- * imperatively, so an `items` property would be lost, and light-DOM children
- * would all exist before anything could window them. The JSON text is one node
- * whatever the row count.
+ * **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. 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.
  *
- * For assistive technology the list exposes the rendered window with
- * `aria-setsize`. Charts that use the same `for="<id>"` shape render an
- * accessible `<table>`, and ten thousand rows in one is the cost this component
- * avoids.
+ * **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 the source: editing the script's text, or replacing the
- * script under the same id, draws the new rows. A row that stays in view keeps
- * its element as the list scrolls, and the row holding focus stays drawn when
- * it scrolls out, so a link or a button in a row keeps focus.
+ * 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
+ * stays in view keeps its element as the list scrolls.
  *
  * The viewport scrolls on this tier. It carries `data-scroller`, and `core`
  * ships `[data-scroller] { overflow: auto }` into every shadow root, so
@@ -36,9 +103,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @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 {
@@ -50,9 +124,24 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      */
     estimate: number;
     /**
-     * The id of the script element that holds the rows as JSON.
+     * The id of the script element that holds the items as JSON. `items` wins
+     * where both are set.
      */
     for: string;
+    /**
+     * The items, as an array. Set it as a property.
+     *
+     * Each item is drawn by `renderItem`, or into the row `<template>` by its
+     * fields. A new array draws the new rows, so replace the array to change it.
+     * 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.
@@ -62,28 +151,83 @@ 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.
      */
     measured: boolean;
     /**
-     * The parsed source.
+     * Draws one item into its row, given the item and its index. Set it as a
+     * property.
+     *
+     * It returns what Lit renders: a template from `html`, a string, or a DOM
+     * node. The list wraps each result in a `<div>` that carries the row's role
+     * 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.
      *
      * Empty on a server, which has nothing to read.
      */
     private rows;
     /** The `for` that `rows` came from, so it is read again only when that changes. */
     private readFor;
-    /** The rows the drawn elements were filled from, so new data fills them again. */
+    /** The items the drawn rows were filled from, so new data fills them again. */
     private filledFrom;
+    /** The function the drawn rows were filled by, so a new one draws them again. */
+    private filledBy;
     /** The script the rows were read from, which the watcher follows. */
     private source;
+    /**
+     * The item whose row holds the tab stop.
+     *
+     * A plain field, because the pass that places the rows is the one that keeps
+     * it on a drawn row and writes the `tabindex` that follows from it.
+     */
+    private active;
+    /** The item whose row's own controls are in the tab order. */
+    private released;
+    /** The range last reported, so `helix-range-change` fires only on a change. */
+    private said;
+    /** 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.
      *
@@ -96,6 +240,23 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     /** Carries a host `aria-label` and `aria-labelledby` to the element with the `list` role. */
     protected readonly aria: AriaForwardController;
     private readonly virtualize;
+    /**
+     * The items on screen, as `items.slice(first, last)` reads them.
+     *
+     * Read from the scroll offset when asked. Both are 0 before the list has a
+     * box to measure.
+     */
+    get range(): VirtualListRange;
+    /**
+     * Scrolls the list to show the item at `index`.
+     *
+     * By default the least distance that shows it whole. `align` puts it at the
+     * `start`, `center` or `end` of the box, and `behavior: 'smooth'` animates the
+     * scroll. An index past either end goes to the first or the last item.
+     */
+    scrollToIndex(index: number, options?: VirtualListScrollOptions): void;
+    /** The items in force: `items` where it is set, and the script otherwise. */
+    private get data();
     /**
      * The rows in the tree, each with the item it drew.
      *
@@ -133,6 +294,62 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     private read;
+    /**
+     * Fires `helix-range-change` when the items on screen moved, and
+     * `helix-load-more` when a reader is within one screen of the end.
+     *
+     * After a render and on every scroll, which are the two times either can
+     * change. `helix-load-more` waits for a box with a height, so a list that
+     * 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. */
+    private rowFor;
+    /**
+     * Moves between items with the keys `stepIndex` names.
+     *
+     * Only from a row itself. A key pressed in a row's own link, button or field
+     * 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.
+     */
+    private focusIndex;
+    /** The row kept for focus is let go once focus has left it. */
+    private readonly handleFocusOut;
+    /** A row that takes focus, by a press or by Tab, takes the tab stop with it. */
+    private readonly handleFocusIn;
     /**
      * The item whose row holds focus, where one does.
      *
@@ -140,10 +357,22 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * own shadow root to the row's element.
      */
     private focusedIndex;
-    /** The item drawn outside the window to keep focus, if there is one. */
+    /** The item a key is moving focus to, drawn until it has it. */
+    private focusing;
+    /** The item drawn outside the window to keep focus, or to take it, if there is one. */
     private keptIndex;
-    /** Fills a row's holes and its place in the set from an item. */
+    /**
+     * 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;
+    /** New elements for item `at`: a `<div>` for `renderItem`, or the template's clone. */
+    private draw;
     /**
      * Puts the windowed rows into the light DOM, and takes the rest out.
      *
@@ -151,10 +380,14 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * cloning every row on every move replaced the node a reader had focused,
      * so a link in a row lost focus to the body on any scroll, even with its row
      * still on screen. Rows are keyed by item: the ones leaving go, the ones
-     * arriving are cloned in their place, and the ones staying are not moved.
+     * arriving are drawn in their place, and the ones staying are not moved.
      *
      * **The row holding focus is drawn outside the window too**, beside it on the
      * side it belongs, and the spacer on that side gives up its room.
+     *
+     * **One row holds the tab stop**, the one the reader last focused while it is
+     * drawn, and the first row on screen once it is not. Its own links and
+     * buttons are in the tab order, and those of every other row wait.
      */
     private place;
     protected render(): TemplateResult;