vlist 2.2.0 → 2.4.0

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

@@ -0,0 +1,84 @@
+/**
+ * vlist — Search Plugin (RFC-008, Phase 1)
+ *
+ * A ready-to-use search bar with client-side filtering, match navigation, and
+ * `<mark>` highlighting. Operates at the data layer (no `setRenderFn`), so it
+ * composes with any layout.
+ *
+ * - **filter** mode (default): virtually hides non-matching items via
+ *   `setGetItemFn` + `setVirtualTotalFn` (non-destructive — clear restores).
+ * - **navigate** mode: keeps all items, scrolls between matches, highlights
+ *   the current one.
+ *
+ * Phase 2 (server-side search via `data()`, column-aware, fuzzy, query syntax)
+ * is out of scope here.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+import { type FieldAccessor } from "./match";
+/**
+ * Consumer-facing UI text for the search bar (RFC-010 — Externalized UI Text).
+ * This is the plugin's entire human-language surface: static accessible names
+ * plus the dynamic counter formatters. All fields are optional; unset fields
+ * fall back to {@link DEFAULT_SEARCH_TEXT} (English). Consumers localizing for a
+ * non-English document should override these *and* set `lang` on the page.
+ */
+export interface SearchText {
+    /** Input placeholder + accessible name. */
+    placeholder?: string;
+    /** Accessible name for the clear (×) button. */
+    clear?: string;
+    /** Accessible name for the previous-match button (navigate mode). */
+    previous?: string;
+    /** Accessible name for the next-match button (navigate mode). */
+    next?: string;
+    /** Counter text when there are no matches. */
+    noResults?: string;
+    /** Counter text in filter mode — total match count. */
+    results?: (count: number) => string;
+    /** Counter text in navigate mode — current position within matches. */
+    position?: (current: number, total: number) => string;
+    /** Accessible name for the `role="search"` landmark. Unnamed when omitted. */
+    region?: string;
+}
+/**
+ * Default English UI text for the search plugin. The single, documented,
+ * fully-overridable language surface (RFC-010): the only place human-readable
+ * strings live in the library.
+ */
+export declare const DEFAULT_SEARCH_TEXT: Required<SearchText>;
+export interface SearchPluginConfig<T extends VListItem = VListItem> {
+    /** Hide non-matching items ("filter") or jump between matches ("navigate"). Default "filter". */
+    mode?: "filter" | "navigate";
+    /** Where to place the search bar. "none" = invisible, keyboard-only. Default "top". */
+    position?: "top" | "bottom" | "none";
+    /** Field(s) to search — a property key, accessor, or (default) all string values. */
+    field?: FieldAccessor<T>;
+    /** Case-sensitive matching. Default false. */
+    caseSensitive?: boolean;
+    /**
+     * Highlight matched substrings in rendered rows by wrapping them in
+     * `<mark class="{prefix}-search-match">`. Default `true`.
+     *
+     * - `false` — disable highlighting.
+     * - `{ within }` — restrict highlighting to descendants matching the CSS
+     *   selector (e.g. `".person__name"`) instead of the whole row. Useful when
+     *   the query can coincidentally appear in fields you didn't search.
+     */
+    highlight?: boolean | {
+        within?: string;
+    };
+    /** Minimum query length to trigger search. Default 1. */
+    minLength?: number;
+    /** Auto-close the search bar after N ms of inactivity (0 = never). Default 0. */
+    cancelTimeout?: number;
+    /** Visual style of the search bar. `"md3"` applies a Material Design 3 pill
+     *  (requires the search stylesheet). Default `"default"`. */
+    variant?: "default" | "md3";
+    /** Consumer-supplied UI text / localization. Falls back to {@link DEFAULT_SEARCH_TEXT}. */
+    text?: SearchText;
+}
+export interface SearchPluginInstance<T extends VListItem = VListItem> extends VListPlugin<T> {
+}
+export declare function search<T extends VListItem = VListItem>(config?: SearchPluginConfig<T>): SearchPluginInstance<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/search/searchbar.d.ts

