@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -29,7 +29,10 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             this.chased = true;
             this.step(-1);
         };
-        this.handleEnded = () => {
+        this.handleEnded = (event) => {
+            if (event.target !== this.player) {
+                return;
+            }
             this.chased = true;
             this.step(1);
         };
@@ -55,14 +58,14 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.addEventListener('helix-select', this.handleSelect);
         this.addEventListener('helix-next', this.handleNext);
         this.addEventListener('helix-previous', this.handlePrevious);
-        this.addEventListener('ended', this.handleEnded);
+        this.addEventListener('ended', this.handleEnded, true);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelect);
         this.removeEventListener('helix-next', this.handleNext);
         this.removeEventListener('helix-previous', this.handlePrevious);
-        this.removeEventListener('ended', this.handleEnded);
+        this.removeEventListener('ended', this.handleEnded, true);
     }
     updated(changed) {
         super.updated?.(changed);

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A list that renders only the rows of a long set that are on screen.
@@ -21,6 +21,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * accessible `<table>`, and ten thousand rows in one is the cost this component
  * avoids.
  *
+ * 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 viewport scrolls on this tier. It carries `data-scroller`, and `core`
  * ships `[data-scroller] { overflow: auto }` into every shadow root, so
  * `scrollTop` works with no stylesheet. You still need to set a block size.
@@ -30,6 +35,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @category layout
  * @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.
+ *
  * @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.
@@ -49,6 +56,9 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     /**
      * The list's name, read by screen readers, because only some of its rows
      * are rendered at a time.
+     *
+     * An `aria-label` or `aria-labelledby` on the host names the list too, and
+     * wins over this.
      */
     label: string;
     /**
@@ -70,6 +80,21 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     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. */
+    private filledFrom;
+    /** The script the rows were read from, which the watcher follows. */
+    private source;
+    /**
+     * Watches the source and the tree around it.
+     *
+     * **The list read its source once per `for`**, so a page that wrote new JSON
+     * into the script, the way a framework updates a text child, kept the old
+     * rows. The script's own text is watched, and the tree it sits in, for a
+     * script replaced under the same id.
+     */
+    private watcher;
+    /** Carries a host `aria-label` and `aria-labelledby` to the element with the `list` role. */
+    protected readonly aria: AriaForwardController;
     private readonly virtualize;
     /**
      * The rows in the tree, each with the item it drew.
@@ -98,15 +123,38 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * so by itself.
      */
     protected willUpdate(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Reads the source again when its text changed or another element took its
+     * id. Rows this list drew are its own writes and are not news.
+     */
+    private handleMutations;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     private read;
+    /**
+     * The item whose row holds focus, where one does.
+     *
+     * Asked of the root this list is in, which retargets focus inside a row's
+     * own shadow root to the row's element.
+     */
+    private focusedIndex;
+    /** The item drawn outside the window to keep focus, if there is one. */
+    private keptIndex;
+    /** Fills a row's holes and its place in the set from an item. */
+    private fill;
     /**
      * Puts the windowed rows into the light DOM, and takes the rest out.
      *
-     * Cleared and re-cloned rather than reconciled: a window is twenty-odd rows
-     * and cloning that many is well under a frame. A reconciler here would carry
-     * keys and identity for a set nothing selects into.
+     * **A row that stays in the window keeps its element.** Clearing and
+     * 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.
+     *
+     * **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.
      */
     private place;
     protected render(): TemplateResult;

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

@@ -4,7 +4,7 @@ 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, elementById, HelixElement, searchableById, VirtualizeController, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, elementById, HelixElement, searchableById, VirtualizeController, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixElement {
@@ -15,6 +15,11 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.label = '';
         this.measured = false;
         this.rows = [];
+        this.source = null;
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('viewport'),
+        });
         this.virtualize = new VirtualizeController(this, {
             container: () => this.partNamed('viewport'),
             count: () => this.rows.length,
@@ -36,6 +41,33 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             this.read();
         }
     }
+    connectedCallback() {
+        super.connectedCallback();
+        if (typeof MutationObserver === 'undefined') {
+            return;
+        }
+        this.watcher = new MutationObserver((records) => this.handleMutations(records));
+        this.watcher.observe(this.getRootNode(), {
+            characterData: true,
+            childList: true,
+            subtree: true,
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    handleMutations(records) {
+        if (this.for === '' || this.hydrating || this.readFor === undefined) {
+            return;
+        }
+        const found = elementById(this, this.for);
+        const edited = records.some((record) => found !== null && (record.target === found || found.contains(record.target)));
+        if (found !== this.source || edited) {
+            this.read();
+        }
+    }
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
         this.finishHydration();
@@ -47,6 +79,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     }
     read() {
         const source = this.for === '' ? null : elementById(this, this.for);
+        this.source = source;
         const text = source?.textContent ?? '';
         if (text.trim() === '') {
             this.rows = [];
@@ -60,40 +93,89 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             this.rows = [];
         }
     }
+    focusedIndex() {
+        const root = this.getRootNode();
+        let node = root.activeElement;
+        while (node && node.parentElement !== this) {
+            node = node.parentElement;
+        }
+        const index = node instanceof HTMLElement ? node.dataset.index : undefined;
+        return index === undefined ? undefined : Number(index);
+    }
+    keptIndex() {
+        const index = this.focusedIndex();
+        const { first, last } = this.virtualize.window;
+        return index !== undefined && index < this.rows.length && (index < first || index >= last)
+            ? index
+            : undefined;
+    }
+    fill(elements, row, at) {
+        const total = String(this.rows.length);
+        for (const element of elements) {
+            for (const hole of [
+                ...(element.matches('[data-field]') ? [element] : []),
+                ...element.querySelectorAll('[data-field]'),
+            ]) {
+                hole.textContent = row[hole.dataset.field ?? ''] ?? '';
+            }
+            element.setAttribute('role', 'listitem');
+            element.setAttribute('aria-posinset', String(at + 1));
+            element.setAttribute('aria-setsize', total);
+            element.setAttribute('data-index', String(at));
+        }
+    }
     place() {
         const template = this.querySelector('template');
         if (!template) {
             return;
         }
-        for (const stale of [...this.children]) {
-            if (stale !== template) {
-                stale.remove();
+        const { first, last } = this.virtualize.window;
+        const kept = this.keptIndex();
+        const wanted = [];
+        for (let at = first; at < Math.min(last, this.rows.length); at += 1) {
+            wanted.push(at);
+        }
+        if (kept !== undefined) {
+            wanted.push(kept);
+            wanted.sort((a, b) => a - b);
+        }
+        const keep = new Set(wanted);
+        const drawn = new Map();
+        for (const child of [...this.children]) {
+            if (child === template) {
+                continue;
+            }
+            const index = Number(child.dataset.index);
+            if (!Number.isInteger(index) || !keep.has(index)) {
+                child.remove();
+                continue;
             }
+            drawn.set(index, [...(drawn.get(index) ?? []), child]);
         }
-        const { first, last } = this.virtualize.window;
-        const total = this.rows.length;
-        const fragment = this.ownerDocument.createDocumentFragment();
-        for (let at = first; at < last; at += 1) {
+        const refill = this.filledFrom !== this.rows;
+        this.filledFrom = this.rows;
+        let anchor = drawn.values().next().value?.[0] ?? null;
+        for (const at of wanted) {
             const row = this.rows[at];
-            if (!row) {
+            const group = drawn.get(at);
+            if (group) {
+                if (refill) {
+                    this.fill(group, row, at);
+                }
+                anchor = group.at(-1).nextElementSibling;
                 continue;
             }
             const clone = template.content.cloneNode(true);
-            for (const hole of clone.querySelectorAll('[data-field]')) {
-                hole.textContent = row[hole.dataset.field ?? ''] ?? '';
-            }
-            for (const element of clone.children) {
-                element.setAttribute('role', 'listitem');
-                element.setAttribute('aria-posinset', String(at + 1));
-                element.setAttribute('aria-setsize', String(total));
-                element.setAttribute('data-index', String(at));
-            }
-            fragment.append(clone);
+            this.fill([...clone.children], row, at);
+            this.insertBefore(clone, anchor);
         }
-        this.append(fragment);
     }
     render() {
-        const { after, before } = this.virtualize.window;
+        const window = this.virtualize.window;
+        const kept = this.hasUpdated ? this.keptIndex() : undefined;
+        const room = kept === undefined ? 0 : this.virtualize.sizeOf(kept);
+        const before = window.before - (kept !== undefined && kept < window.first ? room : 0);
+        const after = window.after - (kept !== undefined && kept >= window.last ? room : 0);
         return html `<div
       data-scroller
       part="viewport"