@floor/vlist 0.7.6 → 0.8.0

package/dist/builder/core.d.ts

@@ -1,9 +1,9 @@
 /**
- * vlist/builder — Self-contained composable virtual list builder
+ * vlist/builder — Composable virtual list builder
  *
- * Everything inlined — height cache, emitter, DOM, element pool, renderer,
- * range calculations, scroll handling. Zero module imports means the builder
- * core is ~12 KB minified instead of ~25 KB.
+ * Pure utilities (velocity, DOM, pool, range, scroll) live in sibling files.
+ * Height cache and emitter are reused from rendering/ and events/ modules.
+ * Bun.build inlines everything into a single bundle automatically.
  *
  * Plugins compose features *around* the hot path via extension points:
  * afterScroll, clickHandlers, keydownHandlers, resizeHandlers, destroyHandlers,

package/dist/builder/data.d.ts

@@ -36,18 +36,16 @@ export interface SimpleDataManager<T extends VListItem = VListItem> {
     getStorage: () => unknown;
     getPlaceholders: () => unknown;
     getItem: (index: number) => T | undefined;
-    getItemById: (id: string | 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: (id: string | number, updates: Partial<T>) => boolean;
-    removeItem: (id: string | number) => boolean;
+    updateItem: (index: number, updates: Partial<T>) => boolean;
+    removeItem: (index: number) => boolean;
     loadRange: (start: number, end: number) => Promise<void>;
     ensureRange: (start: number, end: number) => Promise<void>;
     loadInitial: () => Promise<void>;
-    loadMore: () => Promise<boolean>;
+    loadMore: (direction?: "down" | "up") => Promise<boolean>;
     reload: () => Promise<void>;
     evictDistant: (visibleStart: number, visibleEnd: number) => void;
     clear: () => void;

package/dist/builder/dom.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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;
+}
+export declare const resolveContainer: (container: HTMLElement | string) => HTMLElement;
+export declare const createDOMStructure: (container: HTMLElement, classPrefix: string, ariaLabel?: string, horizontal?: boolean) => DOMStructure;
+//# sourceMappingURL=dom.d.ts.map

package/dist/builder/materializectx.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 { HeightCache } from "../rendering/heights";
+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   | heightCache            |
+ * | 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[];
+    /** heightCache */
+    hc: HeightCache;
+    /** 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: HeightCache, total: number, out: Range) => void;
+    /** getScrollToPos */
+    gsp: (index: number, hc: HeightCache, 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;
+    /** getContainerWidth */
+    gcw: () => number;
+    /** getContainerHeight */
+    gch: () => number;
+}
+/** 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 afterScroll: Array<(scrollTop: 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 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=materializectx.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 { HeightCache } from "../rendering/heights";
+export declare const calcVisibleRange: (scrollTop: number, containerHeight: number, hc: HeightCache, 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: HeightCache, containerHeight: number, totalItems: number, align: "start" | "center" | "end") => number;
+//# sourceMappingURL=range.d.ts.map

package/dist/builder/scroll.d.ts

@@ -0,0 +1,13 @@
+/**
+ * vlist/builder — Scroll Utilities
+ * Easing function and scroll-argument resolution for smooth scrolling.
+ */
+import type { ScrollToOptions } from "../types";
+export declare const DEFAULT_SMOOTH_DURATION = 300;
+export declare const easeInOutQuad: (t: number) => number;
+export declare const resolveScrollArgs: (alignOrOptions?: "start" | "center" | "end" | ScrollToOptions) => {
+    align: "start" | "center" | "end";
+    behavior: "auto" | "smooth";
+    duration: number;
+};
+//# sourceMappingURL=scroll.d.ts.map

package/dist/builder/types.d.ts

@@ -255,7 +255,6 @@ export interface BuiltVList<T extends VListItem = VListItem> {
     removeItem: (id: string | number) => void;
     reload: () => Promise<void>;
     scrollToIndex: (index: number, alignOrOptions?: "start" | "center" | "end" | ScrollToOptions) => void;
-    scrollToItem: (id: string | number, alignOrOptions?: "start" | "center" | "end" | ScrollToOptions) => void;
     cancelScroll: () => void;
     getScrollPosition: () => number;
     on: <K extends keyof VListEvents<T>>(event: K, handler: EventHandler<VListEvents<T>[K]>) => Unsubscribe;

package/dist/builder/velocity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vlist/builder — Velocity Tracking
+ * Circular-buffer velocity tracker for scroll momentum detection.
+ */
+export declare const VELOCITY_SAMPLE_COUNT = 5;
+export declare const STALE_GAP_MS = 100;
+export declare const MIN_RELIABLE_SAMPLES = 2;
+export interface VelocitySample {
+    position: number;
+    time: number;
+}
+export interface VelocityTracker {
+    velocity: number;
+    lastPosition: number;
+    lastTime: number;
+    samples: VelocitySample[];
+    sampleIndex: number;
+    sampleCount: number;
+}
+export declare const createVelocityTracker: (initialPosition?: number) => VelocityTracker;
+export declare const updateVelocityTracker: (tracker: VelocityTracker, newPosition: number) => VelocityTracker;
+//# sourceMappingURL=velocity.d.ts.map