@@ -0,0 +1,57 @@
+/**
+ * vlist/search — Search bar DOM
+ *
+ * A modular, MD3-aligned structure (mirrors mtrl `_search.scss`):
+ *
+ *   .{p}-search .{p}-search--bar .{p}-search--{top|bottom}   (role="search")
+ *   └── .{p}-search__container
+ *       ├── span.{p}-search__leading-icon       (magnifier — decorative)
+ *       ├── .{p}-search__input-wrapper
+ *       │   └── input.{p}-search__input
+ *       ├── span.{p}-search__counter              (match count — empty when idle)
+ *       ├── button.{p}-search__nav-prev           (navigate mode only)
+ *       ├── button.{p}-search__nav-next           (navigate mode only)
+ *       └── button.{p}-search__clear-button       (--hidden when empty)
+ *
+ * Per RFC-010, the bar carries no inline human-language text: all accessible
+ * names come from the `text` parameter (consumer-supplied, with English
+ * defaults resolved in the plugin). The leading magnifier is decorative
+ * (`aria-hidden`, not focusable, no accessible name) — the input is the
+ * meaningful control. The `role="search"` landmark is unnamed unless the
+ * consumer passes `text.region`.
+ *
+ * Invisible mode (`position: "none"`) renders no bar — the plugin drives the
+ * query from keystrokes only.
+ */
+export interface SearchBarCallbacks {
+    onInput(value: string): void;
+    onClear(): void;
+    onPrev(): void;
+    onNext(): void;
+    /** Forwarded keydown from the input (Enter / Escape / arrows). */
+    onKeydown(event: KeyboardEvent): void;
+}
+/**
+ * Resolved accessible names for the bar (consumer-supplied via the plugin's
+ * `text` config; the plugin fills English defaults). `region` is `""` when the
+ * search landmark should stay unnamed (the default).
+ */
+export interface SearchBarText {
+    placeholder: string;
+    clear: string;
+    previous: string;
+    next: string;
+    region: string;
+}
+export interface SearchBar {
+    readonly root: HTMLElement;
+    readonly input: HTMLInputElement;
+    setCounter(text: string): void;
+    /** Show/hide the prev/next buttons (navigate mode only). */
+    showNav(show: boolean): void;
+    focus(): void;
+    setValue(value: string): void;
+    destroy(): void;
+}
+export declare const createSearchBar: (parent: HTMLElement, before: HTMLElement | null, classPrefix: string, position: "top" | "bottom", text: SearchBarText, listId: string | undefined, cb: SearchBarCallbacks) => SearchBar;
+//# sourceMappingURL=searchbar.d.ts.map

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

@@ -11,6 +11,13 @@ export interface SelectionPluginConfig {
     initial?: Array<string | number>;
     followFocus?: boolean;
     focusOnClick?: boolean;
+    /**
+     * Whether this plugin handles arrow/Home/End/PageUp-Down/Enter/Space
+     * keyboard navigation. Default true. Set false to keep click-selection and
+     * the selection model while letting an outer system own keyboard navigation
+     * (e.g. a global, focus-independent hotkey layer).
+     */
+    keyboard?: boolean;
 }
 export declare function selection<T extends VListItem = VListItem>(config?: SelectionPluginConfig): VListPlugin<T>;
 //# sourceMappingURL=plugin.d.ts.map

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

@@ -31,14 +31,11 @@
  */
 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;
+    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number) => 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 */
@@ -68,5 +65,5 @@ export interface TableRendererInstance<T extends VListItem = VListItem> {
  * @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>;
+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, getBaseOffset?: () => number) => TableRendererInstance<T>;
 //# sourceMappingURL=renderer.d.ts.map

package/dist/rendering/index.d.ts

@@ -1,12 +1,7 @@
 /**
  * vlist - Rendering Domain
- * Rendering, virtualization, and scaling for large datasets
+ * Size cache and DOM sorting shared by the core engine and layout plugins.
  */
 export { createSizeCache, countVisibleItems, countItemsFittingFromBottom, getOffsetForVirtualIndex, type SizeCache, } from "./sizes";
