vlist 0.1.3 → 1.5.4

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

@@ -0,0 +1,73 @@
+/**
+ * vlist - Custom Scrollbar
+ * Provides visual scroll indication for compressed mode where native scrollbar is hidden
+ *
+ * Features:
+ * - Visual track and thumb
+ * - Thumb size proportional to visible content
+ * - Click on track to jump to position
+ * - Drag thumb to scroll
+ * - Auto-hide after idle (optional)
+ * - Show on hover with configurable hover zone (optional)
+ * - CSS variables for customization
+ * - Horizontal mode support (direction-aware axis)
+ */
+/** Scrollbar configuration */
+export interface ScrollbarConfig {
+    /** Enable scrollbar (default: true when compressed) */
+    enabled?: boolean;
+    /** 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.
+     * Moving the mouse into this zone reveals the scrollbar; it stays visible
+     * as long as the cursor remains over the zone or the track.
+     */
+    showOnHover?: boolean;
+    /**
+     * Width of the invisible hover zone in pixels (default: 16).
+     * Only used when `showOnHover` is true.
+     * A wider zone makes the scrollbar easier to discover;
+     * a narrower zone avoids interference with content near the edge.
+     */
+    hoverZoneWidth?: number;
+    /**
+     * Show scrollbar when the mouse enters the list viewport (default: true).
+     * When false, the scrollbar only appears on scroll or when hovering
+     * near the scrollbar edge (if `showOnHover` is true).
+     */
+    showOnViewportEnter?: boolean;
+}
+/** Scrollbar instance */
+export interface Scrollbar {
+    /** Show the scrollbar */
+    show: () => void;
+    /** Hide the scrollbar */
+    hide: () => void;
+    /** Update scrollbar dimensions based on content/container size */
+    updateBounds: (totalHeight: number, containerHeight: number) => void;
+    /** Update thumb position based on scroll position */
+    updatePosition: (scrollTop: number) => void;
+    /** Check if scrollbar is visible */
+    isVisible: () => boolean;
+    /** Destroy and cleanup */
+    destroy: () => void;
+}
+/** Callback for scroll position changes */
+export type ScrollCallback = (position: number) => void;
+/**
+ * Create a scrollbar instance
+ *
+ * @param viewport - The viewport element to attach scrollbar to
+ * @param onScroll - Callback when scrollbar interaction causes scroll
+ * @param config - Scrollbar configuration
+ * @param classPrefix - CSS class prefix (default: 'vlist')
+ * @param horizontal - Whether the scrollbar is horizontal (default: false)
+ */
+export declare const createScrollbar: (viewport: HTMLElement, onScroll: ScrollCallback, config?: ScrollbarConfig, classPrefix?: string, horizontal?: boolean) => Scrollbar;
+//# sourceMappingURL=scrollbar.d.ts.map

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

@@ -0,0 +1,75 @@
+/**
+ * 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";
+}
+/**
+ * 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

@@ -0,0 +1,7 @@
+/**
+ * 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/selection/state.d.ts

@@ -0,0 +1,115 @@
+/**
+ * vlist - Selection State Management
+ * Pure functions for managing selection state
+ */
+import type { VListItem, SelectionMode, SelectionState } from "../../types";
+export type { SelectionState } from "../../types";
+/**
+ * Transfer selection from a placeholder ID to a real item ID.
+ *
+ * When select-all or shift-click ranges include unloaded async items, the
+ * selection Set contains index-based placeholder IDs (`__placeholder_{index}`).
+ * When those items load, this function swaps the placeholder entry for the
+ * real item ID so the item renders as selected.
+ *
+ * @returns `true` if a transfer occurred (the item was selected via its placeholder).
+ */
+export declare const claimPlaceholderSelection: (selectedIds: Set<string | number>, index: number, itemId: string | number) => boolean;
+/**
+ * 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
+ * @param delta - Number of items to move by (default 1). Useful for grid layouts where row navigation moves by `columns`.
+ */
+export declare const moveFocusUp: (state: SelectionState, totalItems: number, wrap?: boolean, delta?: number) => SelectionState;
+/**
+ * Move focus down
+ * Mutates state in-place to avoid allocation on hot path
+ * @param delta - Number of items to move by (default 1). Useful for grid layouts where row navigation moves by `columns`.
+ */
+export declare const moveFocusDown: (state: SelectionState, totalItems: number, wrap?: boolean, delta?: number) => 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/snapshots/feature.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * 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

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

