vlist 1.9.1 → 2.0.0

package/dist/builder/api.d.ts

@@ -1,21 +0,0 @@
-/**
- * vlist/builder — Public API Assembly
- *
- * Constructs the public VList API object, base data method wrappers,
- * scroll methods (cancelScroll, animateScroll, scrollToIndex), event
- * subscription (on/off), and the destroy teardown.
- *
- * Extracted from core.ts materialize() — pure wiring with no hot-path
- * implications. All mutable state accessed via the `$` refs bag.
- *
- * Uses positional parameters (not a deps object) so the minifier can
- * rename every argument — no long property-name strings in the bundle.
- */
-import type { VListItem, VListEvents } from "../types";
-import type { Emitter } from "../events/emitter";
-import type { DOMStructure } from "./dom";
-import type { createElementPool } from "./pool";
-import type { BuilderContext, VListFeature, VList } from "./types";
-import type { MRefs } from "./materialize";
-export declare const createApi: <T extends VListItem = VListItem>($: MRefs<T>, dom: DOMStructure, emitter: Emitter<VListEvents<T>>, rendered: Map<number, HTMLElement>, pool: ReturnType<typeof createElementPool>, methods: Map<string, Function>, sortedFeatures: VListFeature<T>[], destroyHandlers: Array<() => void>, ctx: BuilderContext<T>, isReverse: boolean, wrapEnabled: boolean, handleClick: (event: MouseEvent) => void, handleDblClick: (event: MouseEvent) => void, handleContextMenu: (event: MouseEvent) => void, handleKeydown: (event: KeyboardEvent) => void, onScrollFrame: () => void, resizeObserver: ResizeObserver, disconnectItemObserver: () => void, clearIdleTimer: () => void) => VList<T>;
-//# sourceMappingURL=api.d.ts.map

package/dist/builder/context.d.ts

@@ -1,36 +0,0 @@
-/**
- * vlist/builder - BuilderContext Factory
- * Central state container that features receive during setup.
- *
- * The BuilderContext provides access to all core components plus
- * registration points for handlers, methods, and cleanup callbacks.
- */
-import type { VListItem, VListEvents } from "../types";
-import type { SizeCache } from "../rendering/sizes";
-import type { Renderer, DOMStructure } from "../rendering/renderer";
-import type { SimpleDataManager } from "./data";
-import type { ScrollController } from "../features/scrollbar/controller";
-import type { Emitter } from "../events/emitter";
-import type { BuilderConfig, BuilderContext, BuilderState, ResolvedBuilderConfig } from "./types";
-/** Options for creating a BuilderContext */
-export interface CreateBuilderContextOptions<T extends VListItem = VListItem> {
-    rawConfig: BuilderConfig<T>;
-    resolvedConfig: ResolvedBuilderConfig;
-    dom: DOMStructure;
-    sizeCache: SizeCache;
-    dataManager: SimpleDataManager<T>;
-    scrollController: ScrollController;
-    renderer: Renderer<T>;
-    emitter: Emitter<VListEvents<T>>;
-    initialState: BuilderState;
-    initialSizeConfig: number | ((index: number) => number);
-}
-/**
- * Create a BuilderContext from individual components.
- *
- * The context acts as the central hub that features wire into.
- * Unlike VListContext (used by the monolithic factory), BuilderContext
- * exposes registration arrays and replacement methods for features.
- */
-export declare const createBuilderContext: <T extends VListItem = VListItem>(options: CreateBuilderContextOptions<T>) => BuilderContext<T>;
-//# sourceMappingURL=context.d.ts.map

package/dist/builder/core.d.ts

@@ -1,16 +0,0 @@
-/**
- * vlist/builder — Composable virtual list builder
- *
- * Pure utilities (velocity, DOM, pool, range, scroll) live in sibling files.
- * Size cache and emitter are reused from rendering/ and events/ modules.
- * Bun.build inlines everything into a single bundle automatically.
- *
- * Features compose functionality *around* the hot path via extension points:
- * afterScroll, clickHandlers, keydownHandlers, resizeHandlers, destroyHandlers,
- * and the methods Map for public API extension.
- */
-import type { VListItem } from "../types";
-import type { BuilderConfig, VListBuilder } from "./types";
-export type { CompressionState } from "../rendering/viewport";
-export declare const vlist: <T extends VListItem = VListItem>(config: BuilderConfig<T>) => VListBuilder<T>;
-//# sourceMappingURL=core.d.ts.map

package/dist/builder/data.d.ts

