vlist 1.9.1 → 2.0.1

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

@@ -1,75 +0,0 @@
-/**
- * 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
- * - withAsync for grouped lists with async pagination
- * - 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, item?: any) => 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 '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/masonry/feature.d.ts

@@ -1,45 +0,0 @@
-/**
- * vlist/masonry - Builder Feature
- * Switches from list layout to masonry/Pinterest-style layout.
- *
- * Priority: 10 (runs first — replaces the renderer before anything else renders)
- *
- * What it does:
- * - Replaces renderer — swaps the list renderer with a masonry renderer
- * - Calculates item placements using shortest-lane algorithm
- * - Positions items using absolute coordinates (no row alignment)
- * - Renders only visible items based on scroll position
- * - CSS class — adds .vlist--masonry to the root element
- *
- * Key differences from grid:
- * - No row-based virtualization (items flow into shortest column/row)
- * - O(n) layout calculation (must track lane heights)
- * - Items positioned by cached x/y coordinates
- * - Variable heights create organic, packed layout
- *
- * Restrictions:
- * - Cannot be combined with reverse: true
- * - Item sizes must be deterministic (no dynamic content sizing)
- *
- * Can be combined with withSelection for selectable masonry layouts.
- *
- * Performance:
- * - Early exit when scroll position + container size unchanged (zero work per redundant frame)
- * - Cached empty Set for no-selection case (zero allocation per frame)
- * - Viewport state mutated in place (no object creation per frame)
- * - Cached getItem closure (no closure allocation per frame)
- *
- * - Items passed to renderer via data manager reference (no sparse array)
- * - All data mutation methods intercepted for layout recalculation
- */
-import type { VListItem } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/** Masonry feature configuration */
-export interface MasonryFeatureConfig {
-    /** Number of cross-axis divisions (columns in vertical, rows in horizontal) */
-    columns: number;
-    /** Gap between items in pixels (default: 0) */
-    gap?: number;
-}
-export declare const withMasonry: <T extends VListItem = VListItem>(config: MasonryFeatureConfig) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,9 +0,0 @@
-/**
- * vlist - Masonry Domain
- * Pinterest-style layout with shortest-lane placement
- */
-export { withMasonry, type MasonryFeatureConfig } from "./feature";
-export { createMasonryLayout } from "./layout";
-export { createMasonryRenderer, type MasonryRenderer, type GetItemFn } from "./renderer";
-export type { MasonryConfig, MasonryLayout, ItemPlacement, } from "./types";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,109 +0,0 @@
-/**
- * vlist/window - Window Scroll Mode Feature
- *
- * Enables the list to scroll with the page instead of in its own container.
- * Useful for infinite feeds, full-page lists, and chat UIs that integrate
- * with page scroll.
- *
- * Priority: 5 (runs early, before other features that depend on scroll)
- *
- * What it does:
- * - Uses window as scroll target instead of viewport element
- * - Calculates scroll position relative to document
- * - Uses window.innerWidth/innerHeight for container dimensions
- * - Listens to window resize events instead of ResizeObserver
- * - Adjusts DOM styles (overflow: visible, height: auto)
- * - Optionally accounts for fixed/sticky chrome via scrollPadding
- * - Uses behavior: "instant" on all scrollTo calls to override CSS
- *   scroll-behavior: smooth that may be set on the page
- *
- * Bundle impact: ~0.3 KB gzipped when used
- */
-import type { VListItem } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/**
- * Options for the window scroll mode feature.
- */
-export interface WithPageOptions {
-    /**
-     * Scroll padding — insets from the viewport edges where fixed/sticky
-     * elements (headers, footers, toolbars) live.
-     *
-     * When keyboard focus moves an item behind a sticky bar, the list
-     * auto-scrolls to keep it within the visible (unobstructed) area.
-     * Also affects `scrollToIndex` alignment (start/center/end).
-     *
-     * Mirrors CSS `scroll-padding` semantics: defines the optimal viewing
-     * region within the scrollport.
-     *
-     * Values can be numbers (pixels) or functions that return pixels
-     * (useful when the sticky element's height is dynamic).
-     *
-     * @example
-     * ```ts
-     * withPage({
-     *   scrollPadding: { top: 60, bottom: 50 }
-     * })
-     * ```
-     *
-     * @example Dynamic values
-     * ```ts
-     * withPage({
-     *   scrollPadding: {
-     *     top: () => document.getElementById('sticky-header')!.offsetHeight,
-     *     bottom: 50
-     *   }
-     * })
-     * ```
-     */
-    scrollPadding?: {
-        top?: number | (() => number);
-        bottom?: number | (() => number);
-        left?: number | (() => number);
-        right?: number | (() => number);
-    };
-}
-/**
- * Create a window scroll mode feature.
- *
- * Use this when you want your list to scroll with the page instead of
- * in a fixed-height container.
- *
- * @example
- * ```ts
- * import { vlist } from 'vlist/builder'
- * import { withWindow } from 'vlist/window'
- *
- * const feed = vlist({
- *   container: '#infinite-feed',
- *   item: { height: 200, template: renderPost },
- *   items: posts
- * })
- * .use(withWindow())
- * .build()
- * ```
- *
- * @example With scroll padding for sticky chrome
- * ```ts
- * const feed = vlist({
- *   container: '#infinite-feed',
- *   item: { height: 200, template: renderPost },
- *   items: posts
- * })
- * .use(withPage({ scrollPadding: { top: 60, bottom: 50 } }))
- * .build()
- * ```
- *
- * @example Horizontal window scrolling
- * ```ts
- * const timeline = vlist({
- *   container: '#timeline',
- *   item: { height: 100, template: renderEvent },
- *   orientation: 'horizontal'
- * })
- * .use(withWindow())
- * .build()
- * ```
- */
-export declare const withPage: <T extends VListItem = VListItem>(options?: WithPageOptions) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,9 +0,0 @@
-/**
- * vlist/window - Window Scroll Mode Feature
- *
- * Entry point for the window scroll feature.
- */
-export { withPage } from "./feature";
-export type { WithPageOptions } from "./feature";
-export type { VListFeature } from "../../builder/types";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,42 +0,0 @@
-/**
- * vlist/compression - Builder Feature
- * Enables support for lists with 1M+ items by compressing the scroll space
- * when the total height exceeds the browser's ~16.7M pixel limit.
- *
- * Priority: 20 (runs before scrollbar, after grid/groups)
- *
- * What it wires:
- * - Scroll mode switch — transitions from native to compressed scrolling when needed
- * - Scroll position mapping — maps compressed scroll positions to item indices
- * - Item positioning — positions items relative to viewport in compressed mode
- * - Custom scrollbar fallback — forces custom scrollbar in compressed mode
- * - Compression slack — extends scroll range so the linear index formula reaches every item
- * - Cached compression state — recalculates only when total item count changes
- * - Smooth scroll interpolation — lerp-based wheel handling for cross-browser consistency
- * - Touch scroll support — finger tracking + momentum for iOS Safari / mobile browsers
- *
- * No configuration needed — compression activates automatically when the total
- * height exceeds the browser limit, and deactivates when items are removed.
- */
-import type { VListItem } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/** Configuration options for the scale feature */
-export interface ScaleConfig {
-    /**
-     * Force compressed scroll mode even when the total size is below the
-     * browser's ~16.7M pixel limit.
-     *
-     * When `true`, the feature always activates compressed scrolling
-     * (custom wheel/touch handling, lerp-based smooth scroll, custom
-     * scrollbar fallback) regardless of the list size. This is useful for:
-     *
-     * - **Testing** — verify compression behaviour with a small item set
-     * - **Consistent UX** — prefer the smooth scroll physics for all lists
-     * - **Pre-emptive** — avoid the mode switch when items are added at runtime
-     *
-     * @default false
-     */
-    force?: boolean;
-}
-export declare const withScale: <T extends VListItem = VListItem>(config?: ScaleConfig) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,10 +0,0 @@
-/**
- * vlist - Compression Sub-module
- * Re-exports compression utilities for tree-shakeable imports
- *
- * Usage: import { getCompressionInfo } from 'vlist/compression'
- * Usage: import { withScale } from 'vlist/compression'
- */
-export { MAX_VIRTUAL_SIZE, getCompressionState, needsCompression, getMaxItemsWithoutCompression, getCompressionInfo, calculateCompressedVisibleRange, calculateCompressedRenderRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, calculateIndexFromScrollPosition, type CompressionState, } from "../../rendering/scale";
-export { withScale, type ScaleConfig } from "./feature";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,81 +0,0 @@
-/**
- * vlist/scroll - Builder Feature
- * Wraps the custom scrollbar into a VListFeature for the composable builder.
- *
- * Priority: 30 (runs after renderer/data setup but before selection)
- *
- * What it wires:
- * - DOM elements — track, thumb, and optional hover zone appended to viewport
- * - CSS class — .vlist-viewport--custom-scrollbar hides native scrollbar
- * - Drag handlers — mousedown on thumb, mousemove/mouseup on document
- * - Track click — click on track to jump to position
- * - Hover handlers — mouseenter/leave on track, hover zone, and viewport
- * - Scroll sync — updates thumb position on every scroll frame
- * - Resize sync — updates thumb size when container or content height changes
- *
- * No public methods are added — the scrollbar is entirely automatic.
- */
-import type { VListItem } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/** Scrollbar feature configuration */
-export interface ScrollbarFeatureConfig {
-    /** Auto-hide scrollbar after idle (default: true) */
-    autoHide?: boolean;
-    /** Auto-hide delay in milliseconds (default: 1000) */
-    autoHideDelay?: number;
-    /** Minimum thumb size in pixels (default: 30) */
-    minThumbSize?: number;
-    /**
-     * Show scrollbar when hovering near the scrollbar edge (default: true).
-     * When true, an invisible hover zone is placed along the scrollbar edge.
-     */
-    showOnHover?: boolean;
-    /**
-     * Width of the invisible hover zone in pixels (default: 16).
-     * Only used when `showOnHover` is true.
-     */
-    hoverZoneWidth?: number;
-    /**
-     * Show scrollbar when the mouse enters the list viewport (default: true).
-     * When false, the scrollbar only appears on scroll or hover near edge.
-     */
-    showOnViewportEnter?: boolean;
-    /**
-     * Reserve layout space for the scrollbar (default: false).
-     * When true, content shrinks to make room for the scrollbar track so it
-     * never overlaps items. Equivalent to CSS `scrollbar-gutter: stable`.
-     */
-    gutter?: boolean;
-    /**
-     * Padding between the scrollbar track and the viewport edges in pixels (default: 1).
-     * Insets the track from the right wall and from the top and bottom, so the scrollbar
-     * floats rather than sitting flush against the edges. Also adjusts the thumb travel
-     * range to keep position accurate.
-     * Can also be set globally via the `--vlist-custom-scrollbar-padding` CSS variable.
-     */
-    padding?: number;
-    /**
-     * Behavior when clicking on the scrollbar track (not the thumb) (default: 'scroll').
-     * - `'scroll'` — scrolls toward the clicked position, matching macOS native scrollbar
-     *                behavior. Hold to scroll continuously.
-     * - `'jump'`   — jumps directly to the clicked position (centers the thumb there).
-     */
-    clickBehavior?: 'jump' | 'scroll' | 'page';
-}
-/**
- * Create a scrollbar feature for the builder.
- *
- * Replaces the native browser scrollbar with a custom, cross-browser
- * consistent scrollbar.
- *
- * ```ts
- * import { vlist } from 'vlist/builder'
- * import { withScrollbar } from 'vlist/scroll'
- *
- * const list = vlist({ ... })
- *   .use(withScrollbar({ autoHide: true, autoHideDelay: 1000 }))
- *   .build()
- * ```
- */
-export declare const withScrollbar: <T extends VListItem = VListItem>(config?: ScrollbarFeatureConfig) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,8 +0,0 @@
-/**
- * vlist - Scroll Domain
- * Scroll controller and custom scrollbar
- */
-export { withScrollbar, type ScrollbarFeatureConfig } from "./feature";
-export { createScrollController, rafThrottle, isAtBottom, isAtTop, getScrollPercentage, isRangeVisible, type ScrollController, type ScrollControllerConfig, type ScrollEventData, type ScrollDirection, } from "./controller";
-export { createScrollbar, type Scrollbar, type ScrollbarConfig, type ScrollCallback, } from "./scrollbar";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,91 +0,0 @@
-/**
- * vlist/selection - Builder Feature
- * Wraps the selection domain into a VListFeature for the composable builder.
- *
- * Priority: 50 (runs after renderer and data are ready)
- *
- * Follows the WAI-ARIA APG "Recommended" multi-select listbox model:
- *
- * What it wires:
- * - Click handler on items container — toggles selection on item click
- *   - Shift+click in multiple mode selects a contiguous range from last-selected item
- * - Keyboard handler on root — ArrowUp/Down/PageUp/PageDown/Home/End for focus, Space/Enter for toggle
- *   - In single mode with followFocus: true, selection follows focus on arrow keys
- *   - In multiple mode, arrow keys move focus only; Space/Enter toggles selection
- *   - Shift+Arrow toggles the destination item (additive, one at a time)
- *   - Shift+Space selects a contiguous range from last-selected item to focused item
- *   - Ctrl+Shift+Home/End selects from focused item to first/last item
- *   - Ctrl+A / Cmd+A selects all (or deselects all if all are selected)
- * - ARIA attributes — aria-selected on items, aria-activedescendant on root
- * - Live region — announces selection changes to screen readers
- * - Render integration — registers internal getters (_getSelectedIds,
- *   _getFocusedIndex) so renderers read real selection state directly,
- *   eliminating the previous querySelectorAll-based DOM bypass.
- *
- * Added methods: select, deselect, toggleSelect, selectAll, clearSelection,
- *                getSelected, getSelectedItems, selectNext, selectPrevious
- *
- * Internal methods (for renderer integration, not public API):
- *   _getSelectedIds  — returns the live Set<string|number> of selected IDs
- *   _getFocusedIndex  — returns the current focused index
- *
- * Added events: item:click, selection:change
- */
-import type { VListItem, SelectionMode } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/** Selection feature configuration */
-export interface SelectionFeatureConfig {
-    /** Selection mode (default: 'single') */
-    mode?: SelectionMode;
-    /** Initially selected item IDs */
-    initial?: Array<string | number>;
-    /**
-     * When true, arrow keys select the focused item in single mode
-     * (WAI-ARIA "selection follows focus" pattern). Default: false.
-     * Ignored in multiple mode (focus and selection are always independent).
-     */
-    followFocus?: boolean;
-    /**
-     * Which item Shift+Arrow toggles in multiple mode.
-     * - `'origin'` (default) — toggles the item you're moving FROM (macOS-style).
-     * - `'destination'` — toggles the item you're moving TO
-     *   (WAI-ARIA APG recommended model).
-     *
-     * Only affects Shift+Arrow keys; has no effect on Shift+Space,
-     * Shift+Click, or Ctrl+Shift+Home/End.
-     */
-    shiftArrowToggle?: "origin" | "destination";
-    /**
-     * Show focus ring on mouse click (default: false).
-     * By default, clicking an item selects it but does not show the focus
-     * ring — matching the web platform's :focus-visible convention.
-     * Set to true for file-manager or spreadsheet-style UIs where the
-     * focus indicator doubles as a "current item" marker.
-     */
-    focusOnClick?: boolean;
-    /**
-     * How right-click affects selection (default: 'select').
-     * - `'select'` — if the item is not selected, clear selection and select it;
-     *   if already selected, keep current selection (file explorer behavior).
-     * - `'keep'` — never change selection on right-click.
-     * - `false` — don't register a contextmenu handler at all.
-     */
-    contextMenu?: "select" | "keep" | false;
-}
-/**
- * Create a selection feature for the builder.
- *
- * ```ts
- * import { vlist } from 'vlist/builder'
- * import { withSelection } from 'vlist/selection'
- *
- * const list = vlist({ ... })
- *   .use(withSelection({ mode: 'multiple', initial: ['id-1'] }))
- *   .build()
- *
- * list.select('id-2')
- * list.getSelected() // ['id-1', 'id-2']
- * ```
- */
-export declare const withSelection: <T extends VListItem = VListItem>(config?: SelectionFeatureConfig) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,7 +0,0 @@
-/**
- * vlist - Selection Domain
- * Selection state management
- */
-export { withSelection, type SelectionFeatureConfig } from "./feature";
-export { createSelectionState, selectItems, deselectItems, toggleSelection, selectAll, clearSelection, setFocusedIndex, moveFocusUp, moveFocusDown, moveFocusToFirst, moveFocusToLast, moveFocusByPage, selectFocused, selectRange, getSelectedIds, getSelectedItems, getSelectionCount, isSelected, isSelectionEmpty, claimPlaceholderSelection, type SelectionState, } from "./state";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,79 +0,0 @@
-/**
- * vlist/snapshots - Builder Feature
- * Adds scroll save/restore for SPA navigation and tab switching.
- *
- * Priority: 50 (runs last — needs all other features initialized)
- *
- * What it wires:
- * - getScrollSnapshot() — captures current scroll position (item index + sub-pixel offset)
- * - restoreScroll() — restores scroll position from snapshot
- * - autoSave — automatically saves snapshots to sessionStorage on scroll idle
- *   and selection change, and auto-restores on next build()
- *
- * Snapshots capture the first visible item index and the pixel offset within
- * that item — not raw scrollTop. This means:
- * - Snapshots survive list recreation (navigate away and back)
- * - Snapshots work correctly with compression (1M+ items)
- * - Snapshots include selection state if selection is installed
- *
- * Added methods: getScrollSnapshot, restoreScroll
- *
- * Helper:
- * - getAutoSaveSnapshot(key) — read a saved snapshot from sessionStorage
- *   so that withAsync can derive `autoLoad` and `total` from it.
- */
-import type { VListItem, ScrollSnapshot } from "../../types";
-import type { VListFeature } from "../../builder/types";
-/** Configuration for the snapshots feature. */
-export interface SnapshotConfig {
-    /**
-     * Snapshot to restore automatically after `build()` completes.
-     *
-     * When provided, `restoreScroll(restore)` is scheduled via
-     * `queueMicrotask` — it runs right after `.build()` returns but
-     * before the browser paints, so the user never sees position 0.
-     *
-     * ```ts
-     * const saved = sessionStorage.getItem('scroll');
-     * const snapshot = saved ? JSON.parse(saved) : undefined;
-     *
-     * const list = vlist({ ... })
-     *   .use(withAsync({
-     *     adapter,
-     *     autoLoad: !snapshot,                 // skip autoLoad when restoring
-     *     total: snapshot?.total,              // from snapshot — no hardcoded constant needed
-     *   }))
-     *   .use(withSnapshots({ restore: snapshot })) // auto-restores after build()
-     *   .build();
-     * ```
-     */
-    restore?: ScrollSnapshot;
-    /**
-     * Automatically save and restore snapshots via sessionStorage.
-     *
-     * Pass a string key to enable — snapshots are saved to
-     * `sessionStorage` under that key whenever scroll becomes idle
-     * or selection changes. On the next `build()`, the snapshot is
-     * automatically restored if a matching key exists.
-     *
-     * This replaces the manual save/restore pattern — no event
-     * listeners, debounce timers, or sessionStorage calls needed.
-     *
-     * ```ts
-     * // That's it — save and restore are fully automatic:
-     * const list = vlist({ ... })
-     *   .use(withAsync({ adapter }))
-     *   .use(withSnapshots({ autoSave: 'my-list-scroll' }))
-     *   .build();
-     * ```
-     *
-     * When `autoSave` is set, the `restore` option is ignored —
-     * the saved snapshot is read from sessionStorage automatically.
-     * The `autoLoad` and `total` options on `withAsync` are also
-     * configured automatically (autoLoad is skipped when restoring,
-     * and total is read from the snapshot).
-     */
-    autoSave?: string;
-}
-export declare const withSnapshots: <T extends VListItem = VListItem>(config?: SnapshotConfig) => VListFeature<T>;
-//# sourceMappingURL=feature.d.ts.map

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

@@ -1,9 +0,0 @@
-/**
- * vlist/snapshots - Scroll Save/Restore
- * Feature for SPA navigation and tab switching
- *
- * Usage: import { withSnapshots } from 'vlist/snapshots'
- */
-export { withSnapshots } from "./feature";
-export type { SnapshotConfig } from "./feature";
-//# sourceMappingURL=index.d.ts.map