vlist 1.9.0 → 2.0.0

package/dist/plugins/selection/plugin.js

@@ -0,0 +1,601 @@
+/**
+ * vlist v2 — Selection Plugin
+ *
+ * Manages selection state, click/keyboard handlers, ARIA attributes.
+ * Adapted from v1 withSelection feature + a11y.ts to the v2 plugin interface.
+ */
+import { createSelectionState, moveFocus, getSelectedArray, claimPlaceholderSelection, } from "./state";
+import { PLACEHOLDER_ID_PREFIX } from "../../constants";
+// =============================================================================
+// Factory
+// =============================================================================
+const focusPreventScroll = { preventScroll: true };
+export function selection(config) {
+    const mode = config?.mode ?? "single";
+    const followFocus = config?.followFocus ?? false;
+    const focusOnClick = config?.focusOnClick ?? false;
+    let state;
+    let getItem;
+    let forceRender;
+    let emitter;
+    let dom;
+    let sizeCache;
+    let engineState;
+    let scrollTo;
+    let lastSelectedIndex = -1;
+    const selectedItemCache = new Map();
+    let l2dFn = null;
+    let d2lFn = null;
+    let isGHFn = null;
+    let sivFn = null;
+    let getTotalFn;
+    let resolved = false;
+    function resolveOnce(ctx) {
+        if (resolved)
+            return;
+        resolved = true;
+        l2dFn = ctx.getMethod("_layoutToDataIndex") ?? null;
+        d2lFn = ctx.getMethod("_dataToLayoutIndex") ?? null;
+        isGHFn = ctx.getMethod("_isGroupHeader") ?? null;
+        sivFn = ctx.getMethod("_scrollItemIntoView") ?? null;
+        const gl = ctx.getMethod("getGroupLayout");
+        if (gl) {
+            const layout = gl();
+            getTotalFn = () => layout.totalEntries;
+        }
+    }
+    const toDataIndex = (layoutIdx) => l2dFn ? l2dFn(layoutIdx) : layoutIdx;
+    const getItemAtLayout = (layoutIdx) => {
+        const di = toDataIndex(layoutIdx);
+        return di >= 0 ? getItem(di) : undefined;
+    };
+    const skipHeaders = (from, dir, total) => {
+        if (!isGHFn)
+            return from;
+        let i = from;
+        while (i >= 0 && i < total) {
+            if (!isGHFn(i))
+                return i;
+            i += dir;
+        }
+        i = from - dir;
+        while (i >= 0 && i < total) {
+            if (!isGHFn(i))
+                return i;
+            i -= dir;
+        }
+        return from;
+    };
+    // ── Selection mutations (keep Set + item cache in sync) ────────
+    function doSelect(id, item) {
+        if (mode === "single") {
+            state.selected.clear();
+            selectedItemCache.clear();
+        }
+        state.selected.add(id);
+        if (item)
+            selectedItemCache.set(id, item);
+    }
+    function doToggle(id, item) {
+        if (state.selected.has(id)) {
+            state.selected.delete(id);
+            selectedItemCache.delete(id);
+        }
+        else {
+            doSelect(id, item);
+        }
+    }
+    function doClear() {
+        state.selected.clear();
+        selectedItemCache.clear();
+    }
+    function doDeselect(id) {
+        state.selected.delete(id);
+        selectedItemCache.delete(id);
+    }
+    function doSelectRange(from, to) {
+        const start = Math.min(from, to);
+        const end = Math.max(from, to);
+        for (let i = start; i <= end; i++) {
+            const item = getItem(i);
+            if (item) {
+                state.selected.add(item.id);
+                selectedItemCache.set(item.id, item);
+            }
+        }
+    }
+    function doSelectAll() {
+        const total = engineState.totalItems;
+        for (let i = 0; i < total; i++) {
+            const item = getItem(i);
+            if (item) {
+                state.selected.add(item.id);
+                selectedItemCache.set(item.id, item);
+            }
+        }
+    }
+    function collectSelectedItems() {
+        if (state.selected.size === 0)
+            return [];
+        if (selectedItemCache.size >= state.selected.size) {
+            const result = [];
+            for (const id of state.selected) {
+                const item = selectedItemCache.get(id);
+                if (item)
+                    result.push(item);
+            }
+            if (result.length === state.selected.size)
+                return result;
+        }
+        const result = [];
+        const remaining = new Set(state.selected);
+        const total = engineState.totalItems;
+        for (let i = 0; i < total && remaining.size > 0; i++) {
+            const item = getItem(i);
+            if (item && remaining.has(item.id)) {
+                result.push(item);
+                selectedItemCache.set(item.id, item);
+                remaining.delete(item.id);
+            }
+        }
+        return result;
+    }
+    function emitSelectionChange() {
+        forceRender();
+        emitter.emit("selection:change", {
+            selected: getSelectedArray(state.selected),
+            items: collectSelectedItems(),
+        });
+    }
+    let hitItem = null;
+    let hitIndex = -1;
+    return {
+        name: "selection",
+        priority: 50,
+        setup(ctx) {
+            state = createSelectionState(config?.initial);
+            getItem = ctx.getItem.bind(ctx);
+            forceRender = ctx.forceRender.bind(ctx);
+            emitter = ctx.emitter;
+            dom = ctx.dom;
+            const resolvedConfig = ctx.config;
+            sizeCache = ctx.sizeCache;
+            engineState = ctx.getState();
+            scrollTo = ctx.scrollTo.bind(ctx);
+            getTotalFn = () => engineState.totalItems;
+            if (mode === "none") {
+                ctx.registerMethod("select", () => { });
+                ctx.registerMethod("deselect", () => { });
+                ctx.registerMethod("toggleSelect", () => { });
+                ctx.registerMethod("selectAll", () => { });
+                ctx.registerMethod("clearSelection", () => { });
+                ctx.registerMethod("getSelected", () => []);
+                ctx.registerMethod("getSelectedItems", () => []);
+                ctx.registerMethod("selectNext", () => { });
+                ctx.registerMethod("selectPrevious", () => { });
+                ctx.registerMethod("_seedSelection", () => { });
+                ctx.registerMethod("_getFocusedId", () => undefined);
+                ctx.registerMethod("_focusById", () => { });
+                return;
+            }
+            const classPrefix = resolvedConfig.classPrefix;
+            ctx.setItemStateFn((index, is) => {
+                resolveOnce(ctx);
+                if (state.selected.size > 0) {
+                    const di = toDataIndex(index);
+                    const item = di >= 0 ? getItem(di) : undefined;
+                    const id = item?.id;
+                    if (id !== undefined) {
+                        if (state.selected.has(id)) {
+                            is.selected = true;
+                        }
+                        else if (claimPlaceholderSelection(state.selected, di, id)) {
+                            is.selected = true;
+                            selectedItemCache.delete(PLACEHOLDER_ID_PREFIX + di);
+                            selectedItemCache.set(id, item);
+                        }
+                        else {
+                            is.selected = false;
+                        }
+                    }
+                    else {
+                        is.selected = false;
+                    }
+                }
+                else {
+                    is.selected = false;
+                }
+                is.focused = state.focusVisible && state.focusedIndex === index;
+            });
+            ctx.registerMethod("_getSelectedIds", () => state.selected);
+            ctx.registerMethod("_getFocusedIndex", () => state.focusVisible ? state.focusedIndex : -1);
+            dom.root.classList.add(`${classPrefix}--selectable`);
+            // ── Helpers ────────────────────────────────────────────────
+            const findItemFromEvent = (event) => {
+                hitItem = null;
+                hitIndex = -1;
+                const el = event.target.closest("[data-index]");
+                if (!el)
+                    return false;
+                const layoutIdx = parseInt(el.dataset.index ?? "-1", 10);
+                if (layoutIdx < 0)
+                    return false;
+                const di = toDataIndex(layoutIdx);
+                if (di < 0)
+                    return false;
+                const item = getItem(di);
+                if (!item)
+                    return false;
+                hitItem = item;
+                hitIndex = layoutIdx;
+                return true;
+            };
+            const scrollFocusIntoView = (index) => {
+                if (index < 0)
+                    return;
+                if (sivFn) {
+                    sivFn(index);
+                    return;
+                }
+                const nav = ctx.getNavConfig();
+                const ci = nav.scrollIndex ? nav.scrollIndex(index) : index;
+                const offset = sizeCache.getOffset(ci);
+                const size = sizeCache.getSize(ci);
+                const cs = engineState.containerSize;
+                const sp = engineState.scrollPosition;
+                if (offset < sp) {
+                    scrollTo(offset);
+                }
+                else if (offset + size > sp + cs) {
+                    scrollTo(offset - cs + size);
+                }
+            };
+            // ── Focus In/Out ──────────────────────────────────────────
+            const onFocusIn = () => {
+                if (engineState.destroyed)
+                    return;
+                resolveOnce(ctx);
+                if (!dom.content.matches(":focus-visible") && !dom.root.matches(":focus-visible"))
+                    return;
+                const t = getTotalFn();
+                if (t === 0)
+                    return;
+                let tgt = state.focusedIndex >= 0 ? Math.min(state.focusedIndex, t - 1) : 0;
+                tgt = skipHeaders(tgt, 1, t);
+                state.focusedIndex = tgt;
+                state.focusVisible = true;
+                dom.content.setAttribute("aria-activedescendant", `${classPrefix}-item-${tgt}`);
+                scrollFocusIntoView(tgt);
+                forceRender();
+            };
+            dom.root.addEventListener("focusin", onFocusIn);
+            const onFocusOut = (e) => {
+                if (engineState.destroyed)
+                    return;
+                const rel = e.relatedTarget;
+                if (rel && dom.root.contains(rel))
+                    return;
+                state.focusVisible = false;
+                forceRender();
+                dom.content.removeAttribute("aria-activedescendant");
+            };
+            dom.root.addEventListener("focusout", onFocusOut);
+            ctx.registerDestroyHandler(() => {
+                dom.root.removeEventListener("focusin", onFocusIn);
+                dom.root.removeEventListener("focusout", onFocusOut);
+            });
+            // ── Click handler ─────────────────────────────────────────
+            ctx.registerClickHandler((event) => {
+                resolveOnce(ctx);
+                if (!findItemFromEvent(event))
+                    return;
+                if (mode === "multiple" && event.shiftKey && state.focusedIndex >= 0) {
+                    const anchor = lastSelectedIndex >= 0 ? lastSelectedIndex : state.focusedIndex;
+                    const anchorData = toDataIndex(anchor);
+                    const hitData = toDataIndex(hitIndex);
+                    if (anchorData >= 0 && hitData >= 0) {
+                        doSelectRange(anchorData, hitData);
+                    }
+                    state.focusedIndex = hitIndex;
+                    state.focusVisible = focusOnClick;
+                    lastSelectedIndex = hitIndex;
+                    emitSelectionChange();
+                    return;
+                }
+                state.focusedIndex = hitIndex;
+                state.focusVisible = focusOnClick;
+                lastSelectedIndex = hitIndex;
+                dom.content.focus(focusPreventScroll);
+                doToggle(hitItem.id, hitItem);
+                emitSelectionChange();
+            });
+            // ── Keyboard handler ──────────────────────────────────────
+            if (resolvedConfig.interactive) {
+                ctx.registerKeydownHandler((event) => {
+                    resolveOnce(ctx);
+                    const total = getTotalFn();
+                    if (total === 0)
+                        return;
+                    const nav = ctx.getNavConfig();
+                    const prevFocus = state.focusedIndex;
+                    let handled = false;
+                    let selectionChanged = false;
+                    if (nav.navigate && (event.key === "ArrowUp" || event.key === "ArrowDown" || event.key === "ArrowLeft" || event.key === "ArrowRight" || event.key === "PageUp" || event.key === "PageDown" || event.key === "Home" || event.key === "End")) {
+                        const next = nav.navigate(state.focusedIndex, event.key, total);
+                        if (next !== state.focusedIndex) {
+                            state.focusedIndex = Math.max(0, Math.min(next, total - 1));
+                        }
+                        state.focusVisible = true;
+                        handled = true;
+                    }
+                    else
+                        switch (event.key) {
+                            case "ArrowUp": {
+                                const ud = nav.ud || 1;
+                                const lr = nav.lr;
+                                const hz = resolvedConfig.horizontal;
+                                if (hz && !lr)
+                                    break;
+                                moveFocus(state, -(hz ? lr : ud), total, resolvedConfig.reverse);
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            }
+                            case "ArrowDown": {
+                                const ud = nav.ud || 1;
+                                const lr = nav.lr;
+                                const hz = resolvedConfig.horizontal;
+                                if (hz && !lr)
+                                    break;
+                                moveFocus(state, hz ? lr : ud, total, resolvedConfig.reverse);
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            }
+                            case "ArrowLeft": {
+                                const ud = nav.ud || 1;
+                                const lr = nav.lr;
+                                const hz = resolvedConfig.horizontal;
+                                if (!hz && !lr)
+                                    break;
+                                moveFocus(state, -(hz ? ud : lr), total, resolvedConfig.reverse);
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            }
+                            case "ArrowRight": {
+                                const ud = nav.ud || 1;
+                                const lr = nav.lr;
+                                const hz = resolvedConfig.horizontal;
+                                if (!hz && !lr)
+                                    break;
+                                moveFocus(state, hz ? ud : lr, total, resolvedConfig.reverse);
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            }
+                            case "Home":
+                                if (total > 0)
+                                    state.focusedIndex = 0;
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            case "End":
+                                if (total > 0)
+                                    state.focusedIndex = total - 1;
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            case "PageUp":
+                            case "PageDown": {
+                                const ud = nav.ud || 1;
+                                const idx = Math.max(0, state.focusedIndex);
+                                const si = nav.scrollIndex ? nav.scrollIndex(idx) : idx;
+                                const rowH = sizeCache.getSize(si);
+                                const cs = engineState.containerSize;
+                                const visRows = rowH > 0 ? Math.max(1, Math.floor(cs / rowH)) : 10;
+                                const pageSize = visRows * ud;
+                                if (l2dFn && d2lFn) {
+                                    const curData = l2dFn(state.focusedIndex);
+                                    const step = event.key === "PageUp" ? -pageSize : pageSize;
+                                    const maxData = engineState.totalItems - 1;
+                                    state.focusedIndex = d2lFn(Math.max(0, Math.min(maxData, curData + step)));
+                                }
+                                else {
+                                    moveFocus(state, event.key === "PageUp" ? -pageSize : pageSize, total);
+                                }
+                                state.focusVisible = true;
+                                handled = true;
+                                break;
+                            }
+                            case " ":
+                            case "Enter":
+                                if (event.key === " " && event.shiftKey && mode === "multiple" && state.focusedIndex >= 0) {
+                                    if (lastSelectedIndex >= 0) {
+                                        const fromData = toDataIndex(lastSelectedIndex);
+                                        const toData = toDataIndex(state.focusedIndex);
+                                        if (fromData >= 0 && toData >= 0) {
+                                            doSelectRange(fromData, toData);
+                                        }
+                                    }
+                                    state.focusVisible = true;
+                                    selectionChanged = true;
+                                    handled = true;
+                                    break;
+                                }
+                                if (state.focusedIndex >= 0) {
+                                    const item = getItemAtLayout(state.focusedIndex);
+                                    if (item) {
+                                        doToggle(item.id, item);
+                                        lastSelectedIndex = state.focusedIndex;
+                                    }
+                                    state.focusVisible = true;
+                                    selectionChanged = true;
+                                    handled = true;
+                                }
+                                break;
+                            case "a":
+                                if ((event.ctrlKey || event.metaKey) && mode === "multiple") {
+                                    if (state.selected.size === engineState.totalItems) {
+                                        doClear();
+                                    }
+                                    else {
+                                        doSelectAll();
+                                    }
+                                    state.focusVisible = true;
+                                    selectionChanged = true;
+                                    handled = true;
+                                }
+                                break;
+                            case "Delete":
+                            case "Backspace":
+                                if (state.selected.size > 0) {
+                                    emitter.emit("delete", {
+                                        selected: getSelectedArray(state.selected),
+                                        items: collectSelectedItems(),
+                                    });
+                                    handled = true;
+                                }
+                                break;
+                        }
+                    // Skip group headers before shift-selection uses focusedIndex
+                    if (state.focusedIndex !== prevFocus && isGHFn) {
+                        const dir = state.focusedIndex > prevFocus ? 1 : -1;
+                        state.focusedIndex = skipHeaders(state.focusedIndex, dir, total);
+                    }
+                    const focusMoved = state.focusedIndex !== prevFocus;
+                    // Shift+movement: extend selection
+                    if (event.shiftKey && mode === "multiple" && !selectionChanged && focusMoved) {
+                        const isArrow = event.key === "ArrowUp" || event.key === "ArrowDown" || event.key === "ArrowLeft" || event.key === "ArrowRight";
+                        if (isArrow) {
+                            const destItem = getItemAtLayout(state.focusedIndex);
+                            if (destItem)
+                                doToggle(destItem.id, destItem);
+                            lastSelectedIndex = state.focusedIndex;
+                            selectionChanged = true;
+                        }
+                        const isCtrlHomeEnd = (event.ctrlKey || event.metaKey)
+                            && (event.key === "Home" || event.key === "End");
+                        if (isCtrlHomeEnd) {
+                            const fromData = toDataIndex(prevFocus >= 0 ? prevFocus : state.focusedIndex);
+                            const toData = toDataIndex(state.focusedIndex);
+                            if (fromData >= 0 && toData >= 0) {
+                                doSelectRange(fromData, toData);
+                            }
+                            lastSelectedIndex = state.focusedIndex;
+                            selectionChanged = true;
+                        }
+                    }
+                    // Follow focus: auto-select on movement
+                    if (followFocus && mode === "single" && !selectionChanged && focusMoved && state.focusedIndex >= 0) {
+                        const item = getItemAtLayout(state.focusedIndex);
+                        if (item)
+                            doSelect(item.id, item);
+                        selectionChanged = true;
+                    }
+                    if (handled) {
+                        event.preventDefault();
+                        if (focusMoved && state.focusedIndex >= 0) {
+                            scrollFocusIntoView(state.focusedIndex);
+                            dom.content.setAttribute("aria-activedescendant", `${classPrefix}-item-${state.focusedIndex}`);
+                        }
+                        if (selectionChanged) {
+                            emitSelectionChange();
+                        }
+                        else if (focusMoved) {
+                            forceRender();
+                            if (state.focusedIndex >= 0) {
+                                const item = getItemAtLayout(state.focusedIndex);
+                                if (item) {
+                                    emitter.emit("focus:change", { id: item.id, index: state.focusedIndex });
+                                }
+                            }
+                        }
+                    }
+                });
+            }
+            // ── Public methods ────────────────────────────────────────
+            ctx.registerMethod("select", (...ids) => {
+                for (const id of ids)
+                    doSelect(id);
+                emitSelectionChange();
+            });
+            ctx.registerMethod("deselect", (...ids) => {
+                for (const id of ids)
+                    doDeselect(id);
+                emitSelectionChange();
+            });
+            ctx.registerMethod("toggleSelect", (id) => {
+                doToggle(id);
+                emitSelectionChange();
+            });
+            ctx.registerMethod("selectAll", () => {
+                if (mode !== "multiple")
+                    return;
+                doSelectAll();
+                emitSelectionChange();
+            });
+            ctx.registerMethod("clearSelection", () => {
+                doClear();
+                emitSelectionChange();
+            });
+            ctx.registerMethod("getSelected", () => {
+                return getSelectedArray(state.selected);
+            });
+            ctx.registerMethod("getSelectedItems", () => {
+                return collectSelectedItems();
+            });
+            ctx.registerMethod("selectNext", () => {
+                resolveOnce(ctx);
+                const total = getTotalFn();
+                if (total === 0)
+                    return;
+                moveFocus(state, 1, total, resolvedConfig.reverse);
+                if (isGHFn)
+                    state.focusedIndex = skipHeaders(state.focusedIndex, 1, total);
+                const item = getItemAtLayout(state.focusedIndex);
+                if (item)
+                    doSelect(item.id, item);
+                emitSelectionChange();
+            });
+            ctx.registerMethod("selectPrevious", () => {
+                resolveOnce(ctx);
+                const total = getTotalFn();
+                if (total === 0)
+                    return;
+                moveFocus(state, -1, total, resolvedConfig.reverse);
+                if (isGHFn)
+                    state.focusedIndex = skipHeaders(state.focusedIndex, -1, total);
+                const item = getItemAtLayout(state.focusedIndex);
+                if (item)
+                    doSelect(item.id, item);
+                emitSelectionChange();
+            });
+            // ── Internal methods (used by snapshots, sortable) ────────
+            ctx.registerMethod("_seedSelection", (ids) => {
+                for (const id of ids)
+                    state.selected.add(id);
+            });
+            ctx.registerMethod("_getFocusedId", () => {
+                if (state.focusedIndex < 0)
+                    return undefined;
+                return getItemAtLayout(state.focusedIndex)?.id;
+            });
+            ctx.registerMethod("_focusById", (id) => {
+                const total = engineState.totalItems;
+                for (let i = 0; i < total; i++) {
+                    const item = getItem(i);
+                    if (item && item.id === id) {
+                        const layoutIdx = d2lFn ? d2lFn(i) : i;
+                        state.focusedIndex = layoutIdx;
+                        emitter.emit("focus:change", { id, index: layoutIdx });
+                        return;
+                    }
+                }
+            });
+        },
+        destroy() {
+            selectedItemCache.clear();
+        },
+    };
+}

package/dist/{features → plugins}/selection/state.d.ts

@@ -112,4 +112,12 @@ export declare const selectFocused: <T extends VListItem>(state: SelectionState,
  * Pure function - returns new state
  */
 export declare const selectRange: <T extends VListItem>(state: SelectionState, items: T[], fromIndex: number, toIndex: number, mode: SelectionMode) => SelectionState;
+export declare function selectOne(selected: Set<string | number>, id: string | number, mode: SelectionMode): void;
+export declare function toggleOne(selected: Set<string | number>, id: string | number, mode: SelectionMode): void;
+export declare function selectAllItems<T extends VListItem>(selected: Set<string | number>, items: readonly T[]): void;
+export declare function selectRangeMut<T extends VListItem>(selected: Set<string | number>, items: readonly T[], fromIndex: number, toIndex: number): void;
+export declare function moveFocus(state: SelectionState, delta: number, totalItems: number, reverse?: boolean): void;
+export declare function getSelectedArray(selected: Set<string | number>): Array<string | number>;
+export { getSelectedItems as getSelectedItemsImmutable };
+export declare function getSelectedItemsMut<T extends VListItem>(selected: Set<string | number>, items: readonly T[]): T[];
 //# sourceMappingURL=state.d.ts.map