react-virtual-renderer 1.1.2 → 1.1.4

package/dist/core/GridLayoutEngine.js

@@ -0,0 +1,153 @@
+/**
+ * Incremental, append-only masonry/grid position engine.
+ *
+ * PERFORMANCE: the previous VirtualGrid recomputed EVERY item's
+ * position from scratch (a full O(n) pass) whenever the items array
+ * changed identity - including the ordinary infinite-scroll case of
+ * appending 20 new items to an existing 50,000-item masonry board,
+ * which turned a single "load more" into an O(n) pass over everything
+ * already laid out.
+ *
+ * This engine keeps running state - per-column heights for masonry, a
+ * running row-offset for dynamic-height grid rows - and only computes
+ * positions for items it hasn't seen before. Appending k new items
+ * costs O(k), never O(n + k). A full reset (columns/width/gap/layout
+ * changed) is the only path that pays an O(n) cost, same as any other
+ * virtualization library when the layout itself is invalidated.
+ *
+ * NOTE ON VIRTUAL_GRID'S FAST PATH: this engine is only used for
+ * masonry layout, or grid layout with a per-index rowHeight function.
+ * Plain grid layout with a fixed numeric rowHeight never touches this
+ * file at all - VirtualGrid computes those positions with direct O(1)
+ * arithmetic and no array (see VirtualGrid.tsx), which is faster still.
+ */
+export class GridLayoutEngine {
+    constructor() {
+        Object.defineProperty(this, "positions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "colHeights", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "rowOffsets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: [0]
+        });
+        Object.defineProperty(this, "currentRowMax", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "maxBottom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "params", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    sameParams(p) {
+        if (!this.params)
+            return false;
+        return (this.params.cols === p.cols &&
+            this.params.colWidth === p.colWidth &&
+            this.params.gap === p.gap &&
+            this.params.layout === p.layout &&
+            this.params.rowHeight === p.rowHeight);
+    }
+    reset(p) {
+        this.positions = [];
+        this.colHeights = new Array(p.cols).fill(0);
+        this.rowOffsets = [0];
+        this.currentRowMax = 0;
+        this.maxBottom = 0;
+        this.params = p;
+    }
+    sizeOf(rowHeight, index) {
+        return typeof rowHeight === 'function' ? rowHeight(index) : rowHeight;
+    }
+    /** Masonry: place each new item in whichever column is currently shortest. */
+    appendMasonry(fromIndex, itemCount, p) {
+        for (let i = fromIndex; i < itemCount; i++) {
+            const h = this.sizeOf(p.rowHeight, i);
+            let minCol = 0;
+            for (let c = 1; c < p.cols; c++) {
+                if (this.colHeights[c] < this.colHeights[minCol])
+                    minCol = c;
+            }
+            const x = minCol * (p.colWidth + p.gap);
+            const y = this.colHeights[minCol];
+            this.positions.push({ x, y, width: p.colWidth, height: h });
+            this.colHeights[minCol] += h + p.gap;
+            if (y + h > this.maxBottom)
+                this.maxBottom = y + h;
+        }
+    }
+    /**
+     * Grid with per-index rowHeight function: rows advance by the
+     * tallest item seen in that row so far. `rowOffsets[r]` is only
+     * ever written once (when row r's first item is appended), reading
+     * `currentRowMax` accumulated while row r-1 was being built - so
+     * this stays correct across multiple incremental append() calls,
+     * not just a single full pass.
+     */
+    appendGrid(fromIndex, itemCount, p) {
+        for (let i = fromIndex; i < itemCount; i++) {
+            const row = Math.floor(i / p.cols);
+            const col = i % p.cols;
+            const h = this.sizeOf(p.rowHeight, i);
+            while (this.rowOffsets.length <= row) {
+                const prevRow = this.rowOffsets.length - 1;
+                const gapBefore = prevRow >= 0 ? p.gap : 0;
+                this.rowOffsets.push(this.rowOffsets[prevRow] + this.currentRowMax + gapBefore);
+                this.currentRowMax = 0;
+            }
+            const y = this.rowOffsets[row];
+            const x = col * (p.colWidth + p.gap);
+            this.positions.push({ x, y, width: p.colWidth, height: h });
+            this.currentRowMax = Math.max(this.currentRowMax, h);
+            if (y + h > this.maxBottom)
+                this.maxBottom = y + h;
+        }
+    }
+    /**
+     * Ensure positions exist for `itemCount` items under the given
+     * params. Existing entries are reused by reference - callers get
+     * back the same array instances for indices they've already seen,
+     * which keeps this cheap to call on every render.
+     */
+    sync(itemCount, p) {
+        if (!this.sameParams(p) || itemCount < this.positions.length) {
+            this.reset(p);
+        }
+        const from = this.positions.length;
+        if (from < itemCount) {
+            if (p.layout === 'masonry') {
+                this.appendMasonry(from, itemCount, p);
+            }
+            else {
+                this.appendGrid(from, itemCount, p);
+            }
+        }
+        return this.positions;
+    }
+    /** O(1) - tracked incrementally as items are appended, never rescanned. */
+    getTotalHeight() {
+        return this.maxBottom;
+    }
+}
+//# sourceMappingURL=GridLayoutEngine.js.map

