@fusion.dev/helix-headless 0.172.0 → 0.173.0

package/dist/timeline/item/timeline-item.d.ts

@@ -14,7 +14,9 @@ type TimelineTone = 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'war
  * hours ago", from `datetime`, where the `time` slot is empty. The words move
  * on as they go stale, "3 hours ago" becoming "4 hours ago", with one wakeup
  * shared by every reading on the page, as `FormatDate` keeps its own. They are
- * in the language of the page, or of the nearest `lang`.
+ * in the language of the page, or of the nearest `lang`. The whole date and
+ * time is the reading's `title`, so a pointer resting on "3 hours ago" shows
+ * when it was, and a screen reader reads it as the description.
  *
  * Each entry draws the connector line that arrives at it and hides it when it
  * is the first entry, using `:host(:first-child)`. This needs no index, no
@@ -77,6 +79,8 @@ export declare class HelixHeadlessTimelineItem extends HelixElement {
      * otherwise.
      */
     private reading;
+    /** The whole date and time `datetime` names, the reading's title under `relative`. */
+    private whole;
     /** The instant `datetime` names, where `relative` asks for a reading of it. */
     private get moment();
     /** What the reading says at `now`, and when it stops being true. */

package/dist/timeline/item/timeline-item.js

@@ -21,6 +21,7 @@ let HelixHeadlessTimelineItem = class HelixHeadlessTimelineItem extends HelixEle
             },
         });
         this.reading = '';
+        this.whole = '';
         this.pendingLabel = 'Scheduled';
         this.toneLabel = '';
         this.toneLabels = {
@@ -52,6 +53,13 @@ let HelixHeadlessTimelineItem = class HelixHeadlessTimelineItem extends HelixEle
         }
         const moment = this.moment;
         this.reading = moment ? this.readingAt(moment, new Date(this.clock.now)).text : '';
+        const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(this.datetime);
+        this.whole = moment
+            ? new Intl.DateTimeFormat(wordsLocale(this), {
+                dateStyle: 'long',
+                ...(dateOnly ? { timeZone: 'UTC' } : { timeStyle: 'short' }),
+            }).format(moment)
+            : '';
         hostAria(this.internals, { role: 'listitem' });
     }
     renderMarker() {
@@ -78,6 +86,7 @@ let HelixHeadlessTimelineItem = class HelixHeadlessTimelineItem extends HelixEle
             : html `<time
               part="time"
               datetime=${this.datetime}
+              title=${this.whole || nothing}
               >${when}</time
             >`}
       <div part="content"><slot></slot></div>`;

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

@@ -26,6 +26,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * Write the entries in the order the events happened, oldest or newest first,
  * and the layout only moves where they are drawn.
  *
+ * **A feed that loads more entries sets `loading` while it fetches.** The
+ * timeline is busy, and an entry after the last says "Loading more"
+ * (`loading-label`, or your own content in the `loading` slot). Put a button
+ * that asks for more after the timeline, and move focus to the first new
+ * entry when they arrive.
+ *
  * @since 0.1.0
  * @status stable
  * @category data
@@ -33,12 +39,29 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/timeline
  *
  * @slot - The entries, and any groups of them.
+ * @slot loading - Content for the entry after the last while `loading` is set. Falls back to `loading-label`.
+ *
+ * @csspart loading - The entry after the last while `loading` is set.
+ *
+ * @cssstate loading - While `loading` is set.
  */
 export declare class HelixHeadlessTimeline extends HelixElement {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-timeline': { loadingLabel: 'Wird geladen' } })`.
+     */
+    static words: string;
     /**
      * Accessible name for the timeline, for people who reach it out of context.
      */
     label: string;
+    /**
+     * Marks the timeline as busy fetching more entries, and draws an entry
+     * after the last that says so.
+     */
+    loading: boolean;
+    /** The text of the entry drawn while `loading` is set, where the `loading` slot is empty. */
+    loadingLabel: string;
     protected render(): TemplateResult;
     protected willUpdate(changed: PropertyValues): void;
 }

package/dist/timeline/root/timeline-root.js

