vlist 1.9.1 → 2.0.1

package/dist/core/pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * vlist v2 — 2-Phase Pipeline
+ *
+ * Phase 1: Calculate & Reconcile — zero allocation hot path.
+ *   Reads scroll position + size cache, writes into EngineState TypedArrays.
+ *
+ * Phase 2: Commit — reads EngineState buffers, updates DOM via pool.
+ *   Sub-phases: acquire → identity bind → position → release.
+ *
+ * Both phases are synchronous. No intermediate objects are allocated.
+ */
+import type { SizeCache } from "./sizes";
+import type { VListItem, ItemTemplate, ItemState, VListEvents } from "../types";
+import type { CompiledHooks, ElementPool } from "./types";
+import type { EngineState } from "./state";
+import type { Emitter } from "../events";
+export interface RenderConfig {
+    readonly prefix: string;
+    readonly selectedClass: string;
+    readonly focusedClass: string;
+    readonly placeholderClass: string;
+    readonly replacedClass: string;
+    readonly translateProp: "translateX(" | "translateY(";
+    readonly itemRole: "option" | "listitem";
+    readonly interactive: boolean;
+    readonly horizontal: boolean;
+    readonly startPadding: number;
+    readonly gap: number;
+    readonly hasCrossPad: boolean;
+    readonly crossStartProp: string;
+    readonly crossEndProp: string;
+    readonly crossStartVal: string;
+    readonly crossEndVal: string;
+    readonly oddClass: string;
+    readonly emitter: Emitter<VListEvents> | null;
+}
+export declare function createRenderConfig(classPrefix: string, horizontal: boolean, interactive: boolean, startPadding: number, crossPadStart: number, crossPadEnd: number, oddClass: string, gap: number, emitter?: Emitter<VListEvents> | null): RenderConfig;
+/**
+ * Calculate visible range and fill EngineState buffers.
+ * Zero allocation — all writes go into pre-allocated TypedArrays.
+ *
+ * Guards:
+ * - Zero container size early exit
+ * - Empty range sentinel: visibleCount = 0
+ * - Overscan application
+ * - Render count safety cap
+ */
+export declare function phase1Calculate(state: EngineState, sizeCache: SizeCache, overscan: number, hooks: CompiledHooks, startPadding?: number): boolean;
+export declare function phase2Commit<T extends VListItem>(state: EngineState, pool: ElementPool, contentElement: HTMLElement, template: ItemTemplate<T>, getItems: () => readonly T[], rendered: Map<number, HTMLElement>, rc: RenderConfig, hooks: CompiledHooks, getItemFn?: ((index: number) => T | undefined) | null, itemStateFn?: ((index: number, state: ItemState) => void) | null): void;
+export declare function render<T extends VListItem>(state: EngineState, sizeCache: SizeCache, overscan: number, pool: ElementPool, contentElement: HTMLElement, template: ItemTemplate<T>, getItems: () => readonly T[], rendered: Map<number, HTMLElement>, rc: RenderConfig, hooks: CompiledHooks, getItemFn?: ((index: number) => T | undefined) | null, itemStateFn?: ((index: number, state: ItemState) => void) | null): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/core/pool.d.ts

@@ -0,0 +1,9 @@
+/**
+ * vlist v2 — Element Pool
+ *
+ * acquire() = pop or create, release() = reset + push.
+ * Max pool size: 100.
+ */
+import type { ElementPool } from "./types";
+export declare function createPool(classPrefix: string): ElementPool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/core/scroll.d.ts

@@ -0,0 +1,32 @@
+/**
+ * vlist v2 — Scroll Handling
+ *
+ * Wheel interception for synchronous rendering, scroll idle detection,
+ * and smooth scroll animation.
+ */
+import type { EngineState } from "./state";
+export interface ScrollHandler {
+    /** Attach scroll and wheel listeners */
+    attach(): void;
+    /** Detach all listeners */
+    detach(): void;
+    /** Cancel smooth scroll animation */
+    cancelScroll(): void;
+    /** Animate to a target scroll position */
+    smoothScrollTo(target: number, duration: number, setFn?: (pos: number) => void, easing?: (t: number) => number): void;
+}
+export interface ScrollHandlerConfig {
+    readonly state: EngineState;
+    readonly viewport: HTMLElement;
+    readonly horizontal: boolean;
+    readonly wheelEnabled: boolean;
+    readonly idleTimeout: number;
+    /** Override the event target for scroll/wheel listeners (default: viewport) */
+    readonly scrollTarget?: EventTarget;
+    /** Called synchronously on scroll — triggers the 2-phase pipeline */
+    readonly onFrame: () => void;
+    /** Called when scrolling becomes idle */
+    readonly onIdle: () => void;
+}
+export declare function createScrollHandler(config: ScrollHandlerConfig): ScrollHandler;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/core/sizes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist v2 — Size Cache
+ *
+ * Float64Array prefix sums with O(1) offset lookups and O(log n) binary search.
+ */
+export { createSizeCache, countVisibleItems, countItemsFittingFromBottom, getOffsetForVirtualIndex, } from "../rendering/sizes";
+export type { SizeCache } from "../rendering/sizes";
+//# sourceMappingURL=sizes.d.ts.map