package/dist/core/GridLayoutEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GridLayoutEngine.js","sourceRoot":"","sources":["../../src/core/GridLayoutEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/GroupedListEngine.d.ts

@@ -0,0 +1,21 @@
+export interface GroupDefinition<T> {
+    items: T[];
+    getGroupKey: (item: T) => string;
+}
+export interface FlattenedRow<T> {
+    type: 'header' | 'item';
+    groupKey: string;
+    item?: T;
+    itemIndex?: number;
+}
+/**
+ * Flattens grouped data into one virtualizable array with header rows
+ * interspersed - VirtualList treats a header as just another row, no
+ * special-casing in the engine. Your existing `stickyIndices` prop is
+ * what actually pins headers visually while scrolling.
+ */
+export declare function flattenGroups<T>({ items, getGroupKey }: GroupDefinition<T>): {
+    rows: FlattenedRow<T>[];
+    stickyIndices: number[];
+};
+//# sourceMappingURL=GroupedListEngine.d.ts.map

package/dist/core/GroupedListEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupedListEngine.d.ts","sourceRoot":"","sources":["../../src/core/GroupedListEngine.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;IAC1E,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;CAC3B,CAgBA"}

package/dist/core/GroupedListEngine.js

@@ -0,0 +1,22 @@
+/**
+ * Flattens grouped data into one virtualizable array with header rows
+ * interspersed - VirtualList treats a header as just another row, no
+ * special-casing in the engine. Your existing `stickyIndices` prop is
+ * what actually pins headers visually while scrolling.
+ */
+export function flattenGroups({ items, getGroupKey }) {
+    const rows = [];
+    const stickyIndices = [];
+    let lastKey = null;
+    items.forEach((item, itemIndex) => {
+        const key = getGroupKey(item);
+        if (key !== lastKey) {
+            stickyIndices.push(rows.length);
+            rows.push({ type: 'header', groupKey: key });
+            lastKey = key;
+        }
+        rows.push({ type: 'item', groupKey: key, item, itemIndex });
+    });
+    return { rows, stickyIndices };
+}
+//# sourceMappingURL=GroupedListEngine.js.map

package/dist/core/GroupedListEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupedListEngine.js","sourceRoot":"","sources":["../../src/core/GroupedListEngine.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,EAAE,KAAK,EAAE,WAAW,EAAsB;IAIvE,MAAM,IAAI,GAAsB,EAAE,CAAC;IACnC,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAElC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;YAC7C,OAAO,GAAG,GAAG,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;AACnC,CAAC"}

package/dist/core/ListController.d.ts

@@ -0,0 +1,31 @@
+export interface ListControllerOptions {
+    itemCount: number;
+    estimatedItemSize: number;
+    overscan?: number;
+}
+type Listener = () => void;
+/**
+ * Framework-agnostic controller: owns the engine + scroll state,
+ * exposes subscribe/getSnapshot. React binds via useSyncExternalStore;
+ * Vue could bind via a reactive ref; Svelte via a store - the engine
+ * itself never needs to know any of that exists.
+ */
+export declare class ListController {
+    private engine;
+    private scrollOffset;
+    private containerSize;
+    private itemCount;
+    private overscan;
+    private listeners;
+    constructor({ itemCount, estimatedItemSize, overscan }: ListControllerOptions);
+    subscribe: (listener: Listener) => () => boolean;
+    private notify;
+    setScrollOffset(offset: number): void;
+    setContainerSize(size: number): void;
+    setItemCount(count: number): void;
+    recordItemSize(index: number, size: number): void;
+    getSnapshot(): import("..").ItemSize[];
+    getTotalSize(): number;
+}
+export {};
+//# sourceMappingURL=ListController.d.ts.map

