@fusion.dev/helix-headless 0.143.0 → 0.145.0

package/dist/video-playlist/root/video-playlist-root.d.ts

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import { type Repeat } from '../order.js';
 declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
  * @summary A list of video clips that play one after another in a single player.
@@ -22,7 +23,11 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * - the player reaches the end.
  *
  * On `ended` the playlist advances and the next clip starts playing, because
- * the user already pressed play once.
+ * the user already pressed play once. `repeat` decides what happens at the
+ * end: `one` plays the same entry again, and `all` goes from the last entry
+ * back to the first. Without it, the playlist stops on the last entry and
+ * sends `helix-end`. `shuffle` plays the entries in a random order, starting
+ * from the one that is current, and `previous` retraces that order.
  *
  * @since 0.1.0
  * @status stable
@@ -35,6 +40,7 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  *
  * @event {HelixActivateEvent} helix-activate - The current entry changed. The playlist already holds the new entry when this is sent.
  * @event {HelixBeforeActivateEvent} helix-before-activate - The current entry is about to change. Cancelable: cancel it to keep the current entry.
+ * @event {HelixEndEvent} helix-end - The last entry finished playing, and the playlist stopped there. Not sent while `repeat` is set.
  *
  * @csspart items - The list of entries.
  * @csspart player - The region that holds the player.
@@ -44,6 +50,30 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * The list's name, read by screen readers.
      */
     label: string;
+    /**
+     * What happens when an entry ends with no next one to go to. `one` plays the
+     * same entry again, and `all` goes from the last entry back to the first.
+     * Absent, the playlist stops on the last entry and sends `helix-end`.
+     *
+     * `all` also lets the next and previous controls go round, so next on the
+     * last entry is the first. `one` changes only what an ending does: next and
+     * previous still move, being a reader asking for another entry.
+     */
+    repeat?: Repeat;
+    /**
+     * Whether the entries play in a random order. The order starts from the
+     * entry that is current, and holds until shuffle is turned off or an entry
+     * arrives or leaves, so previous goes back through what has played.
+     */
+    shuffle: boolean;
+    /**
+     * The shuffled order of the entries' values, while `shuffle` is on.
+     *
+     * Held rather than drawn on each step, so previous retraces the way next
+     * came. Dropped when shuffle turns off, so turning it on again deals a new
+     * order from wherever the reader is.
+     */
+    private dealt;
     /**
      * The entries, in the order the consumer wrote them.
      *
@@ -82,14 +112,52 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * contract.
      */
     private get player();
-    /** Moves by one, and does nothing at either end. */
+    /**
+     * The entry a step of `by` lands on, in the order the playlist plays in, or
+     * `undefined` past an end. Disabled entries are not in the order, so a step
+     * passes over them.
+     */
+    private following;
+    /**
+     * Moves by one in the playing order and plays what it lands on. At an end it
+     * stays, unless `repeat` is `all`.
+     *
+     * A move a consumer refuses with `helix-before-activate` plays nothing, and
+     * leaves nothing behind to play on a later change.
+     */
     private step;
+    /**
+     * Plays the current entry again from its start, which is what an ending
+     * under `repeat="one"` asks for, and a list of one under `repeat="all"`.
+     */
+    private replay;
+    /**
+     * Moves to the next entry and plays it, as the player's next control does.
+     * Follows `shuffle`, goes round under `repeat="all"`, and stays on the last
+     * entry otherwise.
+     */
+    next(): void;
+    /**
+     * Moves to the previous entry and plays it, as the player's previous control
+     * does. Under `shuffle` it goes back through the order that played.
+     */
+    previous(): void;
     private readonly handleSelect;
     private readonly handleNext;
     private readonly handlePrevious;
+    /**
+     * An entry ended: the same one again under `repeat="one"`, the next one in
+     * the order, or, past the last, `helix-end`.
+     *
+     * **A notification with no class of its own**, sent as a plain event and
+     * carrying nothing: the playlist is still on the last entry, and `active`
+     * says which. Not sent under `repeat`, where a list never runs out.
+     */
     private readonly handleEnded;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** A shuffle turned off forgets its order, so the next one is new. */