-export { createMeasuredSizeCache, type MeasuredSizeCache, } from "./measured";
 export { sortRenderedDOM } from "./sort";
-export { createRenderer, createDOMStructure, updateContentHeight, updateContentWidth, resolveContainer, getContainerDimensions, type Renderer, type DOMStructure, type CompressionContext, type CompressedPositionFn, type CompressionStateFn, } from "./renderer";
-export { createViewportState, updateViewportState, updateViewportSize, updateViewportItems, calculateRenderRange, calculateTotalSize, calculateActualSize, calculateItemOffset, calculateScrollToIndex, clampScrollPosition, getScrollDirection, rangesEqual, isInRange, getRangeCount, rangeToIndices, diffRanges, getSimpleCompressionState, simpleVisibleRange, simpleScrollToIndex, NO_COMPRESSION, type CompressionState, type VisibleRangeFn, type ScrollToIndexFn, } from "./viewport";
-export { MAX_VIRTUAL_SIZE, getCompressionState, getCompressionState as getCompression, needsCompression, getMaxItemsWithoutCompression, getCompressionInfo, calculateCompressedVisibleRange, calculateCompressedRenderRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, calculateIndexFromScrollPosition, } from "./scale";
-export { scrollToFocus, scrollToFocusSimple, } from "./scroll";
 //# sourceMappingURL=index.d.ts.map

package/dist/size.json

@@ -1 +1 @@
-{"base":{"minified":"22.2","gzipped":"8.2","minBytes":22725,"gzBytes":8357},"a11y":{"minified":"25.2","gzipped":"9.3","minBytes":25848,"gzBytes":9486},"selection":{"minified":"30.8","gzipped":"10.7","minBytes":31532,"gzBytes":10910},"data":{"minified":"35.8","gzipped":"13.0","minBytes":36694,"gzBytes":13294},"scrollbar":{"minified":"29.3","gzipped":"10.2","minBytes":30038,"gzBytes":10423},"sortable":{"minified":"31.6","gzipped":"11.1","minBytes":32330,"gzBytes":11320},"groups":{"minified":"37.7","gzipped":"13.4","minBytes":38615,"gzBytes":13682},"scale":{"minified":"35.5","gzipped":"12.1","minBytes":36357,"gzBytes":12383},"page":{"minified":"24.6","gzipped":"8.9","minBytes":25211,"gzBytes":9146},"snapshots":{"minified":"25.9","gzipped":"9.4","minBytes":26486,"gzBytes":9663},"transition":{"minified":"29.0","gzipped":"10.0","minBytes":29660,"gzBytes":10236},"autosize":{"minified":"24.6","gzipped":"9.0","minBytes":25208,"gzBytes":9241},"grid":{"minified":"30.5","gzipped":"11.1","minBytes":31230,"gzBytes":11320},"table":{"minified":"41.7","gzipped":"14.4","minBytes":42719,"gzBytes":14765},"masonry":{"minified":"32.4","gzipped":"11.9","minBytes":33172,"gzBytes":12141},"tree":{"minified":"38.1","gzipped":"13.5","minBytes":39025,"gzBytes":13849}}
+{"base":{"minified":"27.4","gzipped":"9.9","minBytes":28041,"gzBytes":10108},"a11y":{"minified":"30.5","gzipped":"11.0","minBytes":31188,"gzBytes":11254},"selection":{"minified":"36.3","gzipped":"12.5","minBytes":37221,"gzBytes":12828},"data":{"minified":"41.1","gzipped":"14.7","minBytes":42072,"gzBytes":15057},"scrollbar":{"minified":"34.5","gzipped":"11.9","minBytes":35288,"gzBytes":12152},"sortable":{"minified":"36.8","gzipped":"12.9","minBytes":37674,"gzBytes":13175},"groups":{"minified":"43.3","gzipped":"15.2","minBytes":44362,"gzBytes":15525},"page":{"minified":"29.8","gzipped":"10.6","minBytes":30527,"gzBytes":10892},"snapshots":{"minified":"30.6","gzipped":"11.0","minBytes":31385,"gzBytes":11289},"transition":{"minified":"34.1","gzipped":"11.7","minBytes":34965,"gzBytes":11981},"autosize":{"minified":"29.8","gzipped":"10.7","minBytes":30517,"gzBytes":10980},"grid":{"minified":"34.4","gzipped":"12.3","minBytes":35224,"gzBytes":12605},"table":{"minified":"45.6","gzipped":"15.6","minBytes":46658,"gzBytes":15992},"masonry":{"minified":"38.4","gzipped":"13.9","minBytes":39362,"gzBytes":14219},"tree":{"minified":"42.5","gzipped":"14.9","minBytes":43528,"gzBytes":15255},"search":{"minified":"36.5","gzipped":"13.0","minBytes":37354,"gzBytes":13354},"carousel":{"minified":"33.9","gzipped":"12.2","minBytes":34710,"gzBytes":12509}}