package/dist/core/ListController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListController.d.ts","sourceRoot":"","sources":["../../src/core/ListController.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B;;;;;GAKG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAuB;gBAE5B,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAY,EAAE,EAAE,qBAAqB;IAOjF,SAAS,GAAI,UAAU,QAAQ,mBAG7B;IAEF,OAAO,CAAC,MAAM;IAEd,eAAe,CAAC,MAAM,EAAE,MAAM;IAC9B,gBAAgB,CAAC,IAAI,EAAE,MAAM;IAC7B,YAAY,CAAC,KAAK,EAAE,MAAM;IAC1B,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAE1C,WAAW;IAIX,YAAY;CACf"}

package/dist/core/ListController.js

@@ -0,0 +1,71 @@
+// packages/core/src/ListController.ts
+import { VirtualizationEngine } from './VirtualizationEngine';
+/**
+ * Framework-agnostic controller: owns the engine + scroll state,
+ * exposes subscribe/getSnapshot. React binds via useSyncExternalStore;
+ * Vue could bind via a reactive ref; Svelte via a store - the engine
+ * itself never needs to know any of that exists.
+ */
+export class ListController {
+    constructor({ itemCount, estimatedItemSize, overscan = 5 }) {
+        Object.defineProperty(this, "engine", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "scrollOffset", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "containerSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "itemCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "overscan", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "subscribe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (listener) => {
+                this.listeners.add(listener);
+                return () => this.listeners.delete(listener);
+            }
+        });
+        this.engine = new VirtualizationEngine(estimatedItemSize);
+        this.itemCount = itemCount;
+        this.overscan = overscan;
+        this.engine.setItemCount(itemCount);
+    }
+    notify() { this.listeners.forEach((l) => l()); }
+    setScrollOffset(offset) { this.scrollOffset = offset; this.notify(); }
+    setContainerSize(size) { this.containerSize = size; this.notify(); }
+    setItemCount(count) { this.itemCount = count; this.engine.setItemCount(count); this.notify(); }
+    recordItemSize(index, size) { this.engine.recordItemSize(index, size); this.notify(); }
+    getSnapshot() {
+        return this.engine.getVisibleItems(this.scrollOffset, this.containerSize, this.itemCount, this.overscan);
+    }
+    getTotalSize() { return this.engine.getTotalSize(); }
+}
+//# sourceMappingURL=ListController.js.map

package/dist/core/ListController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListController.js","sourceRoot":"","sources":["../../src/core/ListController.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAU9D;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAQvB,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,GAAG,CAAC,EAAyB;QAPzE;;;;;WAA6B;QAC7B;;;;mBAAe,CAAC;WAAC;QACjB;;;;mBAAgB,CAAC;WAAC;QAClB;;;;;WAAkB;QAClB;;;;;WAAiB;QACjB;;;;mBAAY,IAAI,GAAG,EAAY;WAAC;QASxC;;;;mBAAY,CAAC,QAAkB,EAAE,EAAE;gBAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACjD,CAAC;WAAC;QATE,IAAI,CAAC,MAAM,GAAG,IAAI,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAOO,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAExD,eAAe,CAAC,MAAc,IAAI,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9E,gBAAgB,CAAC,IAAY,IAAI,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5E,YAAY,CAAC,KAAa,IAAI,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACvG,cAAc,CAAC,KAAa,EAAE,IAAY,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAEvG,WAAW;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7G,CAAC;IAED,YAAY,KAAK,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;CACxD"}

package/dist/core/MeasurementSystem.d.ts

