vlist 1.9.0 → 2.0.0

package/dist/plugins/groups/async-bridge.js

@@ -0,0 +1,246 @@
+/**
+ * vlist - Async Group Bridge
+ * Virtual group layer that bridges withAsync's sparse data manager with
+ * withGroups' layout system.
+ *
+ * Instead of physically inserting header pseudo-items into the data array
+ * (which is impossible with sparse storage), this bridge:
+ * - Observes items as they load via onItemsLoaded callbacks
+ * - Discovers group boundaries incrementally from loaded data
+ * - Maps between "data indices" (what the async manager knows) and
+ *   "layout indices" (what the renderer sees, including header slots)
+ * - Provides header/item resolution at render time
+ *
+ * Group boundaries are only computed for contiguous loaded ranges.
+ * Unloaded gaps have no headers — placeholders render as regular items.
+ * When gaps fill in, boundaries are recomputed.
+ */
+import { findGroupByDataIndex, findGroupByLayoutIndex } from "./layout";
+// =============================================================================
+// Factory
+// =============================================================================
+const EMPTY_GROUP = {
+    key: "",
+    groupIndex: 0,
+    headerLayoutIndex: 0,
+    firstDataIndex: 0,
+    count: 0,
+};
+/**
+ * Create an async group bridge.
+ *
+ * The bridge discovers group boundaries incrementally as items load from
+ * the async adapter. It maintains a mapping between data indices (sparse
+ * storage) and layout indices (data items + group headers).
+ *
+ * @param config - Bridge configuration
+ * @param getItem - Item accessor from the async data manager
+ * @param isItemLoaded - Check if an item at index is loaded (not placeholder)
+ */
+export const createAsyncGroupBridge = (config, _getItem, _isItemLoaded) => {
+    let groups = [];
+    let dataTotal = 0;
+    let totalEntries = 0;
+    // Track group key for each loaded data index.
+    // This survives across onItemsLoaded calls so we can detect
+    // cross-page group boundaries.
+    const groupKeyByIndex = new Map();
+    /**
+     * Rebuild group boundaries from all known group keys.
+     *
+     * Scans from index 0 to dataTotal-1. For loaded items, uses the cached
+     * group key. For unloaded items, skips them — no header is inserted at
+     * load/unload boundaries.
+     *
+     * This runs on each onItemsLoaded. It's O(dataTotal) in theory but
+     * only does map lookups per index — fast in practice.
+     */
+    const rebuildGroups = () => {
+        groups = [];
+        if (dataTotal === 0 || groupKeyByIndex.size === 0) {
+            totalEntries = dataTotal;
+            return;
+        }
+        let currentKey = null;
+        let groupStart = -1;
+        // Running header count — each discovered group adds 1 header
+        let headerCount = 0;
+        for (let i = 0; i < dataTotal; i++) {
+            const key = groupKeyByIndex.get(i);
+            if (key === undefined) {
+                // Unloaded item — close any open group
+                if (currentKey !== null && groupStart >= 0) {
+                    const count = i - groupStart;
+                    groups.push({
+                        key: currentKey,
+                        groupIndex: groups.length,
+                        headerLayoutIndex: groupStart + headerCount,
+                        firstDataIndex: groupStart,
+                        count,
+                    });
+                    headerCount++;
+                    currentKey = null;
+                    groupStart = -1;
+                }
+                continue;
+            }
+            if (key !== currentKey) {
+                // Close previous group if any
+                if (currentKey !== null && groupStart >= 0) {
+                    const count = i - groupStart;
+                    groups.push({
+                        key: currentKey,
+                        groupIndex: groups.length,
+                        headerLayoutIndex: groupStart + headerCount,
+                        firstDataIndex: groupStart,
+                        count,
+                    });
+                    headerCount++;
+                }
+                // Start new group
+                currentKey = key;
+                groupStart = i;
+            }
+        }
+        // Close last open group
+        if (currentKey !== null && groupStart >= 0) {
+            const count = dataTotal - groupStart;
+            groups.push({
+                key: currentKey,
+                groupIndex: groups.length,
+                headerLayoutIndex: groupStart + headerCount,
+                firstDataIndex: groupStart,
+                count,
+            });
+            headerCount++;
+        }
+        totalEntries = dataTotal + headerCount;
+    };
+    // ── Public API ──
+    const onItemsLoaded = (items, offset, total) => {
+        dataTotal = total;
+        // Cache group keys for loaded items
+        for (let i = 0; i < items.length; i++) {
+            const dataIndex = offset + i;
+            const item = items[i];
+            if (item !== undefined) {
+                const key = config.getGroupForIndex(dataIndex, item);
+                groupKeyByIndex.set(dataIndex, key);
+            }
+        }
+        rebuildGroups();
+    };
+    const isHeader = (layoutIndex) => {
+        if (groups.length === 0)
+            return false;
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        const group = groups[gi];
+        return layoutIndex === group.headerLayoutIndex;
+    };
+    const getHeaderItem = (layoutIndex) => {
+        if (groups.length === 0)
+            return undefined;
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        const group = groups[gi];
+        if (layoutIndex !== group.headerLayoutIndex)
+            return undefined;
+        return {
+            id: `__group_header_${group.groupIndex}`,
+            __groupHeader: true,
+            groupKey: group.key,
+            groupIndex: group.groupIndex,
+        };
+    };
+    const layoutToDataIndex = (layoutIndex) => {
+        if (groups.length === 0)
+            return layoutIndex;
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        const group = groups[gi];
+        if (layoutIndex === group.headerLayoutIndex) {
+            return -1;
+        }
+        const offsetInGroup = layoutIndex - group.headerLayoutIndex - 1;
+        return group.firstDataIndex + offsetInGroup;
+    };
+    const dataToLayoutIndex = (dataIndex) => {
+        if (groups.length === 0)
+            return dataIndex;
+        const gi = findGroupByDataIndex(groups, dataIndex);
+        const group = groups[gi];
+        const offsetInGroup = dataIndex - group.firstDataIndex;
+        return group.headerLayoutIndex + 1 + offsetInGroup;
+    };
+    const getHeaderHeight = (_groupIndex) => config.headerHeight;
+    const getGroupAtLayoutIndex = (layoutIndex) => {
+        if (groups.length === 0)
+            return EMPTY_GROUP;
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        return groups[gi];
+    };
+    const getGroupAtDataIndex = (dataIndex) => {
+        if (groups.length === 0)
+            return EMPTY_GROUP;
+        const gi = findGroupByDataIndex(groups, dataIndex);
+        return groups[gi];
+    };
+    const insertAt = (dataIndex, item) => {
+        const newMap = new Map();
+        for (const [idx, key] of groupKeyByIndex) {
+            if (idx < dataIndex)
+                newMap.set(idx, key);
+            else
+                newMap.set(idx + 1, key);
+        }
+        groupKeyByIndex.clear();
+        for (const [idx, key] of newMap)
+            groupKeyByIndex.set(idx, key);
+        const key = config.getGroupForIndex(dataIndex, item);
+        groupKeyByIndex.set(dataIndex, key);
+        dataTotal++;
+        rebuildGroups();
+    };
+    const removeAt = (dataIndex) => {
+        // Remove the key at dataIndex and shift all subsequent keys down by 1
+        const newMap = new Map();
+        for (const [idx, key] of groupKeyByIndex) {
+            if (idx < dataIndex)
+                newMap.set(idx, key);
+            else if (idx > dataIndex)
+                newMap.set(idx - 1, key);
+            // idx === dataIndex is dropped
+        }
+        groupKeyByIndex.clear();
+        for (const [idx, key] of newMap)
+            groupKeyByIndex.set(idx, key);
+        dataTotal--;
+        rebuildGroups();
+    };
+    const reset = () => {
+        groups = [];
+        dataTotal = 0;
+        totalEntries = 0;
+        groupKeyByIndex.clear();
+    };
+    return {
+        onItemsLoaded,
+        get totalEntries() {
+            return totalEntries;
+        },
+        get groupCount() {
+            return groups.length;
+        },
+        get groups() {
+            return groups;
+        },
+        isHeader,
+        getHeaderItem,
+        layoutToDataIndex,
+        dataToLayoutIndex,
+        getHeaderHeight,
+        getGroupAtLayoutIndex,
+        getGroupAtDataIndex,
+        insertAt,
+        removeAt,
+        reset,
+    };
+};