package/dist/types.d.ts

@@ -295,7 +295,7 @@ export interface ScrollConfig {
      * Scrollbar mode (default: custom scrollbar).
      *
      * - *omitted* — Custom scrollbar (default), native scrollbar hidden via CSS
-     * - `'native'` — Browser native scrollbar (falls back to custom in compressed mode)
+     * - `'native'` — Browser native scrollbar
      * - `'none'` — No scrollbar at all (native hidden, custom not created)
      * - `ScrollbarOptions` — Custom scrollbar with fine-tuning options
      */
@@ -370,11 +370,23 @@ export interface TreeState {
     isLastChild: boolean;
     loading: boolean;
 }
+/** Search-specific state available in templates when the search plugin is active */
+export interface SearchState {
+    /** Whether this item matches the current query */
+    matched: boolean;
+    /** Current search query (empty string when no search is active) */
+    query: string;
+    /** This item's position in the match list (-1 if not matched) */
+    matchIndex: number;
+    /** Whether this is the currently focused match (navigate mode) */
+    isCurrent: boolean;
+}
 /** State passed to template */
 export interface ItemState {
     selected: boolean;
     focused: boolean;
     tree?: TreeState;
+    search?: SearchState;
 }
 /** Selection mode */
 export type SelectionMode = "none" | "single" | "multiple";
@@ -437,14 +449,8 @@ export interface ViewportState {
     scrollPosition: number;
     /** Container size along main axis (height for vertical, width for horizontal) */
     containerSize: number;
-    /** Total content size (may be capped for compression) */
+    /** Total content size */
     totalSize: number;
-    /** Actual total size without compression */
-    actualSize: number;
-    /** Whether compression is active */
-    isCompressed: boolean;
-    /** Compression ratio (1 = no compression, <1 = compressed) */
-    compressionRatio: number;
     /** Visible item range */
     visibleRange: Range;
     /** Render range (includes overscan) */
@@ -463,7 +469,6 @@ export interface ErrorViewportSnapshot {
         end: number;
     };
     totalItems: number;
-    isCompressed: boolean;
 }
 /** Event types and their payloads */
 export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
@@ -601,6 +606,23 @@ export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
         item: T;
         error: unknown;
     };
+    /** Search bar opened / focused */
+    "search:open": undefined;
+    /** Search bar closed and query cleared */
+    "search:close": undefined;
+    /** Query or results changed */
+    "search:change": {
+        query: string;
+        matches: number;
+        total: number;
+    };
+    /** Navigated to a match (navigate mode) */
+    "search:match": {
+        index: number;
+        item: T | undefined;
+        matchIndex: number;
+        matches: number;
+    };
     /** Destroy — fired just before the instance is torn down */
     destroy: undefined;
 }

package/dist/vlist-search.css