@@ -1,71 +0,0 @@
-/**
- * vlist/builder - Lightweight In-Memory Data Manager
- *
- * A minimal data manager that stores items in a plain array.
- * No sparse storage, no placeholders, no async adapter support.
- *
- * This keeps the builder core small (~12 KB). When the user installs
- * withData(), that feature replaces this manager with the full
- * adapter-backed data manager from src/data/manager.ts.
- */
-import type { VListItem, Range } from "../types";
-/** Minimal data state */
-export interface SimpleDataState<_T extends VListItem = VListItem> {
-    total: number;
-    cached: number;
-    isLoading: boolean;
-    pendingRanges: Range[];
-    error: Error | undefined;
-    hasMore: boolean;
-    cursor: string | undefined;
-}
-/**
- * SimpleDataManager — the same interface as the full DataManager,
- * but backed by a plain array instead of sparse storage + placeholders.
- *
- * Only the methods used by the builder core and features are implemented.
- * Adapter-related methods (loadRange, ensureRange, loadInitial, loadMore,
- * reload, evictDistant) are no-ops or stubs.
- */
-export interface SimpleDataManager<T extends VListItem = VListItem> {
-    getState: () => SimpleDataState<T>;
-    getTotal: () => number;
-    getCached: () => number;
-    getIsLoading: () => boolean;
-    getHasMore: () => boolean;
-    getStorage: () => unknown;
-    getPlaceholders: () => unknown;
-    getItem: (index: number) => T | undefined;
-    getIndexById: (id: string | number) => number;
-    isItemLoaded: (index: number) => boolean;
-    getItemsInRange: (start: number, end: number) => T[];
-    setTotal: (total: number) => void;
-    setItems: (items: T[], offset?: number, total?: number) => void;
-    updateItem: (index: number, updates: Partial<T>) => boolean;
-    insertItem: (item: T, index: number) => void;
-    removeItem: (id: string | number) => boolean;
-    loadRange: (start: number, end: number) => Promise<void>;
-    ensureRange: (start: number, end: number) => Promise<void>;
-    loadInitial: () => Promise<void>;
-    loadMore: (direction?: "down" | "up") => Promise<boolean>;
-    reload: () => Promise<void>;
-    evictDistant: (visibleStart: number, visibleEnd: number) => void;
-    clear: () => void;
-    reset: () => void;
-}
-export interface SimpleDataManagerConfig<T extends VListItem = VListItem> {
-    initialItems?: T[];
-    initialTotal?: number;
-    onStateChange?: (state: SimpleDataState<T>) => void;
-    onItemsLoaded?: (items: T[], offset: number, total: number) => void;
-}
-/**
- * Create a lightweight in-memory data manager.
- *
- * Items are stored in a plain array. ID lookups use a Map.
- * No sparse storage, no placeholders, no chunking, no eviction.
- *
- * ~1 KB minified vs ~8 KB for the full data manager.
- */
-export declare const createSimpleDataManager: <T extends VListItem = VListItem>(config?: SimpleDataManagerConfig<T>) => SimpleDataManager<T>;
-//# sourceMappingURL=data.d.ts.map

package/dist/builder/dom.d.ts

@@ -1,15 +0,0 @@
-/**
- * vlist/builder — DOM Structure
- * Container resolution and DOM scaffold creation for the virtual list.
- */
-export interface DOMStructure {
-    root: HTMLElement;
-    viewport: HTMLElement;
-    content: HTMLElement;
-    items: HTMLElement;
-    /** Visually-hidden live region for screen reader range announcements */
-    liveRegion: HTMLElement;
-}
-export declare const resolveContainer: (container: HTMLElement | string) => HTMLElement;
-export declare const createDOMStructure: (container: HTMLElement, classPrefix: string, ariaLabel?: string, horizontal?: boolean, interactive?: boolean) => DOMStructure;
-//# sourceMappingURL=dom.d.ts.map

package/dist/builder/index.d.ts

@@ -1,25 +0,0 @@
-/**
- * vlist/builder - Composable Virtual List Builder
- * Pick only the features you need, pay only for what you ship.
- *
- * @example
- * ```ts
- * import { vlist } from 'vlist/builder'
- * import { withSelection } from 'vlist/selection'
- * import { withScrollbar } from 'vlist/scroll'
- *
- * const list = vlist({
- *   container: '#app',
- *   item: { height: 48, template: renderItem },
- *   items: data,
- * })
- * .use(withSelection({ mode: 'multiple' }))
- * .use(withScrollbar())
- * .build()
- * ```
- *
- * @packageDocumentation
- */
-export { vlist } from "./core";
-export type { VListBuilder, VList, BuilderConfig, VListConfig, VListFeature, FeatureFactory, BuilderContext, ReloadOptions, BuilderState, ResolvedBuilderConfig, } from "./types";
-//# sourceMappingURL=index.d.ts.map

package/dist/builder/materialize.d.ts