@@ -1,19 +1,54 @@
 export declare class MeasurementSystem {
     private resizeObserver;
     private measurements;
+    /**
+     * NEW (additive): separate cache for width measurements, used
+     * only when an element is observed in 'horizontal' axis mode.
+     * Existing height-only consumers never populate or read this.
+     */
+    private widthMeasurements;
     private observedElements;
+    /**
+     * NEW (additive): tracks which axis each observed element
+     * should report on. Defaults to 'height' to preserve existing
+     * behavior for every caller that doesn't pass an axis.
+     */
+    private observedAxis;
     private pendingUpdates;
+    /**
+     * NEW (additive): pending width updates, flushed alongside
+     * height updates on the same RAF batch.
+     */
+    private pendingWidthUpdates;
     private rafId;
     private onMeasure;
+    /**
+     * NEW (additive): optional width callback. If not provided,
+     * width measurements are still tracked internally (available
+     * via getWidthMeasurement) but no callback fires - existing
+     * callers that only pass onMeasure are unaffected.
+     */
+    private onMeasureWidth;
     constructor();
     /**
-     * Start measuring container
+     * Start measuring container.
+     *
+     * `onMeasureWidth` is optional and additive: existing callers
+     * that only pass `onMeasure` keep working exactly as before
+     * (height-only). Pass `onMeasureWidth` to also receive width
+     * updates for elements observed in 'width' axis mode.
      */
-    startMeasuring(container: HTMLElement, onMeasure: (index: number, size: number) => void): void;
+    startMeasuring(container: HTMLElement, onMeasure: (index: number, size: number) => void, onMeasureWidth?: (index: number, size: number) => void): void;
     /**
-     * Observe item
+     * Observe item.
+     *
+     * `axis` is optional and additive, defaulting to 'height' so
+     * every existing call site (which never passes a third arg)
+     * behaves exactly as before. Pass axis='width' for elements in
+     * a horizontal-scrolling list so contentRect.width is measured
+     * instead of contentRect.height.
      */
-    observeItem(index: number, element: HTMLElement): void;
+    observeItem(index: number, element: HTMLElement, axis?: 'height' | 'width'): void;
     /**
      * Unobserve item
      */
@@ -27,15 +62,28 @@ export declare class MeasurementSystem {
      */
     private flushPendingUpdates;
     /**
-     * Fallback measurement
+     * Fallback measurement.
+     *
+     * `axis` is optional and additive, defaulting to 'height' to
+     * preserve existing behavior for all current call sites.
      */
-    syncMeasure(index: number, element: HTMLElement): void;
+    syncMeasure(index: number, element: HTMLElement, axis?: 'height' | 'width'): void;
     /**
      * Preserve measurements
      */
     stopMeasuring(): void;
     getMeasurement(index: number): number | undefined;
+    /**
+     * NEW (additive): mirrors getMeasurement() but for the width
+     * cache. Returns undefined for any index never observed in
+     * 'width' axis mode.
+     */
+    getWidthMeasurement(index: number): number | undefined;
     getAllMeasurements(): Map<number, number>;
+    /**
+     * NEW (additive): mirrors getAllMeasurements() for widths.
+     */
+    getAllWidthMeasurements(): Map<number, number>;
     clearPending(): void;
     /**
      * Explicit cache clear

package/dist/core/MeasurementSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeasurementSystem.d.ts","sourceRoot":"","sources":["../../src/core/MeasurementSystem.ts"],"names":[],"mappings":"AAAA,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,cAAc,CAA+B;IAErD,OAAO,CAAC,YAAY,CAA6B;IAEjD,OAAO,CAAC,gBAAgB,CACe;IAEvC,OAAO,CAAC,cAAc,CACQ;IAE9B,OAAO,CAAC,KAAK,CAAuB;IAEpC,OAAO,CAAC,SAAS,CAEC;;IAclB;;OAEG;IACH,cAAc,CACV,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,KACX,IAAI,GACV,IAAI;IA4BP;;OAEG;IACH,WAAW,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,IAAI;IAmBP;;OAEG;IACH,aAAa,CACT,OAAO,EAAE,WAAW,GACrB,IAAI;IAUP;;OAEG;IACH,OAAO,CAAC,YAAY,CAwClB;IAEF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;OAEG;IACH,WAAW,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,IAAI;IA+BP;;OAEG;IACH,aAAa,IAAI,IAAI;IAYrB,cAAc,CACV,KAAK,EAAE,MAAM,GACd,MAAM,GAAG,SAAS;IAMrB,kBAAkB,IAAI,GAAG,CACrB,MAAM,EACN,MAAM,CACT;IAMD,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB,OAAO,IAAI,IAAI;CAWlB"}
+{"version":3,"file":"MeasurementSystem.d.ts","sourceRoot":"","sources":["../../src/core/MeasurementSystem.ts"],"names":[],"mappings":"AAAA,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,cAAc,CAA+B;IAErD,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,OAAO,CAAC,gBAAgB,CACe;IAEvC;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAC+B;IAEnD,OAAO,CAAC,cAAc,CACQ;IAE9B;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CACG;IAE9B,OAAO,CAAC,KAAK,CAAuB;IAEpC,OAAO,CAAC,SAAS,CAEC;IAElB;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAEJ;;IAclB;;;;;;;OAOG;IACH,cAAc,CACV,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,KACX,IAAI,EACT,cAAc,CAAC,EAAE,CACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,KACX,IAAI,GACV,IAAI;IA6BP;;;;;;;;OAQG;IACH,WAAW,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE,QAAQ,GAAG,OAAkB,GACpC,IAAI;IAsBP;;OAEG;IACH,aAAa,CACT,OAAO,EAAE,WAAW,GACrB,IAAI;IAYP;;OAEG;IACH,OAAO,CAAC,YAAY,CAkElB;IAEF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;;;;OAKG;IACH,WAAW,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE,QAAQ,GAAG,OAAkB,GACpC,IAAI;IAwCP;;OAEG;IACH,aAAa,IAAI,IAAI;IAarB,cAAc,CACV,KAAK,EAAE,MAAM,GACd,MAAM,GAAG,SAAS;IAMrB;;;;OAIG;IACH,mBAAmB,CACf,KAAK,EAAE,MAAM,GACd,MAAM,GAAG,SAAS;IAIrB,kBAAkB,IAAI,GAAG,CACrB,MAAM,EACN,MAAM,CACT;IAMD;;OAEG;IACH,uBAAuB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAI9C,YAAY,IAAI,IAAI;IAKpB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAKzB,OAAO,IAAI,IAAI;CAgBlB"}

package/dist/core/MeasurementSystem.js

@@ -12,18 +12,50 @@ export class MeasurementSystem {
             writable: true,
             value: new Map()
         });
+        /**
+         * NEW (additive): separate cache for width measurements, used
+         * only when an element is observed in 'horizontal' axis mode.
+         * Existing height-only consumers never populate or read this.
+         */
+        Object.defineProperty(this, "widthMeasurements", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "observedElements", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new WeakMap()
         });
+        /**
+         * NEW (additive): tracks which axis each observed element
+         * should report on. Defaults to 'height' to preserve existing
+         * behavior for every caller that doesn't pass an axis.
+         */
+        Object.defineProperty(this, "observedAxis", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new WeakMap()
+        });
         Object.defineProperty(this, "pendingUpdates", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Map()
         });