+    protected willUpdate(changed: PropertyValues): void;
     /**
      * Points the player at the current entry, and tells the entries which is on.
      *

package/dist/video-playlist/root/video-playlist-root.js

@@ -4,14 +4,16 @@ 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, MixinControllerActive } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HelixEndEvent, MixinControllerActive, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessVideoPlaylistItem } from '../item/video-playlist-item.js';
+import { playOrder, stepTo } from '../order.js';
 let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
         this.label = 'Playlist';
+        this.shuffle = false;
         this.chased = false;
         this.handleSelect = (event) => {
             event.stopImmediatePropagation();
@@ -22,18 +24,23 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             this.requestActive(event.detail.value);
         };
         this.handleNext = () => {
-            this.chased = true;
-            this.step(1);
+            this.next();
         };
         this.handlePrevious = () => {
-            this.chased = true;
-            this.step(-1);
+            this.previous();
         };
         this.handleEnded = (event) => {
             if (event.target !== this.player) {
                 return;
             }
-            this.chased = true;
+            if (this.repeat === 'one') {
+                this.replay();
+                return;
+            }
+            if (this.following(1).next === undefined) {
+                this.dispatchEvent(new HelixEndEvent());
+                return;
+            }
             this.step(1);
         };
     }
@@ -42,17 +49,44 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
     }
     get player() {
         const slot = this.renderRoot?.querySelector('slot[name="player"]');
-        const first = slot?.assignedElements()[0];
-        return (first ?? null);
+        return slot?.assignedElements()[0] ?? null;
     }
-    step(by) {
+    following(by) {
         const items = this.items.filter((one) => !one.disabled);
-        const at = items.findIndex((one) => one.value === this.resolveActive(items)?.value);
-        const next = items[at + by];
-        if (next) {
-            this.requestActive(next.value);
+        const values = items.map((one) => one.value);
+        const current = this.resolveActive(items)?.value;
+        this.dealt = this.shuffle ? playOrder(values, true, this.dealt, current) : undefined;
+        const order = this.dealt ?? values;
+        return { current, next: stepTo(order, current, by, this.repeat === 'all') };
+    }
+    step(by) {
+        const { current, next } = this.following(by);
+        if (next === undefined) {
+            return;
+        }
+        if (next === current) {
+            this.replay();
+            return;
+        }
+        this.chased = true;
+        if (!this.requestActive(next)) {
+            this.chased = false;
         }
     }
+    replay() {
+        const player = this.player;
+        if (!player) {
+            return;
+        }
+        player.currentTime = 0;
+        void Promise.resolve(player.play()).catch(() => { });
+    }
+    next() {
+        this.step(1);
+    }
+    previous() {
+        this.step(-1);
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelect);
@@ -67,6 +101,12 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.removeEventListener('helix-previous', this.handlePrevious);
         this.removeEventListener('ended', this.handleEnded, true);
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has('shuffle') && !this.shuffle) {
+            this.dealt = undefined;
+        }
+    }
     updated(changed) {
         super.updated?.(changed);
         const items = this.items;
@@ -83,9 +123,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             player.poster = current.poster;
             player.label = current.text;
             if (this.chased) {
-                void player.updateComplete?.then(() => {
-                    player.play();
-                });
+                void player.updateComplete?.then(() => player.play()).catch(() => { });
             }
         }
         this.chased = false;
@@ -100,6 +138,12 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
 __decorate([
     property()
 ], HelixHeadlessVideoPlaylist.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessVideoPlaylist.prototype, "repeat", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessVideoPlaylist.prototype, "shuffle", void 0);
 HelixHeadlessVideoPlaylist = __decorate([
     customElement('helix-headless-video-playlist')
 ], HelixHeadlessVideoPlaylist);

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

@@ -0,0 +1,4 @@
+/** Takes the controls in `rows` out of the tab order. */
+export declare const holdControls: (rows: Element[]) => void;
+/** Puts the controls in `rows` back in the tab order, as they were written. */
+export declare const releaseControls: (rows: Element[]) => void;

package/dist/virtual-list/controls.js