@@ -1,166 +0,0 @@
-/**
- * vlist/builder — Materialize Context Factory
- *
- * Extracts the BuilderContext object, default data-manager proxy, and default
- * scroll-controller proxy out of materialize() in core.ts.
- *
- * All shared mutable state lives in a single `$` (MRefs) object that both
- * core.ts and this module read/write through. Property names are kept short
- * (2–3 chars) so they survive minification without bloating the bundle.
- * Each factory destructures to readable locals on entry.
- *
- * Immutable dependencies are passed via a `deps` (MDeps) object — these are
- * destructured once and never re-read, so their names don't matter at runtime.
- */
-import type { VListItem, VListEvents, ItemTemplate, ItemState, Range } from "../types";
-import type { SizeCache } from "../rendering/sizes";
-import type { Emitter } from "../events/emitter";
-import type { DOMStructure } from "./dom";
-import type { createElementPool } from "./pool";
-import type { BuilderConfig, BuilderContext, BuilderState, ResolvedBuilderConfig } from "./types";
-/**
- * Mutable refs object shared between core.ts materialize() and context factories.
- *
- * Key mapping (short → long):
- *
- * | Key  | Meaning                |
- * |------|------------------------|
- * | it   | items                  |
- * | hc   | sizeCache              |
- * | ch   | containerHeight        |
- * | cw   | containerWidth         |
- * | id   | isDestroyed            |
- * | ii   | isInitialized          |
- * | ls   | lastScrollTop          |
- * | vt   | velocityTracker        |
- * | ss   | selectionSet           |
- * | fi   | focusedIndex           |
- * | la   | lastAriaSetSize        |
- * | dm   | dataManagerProxy       |
- * | sc   | scrollControllerProxy  |
- * | vtf  | virtualTotalFn         |
- * | sgt  | scrollGetTop           |
- * | sst  | scrollSetTop           |
- * | sab  | scrollIsAtBottom       |
- * | sic  | scrollIsCompressed     |
- * | rfn  | renderIfNeededFn       |
- * | ffn  | forceRenderFn          |
- * | gvr  | getVisibleRange        |
- * | gsp  | getScrollToPos         |
- * | pef  | positionElementFn      |
- * | at   | activeTemplate         |
- * | vre  | viewportResizeEnabled  |
- * | st   | scrollTarget           |
- * | gcw  | getContainerWidth      |
- * | gch  | getContainerHeight     |
- */
-export interface MRefs<T extends VListItem = VListItem> {
-    /** items */
-    it: T[];
-    /** sizeCache */
-    hc: SizeCache;
-    /** containerHeight */
-    ch: number;
-    /** containerWidth */
-    cw: number;
-    /** isDestroyed */
-    id: boolean;
-    /** isInitialized */
-    ii: boolean;
-    /** lastScrollTop */
-    ls: number;
-    /** velocityTracker */
-    vt: {
-        velocity: number;
-        sampleCount: number;
-    };
-    /** selectionSet */
-    ss: Set<string | number>;
-    /** focusedIndex */
-    fi: number;
-    /** lastAriaSetSize */
-    la: string;
-    /** dataManagerProxy */
-    dm: any;
-    /** scrollControllerProxy */
-    sc: any;
-    /** virtualTotalFn */
-    vtf: () => number;
-    /** scrollGetTop */
-    sgt: () => number;
-    /** scrollSetTop */
-    sst: (pos: number) => void;
-    /** scrollIsAtBottom */
-    sab: (threshold?: number) => boolean;
-    /** scrollIsCompressed */
-    sic: boolean;
-    /** renderIfNeededFn */
-    rfn: () => void;
-    /** forceRenderFn */
-    ffn: () => void;
-    /** getVisibleRange */
-    gvr: (scrollTop: number, cHeight: number, hc: SizeCache, total: number, out: Range) => void;
-    /** getScrollToPos */
-    gsp: (index: number, hc: SizeCache, cHeight: number, total: number, align: "start" | "center" | "end") => number;
-    /** positionElementFn */
-    pef: (element: HTMLElement, index: number) => void;
-    /** activeTemplate */
-    at: ItemTemplate<T>;
-    /** viewportResizeEnabled */
-    vre: boolean;
-    /** scrollTarget */
-    st: HTMLElement | Window;
-    /** wheelHandler - for features to disable wheel handling if needed */
-    wh: ((e: WheelEvent) => void) | null;
-    /** getContainerWidth */
-    gcw: () => number;
-    /** getContainerHeight */
-    gch: () => number;
-    /** gap — item spacing along main axis (0 = none) */
-    gp: number;
-    /** mainAxisPadding — sum of CSS padding along scroll axis (0 = none) */
-    mp: number;
-    /** stripeIndexFn — maps layout index to stripe index (-1 = skip) */
-    sif: (index: number) => number;
-    /** itemToScrollIndex — maps flat item index to size-cache index (identity for list, floor(index/cols) for grid) */
-    i2s: (index: number) => number;
-    /** updateItemClassesFn */
-    uic: (index: number, isSelected: boolean, isFocused: boolean) => void;
-    /** constrainSizeForIndex — null = always constrain (Mode A default) */
-    csi: ((index: number) => boolean) | null;
-}
-/** Immutable dependencies the context factory needs from materialize(). */
-export interface MDeps<T extends VListItem = VListItem> {
-    readonly dom: DOMStructure;
-    readonly emitter: Emitter<VListEvents<T>>;
-    readonly resolvedConfig: ResolvedBuilderConfig;
-    readonly rawConfig: BuilderConfig<T>;
-    readonly rendered: Map<number, HTMLElement>;
-    readonly pool: ReturnType<typeof createElementPool>;
-    readonly itemState: ItemState;
-    readonly sharedState: BuilderState;
-    readonly renderRange: Range;
-    readonly isHorizontal: boolean;
-    readonly classPrefix: string;
-    readonly contentSizeHandlers: Array<() => void>;
-    readonly idleHandlers: Array<() => void>;
-    readonly afterScroll: Array<(scrollPosition: number, direction: string) => void>;
-    readonly clickHandlers: Array<(event: MouseEvent) => void>;
-    readonly contextMenuHandlers: Array<(event: MouseEvent) => void>;
-    readonly keydownHandlers: Array<(event: KeyboardEvent) => void>;
-    readonly resizeHandlers: Array<(width: number, height: number) => void>;
-    readonly destroyHandlers: Array<() => void>;
-    readonly methods: Map<string, Function>;
-    readonly onScrollFrame: () => void;
-    readonly resizeObserver: ResizeObserver;
-    readonly afterRenderBatch: ReadonlyArray<(items: ReadonlyArray<{
-        index: number;
-        element: HTMLElement;
-    }>) => void>;
-    readonly applyTemplate: (element: HTMLElement, result: string | HTMLElement) => void;
-    readonly updateContentSize: () => void;
-}
-export declare const createMaterializeCtx: <T extends VListItem = VListItem>($: MRefs<T>, deps: MDeps<T>) => BuilderContext<T>;
-export declare const createDefaultDataProxy: <T extends VListItem = VListItem>($: MRefs<T>, deps: Pick<MDeps<T>, "rendered" | "itemState" | "contentSizeHandlers" | "applyTemplate" | "updateContentSize">, ctx: BuilderContext<T>) => any;
-export declare const createDefaultScrollProxy: <T extends VListItem = VListItem>($: MRefs<T>, deps: Pick<MDeps<T>, "dom" | "classPrefix" | "onScrollFrame">) => any;
-//# sourceMappingURL=materialize.d.ts.map