@@ -4,25 +4,39 @@ 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 { customElement, HelixElement, hostAria, words } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessTimeline = class HelixHeadlessTimeline extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.loading = false;
+        this.loadingLabel = 'Loading more';
     }
+    static { this.words = 'helix-timeline'; }
     render() {
-        return html `<slot></slot>`;
+        return html `<slot></slot>${this.loading
+            ? html `<div part="loading" role="listitem"><slot name="loading">${this.loadingLabel}</slot></div>`
+            : nothing}`;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'list' });
+        this.internals.ariaBusy = this.loading ? 'true' : null;
+        this.toggleState('loading', this.loading);
     }
 };
 __decorate([
     property()
 ], HelixHeadlessTimeline.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTimeline.prototype, "loading", void 0);
+__decorate([
+    words,
+    property({ attribute: 'loading-label' })
+], HelixHeadlessTimeline.prototype, "loadingLabel", void 0);
 HelixHeadlessTimeline = __decorate([
     customElement('helix-headless-timeline')
 ], HelixHeadlessTimeline);

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

@@ -32,6 +32,9 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * describes a Helix component and leaves a plain element undescribed. In the
  * `for` form the tooltip itself is out of the accessibility tree while its
  * bubble is down, so you meet its words once, as the trigger's description.
+ * A trigger whose name is already the tooltip's words, such as an icon button
+ * named Settings under a tooltip reading Settings, is not described by them
+ * again.
  *
  * The tooltip shows on hover and on focus. It hides on pointer leave, on blur,
  * on Escape, and when the trigger is activated. The pointer can move from the
@@ -394,6 +397,13 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * plain element in the consumer's markup. See `linkDescription`.
      */
     private link;
+    /**
+     * Whether the bubble's words add anything to the trigger: they are not
+     * empty, and they are not the trigger's own name, such as an icon button
+     * named Settings under a tooltip reading Settings, which a screen reader
+     * read as "Settings, Settings".
+     */
+    private get describes();
     /** A reader arriving on the trigger, which is late enough to write the link. */
     private readonly linkOnArrival;
     private unbind;

package/dist/tooltip/root/tooltip-root.js

