vlist 0.1.3 → 1.5.4

package/dist/builder/data.d.ts

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

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

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

@@ -0,0 +1,165 @@
+/**
+ * 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 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">) => any;
+//# sourceMappingURL=materialize.d.ts.map

package/dist/builder/pool.d.ts

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

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

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