@@ -0,0 +1 @@
+:root{--vlist-search-match-bg:#fde047;--vlist-search-match-current-bg:#f59e0b;--vlist-search-md3-surface:#ececf1;--vlist-search-md3-state:rgba(0,0,0,0.08)}[data-theme-mode="dark"]{--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]):not([data-theme-mode="dark"]){--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}}.dark{--vlist-search-match-bg:#92710b;--vlist-search-match-current-bg:#b45309;--vlist-search-md3-surface:#2b3039;--vlist-search-md3-state:rgba(255,255,255,0.08)}.vlist--has-search{display:flex;flex-direction:column}.vlist--has-search .vlist-viewport{flex:1 1 auto;min-height:0}.vlist-search{flex:0 0 auto;box-sizing:border-box;display:flex}.vlist-search__container{display:flex;align-items:center;gap:6px;width:100%;box-sizing:border-box;padding:6px 8px;background-color:var(--vlist-bg);border-bottom:1px solid var(--vlist-border)}.vlist-search--bottom .vlist-search__container{border-bottom:none;border-top:1px solid var(--vlist-border)}.vlist-search__leading-icon,.vlist-search__nav-prev,.vlist-search__nav-next,.vlist-search__clear-button{flex:0 0 auto;display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px;padding:0;border:none;border-radius:4px;background:transparent;color:var(--vlist-text-muted);cursor:pointer}.vlist-search__leading-icon svg,.vlist-search__nav-prev svg,.vlist-search__nav-next svg,.vlist-search__clear-button svg{width:18px;height:18px;fill:currentColor}.vlist-search__leading-icon:hover,.vlist-search__nav-prev:hover,.vlist-search__nav-next:hover,.vlist-search__clear-button:hover{color:var(--vlist-text);background-color:var(--vlist-bg-hover)}.vlist-search__clear-button--hidden,.vlist-search__nav-prev--hidden,.vlist-search__nav-next--hidden{display:none}.vlist-search__input-wrapper{flex:1 1 auto;min-width:0;display:flex;align-items:center}.vlist-search__input{width:100%;min-width:0;padding:4px 8px;font:inherit;color:var(--vlist-text);background-color:var(--vlist-bg);border:1px solid var(--vlist-border);border-radius:4px;outline:none;box-sizing:border-box}.vlist-search__input:focus{border-color:var(--vlist-focus-ring)}.vlist-search__input:focus,.vlist-search__input:focus-visible{outline:none}.vlist-search__counter{flex:0 0 auto;font-size:0.75rem;color:var(--vlist-text-muted);white-space:nowrap}.vlist-search__counter:empty{display:none}.vlist-search-match{color:inherit;background-color:var(--vlist-search-match-bg);border-radius:2px}.vlist-search-match--current{background-color:var(--vlist-search-match-current-bg)}.vlist-search--md3{display:flex;align-items:center;box-sizing:border-box;height:56px;padding:0 12px;border-bottom:1px solid var(--vlist-border)}.vlist-search--md3 .vlist-search__container{flex:1 1 auto;height:40px;padding:0 16px;gap:0;border:none;border-radius:20px;overflow:hidden;background-color:var(--vlist-search-md3-surface);transition:background-color 200ms cubic-bezier(0.2,0,0,1)}.vlist-search--md3 .vlist-search__leading-icon{width:24px;height:24px;margin-right:16px;border-radius:50%;color:var(--vlist-text)}.vlist-search--md3 .vlist-search__leading-icon svg{width:24px;height:24px}.vlist-search--md3 .vlist-search__input{width:100%;height:100%;padding:8px 0;border:none;background:transparent;font:inherit;font-size:16px;line-height:24px;color:var(--vlist-text);caret-color:var(--vlist-focus-ring)}.vlist-search--md3 .vlist-search__input::placeholder{color:var(--vlist-text-muted)}.vlist-search--md3 .vlist-search__counter{margin-left:16px;font-size:12px;color:var(--vlist-text-muted)}.vlist-search--md3 .vlist-search__nav-prev,.vlist-search--md3 .vlist-search__nav-next,.vlist-search--md3 .vlist-search__clear-button{width:24px;height:24px;margin-left:16px;border-radius:50%;color:var(--vlist-text-muted);transition:background-color 200ms cubic-bezier(0.2,0,0,1)}.vlist-search--md3 .vlist-search__nav-prev svg,.vlist-search--md3 .vlist-search__nav-next svg,.vlist-search--md3 .vlist-search__clear-button svg{width:20px;height:20px}.vlist-search--md3 .vlist-search__leading-icon:hover,.vlist-search--md3 .vlist-search__nav-prev:hover,.vlist-search--md3 .vlist-search__nav-next:hover,.vlist-search--md3 .vlist-search__clear-button:hover{background-color:var(--vlist-search-md3-state)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vlist",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",
@@ -45,6 +45,7 @@
     "./styles/table": "./dist/vlist-table.css",
     "./styles/extras": "./dist/vlist-extras.css",
     "./styles/tree": "./dist/vlist-tree.css",
+    "./styles/search": "./dist/vlist-search.css",
     "./package.json": "./package.json"
   },
   "files": [

package/dist/plugins/scrollbar/controller.d.ts

@@ -1,121 +0,0 @@
-/**
- * vlist - Scroll Controller
- * Handles both native scrolling and manual wheel-based scrolling for compressed lists
- *
- * When compression is active (large lists exceeding browser height limits),
- * we switch from native scrolling to manual wheel event handling.
- * This allows smooth scrolling through millions of items.
- */
-import type { CompressionState } from "../../rendering/scale";
-/** Scroll direction */
-export type ScrollDirection = "up" | "down" | "left" | "right";
-/** Scroll event data */
-export interface ScrollEventData {
-    scrollTop: number;
-    direction: ScrollDirection;
-    velocity: number;
-}
-/** Scroll controller configuration */
-export interface ScrollControllerConfig {
-    /** Enable compressed scroll mode (manual wheel handling) */
-    compressed?: boolean;
-    /** Compression state for calculating bounds */
-    compression?: CompressionState;
-    /**
-     * External scroll element for window/document scrolling.
-     * When set, the controller listens to this element's scroll events
-     * and computes list-relative positions from the viewport's bounding rect.
-     */
-    scrollElement?: Window;
-    /** Allow mouse wheel to scroll (default: true) */
-    wheel?: boolean;
-    /** Wheel sensitivity multiplier (default: 1) */
-    sensitivity?: number;
-    /** Enable smooth scrolling interpolation */
-    smoothing?: boolean;
-    /** Scroll idle detection timeout in ms (default: 150) */
-    idleTimeout?: number;
-    /**
-     * Primary axis is X (horizontal scrolling mode).
-     * When true, the controller reads scrollLeft instead of scrollTop,
-     * uses clientWidth instead of clientHeight, and maps wheel deltaX.
-     */
-    isX?: boolean;
-    /** Callback when scroll position changes */
-    onScroll?: (data: ScrollEventData) => void;
-    /** Callback when scrolling becomes idle */
-    onIdle?: () => void;
-}
-/** Scroll controller instance */
-export interface ScrollController {
-    /** Get current scroll position */
-    getScrollTop: () => number;
-    /** Set scroll position */
-    scrollTo: (position: number, smooth?: boolean) => void;
-    /** Scroll by delta */
-    scrollBy: (delta: number) => void;
-    /** Check if at top */
-    isAtTop: () => boolean;
-    /** Check if at bottom */
-    isAtBottom: (threshold?: number) => boolean;
-    /** Get scroll percentage (0-1) */
-    getScrollPercentage: () => number;
-    /** Get current scroll velocity (px/ms, absolute value) */
-    getVelocity: () => number;
-    /**
-     * Check if the velocity tracker is actively tracking with enough samples.
-     * Returns false during ramp-up (first few frames of a new scroll gesture)
-     * when the tracker doesn't have enough samples yet.
-     */
-    isTracking: () => boolean;
-    /** Check if currently scrolling */
-    isScrolling: () => boolean;
-    /** Update configuration (e.g., when compression state changes) */
-    updateConfig: (config: Partial<ScrollControllerConfig>) => void;
-    /** Enable compressed mode */
-    enableCompression: (compression: CompressionState) => void;
-    /** Disable compressed mode (revert to native scroll) */
-    disableCompression: () => void;
-    /** Check if compressed mode is active */
-    isCompressed: () => boolean;
-    /** Check if in window scroll mode */
-    isWindowMode: () => boolean;
-    /**
-     * Update the container height used for scroll calculations.
-     * In window mode, call this when the window resizes.
-     */
-    updateContainerHeight: (height: number) => void;
-    /** Destroy and cleanup */
-    destroy: () => void;
-}
-/**
- * Create a scroll controller for a viewport element
- *
- * Supports two modes:
- * 1. Native scrolling (default) - uses browser's built-in scroll
- * 2. Compressed scrolling - manual wheel handling for large lists
- */
-export declare const createScrollController: (viewport: HTMLElement, config?: ScrollControllerConfig) => ScrollController;
-/**
- * Throttle scroll handler using requestAnimationFrame
- */
-export declare const rafThrottle: <T extends (...args: any[]) => void>(fn: T) => ((...args: Parameters<T>) => void) & {
-    cancel: () => void;
-};
-/**
- * Check if scroll position is at bottom
- */
-export declare const isAtBottom: (scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number) => boolean;
-/**
- * Check if scroll position is at top
- */
-export declare const isAtTop: (scrollTop: number, threshold?: number) => boolean;
-/**
- * Get scroll percentage (0-1)
- */
-export declare const getScrollPercentage: (scrollTop: number, scrollHeight: number, clientHeight: number) => number;
-/**
- * Check if a range is visible in the scroll viewport
- */
-export declare const isRangeVisible: (rangeStart: number, rangeEnd: number, visibleStart: number, visibleEnd: number) => boolean;
-//# sourceMappingURL=controller.d.ts.map

package/dist/rendering/measured.d.ts

@@ -1,52 +0,0 @@
-/**
- * vlist - Measured Size Cache
- * Auto-measurement support for items with unknown sizes (Mode B)
- *
- * Wraps the existing variable SizeCache with measurement tracking.
- * Once an item is measured, it behaves identically to Mode A (known size).
- * Unmeasured items use the estimated size as a fallback.
- *
- * Fully axis-neutral: works identically for vertical (estimatedHeight)
- * and horizontal (estimatedWidth) orientations. This cache stores plain
- * numbers representing the main-axis dimension — it never knows whether
- * those numbers are heights or widths. The axis-specific translation
- * happens in builder/core.ts at the DOM boundary.
- *
- * Implements the SizeCache interface so all downstream code
- * (viewport, scale, features) works unchanged.
- */
-import type { SizeCache } from "./sizes";
-/** Extended SizeCache with measurement tracking */
-export interface MeasuredSizeCache extends SizeCache {
-    /** Record actual measured size for an item */
-    setMeasuredSize(index: number, size: number): void;
-    /** Check if an item has been measured */
-    isMeasured(index: number): boolean;
-    /** Get the estimated size (used for unmeasured items) */
-    getEstimatedSize(): number;
-    /** Number of items that have been measured */
-    measuredCount(): number;
-}
-/**
- * Create a measured size cache for auto-measurement (Mode B)
- *
- * Works for both orientations:
- *   - Vertical:   estimatedSize = estimatedHeight, measures block size
- *   - Horizontal: estimatedSize = estimatedWidth, measures inline size
- *
- * The cache itself is axis-neutral — it only stores numbers. The caller
- * (builder/core.ts) is responsible for reading the correct axis from
- * the config and from ResizeObserver entries (blockSize vs inlineSize).
- *
- * Internally maintains a Map of measured sizes keyed by item index.
- * Unmeasured items fall back to the estimated size. The underlying
- * prefix-sum array is rebuilt when measurements change.
- *
- * The size function fed into the variable SizeCache becomes:
- *   (index) => measuredSizes.has(index) ? measuredSizes.get(index) : estimatedSize
- *
- * This means all existing viewport, compression, and range calculations
- * work unchanged — they only see a SizeCache with variable sizes.
- */
-export declare const createMeasuredSizeCache: (estimatedSize: number, initialTotal: number) => MeasuredSizeCache;
-//# sourceMappingURL=measured.d.ts.map

package/dist/rendering/renderer.d.ts

@@ -1,113 +0,0 @@
-/**
- * vlist - DOM Rendering
- * Efficient DOM rendering with element pooling
- * Supports compression for large lists (1M+ items)
- */
-import type { VListItem, ItemTemplate, Range } from "../types";
-import type { CompressionState } from "./viewport";
-import type { SizeCache } from "./sizes";
-/**
- * Optional compression position calculator.
- * Injected by the monolithic factory or the withCompression feature.
- * When not provided, the renderer uses simple sizeCache offsets.
- */
-export type CompressedPositionFn = (index: number, scrollTop: number, sizeCache: SizeCache, totalItems: number, containerHeight: number, compression: CompressionState, rangeStart?: number) => number;
-/**
- * Optional compression state getter.
- * Injected by the monolithic factory or the withCompression feature.
- * When not provided, the renderer assumes no compression.
- */
-export type CompressionStateFn = (totalItems: number, sizeCache: SizeCache) => CompressionState;
-/** Element pool for recycling DOM elements */
-export interface ElementPool {
-    /** Get an element from the pool (or create new) */
-    acquire: () => HTMLElement;
-    /** Return an element to the pool */
-    release: (element: HTMLElement) => void;
-    /** Clear the pool */
-    clear: () => void;
-    /** Get pool statistics */
-    stats: () => {
-        poolSize: number;
-        created: number;
-        reused: number;
-    };
-}
-/** Compression context for positioning */
-export interface CompressionContext {
-    scrollPosition: number;
-    totalItems: number;
-    containerSize: number;
-    rangeStart: number;
-    /** Pre-computed compression state (includes force flag) */
-    compression?: CompressionState;
-}
-/** DOM structure created by createDOMStructure */
-export interface DOMStructure {
-    root: HTMLElement;
-    viewport: HTMLElement;
-    content: HTMLElement;
-    items: HTMLElement;
-    /** Visually-hidden live region for screen reader announcements */
-    liveRegion: HTMLElement;
-}
-/** Renderer instance */
-export interface Renderer<T extends VListItem = VListItem> {
-    /** Render items for a range */
-    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 */
-    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 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;
-    /** Clear all rendered items */
-    clear: () => void;
-    /** Destroy renderer and cleanup */
-    destroy: () => void;
-}
-/**
- * Create an element pool for recycling DOM elements
- * Reduces garbage collection and improves performance
- */
-export declare const createElementPool: (tagName?: string, maxSize?: number) => ElementPool;
-/**
- * Create a renderer for managing DOM elements
- * Supports compression for large lists
- */
-export declare const createRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, classPrefix: string, totalItemsGetter?: () => number, ariaIdPrefix?: string, isX?: boolean, crossAxisSize?: number, compressionFns?: {
-    getState: CompressionStateFn;
-    getPosition: CompressedPositionFn;
-}, striped?: boolean | "data" | "even" | "odd", stripeIndexFn?: () => (index: number) => number, ariaPosInSetGetter?: (layoutIndex: number) => number, interactive?: boolean) => Renderer<T>;
-/**
- * Create the vlist DOM structure
- */
-export declare const createDOMStructure: (container: HTMLElement, classPrefix: string, ariaLabel?: string, isX?: boolean, interactive?: boolean) => DOMStructure;
-/**
- * Update content height for virtual scrolling
- */
-export declare const updateContentHeight: (content: HTMLElement, totalHeight: number) => void;
-/**
- * Update content width for horizontal virtual scrolling
- */
-export declare const updateContentWidth: (content: HTMLElement, totalWidth: number) => void;
-/**
- * Get container dimensions
- */
-export declare const getContainerDimensions: (viewport: HTMLElement) => {
-    width: number;
-    height: number;
-};
-/**
- * Resolve container from selector or element
- */
-export declare const resolveContainer: (container: HTMLElement | string) => HTMLElement;
-//# sourceMappingURL=renderer.d.ts.map