@@ -0,0 +1,67 @@
+/**
+ * vlist/table - Builder Feature
+ * Switches from list layout to a data table with columns, resizable headers,
+ * sticky header row, and cell-based rendering.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it wires:
+ * - Replaces render functions — swaps the core render loop with table-aware rendering
+ * - Sticky header — creates a fixed header row above the viewport
+ * - Column layout — manages column widths, offsets, and resize logic
+ * - Resize interaction — drag handles on header column borders
+ * - Sort events — click on sortable header emits column:sort
+ * - Horizontal scroll sync — header scrolls in sync with the viewport
+ * - CSS class — adds .vlist--table to the root element
+ * - Variable row heights — supports fixed and function-based heights
+ *
+ * Critical design: This feature uses ctx.setRenderFns() to completely replace
+ * the core's render loop, NOT ctx.replaceRenderer() which is a no-op in the
+ * materialize context. This follows the same pattern as withGrid.
+ *
+ * Restrictions:
+ * - Cannot be combined with withGrid or withMasonry (conflicting layout modes)
+ * - Cannot be combined with orientation: 'horizontal' (tables are always vertical)
+ *
+ * Can be combined with:
+ * - withSelection (row selection works as-is)
+ * - withScrollbar (custom scrollbar)
+ * - withAsync (async data loading)
+ * - withSnapshots (scroll position save/restore)
+ * - withScale (large dataset compression)
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+import type { TableConfig } from "./types";
+/** Table feature configuration — re-exported as TableFeatureConfig */
+export type TableFeatureConfig<T extends VListItem = VListItem> = TableConfig<T>;
+/**
+ * Create a table feature for the builder.
+ *
+ * Switches from list layout to a data table with column headers, resizable
+ * columns, and cell-based row rendering.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withTable } from 'vlist/table'
+ *
+ * const table = vlist({
+ *   container: '#my-table',
+ *   item: { height: 40, template: () => '' },
+ *   items: users,
+ * })
+ * .use(withTable({
+ *   columns: [
+ *     { key: 'name',   label: 'Name',   width: 200 },
+ *     { key: 'email',  label: 'Email',  width: 300 },
+ *     { key: 'role',   label: 'Role',   width: 120 },
+ *   ],
+ *   rowHeight: 40,
+ *   headerHeight: 44,
+ *   resizable: true,
+ * }))
+ * .build()
+ * ```
+ */
+export declare const withTable: <T extends VListItem = VListItem>(config: TableFeatureConfig<T>) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/table/header.d.ts