package/dist/builder/pool.d.ts

@@ -1,10 +0,0 @@
-/**
- * vlist/builder — Element Pool
- * Recycling pool for DOM elements to reduce allocation during scrolling.
- */
-export declare const createElementPool: (maxSize?: number) => {
-    acquire: () => HTMLElement;
-    release: (el: HTMLElement) => void;
-    clear: () => void;
-};
-//# sourceMappingURL=pool.d.ts.map

package/dist/builder/range.d.ts

@@ -1,10 +0,0 @@
-/**
- * vlist/builder — Range Calculations
- * Visible range detection, overscan application, and scroll-to-index positioning.
- */
-import type { Range } from "../types";
-import type { SizeCache } from "../rendering/sizes";
-export declare const calcVisibleRange: (scrollPosition: number, containerHeight: number, hc: SizeCache, totalItems: number, out: Range) => void;
-export declare const applyOverscan: (visible: Range, overscan: number, totalItems: number, out: Range) => void;
-export declare const calcScrollToPosition: (index: number, hc: SizeCache, containerHeight: number, totalItems: number, align: "start" | "center" | "end", mainAxisPadding?: number) => number;
-//# sourceMappingURL=range.d.ts.map

package/dist/builder/scroll.d.ts

@@ -1,24 +0,0 @@
-/**
- * vlist/builder — Scroll Utilities
- * Easing, scroll-argument resolution, and smooth scroll animation.
- */
-import type { ScrollToOptions } from "../types";
-export declare const easeInOutQuad: (t: number) => number;
-export declare const resolveScrollArgs: (o?: "start" | "center" | "end" | ScrollToOptions) => {
-    align: "start" | "center" | "end";
-    behavior: "auto" | "smooth";
-    duration: number;
-};
-/** Scroll controller interface — minimal surface needed by the animation. */
-export interface ScrollController {
-    scrollTo: (position: number) => void;
-    getScrollTop: () => number;
-}
-/**
- * Create a smooth scroll animator with its own animation state.
- */
-export declare const createSmoothScroll: (scrollController: ScrollController, renderFn: () => void) => {
-    animateScroll: (from: number, to: number, duration: number) => void;
-    cancelScroll: () => void;
-};
-//# sourceMappingURL=scroll.d.ts.map