vlist 3.0.0-next.3 → 3.0.0-next.4

package/dist/core/fold.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wrap-mode fold: re-key mounted rows and shift the render window.
+ *
+ * A fold moves every virtual index by whole laps; the nodes and their paint
+ * positions are unchanged. Re-keying the map (and the `id` that encodes the
+ * virtual index) lets the next commit find them instead of releasing,
+ * re-templating and re-inserting the viewport. Lives here — not in pipeline
+ * or create — so a native list that never wraps does not import it (runway
+ * is pulled by carousel). The synthetic handler imports it because wrap
+ * folds for that entry go through commit(), not wrapRebase; putting the
+ * import in create.ts would charge every native list.
+ *
+ * Shifted with the fold: the typed-array window (`shiftWindow`), carousel
+ * `intendedVi`, velocity `_lp`, `lastEventScrollPos`, `id` (virtual index),
+ * `aria-activedescendant` (resolved to the same node after its id rewrite),
+ * `oddClass` when `indexShift` is odd (stripe is virtual-index parity).
+ * Fold-invariant: `data-index` / `aria-posinset` (public index), selection
+ * `focusedIndex` (data space under `indexMap`), snapshots (`dataIndex`).
+ */
+import type { EngineState } from "./state";
+import type { WrapConfig } from "./runway";
+/**
+ * Move every `rendered` key by `-indexShift` without touching the DOM tree.
+ * `data-index` / `aria-posinset` carry the public index and stay put.
+ *
+ * `aria-activedescendant` is resolved after every id rewrite: a uniform shift
+ * can make two nodes share an id mid-loop, so rewriting the attribute from a
+ * reconstructed old id in that window can point at the wrong node.
+ */
+export declare function rekeyRendered(rendered: Map<number, HTMLElement>, indexShift: number, prefix: string, content: HTMLElement, oddClass?: string): void;
+/**
+ * Shift the committed render window by whole laps after a wrap fold.
+ *
+ * Virtual indices and offsets move with the logical origin; shifting them
+ * (and `prevBaseOffset`) keeps the range-unchanged fast path honest so the
+ * next frame does not treat identical paint as a new window.
+ */
+export declare function shiftWindow(state: EngineState, indexShift: number, pixelShift: number): void;
+/**
+ * How many whole laps to fold by, for a drift from home measured in laps; 0 for none.
+ *
+ * An owner that folds every lap (threshold 1) keeps its position in
+ * `[home, home + lap)`: the floor, so that leaving the home lap backwards folds
+ * at once, exactly as leaving it forwards does. Truncation folded forwards on
+ * leaving the lap but backwards only a whole lap later — a carousel could rest in
+ * the lap before home at index 0, where a leading peek needs index -1: a blank
+ * peek, then a pop. A larger threshold keeps the symmetric dead zone it always had.
+ */
+export declare function wrapLaps(driftLaps: number, threshold: number): number;
+/** Re-key mounted rows and shift window state for a wrap fold, before the next render. */
+export declare function applyWrapFold(wrap: WrapConfig, shift: number, state: EngineState, content: HTMLElement, rendered: Map<number, HTMLElement> | undefined, prefix: string, oddClass?: string): void;
+//# sourceMappingURL=fold.d.ts.map

package/dist/core/pool.d.ts

@@ -2,7 +2,14 @@
  * vlist — Element Pool
  *
  * acquire() = pop or create, release() = reset + push.
- * Max pool size: 100.
+ *
+ * No fixed cap. A cap of 100 dropped a window of 300 cells on a jump, and the
+ * next frame cloned 200 of them again. The pool still grows to the most rows
+ * that were on screen at once, and that peak does not fall on its own:
+ * release() only pushes, so a list that shrinks keeps every spare node until
+ * trim() drops them back to the number currently mounted. Core trims when
+ * scrolling has gone idle, and after a data change that is not mid-scroll, so
+ * a jump during a gesture still reuses the previous window.
  */
 import type { ElementPool } from "./types";
 export declare function createPool(classPrefix: string): ElementPool;

package/dist/core/runway.d.ts

@@ -56,7 +56,13 @@ export interface BoundedScrollHandler extends ScrollHandler {
 export interface WrapConfig {
     /** Current lap period in virtual px (`realTotal × stepSize`). */
     readonly lapSize: () => number;
-    /** Logical position to fold back toward (e.g. the middle cycle). */
+    /**
+     * Real items in one lap (e.g. the carousel's `realTotal`). The wrap handler
+     * uses this to re-key mounted elements on a fold so the same DOM nodes
+     * survive the virtual-index shift — only the key changed; paint did not.
+     */
+    readonly itemsPerLap: () => number;
+    /** Logical position to fold back toward (the home lap). */
     readonly home: () => number;
     /** Fold the logical position back toward `home` once it drifts this many laps away. */
     readonly thresholdLaps: number;
@@ -80,6 +86,22 @@ 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;
+    /**
+     * Mounted row map. A wrap fold re-keys it in place so phase 2 finds the
+     * same nodes; omitted when the handler is constructed without a viewport.
+     */
+    readonly rendered?: Map<number, HTMLElement>;
+    /**
+     * Class prefix for rewriting `id` / `aria-activedescendant` on a wrap fold.
+     * Passed explicitly — a prefix containing `-content` cannot be recovered
+     * from the content element's class name.
+     */
+    readonly classPrefix?: string;
+    /**
+     * Stripe class (`{prefix}-item--odd`). Re-toggled on a wrap fold when
+     * `indexShift` is odd, so virtual-index parity survives the re-key.
+     */
+    readonly oddClass?: string;
     /** @internal Coordinate fold: shift core telemetry references before rendering. */
     readonly onFold?: (shift: number) => void;
     /** Called synchronously per frame — triggers the 2-phase pipeline. */

package/dist/core/types.d.ts

@@ -56,6 +56,8 @@ export interface ElementPool {
     acquire(): HTMLElement;
     release(element: HTMLElement): void;
     readonly size: number;
+    /** Drop spare nodes until at most `keep` remain. Does not touch mounted rows. */
+    trim(keep: number): void;
     clear(): void;
 }
 /**
@@ -152,6 +154,16 @@ export interface NavCapability {
         lr?: number;
         scrollIndex?: (itemIndex: number) => number;
         navigate?: (currentIndex: number, key: string, total: number) => number;
+        /**
+         * Bring this navigation / focus index into view, the layout plugin's way.
+         * The index is the same space as `nav.total` (carousel: logical item
+         * index; grid: item index) — not a size-cache index and not a layout
+         * index that counts group headers or carousel laps.
+         * `selectNext` / `selectPrevious` call this when present so a plugin that
+         * owns motion (carousel snap, current virtual lap) reveals the item
+         * without selection falling back to a raw size-cache offset.
+         */
+        reveal?: (index: number) => void;
     }): void;
     get(): {
         ud: number;
@@ -159,6 +171,12 @@ export interface NavCapability {
         scrollIndex: ((itemIndex: number) => number) | null;
         navigate: ((currentIndex: number, key: string, total: number) => number) | null;
         total: (() => number) | null;
+        /**
+         * Always present on the returned object: the owner's reveal, or `null`
+         * when no plugin published one. Plugin authors must read this property
+         * rather than treating a missing key as "no owner".
+         */
+        reveal: ((index: number) => void) | null;
     };
 }
 /**