@floor/vlist 0.5.7 → 0.6.0

package/dist/features/sections/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/sections/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGjE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,aAAa,IAAI,eAAe,EAAE,MAAM,SAAS,CAAC;AAG1E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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 height function for the layout that returns the correct height
+ * for both group headers and data items.
+ *
+ * @param layout - The group layout instance
+ * @param itemHeight - Original item height config (number or function)
+ * @returns A height function (layoutIndex) => number suitable for HeightCache
+ */
+export declare const createGroupedHeightFn: (layout: GroupLayout, itemHeight: number | ((index: number) => number)) => ((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

package/dist/features/sections/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/features/sections/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EAEX,eAAe,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA+G7C;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,SAAS,EAClD,OAAO,CAAC,EAAE,EACV,QAAQ,SAAS,aAAa,EAAE,KAC/B,KAAK,CAAC,CAAC,GAAG,eAAe,CA0B3B,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,KAC/C,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAelC,CAAC;AAMF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,EACjB,QAAQ,YAAY,KACnB,WAkIF,CAAC"}

package/dist/features/sections/plugin.d.ts

@@ -0,0 +1,64 @@
+/**
+ * vlist/groups - Builder Plugin
+ * Adds grouped lists with sticky section 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
+ * - Cannot be combined with direction: 'horizontal'
+ *
+ * Can be combined with:
+ * - withGrid for grouped 2D layouts
+ * - reverse: true (sticky header shows current section as you scroll up through history)
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Groups plugin configuration */
+export interface GroupsPluginConfig {
+    /** Returns group key for item at index (required) */
+    getGroupForIndex: (index: number) => string;
+    /** Height of group headers in pixels (required) */
+    headerHeight: number;
+    /** Render function for headers (required) */
+    headerTemplate: (key: string, groupIndex: number) => HTMLElement | string;
+    /** Enable sticky headers — iOS Contacts style (default: true) */
+    sticky?: boolean;
+}
+/**
+ * Create a groups plugin for the builder.
+ *
+ * Adds grouped lists with sticky section headers.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withGroups } from 'vlist/groups'
+ *
+ * const contacts = vlist({
+ *   container: '#contacts',
+ *   item: { height: 56, template: renderContact },
+ *   items: sortedContacts,
+ * })
+ * .use(withGroups({
+ *   getGroupForIndex: (i) => sortedContacts[i].lastName[0],
+ *   headerHeight: 32,
+ *   headerTemplate: (letter) => {
+ *     const el = document.createElement('div')
+ *     el.className = 'letter-header'
+ *     el.textContent = letter
+ *     return el
+ *   },
+ * }))
+ * .build()
+ * ```
+ */
+export declare const withSections: <T extends VListItem = VListItem>(config: GroupsPluginConfig) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/sections/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/sections/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAuBvE,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAE5C,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,WAAW,GAAG,MAAM,CAAC;IAE1E,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAC1D,QAAQ,kBAAkB,KACzB,WAAW,CAAC,CAAC,CAmRf,CAAC"}

package/dist/features/sections/sticky.d.ts

@@ -0,0 +1,33 @@
+/**
+ * vlist - Sticky Header
+ * Manages a floating header element that "sticks" to the top of the viewport
+ * and transitions smoothly when the next group's header approaches.
+ *
+ * The sticky header is a separate DOM element positioned absolutely at the
+ * top of the root container. It overlays the scrolling content and shows
+ * the current group's header. When the next group's inline header scrolls
+ * into view, the sticky header is pushed upward to create the classic
+ * iOS Contacts-style transition effect.
+ *
+ * Layout:
+ *   .vlist (root, position: relative)
+ *   ├── .vlist-sticky-header (position: absolute, top: 0, z-index: 5)
+ *   │   └── (content rendered by headerTemplate)
+ *   └── .vlist-viewport
+ *       └── .vlist-content
+ *           └── .vlist-items
+ */
+import type { GroupLayout, GroupsConfig, StickyHeader } from "./types";
+import type { HeightCache } from "../../rendering/heights";
+/**
+ * Create a sticky header manager.
+ *
+ * @param root - The vlist root element (.vlist) — sticky header is appended here
+ * @param layout - Group layout for index/group resolution
+ * @param heightCache - The LAYOUT height cache (includes headers)
+ * @param config - Groups configuration (headerTemplate, headerHeight)
+ * @param classPrefix - CSS class prefix (default: 'vlist')
+ * @returns StickyHeader instance
+ */
+export declare const createStickyHeader: (root: HTMLElement, layout: GroupLayout, heightCache: HeightCache, config: GroupsConfig, classPrefix: string) => StickyHeader;
+//# sourceMappingURL=sticky.d.ts.map

package/dist/features/sections/sticky.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticky.d.ts","sourceRoot":"","sources":["../../../src/features/sections/sticky.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,WAAW,EACjB,QAAQ,WAAW,EACnB,aAAa,WAAW,EACxB,QAAQ,YAAY,EACpB,aAAa,MAAM,KAClB,YAgMF,CAAC"}

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

@@ -0,0 +1,86 @@
+/**
+ * vlist - Group Types
+ * Types for sticky headers and grouped lists
+ */
+import type { VListItem, GroupsConfig } from "../../types";
+export type { GroupsConfig };
+/** A single group boundary */
+export interface GroupBoundary {
+    /** Group key (return value of getGroupForIndex) */
+    key: string;
+    /** Sequential group index (0-based) */
+    groupIndex: number;
+    /** Layout index of this group's header */
+    headerLayoutIndex: number;
+    /** Data index of the first item in this group */
+    firstDataIndex: number;
+    /** Number of data items in this group */
+    count: number;
+}
+/** Entry type in the layout — either a group header or a data item */
+export type LayoutEntry = {
+    type: "header";
+    group: GroupBoundary;
+} | {
+    type: "item";
+    dataIndex: number;
+    group: GroupBoundary;
+};
+/**
+ * Internal marker for group header pseudo-items inserted into the layout.
+ * These are interleaved with real data items in the transformed items array.
+ */
+export interface GroupHeaderItem extends VListItem {
+    /** Always `__group_header_{groupIndex}` */
+    id: string;
+    /** Discriminator flag */
+    __groupHeader: true;
+    /** The group key */
+    groupKey: string;
+    /** Sequential group index (0-based) */
+    groupIndex: number;
+}
+/**
+ * Type guard: check if an item is a group header pseudo-item
+ */
+export declare const isGroupHeader: (item: unknown) => item is GroupHeaderItem;
+/** Group layout — maps between data indices and layout indices */
+export interface GroupLayout {
+    /** Total layout entries (data items + group headers) */
+    readonly totalEntries: number;
+    /** Number of groups */
+    readonly groupCount: number;
+    /** All group boundaries, in order */
+    readonly groups: readonly GroupBoundary[];
+    /** Get the layout entry at a layout index — O(log g) */
+    getEntry: (layoutIndex: number) => LayoutEntry;
+    /** Map layout index → data index, or -1 if it's a header — O(log g) */
+    layoutToDataIndex: (layoutIndex: number) => number;
+    /** Map data index → layout index — O(log g) */
+    dataToLayoutIndex: (dataIndex: number) => number;
+    /** Get the group boundary that contains a given layout index — O(log g) */
+    getGroupAtLayoutIndex: (layoutIndex: number) => GroupBoundary;
+    /** Get the group boundary that contains a given data index — O(log g) */
+    getGroupAtDataIndex: (dataIndex: number) => GroupBoundary;
+    /** Get header height for a group */
+    getHeaderHeight: (groupIndex: number) => number;
+    /**
+     * Rebuild the layout from scratch.
+     * Call when items change (setItems, append, prepend, remove, etc.)
+     */
+    rebuild: (itemCount: number) => void;
+}
+/** Sticky header manager */
+export interface StickyHeader {
+    /** Update sticky header position and content based on scroll position */
+    update: (scrollTop: number) => void;
+    /** Force refresh the sticky header content (e.g. after items change) */
+    refresh: () => void;
+    /** Show the sticky header */
+    show: () => void;
+    /** Hide the sticky header */
+    hide: () => void;
+    /** Destroy and remove the sticky header DOM element */
+    destroy: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/sections/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/sections/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3D,YAAY,EAAE,YAAY,EAAE,CAAC;AAM7B,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IAEZ,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAE1B,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IAEvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IAEX,yBAAyB;IACzB,aAAa,EAAE,IAAI,CAAC;IAEpB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,eAMrD,CAAC;AAMF,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,uBAAuB;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAE1C,wDAAwD;IACxD,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,WAAW,CAAC;IAE/C,uEAAuE;IACvE,iBAAiB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;IAEnD,+CAA+C;IAC/C,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEjD,2EAA2E;IAC3E,qBAAqB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,aAAa,CAAC;IAE9D,yEAAyE;IACzE,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,aAAa,CAAC;IAE1D,oCAAoC;IACpC,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAEhD;;;OAGG;IACH,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAMD,4BAA4B;AAC5B,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC,wEAAwE;IACxE,OAAO,EAAE,MAAM,IAAI,CAAC;IAEpB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/selection/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGrE,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,SAAS,EACT,cAAc,EACd,eAAe,EACf,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC"}

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

@@ -0,0 +1,44 @@
+/**
+ * vlist/selection - Builder Plugin
+ * Wraps the selection domain into a VListPlugin for the composable builder.
+ *
+ * Priority: 50 (runs after renderer and data are ready)
+ *
+ * What it wires:
+ * - Click handler on items container — toggles selection on item click
+ * - Keyboard handler on root — ArrowUp/Down for focus, Space/Enter for toggle
+ * - ARIA attributes — aria-selected on items, aria-activedescendant on root
+ * - Live region — announces selection changes to screen readers
+ * - Render integration — passes selection state to render pipeline
+ *
+ * Added methods: select, deselect, toggleSelect, selectAll, clearSelection,
+ *                getSelected, getSelectedItems
+ *
+ * Added events: item:click, selection:change
+ */
+import type { VListItem, SelectionMode } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Selection plugin configuration */
+export interface SelectionPluginConfig {
+    /** Selection mode (default: 'single') */
+    mode?: SelectionMode;
+    /** Initially selected item IDs */
+    initial?: Array<string | number>;
+}
+/**
+ * Create a selection plugin 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?: SelectionPluginConfig) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/selection/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/selection/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAwBvE,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,IAAI,CAAC,EAAE,aAAa,CAAC;IAErB,kCAAkC;IAClC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAClC;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAC3D,SAAS,qBAAqB,KAC7B,WAAW,CAAC,CAAC,CAwWf,CAAC"}

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

@@ -0,0 +1,102 @@
+/**
+ * vlist - Selection State Management
+ * Pure functions for managing selection state
+ */
+import type { VListItem, SelectionMode, SelectionState } from "../../types";
+export type { SelectionState } from "../../types";
+/**
+ * Create initial selection state
+ * Pure function - no side effects
+ */
+export declare const createSelectionState: (initial?: Array<string | number>) => SelectionState;
+/**
+ * Select items by ID
+ * Pure function - returns new state
+ */
+export declare const selectItems: (state: SelectionState, ids: Array<string | number>, mode: SelectionMode) => SelectionState;
+/**
+ * Deselect items by ID
+ * Pure function - returns new state
+ */
+export declare const deselectItems: (state: SelectionState, ids: Array<string | number>) => SelectionState;
+/**
+ * Toggle item selection
+ * Pure function - returns new state
+ */
+export declare const toggleSelection: (state: SelectionState, id: string | number, mode: SelectionMode) => SelectionState;
+/**
+ * Select all items
+ * Pure function - returns new state
+ */
+export declare const selectAll: <T extends VListItem>(state: SelectionState, items: T[], mode: SelectionMode) => SelectionState;
+/**
+ * Clear all selection
+ * Pure function - returns new state
+ */
+export declare const clearSelection: (state: SelectionState) => SelectionState;
+/**
+ * Set focused index
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const setFocusedIndex: (state: SelectionState, index: number) => SelectionState;
+/**
+ * Move focus up
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const moveFocusUp: (state: SelectionState, totalItems: number, wrap?: boolean) => SelectionState;
+/**
+ * Move focus down
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const moveFocusDown: (state: SelectionState, totalItems: number, wrap?: boolean) => SelectionState;
+/**
+ * Move focus to first item
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const moveFocusToFirst: (state: SelectionState, totalItems: number) => SelectionState;
+/**
+ * Move focus to last item
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const moveFocusToLast: (state: SelectionState, totalItems: number) => SelectionState;
+/**
+ * Move focus by page (for Page Up/Down)
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export declare const moveFocusByPage: (state: SelectionState, totalItems: number, pageSize: number, direction: "up" | "down") => SelectionState;
+/**
+ * Check if an item is selected
+ * Pure function - no side effects
+ */
+export declare const isSelected: (state: SelectionState, id: string | number) => boolean;
+/**
+ * Get selected IDs as array
+ * Pure function - no side effects
+ */
+export declare const getSelectedIds: (state: SelectionState) => Array<string | number>;
+/**
+ * Get selected items using ID lookup (O(k) where k = selected count)
+ * Pure function - no side effects
+ */
+export declare const getSelectedItems: <T extends VListItem>(state: SelectionState, getItemById: (id: string | number) => T | undefined) => T[];
+/**
+ * Get selection count
+ * Pure function - no side effects
+ */
+export declare const getSelectionCount: (state: SelectionState) => number;
+/**
+ * Check if selection is empty
+ * Pure function - no side effects
+ */
+export declare const isSelectionEmpty: (state: SelectionState) => boolean;
+/**
+ * Handle keyboard selection (Space/Enter on focused item)
+ * Pure function - returns new state
+ */
+export declare const selectFocused: <T extends VListItem>(state: SelectionState, items: T[], mode: SelectionMode) => SelectionState;
+/**
+ * Handle shift+click range selection
+ * Pure function - returns new state
+ */
+export declare const selectRange: <T extends VListItem>(state: SelectionState, items: T[], fromIndex: number, toIndex: number, mode: SelectionMode) => SelectionState;
+//# sourceMappingURL=state.d.ts.map

package/dist/features/selection/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/features/selection/state.ts"],"names":[],"mappings":"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"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/snapshots/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

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

@@ -0,0 +1,44 @@
+/**
+ * vlist/snapshots - Builder Plugin
+ * Adds scroll save/restore for SPA navigation and tab switching.
+ *
+ * Priority: 50 (runs last — needs all other plugins initialized)
+ *
+ * What it wires:
+ * - getScrollSnapshot() — captures current scroll position (item index + sub-pixel offset)
+ * - restoreScroll() — restores scroll position from snapshot
+ *
+ * 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
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/**
+ * Create a snapshots plugin for the builder.
+ *
+ * Adds scroll save/restore for SPA navigation and tab switching.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withSnapshots } from 'vlist/snapshots'
+ *
+ * const list = vlist({ ... })
+ *   .use(withSnapshots())
+ *   .build()
+ *
+ * // Save before navigating away
+ * const snapshot = list.getScrollSnapshot()
+ * sessionStorage.setItem('list-scroll', JSON.stringify(snapshot))
+ *
+ * // Restore when coming back
+ * const saved = JSON.parse(sessionStorage.getItem('list-scroll'))
+ * if (saved) list.restoreScroll(saved)
+ * ```
+ */
+export declare const withSnapshots: <T extends VListItem = VListItem>() => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/snapshots/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/snapshots/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,aAAa,GACxB,CAAC,SAAS,SAAS,GAAG,SAAS,OAC5B,WAAW,CAAC,CAAC,CA8FjB,CAAC"}