@@ -213,17 +213,22 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         });
     }
     link(light, target = focusTarget(this.trigger)) {
-        if (this.linked === target) {
+        const describes = this.describes;
+        if (this.linked === target && describes) {
             return;
         }
         if (this.linked) {
             unlinkDescription(this.linked, this);
             this.linked = undefined;
         }
-        if (linkDescription(target, this, light)) {
+        if (describes && linkDescription(target, this, light)) {
             this.linked = target;
         }
     }
+    get describes() {
+        const text = this.describedText;
+        return text !== '' && !this.triggerSays(text);
+    }
     unbind() {
         if (this.linked) {
             unlinkDescription(this.linked, this);
@@ -314,6 +319,13 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         if (changed.has('for')) {
             this.bind();
         }
+        if (this.linked && !this.describes) {
+            unlinkDescription(this.linked, this);
+            this.linked = undefined;
+        }
+        else if (!this.linked && this.bound) {
+            this.link(false);
+        }
         if (changed.has('open')) {
             const warm = warmth();
             if (this.open) {

package/dist/virtual-list/reorder/index.d.ts

@@ -0,0 +1 @@
+export { reorderVirtualList, VirtualListReorderController } from './virtual-list-reorder.js';

package/dist/virtual-list/reorder/index.js

@@ -0,0 +1,4 @@
+import { HelixHeadlessVirtualList } from '../root/virtual-list-root.js';
+import { reorderVirtualList } from './virtual-list-reorder.js';
+reorderVirtualList(HelixHeadlessVirtualList);
+export { reorderVirtualList, VirtualListReorderController } from './virtual-list-reorder.js';

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

@@ -0,0 +1,86 @@
+import type { CSSResult, ReactiveController } from 'lit';
+import type { HelixHeadlessVirtualList } from '../root/virtual-list-root.js';
+/**
+ * Moves the items of a `reorderable` virtual list, by pointer and by keyboard,
+ * and says each move in a region screen readers announce.
+ *
+ * **Its own entry**, `@fusion.dev/helix-headless/virtual-list/reorder`, so a
+ * list that never moves items carries none of this. Importing the entry gives
+ * every virtual list one, and `reorderable` turns it on.
+ *
+ * - **Alt with Up or Down** moves the item the keys are on a place at once,
+ *   and Alt with Home or End to either end, as the APG's rearrangeable
+ *   listbox does. Across, Alt with Left or Right does, mirrored right to left.
+ *   The keys stay on the item that moved.
+ * - **A pointer** drags a whole row, with no grip: a press that travels is a
+ *   drag, and one that does not is still a press. The list scrolls near an
+ *   edge.
+ * - **The page moves the items.** A drop sends `helix-before-reorder` and then
+ *   `helix-reorder` with every key in the new order.
+ *
+ * A row being dragged carries `data-dragging`, and the row a drop would land
+ * beside `data-drop-before` or `data-drop-after`. While a pointer drags a row,
+ * a copy of it follows the pointer in the list's `drag-preview` part. The
+ * styled tier's entry hands in the sheet that draws those, which the list
+ * adopts while it reorders.
+ */
+export declare class VirtualListReorderController implements ReactiveController {
+    private readonly host;
+    /** The sheet the list adopts while it reorders, from the styled tier. */
+    sheet: CSSResult | undefined;
+    /** The rows marked last, so a mark that moves is taken off where it was. */
+    private marked;
+    /** The region each move is said in, drawn while the list reorders. */
+    private live;
+    private readonly reorder;
+    constructor(host: HelixHeadlessVirtualList, sheet?: CSSResult);
+    /** Whether the list moves its items now: one column, without sections. */
+    private get enabled();
+    /**
+     * The words of each drawn row by its item's key, as they were when the list
+     * last drew. A move is said after the page has moved the items and before
+     * the rows are drawn again, so a row's own words then belong to another item.
+     */
+    private names;
+    hostUpdated(): void;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** The rows the list draws now. */
+    private get rows();
+    /** The key of the item a row draws. */
+    private keyOf;
+    /** The row that draws the item with that key, where one is drawn. */
+    private rowFor;
+    /** The row an event passed through. */
+    private rowOf;
+    /** The place an item moved by a key goes to, until the page has moved it. */
+    private waiting;
+    /**
+     * Keeps the keys on the item that moved. The page moves the items as it
+     * hears this, and the rows are drawn again in place, so the row that had
+     * focus now draws another item. Focus goes to the item's new row once the
+     * list has drawn it.
+     */
+    private readonly handleReorder;
+    /**
+     * Draws the list's `drag-preview` part and its region for the words while it
+     * reorders, and takes them away after. The list's own template draws
+     * neither.
+     */
+    private draw;
+    /** Puts each row's mark in a move on it, and the styled tier's sheet on the list. */
+    private mark;
+}
+/**
+ * Gives every virtual list of a class a `VirtualListReorderController`, and
+ * the class the words it says, as properties that read and write their
+ * attributes: `movedLabel`, `canceledLabel`, `droppedLabel`, and
+ * `pickedUpLabel`.
+ *
+ * The entries call it for their own tier's class: the headless entry for
+ * `HelixHeadlessVirtualList`, and the styled one for `HelixVirtualList`, with
+ * the sheet that draws a move. **Lists already on the page are given one
+ * too**, so a page that imports the list and then this entry has its lists
+ * reorder.
+ */
+export declare const reorderVirtualList: (element: typeof HelixHeadlessVirtualList, sheet?: CSSResult) => void;

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

@@ -0,0 +1,193 @@
+import { ReorderController } from '@fusion.dev/helix-core';
+const WORDS = {
+    canceledLabel: ['canceled-label', 'Canceled'],
+    droppedLabel: ['dropped-label', 'Dropped'],
+    movedLabel: ['moved-label', '{name} moved to position {position} of {count}'],
+    pickedUpLabel: ['picked-up-label', 'Picked up {name}'],
+};
+const MOVES = ['dragging', 'drop-after', 'drop-before'];
+export class VirtualListReorderController {
+    constructor(host, sheet) {
+        this.marked = new Set();
+        this.names = new Map();
+        this.handleReorder = (event) => {
+            const { to } = event.detail;
+            const focused = this.host.contains(document.activeElement);
+            if (!focused) {
+                return;
+            }
+            this.waiting = to;
+            setTimeout(() => {
+                const at = this.waiting;
+                this.waiting = undefined;
+                if (at !== undefined && !event.defaultPrevented && this.host.isConnected) {
+                    void this.host.focusIndex(at);
+                }
+            }, 0);
+        };
+        this.host = host;
+        this.sheet = sheet;
+        host.addController(this);
+        this.reorder = new ReorderController(host, {
+            get axis() {
+                return host.orientation === 'horizontal' ? 'inline' : 'block';
+            },
+            box: (key) => this.rowFor(key)?.getBoundingClientRect(),
+            current: () => {
+                const row = this.rows.find((one) => one.hasAttribute('data-active'));
+                return row && !row.hasAttribute('data-disabled') ? this.keyOf(row) : undefined;
+            },
+            enabled: () => this.enabled,
+            grip: (event) => {
+                const row = this.rowOf(event);
+                const key = row && !row.hasAttribute('data-disabled') ? this.keyOf(row) : undefined;
+                return row && key !== undefined ? { element: row, key } : undefined;
+            },
+            holds: false,
+            keys: () => host.keys(),
+            name: (key) => this.names.get(key) || key,
+            preview: (key) => this.rowFor(key),
+            say: (words) => {
+                if (this.live) {
+                    this.live.textContent = words;
+                }
+            },
+            scroller: () => host.renderRoot?.querySelector('[part="viewport"]') ?? null,
+        });
+    }
+    get enabled() {
+        const host = this.host;
+        return (host.reorderable && host.columns <= 1 && host.minColumnWidth <= 0 && host.sectionField === '');
+    }
+    hostUpdated() {
+        queueMicrotask(() => this.mark());
+    }
+    hostConnected() {
+        this.host.addEventListener('helix-reorder', this.handleReorder);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('helix-reorder', this.handleReorder);
+        this.waiting = undefined;
+    }
+    get rows() {
+        return [...this.host.querySelectorAll(':scope > [data-index]')];
+    }
+    keyOf(row) {
+        const at = Number(row.dataset.index);
+        return Number.isInteger(at) ? this.host.keys()[at] : undefined;
+    }
+    rowFor(key) {
+        const at = this.host.keys().indexOf(key);
+        return at < 0
+            ? undefined
+            : (this.host.querySelector(`:scope > [data-index="${at}"]`) ?? undefined);
+    }
+    rowOf(event) {
+        const rows = this.rows;
+        return event
+            .composedPath()
+            .find((node) => rows.includes(node));
+    }
+    draw(on) {
+        const root = this.host.renderRoot;
+        if (!root) {
+            return;
+        }
+        const drawn = root.querySelector('[part="drag-preview"]');
+        if (on && !drawn) {
+            const preview = document.createElement('div');
+            for (const [name, value] of [
+                ['part', 'drag-preview'],
+                ['popover', 'manual'],
+                ['aria-hidden', 'true'],
+                ['inert', ''],
+            ]) {
+                preview.setAttribute(name, value);
+            }
+            const live = document.createElement('span');
+            live.setAttribute('role', 'status');
+            live.setAttribute('data-reorder-live', '');
+            root.append(preview, live);
+            this.live = live;
+        }
+        else if (!on && drawn) {
+            drawn.remove();
+            this.live?.remove();
+            this.live = undefined;
+        }
+    }
+    mark() {
+        const on = this.enabled;
+        adopt(this.host, this.sheet, on);
+        this.draw(on);
+        const marked = new Set();
+        this.names = new Map();
+        for (const row of this.rows) {
+            const key = on ? this.keyOf(row) : undefined;
+            if (key !== undefined) {
+                this.names.set(key, row.textContent?.trim() ?? '');
+            }
+            const move = key === undefined ? undefined : this.reorder.moveOf(key);
+            if (move || this.marked.has(row)) {
+                for (const one of MOVES) {
+                    row.toggleAttribute(`data-${one}`, one === move);
+                }
+            }
+            if (move) {
+                marked.add(row);
+            }
+        }
+        for (const row of this.marked) {
+            if (!marked.has(row)) {
+                for (const one of MOVES) {
+                    row.removeAttribute(`data-${one}`);
+                }
+            }
+        }
+        this.marked = marked;
+    }
+}
+const adopt = (element, given, on) => {
+    const root = element.shadowRoot;
+    const sheet = given?.styleSheet;
+    if (!root || !sheet || root.adoptedStyleSheets.includes(sheet) === on) {
+        return;
+    }
+    root.adoptedStyleSheets = on
+        ? [...root.adoptedStyleSheets, sheet]
+        : root.adoptedStyleSheets.filter((one) => one !== sheet);
+};
+const given = new WeakMap();
+const attach = (list, sheet) => {
+    const controller = given.get(list) ?? new VirtualListReorderController(list);
+    given.set(list, controller);
+    controller.sheet ??= sheet;
+};
+const onPage = (of, root = document) => [...root.querySelectorAll('*')].flatMap((node) => [
+    ...(node instanceof of ? [node] : []),
+    ...(node.shadowRoot ? onPage(of, node.shadowRoot) : []),
+]);
+export const reorderVirtualList = (element, sheet) => {
+    element.addInitializer((host) => attach(host, sheet));
+    if (typeof document !== 'undefined') {
+        for (const list of onPage(element)) {
+            attach(list, sheet);
+            list.requestUpdate();
+        }
+    }
+    const proto = element.prototype;
+    for (const [name, [attribute, fallback]] of Object.entries(WORDS)) {
+        if (name in proto) {
+            continue;
+        }
+        Object.defineProperty(proto, name, {
+            configurable: true,
+            get() {
+                return this.getAttribute(attribute) ?? fallback;
+            },
+            set(next) {
+                this.setAttribute(attribute, next);
+            },
+        });
+    }
+};

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

@@ -85,11 +85,14 @@ export interface VirtualListRange {
  * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
  * | A letter or a word | Moves to the next item whose text starts with what you typed. |
  * | Escape | Lets go of every chosen item, in a list with `selection-mode`. |
+ * | Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |
  * | 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
+ * reaches the whole set. The row a reader last focused keeps the tab stop and
+ * stays drawn when it scrolls away, so Tab and Shift+Tab come back to it, as
+ * React Aria's collections do. In a list nobody has focused yet, 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.
  *
@@ -131,6 +134,23 @@ export interface VirtualListRange {
  * the last item says "Loading more" (`loading-label`, or your own content in
  * the `loading` slot). `scrollToIndex` takes a reader to an item.
  *
+ * **Moving items** is a separate import, `@fusion.dev/helix/virtual-list/reorder`,
+ * as React Aria's drag and drop is. With it imported, `reorderable` lets a
+ * reader move items in a list of one column without sections:
+ *
+ * - Alt with Up or Down moves the item the keys are on a place, and Alt with
+ *   Home or End to either end, as the APG's rearrangeable listbox does.
+ * - A pointer drags a whole row. A press that does not travel is still a
+ *   press. The list scrolls near an edge, and an item far down a long set is
+ *   reached by dragging to the edge.
+ * - A drop sends `helix-before-reorder`, which you can refuse, and then
+ *   `helix-reorder`, whose `keys` hold every item's key in the new order.
+ *   **You move the items**: set `items` to them in that order. The keys stay
+ *   on the item that moved.
+ * - Each move is said in a region screen readers announce. The row being
+ *   dragged carries `data-dragging`, and the row a drop would land beside
+ *   `data-drop-before` or `data-drop-after`.
+ *
  * **An empty list.** Set `empty-label`, or put your own content in the `empty`
  * slot, for a row shown when there are no items and none are loading, such as
  * "No messages yet" and a link to write one. Without either, an empty list
@@ -168,8 +188,10 @@ export interface VirtualListRange {
  *
  * @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 {HelixBeforeReorderEvent} helix-before-reorder - Fired when an item is dropped at a new place, in a `reorderable` list with `@fusion.dev/helix/virtual-list/reorder` imported, with every key in the new order. Cancelable: cancel it to keep the item where it is.
  * @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.
+ * @event {HelixReorderEvent} helix-reorder - Fired after `helix-before-reorder` when nobody canceled it. Set `items` to the order in `keys`. Cancelable: cancel it to say the move did not happen.
  *
  * @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.
@@ -295,6 +317,15 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * it is unset, the header is the name as text.
      */
     renderSection: VirtualListSectionRenderer | undefined;
+    /**
+     * Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
+     * (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
+     * with an arrow moves the row the keys are on, and a pointer drags a row.
+     * The list moves no item itself: you move your `items` on `helix-reorder`.
+     * Without that import it does nothing, so a list that never moves items
+     * carries none of the code. A list of one column, without sections.
+     */
+    reorderable: boolean;
     /**
      * The field of each item that names its section, as a key or a path of
      * keys. Set, the items are drawn in sections: a header, then the items, in
@@ -511,8 +542,8 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     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;
+    /** @internal Every item's key, in the order of the set, which the reorder entry moves. */
+    keys(): string[];
     /** The keys chosen now. */
     private get chosen();
     /**
@@ -532,10 +563,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      */
     private readonly handleClick;
     /**
-     * Focuses the row for item `index`, scrolling it into view and drawing it
-     * first when it is not drawn.
+     * @internal Focuses the row for item `index`, scrolling it into view and
+     * drawing it first when it is not drawn.
      */
-    private focusIndex;
+    focusIndex(index: number): Promise<void>;
     /**
      * The row kept for focus is let go once focus has left it.
      *
@@ -558,7 +589,13 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private focusedIndex;
     /** 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. */
+    /** Whether a reader has focused a row, after which their row keeps the tab stop. */
+    private visited;
+    /**
+     * The item drawn outside the window to keep focus, to take it, or to take
+     * it back: the row a reader last focused stays drawn after focus leaves the
+     * list, so Shift+Tab returns to it.
+     */
     private keptIndex;
     /**
      * Writes a row's role, and whether it is chosen in a list that selects:
@@ -596,9 +633,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * **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.
+     * **One row holds the tab stop**, the one the reader last focused, which
+     * stays drawn outside the window, and the first row on screen in a list
+     * nobody has focused yet. Its own links and buttons are in the tab order,
+     * and those of every other row wait.
      */
     private place;
     /** The sections the rows were last placed in. */

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

@@ -34,6 +34,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.measured = false;
         this.minColumnWidth = 0;
         this.orientation = 'vertical';
+        this.reorderable = false;
         this.sectionField = '';
         this.selectionBehavior = 'toggle';
         this.textField = '';
@@ -171,9 +172,11 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             const index = this.indexOf(node);
             if (index !== undefined) {
                 this.active = index;
+                this.visited = true;
             }
             this.requestUpdate();
         };
+        this.visited = false;
         this.sectionId = nextSectionId();
     }
     static { this.words = 'helix-virtual-list'; }
@@ -524,7 +527,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         return index === undefined ? undefined : Number(index);
     }
     keptIndex() {
-        const index = this.focusing ?? this.focusedIndex();
+        const index = this.focusing ?? this.focusedIndex() ?? (this.visited ? this.active : undefined);
         const { first, last } = this.itemsOn(this.virtualize.window);
         return index !== undefined && index < this.data.length && (index < first || index >= last)
             ? index
@@ -585,6 +588,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         const count = this.data.length;
         const { first, last } = this.itemsOn(this.virtualize.window);
         const holding = this.focusedIndex();
+        if (this.filledFrom !== this.data && holding === undefined) {
+            this.visited = false;
+        }
         const onScreen = this.range.first;
         if (this.hasUpdated) {
             const spacers = this.spacerSizes();
@@ -868,6 +874,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessVirtualList.prototype, "renderSection", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessVirtualList.prototype, "reorderable", void 0);
 __decorate([
     property({ attribute: 'section-field' })
 ], HelixHeadlessVirtualList.prototype, "sectionField", void 0);