vlist 3.0.0-next.1 → 3.0.0-next.3

package/dist/core/create.d.ts

@@ -1,18 +1,36 @@
 /**
- * vlist v2 — createVList()
+ * vlist — createVList()
  *
  * Factory function. Resolves config, creates DOM, compiles hooks from
  * plugins, wires the 2-phase pipeline, returns the public VList API.
  */
 import type { VListItem } from "../types";
-import type { CreateVListConfig, VListPlugin, VList } from "./types";
+import type { CreateVListConfig, PluginMethods, VListPlugin, VList } from "./types";
 import type { SizeCache } from "./sizes";
 import type { BoundedScrollHandler, BoundedScrollConfig } from "./runway";
 import type { ScrollHandler, ScrollHandlerConfig } from "./scroll";
 import { type Emitter } from "../events";
 import type { VListEvents } from "../types";
-/** Create a list with synthetic input. Native input is available from vlist/native. */
-export declare function createVList<T extends VListItem = VListItem>(config: CreateVListConfig<T>, plugins?: VListPlugin<T>[]): VList<T>;
+/**
+ * Create a list with native scrolling. Opt into synthetic input via vlist/synthetic.
+ *
+ * Let the item type be inferred from the config — its `items`, or the
+ * `template` parameter — rather than passing it as a type argument. The list's
+ * type carries exactly the methods its plugins add, and that inference needs
+ * the plugins tuple as the second type parameter; TypeScript allows no partial
+ * type-argument list, so `createVList<Row>(config, [selection()])` fills the
+ * tuple with its default and returns a bare `VList<Row>`, with every plugin
+ * method gone. It compiles, which is why it looks like the fix for a
+ * `VListItem` constraint error on `Row`. The fix is the constraint: give `Row`
+ * an `id`, and keep the argument list empty.
+ *
+ * @example
+ * // inferred: list has select(), getSelected() …
+ * const list = createVList({ container, items, item: { height: 40, template } }, [selection()]);
+ * // explicit: compiles, and list.select does not exist
+ * const bare = createVList<Row>({ container, items, item: { height: 40, template } }, [selection()]);
+ */
+export declare function createVList<T extends VListItem = VListItem, const P extends readonly VListPlugin<T, any>[] = VListPlugin<T>[]>(config: CreateVListConfig<T>, plugins?: P): VList<T> & PluginMethods<P>;
 /** @internal Shared factory; entries select the input handler. */
 export declare function createCore<T extends VListItem = VListItem>(rawConfig: CreateVListConfig<T>, plugins?: VListPlugin<T>[], 
 /** @internal Omitted by the native entry. */
@@ -22,7 +40,6 @@ logicalHandlerFactory?: (config: BoundedScrollConfig & {
     native: (config: ScrollHandlerConfig) => ScrollHandler & {
         commitScroll(pos?: number): void;
     };
-    wrap: (config: BoundedScrollConfig) => BoundedScrollHandler;
     onContentSize: (size: number, emitter: Emitter<VListEvents<T>>) => void;
 }): VList<T>;
 //# sourceMappingURL=create.d.ts.map

package/dist/core/dom.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — DOM Structure
+ * vlist — DOM Structure
  * Container resolution and DOM scaffold creation.
  */
 import type { DOMStructure } from "./types";

package/dist/core/hooks.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Build-Time Compiled Hooks
+ * vlist — Build-Time Compiled Hooks
  *
  * Hooks are collected during createVList() and frozen into plain arrays.
  * On the hot path they are iterated with a for-loop — no closures,

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Core Public API
+ * vlist — Core Public API
  */
 export { createVList } from "./create";
 export { createEngineState } from "./state";

package/dist/core/pipeline.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — 2-Phase Pipeline
+ * vlist — 2-Phase Pipeline
  *
  * Phase 1: Calculate & Reconcile — zero allocation hot path.
  *   Reads scroll position + size cache, writes into EngineState TypedArrays.

package/dist/core/pool.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Element Pool
+ * vlist — Element Pool
  *
  * acquire() = pop or create, release() = reset + push.
  * Max pool size: 100.

package/dist/core/runway.d.ts

@@ -6,8 +6,8 @@
  *
  * The content element is sized to a bounded *runway* (a multiple of the
  * viewport, capped at the real virtual size) instead of `totalItems × itemSize`.
- * This sidesteps the browser's ~16.7M px element-size limit without the scale
- * plugin's compression — no compression ratio leaks into offsets or hit-testing.
+ * This sidesteps the browser's ~16.7M px element-size limit without compressing
+ * the coordinate space — no compression ratio leaks into offsets or hit-testing.
  *
  * Coordinates:
  *   logical = baseOffset + scrollTop        (absolute virtual pixel position)
@@ -60,6 +60,8 @@ export interface WrapConfig {
     readonly home: () => number;
     /** Fold the logical position back toward `home` once it drifts this many laps away. */
     readonly thresholdLaps: number;
+    /** @internal Notify the wrap owner when its logical coordinates fold. */
+    readonly onFold?: (shift: number) => void;
 }
 export interface BoundedScrollConfig {
     /** Logical row geometry for opt-in input providers (keyboard row steps). */
@@ -78,6 +80,8 @@ export interface BoundedScrollConfig {
     /** Infinite-loop config (carousel). When set, the logical position wraps by
      *  whole laps toward `home` instead of clamping to a maximum. */
     readonly wrap?: WrapConfig;
+    /** @internal Coordinate fold: shift core telemetry references before rendering. */
+    readonly onFold?: (shift: number) => void;
     /** Called synchronously per frame — triggers the 2-phase pipeline. */
     readonly onFrame: () => void;
     /** Called when scrolling becomes idle. */

package/dist/core/scroll.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Scroll Handling
+ * vlist — Scroll Handling
  *
  * Wheel interception for synchronous rendering, scroll idle detection,
  * and smooth scroll animation.

package/dist/core/sizes.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Size Cache
+ * vlist — Size Cache
  *
  * Float64Array prefix sums with O(1) offset lookups and O(log n) binary search.
  */

package/dist/core/state.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — EngineState
+ * vlist — EngineState
  *
  * Persistent singleton instantiated once during createVList().
  * All hot-path state lives in pre-allocated TypedArrays.
@@ -40,11 +40,23 @@ export interface EngineState {
     renderPending: boolean;
     initialized: boolean;
     destroyed: boolean;
+    /** Set when the render window hit its ceiling, which only a degenerate size spec does. */
+    windowClamped: boolean;
+    /** Latch, so the ceiling is reported once rather than once per frame. */
+    windowClampReported: boolean;
     prevAriaTotal: number;
     /**
      * Resize buffers when container changes. Cold path only.
      * Heuristic: capacity = ceil(containerSize / minItemSize) + overscan * 2
      */
+    /**
+     * Grow buffers to hold at least `needed` entries. Cold path only.
+     *
+     * The render window is the authority on how many entries are required. The
+     * container/minItemSize heuristic below is only an estimate, and for a size
+     * function there is no knowable minimum to estimate from.
+     */
+    ensureCapacity(needed: number): void;
     resizeCapacity(containerSize: number, minItemSize: number, overscan?: number): void;
     /** Reset to empty range sentinel. */
     clear(): void;

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * vlist v2 — Core Type Definitions
+ * vlist — Core Type Definitions
  *
  * Zero-allocation pipeline types. All hot-path state lives in TypedArrays
  * on the EngineState singleton — no intermediate object allocation.
@@ -58,77 +58,102 @@ export interface ElementPool {
     readonly size: number;
     clear(): void;
 }
-export interface PluginContext<T extends VListItem = VListItem> {
-    readonly dom: DOMStructure;
-    readonly sizeCache: SizeCache;
-    /**
-     * Logical scroll model boundary (RFC-012). Plugins read and write scroll
-     * position through this adapter rather than touching `getState().scrollPosition`
-     * or raw `scrollTop`/`scrollLeft`. Its pixel-equivalent view keeps existing
-     * pixel-based code paths working during the migration.
-     */
-    readonly scroll: ScrollAdapter;
-    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;
-    enableListboxRole(): void;
-    setSizeConfig(config: number | ((index: number) => number)): void;
+/**
+ * DOM structure, plus the element and role helpers that act on it.
+ */
+export interface DomCapability extends DOMStructure {
+    /** The rendered element for a layout index, honouring a plugin's override. */
+    renderedElement(index: number): HTMLElement | null;
+    /** Adopt the WAI-ARIA listbox roles. Selection and a11y call this; a list
+     * with neither stays a display-only `role="list"`. */
+    enableListbox(): void;
+}
+/**
+ * Logical scroll model boundary (RFC-012): the adapter's reads, plus the
+ * controls that write. Plugins go through this rather than touching
+ * `getState().scrollPosition` or raw `scrollTop`/`scrollLeft`.
+ */
+export interface ScrollCapability extends ScrollAdapter {
+    to(position: number): void;
+    /** Preserve synthetic motion during a measurement/anchor correction. */
+    shiftBy(delta: number): void;
+    smoothTo(target: number | (() => number), duration: number, easing?: (t: number) => number, onComplete?: () => void): void;
+    /** Cancel any in-flight smooth-scroll animation on the active handler. */
+    cancel(): void;
+    /** Commit an external position, render synchronously and schedule idle. */
+    commit(px: number): void;
     /** Install an external writer and disable default scroll/wheel listeners. */
-    setScrollSource(source: {
+    setSource(source: {
         write(px: number): void;
         onContentSize?(px: number): void;
     }): void;
-    /** Commit an external position, render synchronously and schedule configured idle. */
-    commitScroll(px: number): void;
+    setTarget(target: EventTarget): void;
     /** Request the bounded scroll handler in infinite-loop (wrap) mode (carousel). */
-    setBoundedWrap(config: import("./runway").WrapConfig): void;
-    setVirtualTotalFn(fn: () => number): void;
+    setBoundedWrap(config: import("./runway").WrapConfig, createHandler: (config: import("./runway").BoundedScrollConfig) => import("./runway").BoundedScrollHandler): void;
+    setToPosFn(fn: (index: number, sizeCache: import("./sizes").SizeCache, containerSize: number, totalItems: number, align: string) => number): void;
+    setToIndexFn(fn: (index: number, align: string, behavior?: string, duration?: number, easing?: (t: number) => number) => void | false): void;
+    onFrame(): void;
+    onIdle(): void;
+    disableResize(): void;
+}
+/**
+ * The item space: reads, mutations, and the inversion hooks a plugin installs
+ * to own them. One owner per hook — two plugins claiming the same one is how
+ * tree with data rendered nothing.
+ */
+export interface ItemsCapability<T extends VListItem = VListItem> {
+    all(): readonly T[];
+    at(index: number): T | undefined;
+    removeById(id: string | number): number;
+    insertAt(item: T, index: number): void;
+    setGetFn(fn: (index: number) => T | undefined): void;
+    setRemoveFn(fn: (id: string | number) => number): void;
+    setInsertFn(fn: (item: T, index: number) => void): void;
+    setUpdateFn(fn: (id: string | number, updates: Partial<T>) => boolean): void;
+    setIndexByIdFn(fn: (id: string | number) => number): void;
+    /** The public total. Also feeds `aria-setsize`. */
+    setTotalFn(fn: () => number): void;
     setIndexMapFn(fn: (renderIndex: number) => 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;
-    /** Preserve synthetic motion during a measurement/anchor correction. */
-    shiftScroll(delta: number): void;
-    smoothScrollTo(target: number | (() => number), duration: number, easing?: (t: number) => number, onComplete?: () => void): void;
-    /** Cancel any in-flight smooth-scroll animation on the active handler. */
-    cancelScroll(): 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;
-    setGetIndexByIdFn(fn: (id: string | number) => number): void;
-    getRenderedElement(index: number): HTMLElement | null;
-    setNavConfig(config: {
+}
+/** The size cache and the spec behind it. */
+export interface SizesCapability {
+    readonly cache: SizeCache;
+    readonly rawSpec: number | ((index: number, ...args: unknown[]) => number);
+    /** Replace the size spec. `gap` is the spacing baked into the spec, so the
+     * cache can keep excluding one trailing gap from the total; omit it when the
+     * spec carries none (table's fixed row height, for instance). */
+    setConfig(config: number | ((index: number) => number), gap?: number): void;
+    rebuild(): void;
+}
+/** The render pipeline: run it, replace it, or describe item state to it. */
+export interface RenderCapability {
+    force(): void;
+    ifNeeded(): void;
+    contentSize(size: number): void;
+    setFn(renderIfNeeded: () => void, forceRender: () => void): void;
+    setStateFn(fn: (index: number, state: ItemState) => void): void;
+    getStateFn(): ((index: number, state: ItemState) => void) | null;
+}
+/** The cross-plugin method bus and the shared event handlers. */
+export interface HooksCapability {
+    /** Register a public method on the list. Public names are a contract:
+     * a second claimant throws. Underscore names are the internal protocol. */
+    method(name: string, fn: Function): void;
+    get(name: string): Function | undefined;
+    onClick(handler: (event: MouseEvent) => void): void;
+    onKeydown(handler: (event: KeyboardEvent) => void): void;
+    onDestroy(handler: () => void): void;
+}
+/** Keyboard navigation geometry, shared between layout plugins and selection. */
+export interface NavCapability {
+    set(config: {
         total?: () => number;
         ud?: number;
         lr?: number;
         scrollIndex?: (itemIndex: number) => number;
         navigate?: (currentIndex: number, key: string, total: number) => number;
     }): void;
-    getNavConfig(): {
+    get(): {
         ud: number;
         lr: number;
         scrollIndex: ((itemIndex: number) => number) | null;
@@ -136,10 +161,39 @@ export interface PluginContext<T extends VListItem = VListItem> {
         total: (() => number) | null;
     };
 }
-export interface VListPlugin<T extends VListItem = VListItem> {
+/**
+ * What a plugin receives in `setup()`. Grouped by capability rather than laid
+ * out flat: the flat form had fifty members with no map from a member to the
+ * part of the engine it reached.
+ */
+export interface PluginContext<T extends VListItem = VListItem> {
+    readonly dom: DomCapability;
+    readonly scroll: ScrollCapability;
+    readonly items: ItemsCapability<T>;
+    readonly sizes: SizesCapability;
+    readonly render: RenderCapability;
+    readonly hooks: HooksCapability;
+    readonly nav: NavCapability;
+    readonly pool: ElementPool;
+    readonly config: ResolvedConfig;
+    readonly emitter: Emitter<import("../types").VListEvents<T>>;
+    readonly template: ItemTemplate<T>;
+    getState(): EngineState;
+}
+export interface VListPlugin<T extends VListItem = VListItem, M = {}> {
     readonly name: string;
     readonly priority?: number;
     readonly conflicts?: readonly string[];
+    /**
+     * Cold path: reject a list configuration this plugin cannot support.
+     *
+     * Runs before setup and outside its catch, so throwing here reaches the
+     * caller. A throw from `setup()` cannot: it is reported as an `error` event
+     * so that one plugin's failure does not stop the others, which is the right
+     * behaviour for a fault and the wrong one for a configuration the plugin has
+     * already decided it cannot serve.
+     */
+    validateConfig?(config: ResolvedConfig): void;
     /** Cold path: one-time wiring during createVList(). */
     setup?(ctx: PluginContext<T>): void;
     /** Hot path: compiled into linear arrays, iterated per frame. */
@@ -152,7 +206,25 @@ export interface VListPlugin<T extends VListItem = VListItem> {
     };
     /** Cleanup on destroy. */
     destroy?(): void;
+    /**
+     * Phantom marker: the methods this plugin adds to the list instance.
+     * Never set at runtime; `createVList` reads it to type the returned list.
+     */
+    readonly __methods?: M;
 }
+/** @internal Turns a union into an intersection. */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * @internal The method map a single plugin declares. The item type is matched
+ * loosely: a plugin typed for a specific item is not assignable to
+ * `VListPlugin<VListItem, ...>` under strict function types.
+ */
+type MethodsOf<P> = P extends VListPlugin<any, infer M> ? M : {};
+/**
+ * The methods a plugin array adds to the list instance. A plugin that declares
+ * no methods contributes nothing, so `createVList(config)` stays exactly `VList<T>`.
+ */
+export type PluginMethods<P extends readonly unknown[]> = UnionToIntersection<MethodsOf<P[number]>>;
 export interface VList<T extends VListItem = VListItem> {
     readonly element: HTMLElement;
     readonly items: readonly T[];
@@ -176,7 +248,6 @@ export interface VList<T extends VListItem = VListItem> {
     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;
@@ -192,4 +263,5 @@ export interface CreateVListConfig<T extends VListItem = VListItem> {
     /** Defer initial render to the next animation frame. */
     defer?: boolean;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/core/velocity.d.ts

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

package/dist/index.d.ts

@@ -12,7 +12,9 @@ export { createVList } from "./core/create";
 export { scrollbar } from "./plugins/scrollbar";
 export type { ScrollbarPluginConfig } from "./plugins/scrollbar";
 export { grid } from "./plugins/grid";
+export type { GridPluginConfig } from "./plugins/grid";
 export { a11y } from "./plugins/a11y";
+export type { A11yPluginConfig } from "./plugins/a11y";
 export { selection } from "./plugins/selection";
 export type { SelectionPluginConfig } from "./plugins/selection";
 export { page } from "./plugins/page";
@@ -39,10 +41,23 @@ export { search, DEFAULT_SEARCH_TEXT } from "./plugins/search";
 export type { SearchPluginConfig, SearchText } from "./plugins/search";
 export { carousel, registerPreset, getPreset, resolvePreset, full, hero, heroCenter, multi, uncontained } from "./plugins/carousel";
 export type { CarouselPluginConfig, CarouselVariant, CarouselDirection, CarouselState, SlotConfig, SlotConfigResolver, TextFade } from "./plugins/carousel";
+export type { AutosizeMethods } from "./plugins/autosize";
+export type { CarouselMethods } from "./plugins/carousel";
+export type { DataMethods } from "./plugins/data";
+export type { GridMethods } from "./plugins/grid";
+export type { GroupsMethods } from "./plugins/groups";
+export type { MasonryMethods } from "./plugins/masonry";
+export type { ScrollbarMethods } from "./plugins/scrollbar";
+export type { SearchMethods } from "./plugins/search";
+export type { SelectionMethods } from "./plugins/selection";
+export type { SnapshotsMethods } from "./plugins/snapshots";
+export type { SortableMethods } from "./plugins/sortable";
+export type { TableMethods } from "./plugins/table";
+export type { TreeMethods } from "./plugins/tree";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";
 export { rebuild } from "./utils/rebuild";
 export type { RebuildOptions } from "./utils/rebuild";
-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, TreeState, } from "./types";
-export type { Axis, AxisConfig, VList, VListPlugin, PluginContext, CreateVListConfig, CompiledHooks, ResolvedConfig, DOMStructure, ElementPool, } from "./core/types";
+export type { VListItem, VListEvents, ItemConfig, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarPadding, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, GridConfig, MasonryConfig, GroupsConfig, GroupHeaderConfig, GridSizeContext, GridHeightContext, TreeState, } from "./types";
+export type { Axis, AxisConfig, VList, VListPlugin, PluginMethods, PluginContext, CreateVListConfig, CompiledHooks, ResolvedConfig, DOMStructure, ElementPool, } from "./core/types";
 //# sourceMappingURL=index.d.ts.map