package/dist/core/state.d.ts

@@ -0,0 +1,47 @@
+/**
+ * vlist v2 — EngineState
+ *
+ * Persistent singleton instantiated once during createVList().
+ * All hot-path state lives in pre-allocated TypedArrays.
+ * Phase 1 mutates in place. Phase 2 reads directly. Zero allocation.
+ */
+export interface EngineState {
+    /** Data indices of visible items — Phase 1 writes, Phase 2 reads */
+    visibleIndices: Int32Array;
+    /** Pixel offsets along main axis for each visible item */
+    visibleOffsets: Float64Array;
+    /** Sizes along main axis for each visible item */
+    visibleSizes: Float64Array;
+    /** Number of valid entries in the buffers (0 = empty range sentinel) */
+    visibleCount: number;
+    /** First data index in the visible window (contiguous layouts) */
+    startIndex: number;
+    /** Total content size in pixels */
+    totalSize: number;
+    /** Current buffer capacity */
+    capacity: number;
+    scrollPosition: number;
+    prevScrollPosition: number;
+    /** 1 = forward, -1 = backward, 0 = idle */
+    scrollDirection: number;
+    containerSize: number;
+    crossSize: number;
+    totalItems: number;
+    prevRangeStart: number;
+    prevRangeEnd: number;
+    renderPending: boolean;
+    initialized: boolean;
+    destroyed: boolean;
+    isCompressed: boolean;
+    compressionRatio: number;
+    prevAriaTotal: number;
+    /**
+     * Resize buffers when container changes. Cold path only.
+     * Heuristic: capacity = ceil(containerSize / minItemSize) + overscan * 2
+     */
+    resizeCapacity(containerSize: number, minItemSize: number, overscan?: number): void;
+    /** Reset to empty range sentinel. */
+    clear(): void;
+}
+export declare function createEngineState(initialCapacity: number): EngineState;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * vlist v2 — Core Type Definitions
+ *
+ * Zero-allocation pipeline types. All hot-path state lives in TypedArrays
+ * on the EngineState singleton — no intermediate object allocation.
+ */
+import type { VListItem, ItemTemplate, ItemState } from "../types";
+import type { SizeCache } from "./sizes";
+import type { EngineState } from "./state";
+import type { Emitter } from "../events";
+/** Phase 1 hook — mutates EngineState in place, zero allocation */
+export type CalculateHook = (state: EngineState) => void;
+/** Phase 2 hook — runs after DOM commit */
+export type CommitHook = (state: EngineState) => void;
+/** After-scroll hook — runs after both phases complete */
+export type AfterScrollHook = (scrollPosition: number, direction: number) => void;
+/** Idle hook — runs when scrolling stops */
+export type IdleHook = () => void;
+/** Resize hook — runs on container resize (cold path) */
+export type ResizeHook = (width: number, height: number) => void;
+export interface CompiledHooks {
+    readonly calculate: readonly CalculateHook[];
+    readonly commit: readonly CommitHook[];
+    readonly afterScroll: readonly AfterScrollHook[];
+    readonly idle: readonly IdleHook[];
+    readonly resize: readonly ResizeHook[];
+}
+export interface ResolvedConfig {
+    readonly overscan: number;
+    readonly horizontal: boolean;
+    readonly reverse: boolean;
+    readonly classPrefix: string;
+    readonly interactive: boolean;
+    readonly mainAxisPadding: number;
+    readonly crossAxisPadding: number;
+    readonly startPadding: number;
+    readonly endPadding: number;
+    readonly crossPadStart: number;
+    readonly crossPadEnd: number;
+    readonly striped: boolean | "data" | "even" | "odd";
+    readonly gap: number;
+}
+export interface DOMStructure {
+    readonly root: HTMLElement;
+    readonly viewport: HTMLElement;
+    readonly content: HTMLElement;
+    readonly liveRegion: HTMLElement;
+}
+export interface ElementPool {
+    acquire(): HTMLElement;
+    release(element: HTMLElement): void;
+    readonly size: number;
+    clear(): void;
+}
+export type VisibleRangeFn = (scrollPosition: number, containerSize: number, sizeCache: SizeCache, totalItems: number, outStart: {
+    value: number;
+}, outEnd: {
+    value: number;
+}) => void;
+export interface PluginContext<T extends VListItem = VListItem> {
+    readonly dom: DOMStructure;
+    readonly sizeCache: SizeCache;
+    readonly pool: ElementPool;
+    readonly config: ResolvedConfig;
+    readonly emitter: Emitter<import("../types").VListEvents<T>>;
+    readonly template: ItemTemplate<T>;
+    registerMethod(name: string, fn: Function): void;
+    getMethod(name: string): Function | undefined;
+    registerClickHandler(handler: (event: MouseEvent) => void): void;
+    registerKeydownHandler(handler: (event: KeyboardEvent) => void): void;
+    registerDestroyHandler(handler: () => void): void;
+    setSizeConfig(config: number | ((index: number) => number)): void;
+    setVisibleRangeFn(fn: VisibleRangeFn): void;
+    setScrollFns(get: () => number, set: (pos: number) => void): void;
+    setVirtualTotalFn(fn: () => number): void;
+    getItems(): readonly T[];
+    getItem(index: number): T | undefined;
+    getState(): EngineState;
+    rebuildSizeCache(): void;
+    updateContentSize(size: number): void;
+    setRenderFn(renderIfNeeded: () => void, forceRender: () => void): void;
+    renderIfNeeded(): void;
+    forceRender(): void;
+    setGetItemFn(fn: (index: number) => T | undefined): void;
+    setItemStateFn(fn: (index: number, state: ItemState) => void): void;
+    getItemStateFn(): ((index: number, state: ItemState) => void) | null;
+    readonly rawSizeSpec: number | ((index: number, ...args: unknown[]) => number);
+    scrollTo(position: number): void;
+    smoothScrollTo(position: number, duration: number, easing?: (t: number) => number): void;
+    disableDefaultScroll(): void;
+    disableDefaultResize(): void;
+    setScrollTarget(target: EventTarget): void;
+    setScrollToPosFn(fn: (index: number, sizeCache: import("./sizes").SizeCache, containerSize: number, totalItems: number, align: string) => number): void;
+    setScrollToIndexFn(fn: (index: number, align: string, behavior?: string, duration?: number, easing?: (t: number) => number) => void | false): void;
+    onScrollFrame(): void;
+    onScrollIdle(): void;
+    removeItemById(id: string | number): number;
+    insertItemAt(item: T, index: number): void;
+    setRemoveItemFn(fn: (id: string | number) => number): void;
+    setInsertItemFn(fn: (item: T, index: number) => void): void;
+    setUpdateItemFn(fn: (id: string | number, updates: Partial<T>) => boolean): void;
+    getRenderedElement(index: number): HTMLElement | null;
+    setNavConfig(config: {
+        total?: () => number;
+        ud?: number;
+        lr?: number;
+        scrollIndex?: (itemIndex: number) => number;
+        navigate?: (currentIndex: number, key: string, total: number) => number;
+    }): void;
+    getNavConfig(): {
+        ud: number;
+        lr: number;
+        scrollIndex: ((itemIndex: number) => number) | null;
+        navigate: ((currentIndex: number, key: string, total: number) => number) | null;
+    };
+}
+export interface VListPlugin<T extends VListItem = VListItem> {
+    readonly name: string;
+    readonly priority?: number;
+    readonly conflicts?: readonly string[];
+    /** Cold path: one-time wiring during createVList(). */
+    setup?(ctx: PluginContext<T>): void;
+    /** Hot path: compiled into linear arrays, iterated per frame. */
+    hooks?: {
+        onCalculate?(state: EngineState): void;
+        onCommit?(state: EngineState): void;
+        onAfterScroll?(scrollPosition: number, direction: number): void;
+        onIdle?(): void;
+        onResize?(width: number, height: number): void;
+    };
+    /** Cleanup on destroy. */
+    destroy?(): void;
+}
+export interface VList<T extends VListItem = VListItem> {
+    readonly element: HTMLElement;
+    readonly items: readonly T[];
+    readonly total: number;
+    setItems(items: T[]): void;
+    appendItems(items: T[]): void;
+    prependItems(items: T[]): void;
+    updateItem(id: string | number, updates: Partial<T>): void;
+    insertItem(item: T, index?: number): void;
+    removeItem(id: string | number): void;
+    removeItems(ids: ReadonlyArray<string | number>): number;
+    getItemAt(index: number): T | undefined;
+    getIndexById(id: string | number): number;
+    scrollToIndex(index: number, align?: "start" | "center" | "end" | {
+        align?: "start" | "center" | "end";
+        behavior?: "auto" | "smooth";
+        duration?: number;
+        easing?: (t: number) => number;
+    }): void;
+    getScrollPosition(): number;
+    on<K extends keyof import("../types").VListEvents<T>>(event: K, handler: import("../types").EventHandler<import("../types").VListEvents<T>[K]>): import("../types").Unsubscribe;
+    off<K extends keyof import("../types").VListEvents<T>>(event: K, handler: import("../types").EventHandler<import("../types").VListEvents<T>[K]>): void;
+    destroy(): void;
+    [key: string]: unknown;
+}
+export interface CreateVListConfig<T extends VListItem = VListItem> {
+    container: HTMLElement | string;
+    item: {
+        height?: number | ((index: number) => number);
+        width?: number | ((index: number) => number);
+        estimatedHeight?: number;
+        estimatedWidth?: number;
+        template: ItemTemplate<T>;
+        gap?: number;
+        striped?: boolean | "data" | "even" | "odd";
+    };
+    items?: T[];
+    overscan?: number;
+    classPrefix?: string;
+    orientation?: "vertical" | "horizontal";
+    padding?: number | [number, number] | [number, number, number, number];
+    interactive?: boolean;
+    reverse?: boolean;
+    ariaLabel?: string;
+    scroll?: {
+        wheel?: boolean;
+        scrollbar?: "none";
+        gutter?: "auto" | "stable";
+        idleTimeout?: number;
+    };
+    /** Defer initial render to the next animation frame. */
+    defer?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/{builder → core}/velocity.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist/builder — Velocity Tracking
+ * vlist v2 — Velocity Tracking
  * Lightweight 2-sample velocity tracker for scroll momentum detection.
  */
 export declare const MIN_RELIABLE_SAMPLES = 2;

package/dist/index.d.ts

@@ -8,26 +8,35 @@
  *
  * @packageDocumentation
  */
-export { vlist } from "./builder";
-export { withScale } from "./features/scale";
-export type { ScaleConfig } from "./features/scale";
-export { withAsync } from "./features/async";
-export { withScrollbar } from "./features/scrollbar";
-export { withPage } from "./features/page";
-export type { WithPageOptions } from "./features/page";
-export { withGroups } from "./features/groups";
-export { withGrid } from "./features/grid";
-export { withMasonry } from "./features/masonry";
-export { withSelection } from "./features/selection";
-export { withSnapshots } from "./features/snapshots";
-export { withTable } from "./features/table";
-export { withSortable } from "./features/sortable";
-export type { SortableConfig } from "./features/sortable";
-export { withAutoSize } from "./features/autosize";
-export { withTransition } from "./features/transition";
-export type { TransitionConfig, TransitionTiming } from "./features/transition";
+export { createVList } from "./core/create";
+export { scale } from "./plugins/scale";
+export type { ScalePluginConfig } from "./plugins/scale";
+export { scrollbar } from "./plugins/scrollbar";
+export type { ScrollbarPluginConfig } from "./plugins/scrollbar";
+export { grid } from "./plugins/grid";
+export { a11y } from "./plugins/a11y";
+export { selection } from "./plugins/selection";
+export type { SelectionPluginConfig } from "./plugins/selection";
+export { page } from "./plugins/page";
+export type { PagePluginConfig } from "./plugins/page";
+export { snapshots } from "./plugins/snapshots";
+export type { SnapshotsPluginConfig } from "./plugins/snapshots";
+export { transition } from "./plugins/transition";
+export type { TransitionPluginConfig } from "./plugins/transition";
+export { autosize } from "./plugins/autosize";
+export type { AutosizePluginConfig } from "./plugins/autosize";
+export { masonry } from "./plugins/masonry";
+export type { MasonryPluginConfig } from "./plugins/masonry";
+export { data } from "./plugins/async";
+export type { DataPluginConfig } from "./plugins/async";
+export { groups } from "./plugins/groups";
+export type { GroupsPluginConfig } from "./plugins/groups";
+export { table } from "./plugins/table";
+export type { TablePluginConfig } from "./plugins/table";
+export { sortable } from "./plugins/sortable";
+export type { SortablePluginConfig } from "./plugins/sortable";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";
 export type { VListItem, VListEvents, ItemConfig, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarPadding, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, GridConfig, MasonryConfig, GroupsConfig, GroupHeaderConfig, GridSizeContext, GridHeightContext, } from "./types";
-export type { VListBuilder, VList, BuilderConfig, VListConfig, VListFeature, BuilderContext, ReloadOptions, } from "./builder";
+export type { VList, VListPlugin, PluginContext, CreateVListConfig, CompiledHooks, ResolvedConfig, DOMStructure, ElementPool, } from "./core/types";
 //# sourceMappingURL=index.d.ts.map