package/dist/{features → plugins}/groups/index.d.ts

@@ -2,7 +2,7 @@
  * vlist - Groups Domain
  * Sticky headers and grouped lists
  */
-export { withGroups, type GroupsFeatureConfig } from "./feature";
+export { groups, type GroupsPluginConfig } from "./plugin";
 export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLayout, StickyHeader, } from "./types";
 export { isGroupHeader } from "./types";
 export { createGroupLayout, buildLayoutItems, createGroupedSizeFn, } from "./layout";

package/dist/plugins/groups/index.js

@@ -0,0 +1,13 @@
+/**
+ * vlist - Groups Domain
+ * Sticky headers and grouped lists
+ */
+// v2 Plugin
+export { groups } from "./plugin";
+export { isGroupHeader } from "./types";
+// Layout
+export { createGroupLayout, buildLayoutItems, createGroupedSizeFn, } from "./layout";
+// Sticky Header
+export { createStickyHeader } from "./sticky";
+// Async Bridge
+export { createAsyncGroupBridge } from "./async-bridge";

package/dist/plugins/groups/layout.js

@@ -0,0 +1,294 @@
+/**
+ * vlist - Group Layout
+ * Computes group boundaries and maps between data indices and layout indices.
+ *
+ * The layout transforms a flat items array into a "layout" that includes
+ * group header pseudo-items interspersed at group boundaries:
+ *
+ *   Data:   [item0, item1, item2, item3, item4, item5]
+ *   Groups: [  A,     A,     A,     B,     B,     C  ]
+ *   Layout: [headerA, item0, item1, item2, headerB, item3, item4, headerC, item5]
+ *   Index:  [  0,       1,     2,     3,      4,      5,     6,      7,      8  ]
+ *
+ * All lookups are O(log g) where g = number of groups, using binary search
+ * on the sorted group boundaries array.
+ */
+// =============================================================================
+// Binary Search Helpers
+// =============================================================================
+/**
+ * Find the last group whose headerLayoutIndex <= layoutIndex.
+ * Returns the group's index in the groups array.
+ */
+export const findGroupByLayoutIndex = (groups, layoutIndex) => {
+    let lo = 0;
+    let hi = groups.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (groups[mid].headerLayoutIndex <= layoutIndex) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return lo;
+};
+/**
+ * Find the last group whose firstDataIndex <= dataIndex.
+ * Returns the group's index in the groups array.
+ */
+export const findGroupByDataIndex = (groups, dataIndex) => {
+    let lo = 0;
+    let hi = groups.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (groups[mid].firstDataIndex <= dataIndex) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return lo;
+};
+// =============================================================================
+// Layout Builder
+// =============================================================================
+/**
+ * Build the groups array from the items using getGroupForIndex.
+ *
+ * Items MUST be pre-sorted by group — a new group boundary is created
+ * whenever getGroupForIndex returns a different value than the previous call.
+ */
+const buildGroups = (itemCount, getGroupForIndex, getItem) => {
+    if (itemCount === 0)
+        return [];
+    const groups = [];
+    let currentKey = null;
+    let groupStart = 0;
+    let headerLayoutIndex = 0;
+    for (let i = 0; i < itemCount; i++) {
+        const item = getItem?.(i);
+        // Skip unloaded items — they extend the current group without
+        // creating boundaries. This avoids "Unknown" headers for placeholders.
+        if (!item)
+            continue;
+        const key = getGroupForIndex(i, item);
+        if (currentKey === null) {
+            // First loaded item — start first group
+            currentKey = key;
+            groupStart = 0;
+            // All items before this one (unloaded) belong to this group
+        }
+        else if (key !== currentKey) {
+            const count = i - groupStart;
+            groups.push({
+                key: currentKey,
+                groupIndex: groups.length,
+                headerLayoutIndex,
+                firstDataIndex: groupStart,
+                count,
+            });
+            headerLayoutIndex = headerLayoutIndex + 1 + count;
+            currentKey = key;
+            groupStart = i;
+        }
+    }
+    if (currentKey !== null) {
+        // Close the last group — includes all remaining unloaded items
+        groups.push({
+            key: currentKey,
+            groupIndex: groups.length,
+            headerLayoutIndex,
+            firstDataIndex: groupStart,
+            count: itemCount - groupStart,
+        });
+    }
+    return groups;
+};
+// =============================================================================
+// Layout Items Builder
+// =============================================================================
+/**
+ * Build the transformed layout items array with header pseudo-items inserted
+ * at group boundaries.
+ *
+ * @param items - Original data items
+ * @param groups - Computed group boundaries
+ * @returns Array of items and header pseudo-items in layout order
+ */
+export const buildLayoutItems = (items, groups) => {
+    if (items.length === 0 || groups.length === 0)
+        return [];
+    const totalEntries = items.length + groups.length;
+    const result = new Array(totalEntries);
+    let layoutIdx = 0;
+    for (const group of groups) {
+        // Insert header pseudo-item
+        result[layoutIdx] = {
+            id: `__group_header_${group.groupIndex}`,
+            __groupHeader: true,
+            groupKey: group.key,
+            groupIndex: group.groupIndex,
+        };
+        layoutIdx++;
+        // Insert data items for this group
+        for (let i = 0; i < group.count; i++) {
+            result[layoutIdx] = items[group.firstDataIndex + i];
+            layoutIdx++;
+        }
+    }
+    return result;
+};
+// =============================================================================
+// Height Function Builder
+// =============================================================================
+/**
+ * Create a size function for the layout (items + headers).
+ *
+ * Maps layout indices to sizes, accounting for both group headers and data items.
+ *
+ * @param layout - The group layout instance
+ * @param itemSize - Original item size config (number or function)
+ * @returns A size function (layoutIndex) => number suitable for SizeCache
+ */
+export const createGroupedSizeFn = (layout, itemSize, sticky = false) => {
+    const getItemSize = typeof itemSize === "number"
+        ? (_dataIndex) => itemSize
+        : itemSize;
+    return (layoutIndex) => {
+        const entry = layout.getEntry(layoutIndex);
+        if (entry.type === "header") {
+            // When sticky headers are active the first group's inline header
+            // is redundant (the sticky header already shows it).  Collapse it
+            // to 0 so it occupies no space in the layout.
+            if (sticky && entry.group.groupIndex === 0)
+                return 0;
+            return layout.getHeaderHeight(entry.group.groupIndex);
+        }
+        return getItemSize(entry.dataIndex);
+    };
+};
+// =============================================================================
+// GroupLayout Factory
+// =============================================================================
+/**
+ * Create a GroupLayout instance.
+ *
+ * The layout computes group boundaries from items and provides efficient
+ * O(log g) mappings between data indices and layout indices.
+ *
+ * @param itemCount - Number of data items
+ * @param config - Groups configuration
+ */
+export const createGroupLayout = (itemCount, config, getItem) => {
+    let groups = buildGroups(itemCount, config.getGroupForIndex, getItem);
+    let totalEntries = itemCount + groups.length;
+    // Pre-compute header sizes — resolve from height, width, or legacy headerHeight
+    const headerHeightConfig = config.header?.height ?? config.header?.width ?? config.headerHeight;
+    const getHeaderHeight = typeof headerHeightConfig === "number"
+        ? (_groupIndex) => headerHeightConfig
+        : (groupIndex) => {
+            const group = groups[groupIndex];
+            if (!group)
+                return 0;
+            return headerHeightConfig(group.key, groupIndex);
+        };
+    // =========================================================================
+    // Public API
+    // =========================================================================
+    const getEntry = (layoutIndex) => {
+        if (groups.length === 0) {
+            // Fallback: shouldn't happen if totalEntries > 0
+            return {
+                type: "item",
+                dataIndex: layoutIndex,
+                group: {
+                    key: "",
+                    groupIndex: 0,
+                    headerLayoutIndex: 0,
+                    firstDataIndex: 0,
+                    count: 0,
+                },
+            };
+        }
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        const group = groups[gi];
+        if (layoutIndex === group.headerLayoutIndex) {
+            return { type: "header", group };
+        }
+        // It's a data item within this group
+        const offsetInGroup = layoutIndex - group.headerLayoutIndex - 1;
+        const dataIndex = group.firstDataIndex + offsetInGroup;
+        return { type: "item", dataIndex, group };
+    };
+    const layoutToDataIndex = (layoutIndex) => {
+        if (groups.length === 0)
+            return layoutIndex;
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        const group = groups[gi];
+        if (layoutIndex === group.headerLayoutIndex) {
+            return -1; // It's a header
+        }
+        const offsetInGroup = layoutIndex - group.headerLayoutIndex - 1;
+        return group.firstDataIndex + offsetInGroup;
+    };
+    const dataToLayoutIndex = (dataIndex) => {
+        if (groups.length === 0)
+            return dataIndex;
+        const gi = findGroupByDataIndex(groups, dataIndex);
+        const group = groups[gi];
+        // Layout index = header layout index + 1 (skip header) + offset within group
+        const offsetInGroup = dataIndex - group.firstDataIndex;
+        return group.headerLayoutIndex + 1 + offsetInGroup;
+    };
+    const getGroupAtLayoutIndex = (layoutIndex) => {
+        if (groups.length === 0) {
+            return {
+                key: "",
+                groupIndex: 0,
+                headerLayoutIndex: 0,
+                firstDataIndex: 0,
+                count: 0,
+            };
+        }
+        const gi = findGroupByLayoutIndex(groups, layoutIndex);
+        return groups[gi];
+    };
+    const getGroupAtDataIndex = (dataIndex) => {
+        if (groups.length === 0) {
+            return {
+                key: "",
+                groupIndex: 0,
+                headerLayoutIndex: 0,
+                firstDataIndex: 0,
+                count: 0,
+            };
+        }
+        const gi = findGroupByDataIndex(groups, dataIndex);
+        return groups[gi];
+    };
+    const rebuild = (newItemCount, newGetItem) => {
+        groups = buildGroups(newItemCount, config.getGroupForIndex, newGetItem ?? getItem);
+        totalEntries = newItemCount + groups.length;
+    };
+    return {
+        get totalEntries() {
+            return totalEntries;
+        },
+        get groupCount() {
+            return groups.length;
+        },
+        get groups() {
+            return groups;
+        },
+        getEntry,
+        layoutToDataIndex,
+        dataToLayoutIndex,
+        getGroupAtLayoutIndex,
+        getGroupAtDataIndex,
+        getHeaderHeight,
+        rebuild,
+    };
+};

package/dist/plugins/groups/plugin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vlist v2 — Groups Plugin
+ *
+ * Adds grouped lists with sticky headers.
+ * Priority 10 — runs before selection (50).
+ *
+ * Architecture:
+ * - Transforms items list: inserts group header pseudo-items at group boundaries
+ * - Replaces size function: headers use header height, items use item height
+ * - Replaces render pipeline: handles grouped layout rendering
+ * - Sticky header: floating header that updates on scroll
+ * - CSS class: adds .vlist--grouped to root
+ *
+ * Restrictions:
+ * - Items must be pre-sorted by group
+ */
+import type { VListItem, GroupsConfig } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface GroupsPluginConfig extends GroupsConfig {
+}
+export declare function groups<T extends VListItem = VListItem>(config: GroupsPluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map