vlist 0.1.2 → 1.5.4

package/dist/features/async/manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * vlist - Data Management
+ * Handles data with sparse storage for million+ item support
+ */
+import type { VListItem, VListAdapter, Range } from "../../types";
+import { type SparseStorage, type SparseStorageConfig } from "./sparse";
+import { type PlaceholderConfig, type PlaceholderManager } from "./placeholder";
+/** Data manager configuration */
+export interface DataManagerConfig<T extends VListItem = VListItem> {
+    /** Async data adapter */
+    adapter?: VListAdapter<T>;
+    /** Initial items (optional) */
+    initialItems?: T[];
+    /** Initial total count (if known) */
+    initialTotal?: number;
+    /** Sparse storage configuration */
+    storage?: SparseStorageConfig;
+    /** Placeholder configuration */
+    placeholder?: PlaceholderConfig;
+    /** Items per load request (default: 50) */
+    pageSize?: number;
+    /** Callback when state changes */
+    onStateChange?: (state: DataState<T>) => void;
+    /** Callback when items are loaded */
+    onItemsLoaded?: (items: T[], offset: number, total: number) => void;
+    /** Callback when items are evicted */
+    onItemsEvicted?: (count: number) => void;
+}
+/** Data state */
+export interface DataState<_T extends VListItem = VListItem> {
+    /** Total items (declared, may be larger than loaded) */
+    total: number;
+    /** Number of items in memory */
+    cached: number;
+    /** Whether data is loading */
+    isLoading: boolean;
+    /** Pending load ranges */
+    pendingRanges: Range[];
+    /** Error from last operation */
+    error: Error | undefined;
+    /** Whether more items exist */
+    hasMore: boolean;
+    /** Current cursor (for cursor pagination) */
+    cursor: string | undefined;
+}
+/** Data manager instance */
+export interface DataManager<T extends VListItem = VListItem> {
+    /** Get current state */
+    getState: () => DataState<T>;
+    /** Get total item count (direct getter, no allocation) */
+    getTotal: () => number;
+    /** Get cached item count (direct getter, no allocation) */
+    getCached: () => number;
+    /** Check if currently loading (direct getter, no allocation) */
+    getIsLoading: () => boolean;
+    /** Check if more items available (direct getter, no allocation) */
+    getHasMore: () => boolean;
+    /** Get sparse storage */
+    getStorage: () => SparseStorage<T>;
+    /** Get placeholder manager */
+    getPlaceholders: () => PlaceholderManager<T>;
+    /** Get item at index (may return placeholder if not loaded) */
+    getItem: (index: number) => T | undefined;
+    /** Get item by ID */
+    getItemById: (id: string | number) => T | undefined;
+    /** Get index by ID (-1 if not found) */
+    getIndexById: (id: string | number) => number;
+    /** Check if item at index is loaded (not placeholder) */
+    isItemLoaded: (index: number) => boolean;
+    /** Get items in range (includes placeholders for unloaded) */
+    getItemsInRange: (start: number, end: number) => T[];
+    /** Set total item count */
+    setTotal: (total: number) => void;
+    /** Set items at offset */
+    setItems: (items: T[], offset?: number, total?: number) => void;
+    /** Update item at index */
+    updateItem: (index: number, updates: Partial<T>) => boolean;
+    /** Remove item by ID */
+    removeItem: (id: string | number) => boolean;
+    /** Load items for a range */
+    loadRange: (start: number, end: number) => Promise<void>;
+    /** Ensure range is loaded (no-op if already loaded) */
+    ensureRange: (start: number, end: number) => Promise<void>;
+    /** Load initial data */
+    loadInitial: () => Promise<void>;
+    /** Load more items (infinite scroll) */
+    loadMore: () => Promise<boolean>;
+    /** Reload all data */
+    reload: () => Promise<void>;
+    /** Evict items far from visible range */
+    evictDistant: (visibleStart: number, visibleEnd: number) => void;
+    /** Clear all data */
+    clear: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Create a data manager with sparse storage support
+ */
+export declare const createDataManager: <T extends VListItem = VListItem>(config?: DataManagerConfig<T>) => DataManager<T>;
+export { mergeRanges, calculateMissingRanges } from "./sparse";
+export { isPlaceholderItem, filterPlaceholders, countRealItems, } from "./placeholder";
+//# sourceMappingURL=manager.d.ts.map

package/dist/features/async/placeholder.d.ts

@@ -0,0 +1,54 @@
+/**
+ * vlist - Placeholder System
+ * Smart placeholder generation for loading states
+ *
+ * Key features:
+ * - Captures per-item field lengths from the first loaded batch
+ * - Cycles through real data profiles for natural size variance
+ * - Same item template renders both real and placeholder items
+ * - Renderer adds CSS class for visual styling (no JS branching needed)
+ */
+import type { VListItem } from "../../types";
+/** Placeholder configuration */
+export interface PlaceholderConfig {
+    /** Character used for masking text (default: 'x') */
+    maskCharacter?: string;
+    /** Maximum items to sample for length profiling (default: 20) */
+    maxSampleSize?: number;
+}
+/** Placeholder manager instance */
+export interface PlaceholderManager<T extends VListItem = VListItem> {
+    /** Analyze data structure from sample items */
+    analyzeStructure: (items: T[]) => void;
+    /** Check if structure has been analyzed */
+    hasAnalyzedStructure: () => boolean;
+    /** Generate a single placeholder item */
+    generate: (index: number) => T;
+    /** Generate multiple placeholder items */
+    generateRange: (start: number, end: number) => T[];
+    /** Clear analyzed structure */
+    clear: () => void;
+}
+/**
+ * Create a placeholder manager that generates realistic placeholder items
+ * by capturing per-item field lengths from the first loaded data batch.
+ *
+ * Placeholders carry the same field names as real items, filled with
+ * mask characters sized to match actual data. The renderer detects
+ * placeholders via the `_isPlaceholder` flag and applies a CSS class
+ * — no template branching required.
+ */
+export declare const createPlaceholderManager: <T extends VListItem = VListItem>(config?: PlaceholderConfig) => PlaceholderManager<T>;
+/**
+ * Check if an item is a placeholder
+ */
+export declare const isPlaceholderItem: (item: unknown) => boolean;
+/**
+ * Filter out placeholder items from an array
+ */
+export declare const filterPlaceholders: <T extends VListItem>(items: T[]) => T[];
+/**
+ * Count non-placeholder items in an array
+ */
+export declare const countRealItems: <T extends VListItem>(items: (T | undefined)[]) => number;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/features/async/sparse.d.ts

@@ -0,0 +1,91 @@
+/**
+ * vlist - Sparse Storage
+ * Efficient storage for million+ item virtual lists
+ */
+import type { VListItem, Range } from "../../types";
+/** Configuration for sparse storage */
+export interface SparseStorageConfig {
+    /** Number of items per chunk (default: 100) */
+    chunkSize?: number;
+    /** Maximum items to keep in memory (default: 5000) */
+    maxCachedItems?: number;
+    /** Extra items to keep around visible range during eviction (default: 200) */
+    evictionBuffer?: number;
+    /** Callback when items are evicted */
+    onEvict?: (evictedCount: number, evictedRanges: number[]) => void;
+}
+/** Storage statistics */
+export interface SparseStorageStats {
+    /** Total items declared (may be larger than loaded) */
+    totalItems: number;
+    /** Number of items currently in memory */
+    cachedItems: number;
+    /** Number of chunks in memory */
+    cachedChunks: number;
+    /** Chunk size */
+    chunkSize: number;
+    /** Maximum cached items allowed */
+    maxCachedItems: number;
+    /** Memory efficiency (cachedItems / totalItems) */
+    memoryEfficiency: number;
+}
+/** Sparse storage instance */
+export interface SparseStorage<T extends VListItem = VListItem> {
+    readonly chunkSize: number;
+    readonly maxCachedItems: number;
+    /** Get total item count */
+    getTotal: () => number;
+    /** Set total item count (for virtual scrolling height) */
+    setTotal: (total: number) => void;
+    /** Get item at index (undefined if not loaded) */
+    get: (index: number) => T | undefined;
+    /** Check if item at index is loaded */
+    has: (index: number) => boolean;
+    /** Set item at index */
+    set: (index: number, item: T) => void;
+    /** Set multiple items starting at offset */
+    setRange: (offset: number, items: T[]) => void;
+    /** Delete item at index */
+    delete: (index: number) => boolean;
+    /** Get items in range (includes undefined for unloaded) */
+    getRange: (start: number, end: number) => (T | undefined)[];
+    /** Check if range is fully loaded */
+    isRangeLoaded: (start: number, end: number) => boolean;
+    /** Get loaded ranges */
+    getLoadedRanges: () => Range[];
+    /** Find unloaded ranges within a given range */
+    findUnloadedRanges: (start: number, end: number) => Range[];
+    /** Get chunk index for item index */
+    getChunkIndex: (itemIndex: number) => number;
+    /** Check if chunk is loaded */
+    isChunkLoaded: (chunkIndex: number) => boolean;
+    /** Mark chunk as accessed (for LRU) */
+    touchChunk: (chunkIndex: number) => void;
+    /** Mark all chunks in a range as accessed with a single Date.now() call */
+    touchChunksForRange: (start: number, end: number) => void;
+    /** Evict chunks far from visible range */
+    evictDistant: (visibleStart: number, visibleEnd: number) => number;
+    /** Force eviction to meet memory limit */
+    evictToLimit: () => number;
+    /** Get storage statistics */
+    getStats: () => SparseStorageStats;
+    /** Get cached item count */
+    getCachedCount: () => number;
+    /** Clear all data */
+    clear: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Create sparse storage for efficient large list handling
+ */
+export declare const createSparseStorage: <T extends VListItem = VListItem>(config?: SparseStorageConfig) => SparseStorage<T>;
+/**
+ * Merge adjacent/overlapping ranges
+ */
+export declare const mergeRanges: (ranges: Range[]) => Range[];
+/**
+ * Calculate ranges that need to be loaded
+ */
+export declare const calculateMissingRanges: (needed: Range, loaded: Range[], chunkSize: number) => Range[];
+//# sourceMappingURL=sparse.d.ts.map

package/dist/features/autosize/feature.d.ts

@@ -0,0 +1,34 @@
+/**
+ * vlist/autosize — Auto-Size Measurement Feature
+ *
+ * Enables dynamic item measurement via ResizeObserver for items with
+ * unknown sizes (Mode B). Items are rendered with no explicit main-axis
+ * size, measured once by a ResizeObserver, and then pinned to their
+ * measured size for all subsequent renders.
+ *
+ * Priority: 5 (runs before grid/masonry at 10 so the measured cache
+ * is in place before layout features wrap it)
+ *
+ * Requires: `item.estimatedHeight` or `item.estimatedWidth` in config
+ *
+ * @example
+ * ```ts
+ * import { vlist, withAutoSize } from '@floor/vlist';
+ *
+ * vlist({
+ *   container: '#app',
+ *   item: { estimatedHeight: 60, template: (item) => `<div>${item.name}</div>` },
+ *   items: data,
+ * })
+ *   .use(withAutoSize())
+ *   .build();
+ * ```
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/**
+ * Create an auto-size measurement feature for items with unknown sizes.
+ * Reads `estimatedHeight`/`estimatedWidth` from the builder config.
+ */
+export declare const withAutoSize: <T extends VListItem = VListItem>() => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/autosize/index.d.ts

@@ -0,0 +1,2 @@
+export { withAutoSize } from "./feature";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/grid/feature.d.ts

@@ -0,0 +1,48 @@
+/**
+ * vlist/grid - Builder Feature
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it wires:
+ * - Replaces renderer — swaps the list renderer with a grid renderer
+ * - Redefines virtual total — the virtualizer sees rows, not items
+ * - Column width calculation — recalculated on resize
+ * - Item positioning — each item gets translateX (column) and translateY (row)
+ * - CSS class — adds .vlist--grid to the root element
+ *
+ * Restrictions:
+ * - Cannot be combined with orientation: 'horizontal'
+ * - Cannot be combined with reverse: true
+ *
+ * Can be combined with withGroups for grouped 2D layouts.
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Grid feature configuration */
+export interface GridFeatureConfig {
+    /** Number of columns (required, >= 1) */
+    columns: number;
+    /** Gap between items in pixels (default: 0) */
+    gap?: number;
+}
+/**
+ * Create a grid feature for the builder.
+ *
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withGrid } from 'vlist/grid'
+ *
+ * const gallery = vlist({
+ *   container: '#gallery',
+ *   item: { height: 200, template: renderPhoto },
+ *   items: photos,
+ * })
+ * .use(withGrid({ columns: 4, gap: 8 }))
+ * .build()
+ * ```
+ */
+export declare const withGrid: <T extends VListItem = VListItem>(config: GridFeatureConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/grid/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * vlist - Grid Domain
+ * 2D grid/card layout with virtualized rows
+ */
+export { withGrid, type GridFeatureConfig } from "./feature";
+export { createGridLayout } from "./layout";
+export { createGridRenderer, type GridRenderer } from "./renderer";
+export type { GridConfig, GridLayout, GridPosition, ItemRange } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/grid/layout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * vlist - Grid Layout
+ * Pure O(1) calculations for mapping between flat item indices and grid positions.
+ *
+ * The grid transforms a flat list into rows:
+ *   Items:  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ *   Grid (columns=4):
+ *     Row 0: [0, 1, 2, 3]
+ *     Row 1: [4, 5, 6, 7]
+ *     Row 2: [8, 9]          ← partially filled last row
+ *
+ * All operations are O(1) — integer division and modulo only.
+ */
+import type { GridConfig, GridLayout } from "./types";
+/**
+ * Extended grid config with optional groups support
+ */
+export interface GridConfigWithGroups extends GridConfig {
+    /** Optional: check if an item index is a group header (for groups-aware layout) */
+    isHeaderFn?: (index: number) => boolean;
+}
+/**
+ * Create a GridLayout instance.
+ *
+ * @param config - Grid configuration (columns, gap, optional isHeaderFn)
+ * @returns GridLayout with O(1) mapping functions (or groups-aware if isHeaderFn provided)
+ */
+export declare const createGridLayout: (config: GridConfigWithGroups) => GridLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/features/grid/renderer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * vlist - Grid Renderer
+ * Renders items in a 2D grid layout within the virtual scroll container.
+ *
+ * Extends the base renderer pattern but positions items using both
+ * row offsets (translateY from the size cache) and column offsets
+ * (translateX calculated from column index and container width).
+ *
+ * Key differences from the list renderer:
+ * - Items are positioned with translate(x, y) instead of just translateY(y)
+ * - Item width is set to columnWidth (containerWidth / columns - gaps)
+ * - The "index" in the rendered map is the FLAT ITEM INDEX (not row index)
+ * - Row offsets come from the size cache (which operates on row indices)
+ * - Column offsets are calculated from itemIndex % columns
+ *
+ * Performance:
+ * - Element pooling avoids createElement cost
+ * - Template re-evaluation skipped when item data + state unchanged (change tracking)
+ * - Position update skipped when coordinates unchanged (position tracking)
+ * - O(1) Set-based visibility diffing (not O(n) .some())
+ * - Release grace period prevents boundary thrashing (hover blink, transition replay)
+ * - Released elements removed from DOM immediately
+ * - DocumentFragment batched insertion for new elements
+ */
+import type { VListItem, ItemTemplate, Range } from "../../types";
+import type { SizeCache } from "../../rendering/sizes";
+import type { CompressionContext } from "../../rendering/renderer";
+import type { GridLayout } from "./types";
+/** Grid renderer instance */
+export interface GridRenderer<T extends VListItem = VListItem> {
+    /** Render items for a flat item range, positioned in a 2D grid */
+    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number, compressionCtx?: CompressionContext) => void;
+    /** Update item positions (for compressed scrolling) */
+    updatePositions: (compressionCtx: CompressionContext) => void;
+    /** Update a single item (used by selection feature for focused item changes) */
+    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
+    /** Update only CSS classes on a rendered item (no template re-evaluation) */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /** Get rendered item element by flat item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /**
+     * Reorder DOM children to match logical item order (by data-index).
+     * Called on scroll idle so screen readers encounter items in the correct
+     * sequence. Items are position:absolute so visual layout is unaffected.
+     */
+    sortDOM: () => void;
+    /** Update container width (call on resize) */
+    updateContainerWidth: (width: number) => void;
+    /** Clear all rendered items */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a grid renderer for managing DOM elements in a 2D layout.
+ *
+ * The grid renderer receives flat item ranges (not row ranges) and
+ * positions each item at the correct (row, col) coordinate.
+ *
+ * @param itemsContainer - The DOM element that holds rendered items
+ * @param template - Item template function
+ * @param sizeCache - Size cache operating on ROW indices
+ * @param gridLayout - Grid layout for row/col calculations
+ * @param classPrefix - CSS class prefix
+ * @param initialContainerWidth - Initial container width for column sizing
+ * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
+ * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
+ * @param isHorizontal - Whether layout is horizontal (scrolls right)
+ */
+export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string, isHorizontal?: boolean) => GridRenderer<T>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/features/grid/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * vlist - Grid Types
+ * Types for grid/card layout mode
+ *
+ * Grid layout transforms a flat list of items into a 2D grid where:
+ * - Virtualization operates on ROWS (not individual items)
+ * - Each row contains `columns` items side by side
+ * - Items are positioned using row/column coordinates
+ * - Compression applies to row count, not item count
+ */
+import type { GridConfig } from "../../types";
+export type { GridConfig };
+/** Row/column position of an item */
+export interface GridPosition {
+    /** Row index (0-based) */
+    row: number;
+    /** Column index (0-based) */
+    col: number;
+}
+/** Flat item range corresponding to a row range */
+export interface ItemRange {
+    /** First item index (inclusive) */
+    start: number;
+    /** Last item index (inclusive) */
+    end: number;
+}
+/**
+ * GridLayout — maps between flat item indices and row/column positions.
+ *
+ * The virtualizer sees "rows" as its unit of work. Each row contains
+ * up to `columns` items. The last row may be partially filled.
+ *
+ * All operations are O(1) — just integer division and modulo.
+ */
+export interface GridLayout {
+    /** Number of columns */
+    readonly columns: number;
+    /** Gap between items in pixels */
+    readonly gap: number;
+    /** Update grid configuration without recreating the layout */
+    update: (config: Partial<GridConfig>) => void;
+    /** Get total number of rows for a given item count */
+    getTotalRows: (totalItems: number) => number;
+    /** Get the row/col position for a flat item index */
+    getPosition: (itemIndex: number) => GridPosition;
+    /** Get the row index for a flat item index */
+    getRow: (itemIndex: number) => number;
+    /** Get the column index for a flat item index */
+    getCol: (itemIndex: number) => number;
+    /**
+     * Get the flat item range for a range of rows.
+     * The last row may be partially filled (end is clamped to totalItems - 1).
+     */
+    getItemRange: (rowStart: number, rowEnd: number, totalItems: number) => ItemRange;
+    /**
+     * Get the flat item index from a row and column.
+     * Returns -1 if out of bounds.
+     */
+    getItemIndex: (row: number, col: number, totalItems: number) => number;
+    /**
+     * Calculate column width given container width.
+     * Accounts for gaps: width = (containerWidth - (columns - 1) * gap) / columns
+     */
+    getColumnWidth: (containerWidth: number) => number;
+    /**
+     * Calculate the X offset for a column index.
+     * offset = col * (columnWidth + gap)
+     */
+    getColumnOffset: (col: number, containerWidth: number) => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/groups/feature.d.ts

@@ -0,0 +1,74 @@
+/**
+ * vlist/groups - Builder Feature
+ * Adds grouped lists with sticky headers.
+ *
+ * Priority: 10 (runs first — transforms item list and height function before rendering)
+ *
+ * What it wires:
+ * - Transforms item list — inserts header items at group boundaries
+ * - Replaces height function — headers use headerHeight, data items use configured item.height
+ * - Unified template — dispatches to headerTemplate for headers, user template for items
+ * - Sticky header DOM — creates a positioned header element that updates as you scroll
+ * - Index mapping — translates between data indices and layout indices
+ * - CSS class — adds .vlist--grouped to the root element
+ *
+ * Restrictions:
+ * - Items must be pre-sorted by group
+ *
+ * Can be combined with:
+ * - withGrid for grouped 2D layouts
+ * - reverse: true (sticky header shows current section as you scroll up through history)
+ * - orientation: 'horizontal' (sticky headers stick to left edge, push left when next header approaches)
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Groups feature configuration */
+export interface GroupsFeatureConfig {
+    /** Returns group key for item at index (required) */
+    getGroupForIndex: (index: number) => string;
+    /** Group header configuration — mirrors the `item` config shape */
+    header?: {
+        /** Header size in pixels — vertical scrolling (default) */
+        height?: number;
+        /** Header size in pixels — horizontal scrolling */
+        width?: number;
+        /** Render function for headers (required) */
+        template: (key: string, groupIndex: number) => HTMLElement | string;
+    };
+    /** @deprecated Use `header.height` instead. */
+    headerHeight?: number;
+    /** @deprecated Use `header.template` instead. */
+    headerTemplate?: (key: string, groupIndex: number) => HTMLElement | string;
+    /** Enable sticky headers — iOS Contacts style (default: true) */
+    sticky?: boolean;
+}
+/**
+ * Create a groups feature for the builder.
+ *
+ * Adds grouped lists with sticky section headers.
+ *
+ * ```ts
+ * import { vlist, withGroups } from '@floor/vlist'
+ *
+ * const contacts = vlist({
+ *   container: '#contacts',
+ *   item: { height: 56, template: renderContact },
+ *   items: sortedContacts,
+ * })
+ * .use(withGroups({
+ *   getGroupForIndex: (i) => sortedContacts[i].lastName[0],
+ *   header: {
+ *     height: 32,
+ *     template: (letter) => {
+ *       const el = document.createElement('div')
+ *       el.className = 'letter-header'
+ *       el.textContent = letter
+ *       return el
+ *     },
+ *   },
+ * }))
+ * .build()
+ * ```
+ */
+export declare const withGroups: <T extends VListItem = VListItem>(groupsRawConfig: GroupsFeatureConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/groups/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vlist - Groups Domain
+ * Sticky headers and grouped lists
+ */
+export { withGroups, type GroupsFeatureConfig } from "./feature";
+export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLayout, StickyHeader, } from "./types";
+export { isGroupHeader } from "./types";
+export { createGroupLayout, buildLayoutItems, createGroupedSizeFn, } from "./layout";
+export { createStickyHeader } from "./sticky";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/groups/layout.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+import type { GroupsConfig, GroupBoundary, GroupLayout, GroupHeaderItem } from "./types";
+import type { VListItem } from "../../types";
+/**
+ * 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 declare const buildLayoutItems: <T extends VListItem>(items: T[], groups: readonly GroupBoundary[]) => Array<T | GroupHeaderItem>;
+/**
+ * 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 declare const createGroupedSizeFn: (layout: GroupLayout, itemSize: number | ((index: number) => number), sticky?: boolean) => ((layoutIndex: number) => number);
+/**
+ * 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 declare const createGroupLayout: (itemCount: number, config: GroupsConfig) => GroupLayout;
+//# sourceMappingURL=layout.d.ts.map