@fusion.dev/helix-headless 0.171.0 → 0.173.0

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);