@@ -0,0 +1,49 @@
+/**
+ * vlist/table - Header
+ * Manages the sticky header row that sits above the scrolling viewport.
+ *
+ * The header is a positioned DOM element inserted into the vlist root
+ * container (above the viewport, like the sticky group header). It contains
+ * one cell per column, each showing the column label. Resize handles are
+ * rendered at the right edge of each resizable column's header cell.
+ *
+ * Layout:
+ *   .vlist (root, position: relative)
+ *   ├── .vlist-table-header (position: absolute, top: 0, z-index: 5)
+ *   │   ├── .vlist-table-header-cell [col 0]
+ *   │   │   ├── .vlist-table-header-content (label)
+ *   │   │   ├── .vlist-table-header-sort (sort indicator)
+ *   │   │   └── .vlist-table-header-resize (drag handle)
+ *   │   ├── .vlist-table-header-cell [col 1]
+ *   │   │   └── ...
+ *   │   └── ...
+ *   └── .vlist-viewport (scrollable, top offset by headerHeight)
+ *
+ * Resize interaction:
+ *   mousedown on handle → pointermove updates column width → pointerup commits
+ *   During drag, a class is added to the root for cursor override.
+ *
+ * Sort interaction:
+ *   click on a sortable header cell emits column:sort via the provided callback.
+ *   The header renders a visual indicator (▲/▼) for the active sort column.
+ *
+ * Horizontal scroll sync:
+ *   The header's scrollLeft is kept in sync with the viewport's scrollLeft
+ *   via the `syncScroll` method, called from the feature's afterScroll hook.
+ */
+import type { VListItem } from "../../types";
+import type { TableHeader, ColumnSortEvent, ColumnClickEvent } from "./types";
+/**
+ * Create a TableHeader instance.
+ *
+ * @param root - The vlist root element (.vlist)
+ * @param viewport - The vlist viewport element (for scroll sync)
+ * @param headerHeight - Height of the header row in pixels
+ * @param classPrefix - CSS class prefix (default: 'vlist')
+ * @param onResize - Callback when a column is resized (receives column index and new width)
+ * @param onSort - Callback when a sortable header is clicked
+ * @param onClick - Callback when any header cell is clicked
+ * @returns TableHeader instance
+ */
+export declare const createTableHeader: <T extends VListItem = VListItem>(root: HTMLElement, viewport: HTMLElement, headerHeight: number, classPrefix: string, onResize: (columnIndex: number, newWidth: number) => void, onSort?: (event: ColumnSortEvent) => void, onClick?: (event: ColumnClickEvent) => void) => TableHeader<T>;
+//# sourceMappingURL=header.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * vlist - Table Domain
+ * Data table layout with columns, resizable headers, and cell rendering
+ */
+export { withTable, type TableFeatureConfig } from "./feature";
+export { createTableLayout } from "./layout";
+export { createTableHeader } from "./header";
+export { createTableRenderer, type TableRendererInstance } from "./renderer";
+export type { TableConfig, TableColumn, TableLayout, TableHeader, TableRenderer, ResolvedColumn, ColumnResizeEvent, ColumnSortEvent, ColumnClickEvent, } from "./types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * vlist/table - Layout
+ * Manages column widths, offsets, and resize operations.
+ *
+ * Column width resolution strategy:
+ * 1. Columns with explicit `width` get their requested width (clamped to min/max)
+ * 2. Remaining container space is distributed equally among columns without `width`
+ * 3. If all columns have explicit widths and total < container, no stretching occurs
+ * 4. If total column width > container, the table scrolls horizontally
+ *
+ * All offset calculations are O(n) where n = number of columns (typically small).
+ * Resize operations recalculate offsets for columns after the resized one.
+ */
+import type { VListItem } from "../../types";
+import type { TableColumn, TableLayout } from "./types";
+/**
+ * Create a TableLayout instance.
+ *
+ * @param columnDefs - Column definitions from config
+ * @param globalMinWidth - Default min column width (from TableConfig.minColumnWidth)
+ * @param globalMaxWidth - Default max column width (from TableConfig.maxColumnWidth)
+ * @param globalResizable - Default resizable flag (from TableConfig.resizable)
+ * @returns TableLayout with column resolution and resize capabilities
+ */
+export declare const createTableLayout: <T extends VListItem = VListItem>(columnDefs: TableColumn<T>[], globalMinWidth?: number, globalMaxWidth?: number, globalResizable?: boolean) => TableLayout<T>;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1,72 @@
+/**
+ * vlist/table - Renderer
+ * Renders virtualized rows with cell-based layout within the virtual scroll container.
+ *
+ * Each row is an absolutely positioned element (like the list renderer),
+ * containing child elements for each cell. Cells are sized and positioned
+ * according to the resolved column layout from TableLayout.
+ *
+ * Key design decisions:
+ * - Rows are the unit of virtualization (same as list mode — 1:1 with items)
+ * - Each row contains N cell elements (one per column)
+ * - Row positioning is translateY-based (from the size cache)
+ * - Cell positioning uses absolute left + width from the column layout
+ * - Element pooling avoids createElement cost (row-level pooling)
+ * - Change tracking skips template re-evaluation when data + state unchanged
+ * - Release grace period prevents boundary thrashing (hover blink, transition replay)
+ * - DocumentFragment batched insertion for new elements
+ *
+ * Performance:
+ * - O(1) Set-based visibility diffing (not O(n) .some())
+ * - Template re-evaluation skipped when item id + selection/focus state unchanged
+ * - Position update skipped when coordinates unchanged (position tracking)
+ * - Cell widths are only updated when column layout changes (not every scroll frame)
+ * - Released elements removed from DOM immediately, pooled for reuse
+ *
+ * DOM structure per row:
+ *   .vlist-item.vlist-table-row (position: absolute, translateY)
+ *   ├── .vlist-table-cell [col 0] (position: absolute, left, width)
+ *   ├── .vlist-table-cell [col 1]
+ *   └── ...
+ */
+import type { VListItem, Range } from "../../types";
+import type { SizeCache } from "../../rendering/sizes";
+import type { CompressionContext } from "../../rendering/renderer";
+import type { TableLayout, TableColumn } from "./types";
+/** Table renderer instance */
+export interface TableRendererInstance<T extends VListItem = VListItem> {
+    /** Render rows for a range, with cell-based layout */
+    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 row (e.g., after selection change) */
+    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
+    /** Update only CSS classes on a rendered row */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /** Get rendered row element by item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /** Update cell positions and widths after column resize */
+    updateColumnLayout: (layout: TableLayout<T>) => void;
+    /** Set the group header check function (called by withGroups integration) */
+    setGroupHeaderFn: (fn: ((item: T) => boolean) | null, template: ((key: string, groupIndex: number) => HTMLElement | string) | null) => void;
+    /** Clear all rendered rows */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a TableRenderer instance.
+ *
+ * @param container - The .vlist-items container element
+ * @param sizeCache - Size cache for row offset lookups
+ * @param layout - Table layout for column widths/offsets
+ * @param columns - Column definitions (for cell templates)
+ * @param classPrefix - CSS class prefix
+ * @param ariaIdPrefix - Prefix for ARIA IDs
+ * @param columnBorders - Whether to show vertical borders between cells
+ * @param rowBorders - Whether to show horizontal borders between rows
+ * @param getTotalItems - Function to get total item count (for ARIA)
+ * @returns TableRendererInstance
+ */
+export declare const createTableRenderer: <T extends VListItem = VListItem>(container: HTMLElement, getSizeCache: () => SizeCache, layout: TableLayout<T>, _columns: TableColumn<T>[], classPrefix: string, ariaIdPrefix: string, getTotalItems: () => number, striped?: boolean | "data" | "even" | "odd", stripeIndexFn?: () => (index: number) => number) => TableRendererInstance<T>;
+//# sourceMappingURL=renderer.d.ts.map