@@ -0,0 +1,30 @@
+import { focusableElements } from '@fusion.dev/helix-core';
+const held = new WeakMap();
+export const holdControls = (rows) => {
+    for (const row of rows) {
+        if (!(row instanceof HTMLElement)) {
+            continue;
+        }
+        for (const control of focusableElements(row)) {
+            held.set(control, control.getAttribute('tabindex'));
+            control.setAttribute('tabindex', '-1');
+        }
+    }
+};
+export const releaseControls = (rows) => {
+    for (const row of rows) {
+        for (const control of row.querySelectorAll('[tabindex]')) {
+            if (!held.has(control)) {
+                continue;
+            }
+            const was = held.get(control);
+            held.delete(control);
+            if (was === null || was === undefined) {
+                control.removeAttribute('tabindex');
+            }
+            else {
+                control.setAttribute('tabindex', was);
+            }
+        }
+    }
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Filling a row from an item, for a list whose rows come from a `<template>`.
+ *
+ * A row template marks its holes with data attributes, so it stays markup a
+ * server can send and a framework can write as a string:
+ *
+ * - `data-field="name"` takes the item's `name` as its text.
+ * - `data-field-href="url"` takes the item's `url` as its `href`, and the same
+ *   for any attribute: `data-field-aria-label`, `data-field-src`,
+ *   `data-field-title`.
+ *
+ * A field is a key, or a path of keys joined by dots (`author.name`).
+ */
+/**
+ * The value at `path` in `item`, or `undefined` where the path leads nowhere.
+ *
+ * A dot separates keys, so `author.name` reads `item.author.name`. A key that
+ * holds a dot itself is read whole first, which keeps a flat record with a key
+ * such as `"v1.2"` working.
+ */
+export declare const valueAt: (item: unknown, path: string) => unknown;
+/**
+ * The text a value takes in a row.
+ *
+ * Nothing for a missing value, so a hole whose field is absent is empty and
+ * does not read "undefined".
+ */
+export declare const textOf: (value: unknown) => string;
+/** Fills one element's holes, its own and those below it, from an item. */
+export declare const fillHoles: (root: Element, item: unknown) => void;

package/dist/virtual-list/fill.js

@@ -0,0 +1,39 @@
+export const valueAt = (item, path) => {
+    if (item === null || typeof item !== 'object') {
+        return undefined;
+    }
+    const record = item;
+    if (path in record) {
+        return record[path];
+    }
+    let value = record;
+    for (const key of path.split('.')) {
+        if (value === null || typeof value !== 'object') {
+            return undefined;
+        }
+        value = value[key];
+    }
+    return value;
+};
+export const textOf = (value) => value === undefined || value === null || typeof value === 'object' ? '' : String(value);
+const ATTRIBUTE = 'data-field-';
+const writeAttribute = (element, name, value) => {
+    if (value === undefined || value === null || value === false) {
+        element.removeAttribute(name);
+        return;
+    }
+    element.setAttribute(name, value === true ? '' : textOf(value));
+};
+export const fillHoles = (root, item) => {
+    const holes = [...(root.matches('[data-field]') ? [root] : []), ...root.querySelectorAll('*')];
+    for (const hole of holes) {
+        for (const { name, value } of [...hole.attributes]) {
+            if (name === 'data-field') {
+                hole.textContent = textOf(valueAt(item, value));
+            }
+            else if (name.startsWith(ATTRIBUTE)) {
+                writeAttribute(hole, name.slice(ATTRIBUTE.length), valueAt(item, value));
+            }
+        }
+    }
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Which item a key moves to in a vertical list of `count` items, from `at`.
+ *
+ * Index arithmetic, because most of the items are not drawn: the list moves to
+ * an index, scrolls it into view, and focuses the row once it is there. The
+ * keys are the ones a listbox answers:
+ *
+ * - Up and Down move one item.
+ * - Home and End move to the first and the last.
+ * - Page Up and Page Down move by `page`, the number of items on screen less
+ *   one, so the item at one edge of the box lands at the other.
+ *
+ * `undefined` for a key the list does not take, and for an empty list.
+ */
+export declare const stepIndex: (key: string, at: number, count: number, page: number) => number | undefined;

package/dist/virtual-list/keys.js

@@ -0,0 +1,24 @@
+export const stepIndex = (key, at, count, page) => {
+    if (count <= 0) {
+        return undefined;
+    }
+    const last = count - 1;
+    const from = Math.max(0, Math.min(at, last));
+    const jump = Math.max(1, page);
+    switch (key) {
+        case 'ArrowDown':
+            return Math.min(last, from + 1);
+        case 'ArrowUp':
+            return Math.max(0, from - 1);
+        case 'End':
+            return last;
+        case 'Home':
+            return 0;
+        case 'PageDown':
+            return Math.min(last, from + jump);
+        case 'PageUp':
+            return Math.max(0, from - jump);
+        default:
+            return undefined;
+    }
+};

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

@@ -1,30 +1,70 @@
 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:
  *
- * - `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.
+ * - `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`.
  *
- * 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.
+ * Rows are your markup in the light DOM, so your stylesheet styles them.
  *
- * 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.
+ * **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.
  *
- * 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.
+ * 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.
+ *
+ * **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.
+ *
+ * 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
@@ -37,6 +77,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @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.
  *
+ * @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 viewport - The scrolling box. On this tier, it needs only a block size.
@@ -50,9 +93,18 @@ 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 list's name, read by screen readers, because only some of its rows
      * are rendered at a time.
@@ -73,17 +125,41 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      */
     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;
+    /**
+     * 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 length of the set when `helix-load-more` last fired. */
+    private askedAt;
     /**
      * Watches the source and the tree around it.
      *
@@ -96,6 +172,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 +226,35 @@ 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 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;
+    /**
+     * 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 +262,16 @@ 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 its 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 +279,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;