+        /**
+         * NEW (additive): pending width updates, flushed alongside
+         * height updates on the same RAF batch.
+         */
+        Object.defineProperty(this, "pendingWidthUpdates", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "rafId", {
             enumerable: true,
             configurable: true,
@@ -36,6 +68,18 @@ export class MeasurementSystem {
             writable: true,
             value: null
         });
+        /**
+         * NEW (additive): optional width callback. If not provided,
+         * width measurements are still tracked internally (available
+         * via getWidthMeasurement) but no callback fires - existing
+         * callers that only pass onMeasure are unaffected.
+         */
+        Object.defineProperty(this, "onMeasureWidth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         /**
          * ResizeObserver callback
          */
@@ -50,6 +94,16 @@ export class MeasurementSystem {
                     if (index === undefined) {
                         continue;
                     }
+                    const axis = this.observedAxis.get(element) ?? 'height';
+                    if (axis === 'width') {
+                        const widthSize = Math.round(entry.contentRect.width);
+                        if (this.widthMeasurements.get(index) !==
+                            widthSize) {
+                            this.widthMeasurements.set(index, widthSize);
+                            this.pendingWidthUpdates.set(index, widthSize);
+                        }
+                        continue;
+                    }
                     const size = Math.round(entry.contentRect.height);
                     if (this.measurements.get(index) === size) {
                         continue;
@@ -67,10 +121,16 @@ export class MeasurementSystem {
         }
     }
     /**
-     * Start measuring container
+     * Start measuring container.
+     *
+     * `onMeasureWidth` is optional and additive: existing callers
+     * that only pass `onMeasure` keep working exactly as before
+     * (height-only). Pass `onMeasureWidth` to also receive width
+     * updates for elements observed in 'width' axis mode.
      */
-    startMeasuring(container, onMeasure) {
+    startMeasuring(container, onMeasure, onMeasureWidth) {
         this.onMeasure = onMeasure;
+        this.onMeasureWidth = onMeasureWidth ?? null;
         const items = container.querySelectorAll('[data-virtualize-index]');
         items.forEach((item) => {
             const indexAttr = item.dataset.virtualizeIndex;
@@ -82,14 +142,21 @@ export class MeasurementSystem {
         });
     }
     /**
-     * Observe item
+     * Observe item.
+     *
+     * `axis` is optional and additive, defaulting to 'height' so
+     * every existing call site (which never passes a third arg)
+     * behaves exactly as before. Pass axis='width' for elements in
+     * a horizontal-scrolling list so contentRect.width is measured
+     * instead of contentRect.height.
      */
-    observeItem(index, element) {
+    observeItem(index, element, axis = 'height') {
         element.dataset.virtualizeIndex =
             String(index);
         this.observedElements.set(element, index);
+        this.observedAxis.set(element, axis);
         this.resizeObserver?.observe(element);
-        this.syncMeasure(index, element);
+        this.syncMeasure(index, element, axis);
     }
     /**
      * Unobserve item
@@ -97,6 +164,7 @@ export class MeasurementSystem {
     unobserveItem(element) {
         this.resizeObserver?.unobserve(element);
         this.observedElements.delete(element);
+        this.observedAxis.delete(element);
     }
     /**
      * Batch updates using RAF
@@ -111,19 +179,34 @@ export class MeasurementSystem {
                     this.onMeasure?.(index, size);
                 });
                 this.pendingUpdates.clear();
+                this.pendingWidthUpdates.forEach((size, index) => {
+                    this.onMeasureWidth?.(index, size);
+                });
+                this.pendingWidthUpdates.clear();
                 this.rafId = null;
             });
     }
     /**
-     * Fallback measurement
+     * Fallback measurement.
+     *
+     * `axis` is optional and additive, defaulting to 'height' to
+     * preserve existing behavior for all current call sites.
      */
-    syncMeasure(index, element) {
-        const size = element.getBoundingClientRect()
-            .height;
+    syncMeasure(index, element, axis = 'height') {
+        const rect = element.getBoundingClientRect();
+        const size = axis === 'width' ? rect.width : rect.height;
         if (size <= 0) {
             return;
         }
         const rounded = Math.round(size);
+        if (axis === 'width') {
+            if (this.widthMeasurements.get(index) === rounded) {
+                return;
+            }
+            this.widthMeasurements.set(index, rounded);
+            this.onMeasureWidth?.(index, rounded);
+            return;
+        }
         if (this.measurements.get(index) === rounded) {
             return;
         }
@@ -136,6 +219,7 @@ export class MeasurementSystem {
     stopMeasuring() {
         this.resizeObserver?.disconnect();
         this.pendingUpdates.clear();
+        this.pendingWidthUpdates.clear();
         if (this.rafId !== null) {
             cancelAnimationFrame(this.rafId);
         }
@@ -143,25 +227,45 @@ export class MeasurementSystem {
     getMeasurement(index) {
         return this.measurements.get(index);
     }
+    /**
+     * NEW (additive): mirrors getMeasurement() but for the width
+     * cache. Returns undefined for any index never observed in
+     * 'width' axis mode.
+     */
+    getWidthMeasurement(index) {
+        return this.widthMeasurements.get(index);
+    }
     getAllMeasurements() {
         return new Map(this.measurements);
     }
+    /**
+     * NEW (additive): mirrors getAllMeasurements() for widths.
+     */
+    getAllWidthMeasurements() {
+        return new Map(this.widthMeasurements);
+    }
     clearPending() {
         this.pendingUpdates.clear();
+        this.pendingWidthUpdates.clear();
     }
     /**
      * Explicit cache clear
      */
     clearMeasurements() {
         this.measurements.clear();
+        this.widthMeasurements.clear();
     }
     destroy() {
         this.stopMeasuring();
         this.measurements.clear();
         this.pendingUpdates.clear();
+        this.widthMeasurements.clear();
+        this.pendingWidthUpdates.clear();
         this.observedElements =
             new WeakMap();
+        this.observedAxis = new WeakMap();
         this.onMeasure = null;
+        this.onMeasureWidth = null;
     }
 }
 //# sourceMappingURL=MeasurementSystem.js.map