@vielzeug/scroll 1.0.3

package/README.md

@@ -0,0 +1,186 @@
+# @vielzeug/scroll
+
+> Lightweight, framework-agnostic virtual list engine with variable heights, sticky headers, grid support, and zero dependencies.
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/scroll)](https://www.npmjs.com/package/@vielzeug/scroll) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<details>
+<summary>Quick Reference</summary>
+
+**Package:** `@vielzeug/scroll` &nbsp;·&nbsp; **Category:** UI Performance
+
+**Key exports:** `createVirtualizer`, `createDomVirtualList`, `createVirtualScroller`, `createGroupedVirtualizer`, `createGridVirtualizer`, `createReactiveVirtualizer`
+
+**When to use:** Render only visible rows in large lists. Supports fixed heights, variable heights, sticky headers, grouped sections, grid virtualization, programmatic scrolling, and reactive signal integration.
+
+**Related:** [@vielzeug/dnd](https://vielzeug.dev/dnd/) · [@vielzeug/ore](https://vielzeug.dev/ore/) · [@vielzeug/refine](https://vielzeug.dev/refine/)
+
+</details>
+
+`@vielzeug/scroll` is part of Vielzeug and ships as a TypeScript package with ESM+CJS output. The only dependency is `@vielzeug/ripple`, used by the optional reactive integration.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/scroll
+npm install @vielzeug/scroll
+yarn add @vielzeug/scroll
+```
+
+## Quick Start
+
+```ts
+import { createVirtualizer } from '@vielzeug/scroll';
+
+const scrollEl = document.querySelector<HTMLElement>('.scroll-container')!;
+const listEl = document.querySelector<HTMLElement>('.list')!;
+
+const virt = createVirtualizer(scrollEl, {
+  count: 10_000,
+  estimateSize: 36,
+  onChange: ({ items, totalSize }) => {
+    listEl.style.height = `${totalSize}px`;
+    listEl.innerHTML = '';
+
+    for (const item of items) {
+      const row = document.createElement('div');
+      row.style.cssText = `position:absolute;top:${item.start}px;left:0;right:0;height:${item.size}px;`;
+      row.textContent = `Row ${item.index}`;
+      listEl.appendChild(row);
+    }
+  },
+});
+
+// Later:
+virt.dispose();
+```
+
+## DOM Adapter
+
+`createDomVirtualList` manages the virtualizer lifecycle and handles list-height styles automatically. Items are passed as enriched `VirtualRenderItem<T>` objects (layout fields + `.data`). Use `recycle` for efficient DOM node reuse.
+
+```ts
+import { createDomVirtualList } from '@vielzeug/scroll';
+
+type Option = { label: string; value: string };
+
+const domList = createDomVirtualList<Option>({
+  estimateSize: 36,
+  getItemKey: (_, opt) => opt.value,
+  listElement: listEl,
+  scrollElement: dropdownEl,
+  render: ({ items, listEl, recycle }) => {
+    for (const item of items) {
+      const el = recycle(item.data.value, () => document.createElement('div'));
+      el.style.cssText = `position:absolute;top:0;left:0;right:0;transform:translateY(${item.start}px);height:${item.size}px;`;
+      el.textContent = item.data.label;
+      listEl.appendChild(el);
+    }
+  },
+});
+
+domList.setItems(options);
+domList.scrollToIndex(focusedIndex, { align: 'auto' });
+domList.dispose();
+```
+
+## Self-Contained Scroller
+
+`createVirtualScroller` creates the scroll container and list element for you and appends them to a host element:
+
+```ts
+import { createVirtualScroller } from '@vielzeug/scroll';
+
+const list = createVirtualScroller<Option>(document.getElementById('root')!, {
+  estimateSize: 36,
+  render: ({ items, listEl, recycle }) => {
+    for (const item of items) {
+      const el = recycle(item.data.value, () => document.createElement('div'));
+      el.textContent = item.data.label;
+      el.style.cssText = `position:absolute;top:0;left:0;right:0;transform:translateY(${item.start}px);`;
+      listEl.appendChild(el);
+    }
+  },
+});
+
+list.setItems(options);
+list.dispose(); // also removes the generated scroll container
+```
+
+## Grouped Lists
+
+`createGroupedVirtualizer` handles sectioned data with sticky headers automatically:
+
+```ts
+import { createGroupedVirtualizer } from '@vielzeug/scroll';
+
+type Contact = { id: number; name: string };
+
+const virt = createGroupedVirtualizer<Contact>(scrollEl, {
+  estimateHeaderSize: 32,
+  estimateItemSize: 48,
+  sections: [
+    { label: 'A', items: [{ id: 1, name: 'Alice' }] },
+    { label: 'B', items: [{ id: 2, name: 'Bob' }] },
+  ],
+  onChange: ({ headers, items, stickyHeader, totalSize }) => {
+    // render headers and items from a flat offset table
+  },
+});
+
+virt.scrollToSection(1, { align: 'start' });
+virt.update(nextSections);
+virt.dispose();
+```
+
+## Grid Virtualization
+
+```ts
+import { createGridVirtualizer } from '@vielzeug/scroll';
+
+const grid = createGridVirtualizer(scrollEl, {
+  rowCount: 10_000,
+  colCount: 50,
+  estimateRowSize: 36,
+  estimateColSize: 120,
+  onChange: ({ rows, cols, totalHeight, totalWidth }) => {
+    // form the cross-product rows × cols and render each visible cell
+  },
+});
+
+grid.scrollToCell(500, 10, { rowAlign: 'center', colAlign: 'start' });
+grid.dispose();
+```
+
+## Reactive Integration
+
+`createReactiveVirtualizer` wraps the core virtualizer and exposes state as a `Signal<VirtualizerState>` from `@vielzeug/ripple`:
+
+```ts
+import { createReactiveVirtualizer } from '@vielzeug/scroll';
+import { effect } from '@vielzeug/ripple';
+
+const virt = createReactiveVirtualizer(scrollEl, {
+  count: 1000,
+  estimateSize: 40,
+});
+
+effect(() => {
+  const { items, totalSize } = virt.state.value;
+  listEl.style.height = `${totalSize}px`;
+  // render items...
+});
+
+virt.dispose();
+```
+
+## Documentation
+
+- [Overview](https://vielzeug.dev/scroll/)
+- [Usage Guide](https://vielzeug.dev/scroll/usage)
+- [API Reference](https://vielzeug.dev/scroll/api)
+- [Examples](https://vielzeug.dev/scroll/examples)
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/_adapter.cjs

@@ -0,0 +1,2 @@
+const e=require("./_utils.cjs");function t(t,n,r){if(e.isWindowTarget(t))return t.addEventListener(`scroll`,n,{passive:!0}),t.addEventListener(`resize`,r,{passive:!0}),{detach(){t.removeEventListener(`scroll`,n),t.removeEventListener(`resize`,r)},scrollTo:(e,n,r)=>t.scrollTo({behavior:r,left:e,top:n}),x:{readOffset:()=>t.scrollX,readViewportSize:()=>t.innerWidth,writeOffset:(e,n)=>t.scrollTo({behavior:n,left:e})},y:{readOffset:()=>t.scrollY,readViewportSize:()=>t.innerHeight,writeOffset:(e,n)=>t.scrollTo({behavior:n,top:e})}};let i=new ResizeObserver(r);return t.addEventListener(`scroll`,n,{passive:!0}),i.observe(t),{detach(){t.removeEventListener(`scroll`,n),i.disconnect()},scrollTo:(e,n,r)=>t.scrollTo({behavior:r,left:e,top:n}),x:{readOffset:()=>t.scrollLeft,readViewportSize:()=>t.clientWidth,writeOffset:(e,n)=>t.scrollTo({behavior:n,left:e})},y:{readOffset:()=>t.scrollTop,readViewportSize:()=>t.clientHeight,writeOffset:(e,n)=>t.scrollTo({behavior:n,top:e})}}}exports.createScrollAdapter=t;
+//# sourceMappingURL=_adapter.cjs.map

package/dist/_adapter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_adapter.cjs","names":[],"sources":["../src/_adapter.ts"],"sourcesContent":["import { type ScrollTarget, isWindowTarget } from './_utils';\n\n/** Single-axis read/write interface for either horizontal or vertical scroll. */\nexport type Axis = {\n  readOffset: () => number;\n  readViewportSize: () => number;\n  writeOffset: (offset: number, behavior: ScrollBehavior) => void;\n};\n\n/** Unified two-axis scroll adapter returned by `createScrollAdapter`. */\nexport type ScrollAdapter = {\n  /** Detach all listeners (scroll + resize). Call in _dispose(). */\n  detach: () => void;\n  /** Write both axes at once (avoids double scrollTo call). */\n  scrollTo: (left: number, top: number, behavior: ScrollBehavior) => void;\n  x: Axis;\n  y: Axis;\n};\n\n/**\n * Attach scroll and resize listeners on a `ScrollTarget` and return a\n * two-axis `ScrollAdapter`. Handles both `Window` and `HTMLElement` targets.\n */\nexport function createScrollAdapter(target: ScrollTarget, onScroll: () => void, onResize: () => void): ScrollAdapter {\n  if (isWindowTarget(target)) {\n    target.addEventListener('scroll', onScroll, { passive: true });\n    target.addEventListener('resize', onResize, { passive: true });\n\n    return {\n      detach() {\n        target.removeEventListener('scroll', onScroll);\n        target.removeEventListener('resize', onResize);\n      },\n      scrollTo: (left, top, behavior) => target.scrollTo({ behavior, left, top }),\n      x: {\n        readOffset: () => target.scrollX,\n        readViewportSize: () => target.innerWidth,\n        writeOffset: (offset, behavior) => target.scrollTo({ behavior, left: offset }),\n      },\n      y: {\n        readOffset: () => target.scrollY,\n        readViewportSize: () => target.innerHeight,\n        writeOffset: (offset, behavior) => target.scrollTo({ behavior, top: offset }),\n      },\n    };\n  }\n\n  // ⚠️ ResizeObserver is assumed to exist (supported in all modern browsers).\n  // In SSR or older environments, callers must polyfill before constructing a virtualizer.\n  const resizeObserver = new ResizeObserver(onResize);\n\n  target.addEventListener('scroll', onScroll, { passive: true });\n  resizeObserver.observe(target);\n\n  return {\n    detach() {\n      target.removeEventListener('scroll', onScroll);\n      resizeObserver.disconnect();\n    },\n    scrollTo: (left, top, behavior) => target.scrollTo({ behavior, left, top }),\n    x: {\n      readOffset: () => target.scrollLeft,\n      readViewportSize: () => target.clientWidth,\n      writeOffset: (offset, behavior) => target.scrollTo({ behavior, left: offset }),\n    },\n    y: {\n      readOffset: () => target.scrollTop,\n      readViewportSize: () => target.clientHeight,\n      writeOffset: (offset, behavior) => target.scrollTo({ behavior, top: offset }),\n    },\n  };\n}\n"],"mappings":"gCAuBA,SAAgB,EAAoB,EAAsB,EAAsB,EAAqC,CACnH,GAAI,EAAA,eAAe,CAAM,EAIvB,OAHA,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAC7D,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAEtD,CACL,QAAS,CACP,EAAO,oBAAoB,SAAU,CAAQ,EAC7C,EAAO,oBAAoB,SAAU,CAAQ,CAC/C,EACA,UAAW,EAAM,EAAK,IAAa,EAAO,SAAS,CAAE,WAAU,OAAM,KAAI,CAAC,EAC1E,EAAG,CACD,eAAkB,EAAO,QACzB,qBAAwB,EAAO,WAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,KAAM,CAAO,CAAC,CAC/E,EACA,EAAG,CACD,eAAkB,EAAO,QACzB,qBAAwB,EAAO,YAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,IAAK,CAAO,CAAC,CAC9E,CACF,EAKF,IAAM,EAAiB,IAAI,eAAe,CAAQ,EAKlD,OAHA,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAC7D,EAAe,QAAQ,CAAM,EAEtB,CACL,QAAS,CACP,EAAO,oBAAoB,SAAU,CAAQ,EAC7C,EAAe,WAAW,CAC5B,EACA,UAAW,EAAM,EAAK,IAAa,EAAO,SAAS,CAAE,WAAU,OAAM,KAAI,CAAC,EAC1E,EAAG,CACD,eAAkB,EAAO,WACzB,qBAAwB,EAAO,YAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,KAAM,CAAO,CAAC,CAC/E,EACA,EAAG,CACD,eAAkB,EAAO,UACzB,qBAAwB,EAAO,aAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,IAAK,CAAO,CAAC,CAC9E,CACF,CACF"}

package/dist/_adapter.d.ts

@@ -0,0 +1,22 @@
+import { type ScrollTarget } from './_utils';
+/** Single-axis read/write interface for either horizontal or vertical scroll. */
+export type Axis = {
+    readOffset: () => number;
+    readViewportSize: () => number;
+    writeOffset: (offset: number, behavior: ScrollBehavior) => void;
+};
+/** Unified two-axis scroll adapter returned by `createScrollAdapter`. */
+export type ScrollAdapter = {
+    /** Detach all listeners (scroll + resize). Call in _dispose(). */
+    detach: () => void;
+    /** Write both axes at once (avoids double scrollTo call). */
+    scrollTo: (left: number, top: number, behavior: ScrollBehavior) => void;
+    x: Axis;
+    y: Axis;
+};
+/**
+ * Attach scroll and resize listeners on a `ScrollTarget` and return a
+ * two-axis `ScrollAdapter`. Handles both `Window` and `HTMLElement` targets.
+ */
+export declare function createScrollAdapter(target: ScrollTarget, onScroll: () => void, onResize: () => void): ScrollAdapter;
+//# sourceMappingURL=_adapter.d.ts.map

package/dist/_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_adapter.d.ts","sourceRoot":"","sources":["../src/_adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,MAAM,IAAI,GAAG;IACjB,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;CACjE,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAC1B,kEAAkE;IAClE,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IACxE,CAAC,EAAE,IAAI,CAAC;IACR,CAAC,EAAE,IAAI,CAAC;CACT,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,aAAa,CAgDnH"}

package/dist/_adapter.js

@@ -0,0 +1,2 @@
+import{isWindowTarget as e}from"./_utils.js";function t(t,n,r){if(e(t))return t.addEventListener(`scroll`,n,{passive:!0}),t.addEventListener(`resize`,r,{passive:!0}),{detach(){t.removeEventListener(`scroll`,n),t.removeEventListener(`resize`,r)},scrollTo:(e,n,r)=>t.scrollTo({behavior:r,left:e,top:n}),x:{readOffset:()=>t.scrollX,readViewportSize:()=>t.innerWidth,writeOffset:(e,n)=>t.scrollTo({behavior:n,left:e})},y:{readOffset:()=>t.scrollY,readViewportSize:()=>t.innerHeight,writeOffset:(e,n)=>t.scrollTo({behavior:n,top:e})}};let i=new ResizeObserver(r);return t.addEventListener(`scroll`,n,{passive:!0}),i.observe(t),{detach(){t.removeEventListener(`scroll`,n),i.disconnect()},scrollTo:(e,n,r)=>t.scrollTo({behavior:r,left:e,top:n}),x:{readOffset:()=>t.scrollLeft,readViewportSize:()=>t.clientWidth,writeOffset:(e,n)=>t.scrollTo({behavior:n,left:e})},y:{readOffset:()=>t.scrollTop,readViewportSize:()=>t.clientHeight,writeOffset:(e,n)=>t.scrollTo({behavior:n,top:e})}}}export{t as createScrollAdapter};
+//# sourceMappingURL=_adapter.js.map

package/dist/_adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_adapter.js","names":[],"sources":["../src/_adapter.ts"],"sourcesContent":["import { type ScrollTarget, isWindowTarget } from './_utils';\n\n/** Single-axis read/write interface for either horizontal or vertical scroll. */\nexport type Axis = {\n  readOffset: () => number;\n  readViewportSize: () => number;\n  writeOffset: (offset: number, behavior: ScrollBehavior) => void;\n};\n\n/** Unified two-axis scroll adapter returned by `createScrollAdapter`. */\nexport type ScrollAdapter = {\n  /** Detach all listeners (scroll + resize). Call in _dispose(). */\n  detach: () => void;\n  /** Write both axes at once (avoids double scrollTo call). */\n  scrollTo: (left: number, top: number, behavior: ScrollBehavior) => void;\n  x: Axis;\n  y: Axis;\n};\n\n/**\n * Attach scroll and resize listeners on a `ScrollTarget` and return a\n * two-axis `ScrollAdapter`. Handles both `Window` and `HTMLElement` targets.\n */\nexport function createScrollAdapter(target: ScrollTarget, onScroll: () => void, onResize: () => void): ScrollAdapter {\n  if (isWindowTarget(target)) {\n    target.addEventListener('scroll', onScroll, { passive: true });\n    target.addEventListener('resize', onResize, { passive: true });\n\n    return {\n      detach() {\n        target.removeEventListener('scroll', onScroll);\n        target.removeEventListener('resize', onResize);\n      },\n      scrollTo: (left, top, behavior) => target.scrollTo({ behavior, left, top }),\n      x: {\n        readOffset: () => target.scrollX,\n        readViewportSize: () => target.innerWidth,\n        writeOffset: (offset, behavior) => target.scrollTo({ behavior, left: offset }),\n      },\n      y: {\n        readOffset: () => target.scrollY,\n        readViewportSize: () => target.innerHeight,\n        writeOffset: (offset, behavior) => target.scrollTo({ behavior, top: offset }),\n      },\n    };\n  }\n\n  // ⚠️ ResizeObserver is assumed to exist (supported in all modern browsers).\n  // In SSR or older environments, callers must polyfill before constructing a virtualizer.\n  const resizeObserver = new ResizeObserver(onResize);\n\n  target.addEventListener('scroll', onScroll, { passive: true });\n  resizeObserver.observe(target);\n\n  return {\n    detach() {\n      target.removeEventListener('scroll', onScroll);\n      resizeObserver.disconnect();\n    },\n    scrollTo: (left, top, behavior) => target.scrollTo({ behavior, left, top }),\n    x: {\n      readOffset: () => target.scrollLeft,\n      readViewportSize: () => target.clientWidth,\n      writeOffset: (offset, behavior) => target.scrollTo({ behavior, left: offset }),\n    },\n    y: {\n      readOffset: () => target.scrollTop,\n      readViewportSize: () => target.clientHeight,\n      writeOffset: (offset, behavior) => target.scrollTo({ behavior, top: offset }),\n    },\n  };\n}\n"],"mappings":"6CAuBA,SAAgB,EAAoB,EAAsB,EAAsB,EAAqC,CACnH,GAAI,EAAe,CAAM,EAIvB,OAHA,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAC7D,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAEtD,CACL,QAAS,CACP,EAAO,oBAAoB,SAAU,CAAQ,EAC7C,EAAO,oBAAoB,SAAU,CAAQ,CAC/C,EACA,UAAW,EAAM,EAAK,IAAa,EAAO,SAAS,CAAE,WAAU,OAAM,KAAI,CAAC,EAC1E,EAAG,CACD,eAAkB,EAAO,QACzB,qBAAwB,EAAO,WAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,KAAM,CAAO,CAAC,CAC/E,EACA,EAAG,CACD,eAAkB,EAAO,QACzB,qBAAwB,EAAO,YAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,IAAK,CAAO,CAAC,CAC9E,CACF,EAKF,IAAM,EAAiB,IAAI,eAAe,CAAQ,EAKlD,OAHA,EAAO,iBAAiB,SAAU,EAAU,CAAE,QAAS,EAAK,CAAC,EAC7D,EAAe,QAAQ,CAAM,EAEtB,CACL,QAAS,CACP,EAAO,oBAAoB,SAAU,CAAQ,EAC7C,EAAe,WAAW,CAC5B,EACA,UAAW,EAAM,EAAK,IAAa,EAAO,SAAS,CAAE,WAAU,OAAM,KAAI,CAAC,EAC1E,EAAG,CACD,eAAkB,EAAO,WACzB,qBAAwB,EAAO,YAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,KAAM,CAAO,CAAC,CAC/E,EACA,EAAG,CACD,eAAkB,EAAO,UACzB,qBAAwB,EAAO,aAC/B,aAAc,EAAQ,IAAa,EAAO,SAAS,CAAE,WAAU,IAAK,CAAO,CAAC,CAC9E,CACF,CACF"}

package/dist/_axis1d.cjs

@@ -0,0 +1,2 @@
+function e(e,t,n){let r=e,i=n,a=t,o=[],s=0,c=-1,l=-1,u=-1,d=!1,f=1/0;function p(e){return o[e]??0}function m(e){return p(e)+a(e)}function h(e=!1){e&&(c=-1,l=-1,u=-1);let t=[0],n=0;for(let e=0;e<r;e++)n+=a(e)+(e<r-1?i:0),t.push(n);o=t,s=n}function g(e){if(!Number.isFinite(e)||e>=r)return;c=-1,l=-1,u=-1;let t=o[e]??0;for(let n=e;n<r;n++)o[n]=t,t+=a(n)+(n<r-1?i:0);o[r]=t,s=t}function _(e){let t=0,n=r-1;for(;t<n;){let r=t+n>>1;m(r)<=e?t=r+1:n=r}return t}function v(e,t){let n=t,i=r-1;for(;n<i;){let t=n+i+1>>1;p(t)<e?n=t:i=t-1}return n}function y(e,t,n,i){let a=_(e),o=v(t,a);return{renderEnd:Math.min(r-1,o+i),renderStart:Math.max(0,a-n)}}function b(e,t){return e===c&&t===l&&s===u}function x(e,t){c=e,l=t,u=s}function S(){c=-1,l=-1,u=-1}function C(e){d||(d=!0,queueMicrotask(()=>{d=!1;let t=f;f=1/0,g(t),e()}))}function w(e){e<f&&(f=e)}function T(e){let t=p(e),n=a(e);return{end:t+n,index:e,size:n,start:t}}return{commitDedup:x,computeRange:y,consumeMinChangedIndex(){let e=f;return f=1/0,e},get count(){return r},endAt:m,findFirst:_,findLast:v,get gap(){return i},isDedupSame:b,itemAt:T,markChanged:w,get minChangedIndex(){return f},get pendingBuild(){return d},get prevEnd(){return l},get prevStart(){return c},get prevTotalSize(){return u},rebuild:h,rebuildFrom:g,resetDedup:S,scheduleBuild:C,setCount(e){r=e},setGap(e){i=e},sizeAt(e){return a(e)},startAt:p,get totalSize(){return s}}}exports.createAxis1D=e;
+//# sourceMappingURL=_axis1d.cjs.map

package/dist/_axis1d.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_axis1d.cjs","names":[],"sources":["../src/_axis1d.ts"],"sourcesContent":["/**\n * Shared 1D axis primitive: prefix-sum offset table, O(log n) binary search,\n * incremental rebuild, measurement batching via microtask, and dedup guards.\n *\n * Used directly by grid-virtualizer (numeric row/col indices) and composed\n * into virtualizer (which layers VirtualKey translation on top).\n */\n\n/** A single rendered virtual item — position and size on one axis. */\nexport interface VirtualItem {\n  end: number;\n  index: number;\n  size: number;\n  start: number;\n}\n\nexport interface Axis1DRange {\n  renderEnd: number;\n  renderStart: number;\n}\n\n/**\n * Create a self-contained 1D offset-table axis.\n *\n * @param initialCount - Number of items.\n * @param sizeAtFn     - Returns the resolved size for a given index (measured or estimated).\n *                       The virtualizer passes a closure that reads the live measurement cache,\n *                       so changes to the cache are reflected automatically without re-setting.\n * @param initialGap   - Gap between consecutive items (non-negative integer, pixels).\n */\nexport function createAxis1D(initialCount: number, sizeAtFn: (index: number) => number, initialGap: number) {\n  let count = initialCount;\n  let gap = initialGap;\n  const sizeAt = sizeAtFn;\n\n  let offsets: number[] = [];\n  let totalSize = 0;\n\n  // ─── Dedup guards ───────────────────────────────────────────────────────────\n  // Track the last-emitted render range and total size so computeVisible() can\n  // skip re-rendering when nothing changed.\n\n  let prevStart = -1;\n  let prevEnd = -1;\n  let prevTotalSize = -1;\n\n  // ─── Pending measurement flush ─────────────────────────────────────────────\n\n  let pendingBuild = false;\n  let minChangedIndex = Infinity;\n\n  // ─── Offset helpers ─────────────────────────────────────────────────────────\n\n  function startAt(i: number): number {\n    return offsets[i] ?? 0;\n  }\n\n  function endAt(i: number): number {\n    return startAt(i) + sizeAt(i);\n  }\n\n  // ─── Full rebuild ───────────────────────────────────────────────────────────\n\n  /**\n   * Full O(n) prefix-sum rebuild.\n   * Pass `forceEmit = true` to reset dedup guards, ensuring computeVisible()\n   * emits on the next call even if the rendered range is unchanged.\n   */\n  function rebuild(forceEmit = false): void {\n    if (forceEmit) {\n      prevStart = -1;\n      prevEnd = -1;\n      prevTotalSize = -1;\n    }\n\n    const next: number[] = [0];\n    let pos = 0;\n\n    for (let i = 0; i < count; i++) {\n      pos += sizeAt(i) + (i < count - 1 ? gap : 0);\n      next.push(pos);\n    }\n\n    offsets = next;\n    totalSize = pos;\n  }\n\n  // ─── Incremental rebuild ────────────────────────────────────────────────────\n\n  /**\n   * O(count - fromIndex) incremental rebuild — used after measurement.\n   * Always resets dedup guards because measurements change layout.\n   */\n  function rebuildFrom(fromIndex: number): void {\n    if (!Number.isFinite(fromIndex) || fromIndex >= count) return;\n\n    prevStart = -1;\n    prevEnd = -1;\n    prevTotalSize = -1;\n\n    let pos = offsets[fromIndex] ?? 0;\n\n    for (let i = fromIndex; i < count; i++) {\n      offsets[i] = pos;\n      pos += sizeAt(i) + (i < count - 1 ? gap : 0);\n    }\n\n    offsets[count] = pos;\n    totalSize = pos;\n  }\n\n  // ─── Binary search ──────────────────────────────────────────────────────────\n\n  function findFirst(viewportStart: number): number {\n    let lo = 0;\n    let hi = count - 1;\n\n    while (lo < hi) {\n      const mid = (lo + hi) >> 1;\n\n      if (endAt(mid) <= viewportStart) lo = mid + 1;\n      else hi = mid;\n    }\n\n    return lo;\n  }\n\n  function findLast(viewportEnd: number, from: number): number {\n    let lo = from;\n    let hi = count - 1;\n\n    while (lo < hi) {\n      const mid = (lo + hi + 1) >> 1;\n\n      if (startAt(mid) < viewportEnd) lo = mid;\n      else hi = mid - 1;\n    }\n\n    return lo;\n  }\n\n  /**\n   * Compute the render range for a given viewport window and overscan values.\n   * Returns indices clamped to [0, count - 1].\n   */\n  function computeRange(\n    viewportStart: number,\n    viewportEnd: number,\n    overscanStart: number,\n    overscanEnd: number,\n  ): Axis1DRange {\n    const first = findFirst(viewportStart);\n    const last = findLast(viewportEnd, first);\n\n    return {\n      renderEnd: Math.min(count - 1, last + overscanEnd),\n      renderStart: Math.max(0, first - overscanStart),\n    };\n  }\n\n  // ─── Dedup helpers ──────────────────────────────────────────────────────────\n\n  /** Returns `true` when start/end/totalSize are all identical to the last commit. */\n  function isDedupSame(start: number, end: number): boolean {\n    return start === prevStart && end === prevEnd && totalSize === prevTotalSize;\n  }\n\n  function commitDedup(start: number, end: number): void {\n    prevStart = start;\n    prevEnd = end;\n    prevTotalSize = totalSize;\n  }\n\n  function resetDedup(): void {\n    prevStart = -1;\n    prevEnd = -1;\n    prevTotalSize = -1;\n  }\n\n  // ─── Microtask scheduling ───────────────────────────────────────────────────\n\n  /**\n   * Schedule an incremental rebuild on the next microtask, then call `onFlush`.\n   * Multiple calls before the microtask fires are coalesced into one rebuild.\n   * Returns without scheduling if a build is already pending.\n   */\n  function scheduleBuild(onFlush: () => void): void {\n    if (pendingBuild) return;\n\n    pendingBuild = true;\n    queueMicrotask(() => {\n      pendingBuild = false;\n\n      const from = minChangedIndex;\n\n      minChangedIndex = Infinity;\n      rebuildFrom(from);\n      onFlush();\n    });\n  }\n\n  /** Mark an item index as having a changed measurement. Drives incremental rebuilds. */\n  function markChanged(index: number): void {\n    if (index < minChangedIndex) minChangedIndex = index;\n  }\n\n  // ─── Item descriptor ────────────────────────────────────────────────────────\n\n  /** Build a VirtualItem for a given index using current offset table. */\n  function itemAt(index: number): VirtualItem {\n    const start = startAt(index);\n    const size = sizeAt(index);\n\n    return { end: start + size, index, size, start };\n  }\n\n  // ─── Returned object ────────────────────────────────────────────────────────\n\n  return {\n    commitDedup,\n    computeRange,\n    /**\n     * Atomically read and reset minChangedIndex to Infinity.\n     * Used by grid-virtualizer's coordinated flush so it can consume the\n     * changed-index without going through axis1d's own scheduleBuild.\n     */\n    consumeMinChangedIndex(): number {\n      const idx = minChangedIndex;\n\n      minChangedIndex = Infinity;\n\n      return idx;\n    },\n    get count(): number {\n      return count;\n    },\n    endAt,\n    findFirst,\n    findLast,\n    /** Current gap between items (pixels). Used by callers to dedup gap changes. */\n    get gap(): number {\n      return gap;\n    },\n    isDedupSame,\n    itemAt,\n    markChanged,\n    get minChangedIndex(): number {\n      return minChangedIndex;\n    },\n    get pendingBuild(): boolean {\n      return pendingBuild;\n    },\n    get prevEnd(): number {\n      return prevEnd;\n    },\n    get prevStart(): number {\n      return prevStart;\n    },\n    get prevTotalSize(): number {\n      return prevTotalSize;\n    },\n    rebuild,\n    rebuildFrom,\n    resetDedup,\n    scheduleBuild,\n    setCount(n: number): void {\n      count = n;\n    },\n    setGap(n: number): void {\n      gap = n;\n    },\n    sizeAt(i: number): number {\n      return sizeAt(i);\n    },\n    startAt,\n    get totalSize(): number {\n      return totalSize;\n    },\n  };\n}\n\nexport type Axis1D = ReturnType<typeof createAxis1D>;\n"],"mappings":"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"}

package/dist/_axis1d.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared 1D axis primitive: prefix-sum offset table, O(log n) binary search,
+ * incremental rebuild, measurement batching via microtask, and dedup guards.
+ *
+ * Used directly by grid-virtualizer (numeric row/col indices) and composed
+ * into virtualizer (which layers VirtualKey translation on top).
+ */
+/** A single rendered virtual item — position and size on one axis. */
+export interface VirtualItem {
+    end: number;
+    index: number;
+    size: number;
+    start: number;
+}
+export interface Axis1DRange {
+    renderEnd: number;
+    renderStart: number;
+}
+/**
+ * Create a self-contained 1D offset-table axis.
+ *
+ * @param initialCount - Number of items.
+ * @param sizeAtFn     - Returns the resolved size for a given index (measured or estimated).
+ *                       The virtualizer passes a closure that reads the live measurement cache,
+ *                       so changes to the cache are reflected automatically without re-setting.
+ * @param initialGap   - Gap between consecutive items (non-negative integer, pixels).
+ */
+export declare function createAxis1D(initialCount: number, sizeAtFn: (index: number) => number, initialGap: number): {
+    commitDedup: (start: number, end: number) => void;
+    computeRange: (viewportStart: number, viewportEnd: number, overscanStart: number, overscanEnd: number) => Axis1DRange;
+    /**
+     * Atomically read and reset minChangedIndex to Infinity.
+     * Used by grid-virtualizer's coordinated flush so it can consume the
+     * changed-index without going through axis1d's own scheduleBuild.
+     */
+    consumeMinChangedIndex(): number;
+    readonly count: number;
+    endAt: (i: number) => number;
+    findFirst: (viewportStart: number) => number;
+    findLast: (viewportEnd: number, from: number) => number;
+    /** Current gap between items (pixels). Used by callers to dedup gap changes. */
+    readonly gap: number;
+    isDedupSame: (start: number, end: number) => boolean;
+    itemAt: (index: number) => VirtualItem;
+    markChanged: (index: number) => void;
+    readonly minChangedIndex: number;
+    readonly pendingBuild: boolean;
+    readonly prevEnd: number;
+    readonly prevStart: number;
+    readonly prevTotalSize: number;
+    rebuild: (forceEmit?: boolean) => void;
+    rebuildFrom: (fromIndex: number) => void;
+    resetDedup: () => void;
+    scheduleBuild: (onFlush: () => void) => void;
+    setCount(n: number): void;
+    setGap(n: number): void;
+    sizeAt(i: number): number;
+    startAt: (i: number) => number;
+    readonly totalSize: number;
+};
+export type Axis1D = ReturnType<typeof createAxis1D>;
+//# sourceMappingURL=_axis1d.d.ts.map

package/dist/_axis1d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_axis1d.d.ts","sourceRoot":"","sources":["../src/_axis1d.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,UAAU,EAAE,MAAM;yBAyI5E,MAAM,OAAO,MAAM,KAAG,IAAI;kCArBrC,MAAM,eACR,MAAM,iBACJ,MAAM,eACR,MAAM,KAClB,WAAW;IAuEZ;;;;OAIG;8BACuB,MAAM;oBAOnB,MAAM;eAhLH,MAAM,KAAG,MAAM;+BAwDC,MAAM,KAAG,MAAM;4BAclB,MAAM,QAAQ,MAAM,KAAG,MAAM;IAgH1D,gFAAgF;kBACrE,MAAM;yBA7ES,MAAM,OAAO,MAAM,KAAG,OAAO;oBA8ClC,MAAM,KAAG,WAAW;yBAPf,MAAM,KAAG,IAAI;8BA4ChB,MAAM;2BAGT,OAAO;sBAGZ,MAAM;wBAGJ,MAAM;4BAGF,MAAM;sCA9LQ,IAAI;6BAyBT,MAAM,KAAG,IAAI;sBAgFtB,IAAI;6BAaK,MAAM,IAAI,KAAG,IAAI;gBA+EnC,MAAM,GAAG,IAAI;cAGf,MAAM,GAAG,IAAI;cAGb,MAAM,GAAG,MAAM;iBA1NP,MAAM,KAAG,MAAM;wBA8NhB,MAAM;EAI1B;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/_axis1d.js

@@ -0,0 +1,2 @@
+function e(e,t,n){let r=e,i=n,a=t,o=[],s=0,c=-1,l=-1,u=-1,d=!1,f=1/0;function p(e){return o[e]??0}function m(e){return p(e)+a(e)}function h(e=!1){e&&(c=-1,l=-1,u=-1);let t=[0],n=0;for(let e=0;e<r;e++)n+=a(e)+(e<r-1?i:0),t.push(n);o=t,s=n}function g(e){if(!Number.isFinite(e)||e>=r)return;c=-1,l=-1,u=-1;let t=o[e]??0;for(let n=e;n<r;n++)o[n]=t,t+=a(n)+(n<r-1?i:0);o[r]=t,s=t}function _(e){let t=0,n=r-1;for(;t<n;){let r=t+n>>1;m(r)<=e?t=r+1:n=r}return t}function v(e,t){let n=t,i=r-1;for(;n<i;){let t=n+i+1>>1;p(t)<e?n=t:i=t-1}return n}function y(e,t,n,i){let a=_(e),o=v(t,a);return{renderEnd:Math.min(r-1,o+i),renderStart:Math.max(0,a-n)}}function b(e,t){return e===c&&t===l&&s===u}function x(e,t){c=e,l=t,u=s}function S(){c=-1,l=-1,u=-1}function C(e){d||(d=!0,queueMicrotask(()=>{d=!1;let t=f;f=1/0,g(t),e()}))}function w(e){e<f&&(f=e)}function T(e){let t=p(e),n=a(e);return{end:t+n,index:e,size:n,start:t}}return{commitDedup:x,computeRange:y,consumeMinChangedIndex(){let e=f;return f=1/0,e},get count(){return r},endAt:m,findFirst:_,findLast:v,get gap(){return i},isDedupSame:b,itemAt:T,markChanged:w,get minChangedIndex(){return f},get pendingBuild(){return d},get prevEnd(){return l},get prevStart(){return c},get prevTotalSize(){return u},rebuild:h,rebuildFrom:g,resetDedup:S,scheduleBuild:C,setCount(e){r=e},setGap(e){i=e},sizeAt(e){return a(e)},startAt:p,get totalSize(){return s}}}export{e as createAxis1D};
+//# sourceMappingURL=_axis1d.js.map

package/dist/_axis1d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_axis1d.js","names":[],"sources":["../src/_axis1d.ts"],"sourcesContent":["/**\n * Shared 1D axis primitive: prefix-sum offset table, O(log n) binary search,\n * incremental rebuild, measurement batching via microtask, and dedup guards.\n *\n * Used directly by grid-virtualizer (numeric row/col indices) and composed\n * into virtualizer (which layers VirtualKey translation on top).\n */\n\n/** A single rendered virtual item — position and size on one axis. */\nexport interface VirtualItem {\n  end: number;\n  index: number;\n  size: number;\n  start: number;\n}\n\nexport interface Axis1DRange {\n  renderEnd: number;\n  renderStart: number;\n}\n\n/**\n * Create a self-contained 1D offset-table axis.\n *\n * @param initialCount - Number of items.\n * @param sizeAtFn     - Returns the resolved size for a given index (measured or estimated).\n *                       The virtualizer passes a closure that reads the live measurement cache,\n *                       so changes to the cache are reflected automatically without re-setting.\n * @param initialGap   - Gap between consecutive items (non-negative integer, pixels).\n */\nexport function createAxis1D(initialCount: number, sizeAtFn: (index: number) => number, initialGap: number) {\n  let count = initialCount;\n  let gap = initialGap;\n  const sizeAt = sizeAtFn;\n\n  let offsets: number[] = [];\n  let totalSize = 0;\n\n  // ─── Dedup guards ───────────────────────────────────────────────────────────\n  // Track the last-emitted render range and total size so computeVisible() can\n  // skip re-rendering when nothing changed.\n\n  let prevStart = -1;\n  let prevEnd = -1;\n  let prevTotalSize = -1;\n\n  // ─── Pending measurement flush ─────────────────────────────────────────────\n\n  let pendingBuild = false;\n  let minChangedIndex = Infinity;\n\n  // ─── Offset helpers ─────────────────────────────────────────────────────────\n\n  function startAt(i: number): number {\n    return offsets[i] ?? 0;\n  }\n\n  function endAt(i: number): number {\n    return startAt(i) + sizeAt(i);\n  }\n\n  // ─── Full rebuild ───────────────────────────────────────────────────────────\n\n  /**\n   * Full O(n) prefix-sum rebuild.\n   * Pass `forceEmit = true` to reset dedup guards, ensuring computeVisible()\n   * emits on the next call even if the rendered range is unchanged.\n   */\n  function rebuild(forceEmit = false): void {\n    if (forceEmit) {\n      prevStart = -1;\n      prevEnd = -1;\n      prevTotalSize = -1;\n    }\n\n    const next: number[] = [0];\n    let pos = 0;\n\n    for (let i = 0; i < count; i++) {\n      pos += sizeAt(i) + (i < count - 1 ? gap : 0);\n      next.push(pos);\n    }\n\n    offsets = next;\n    totalSize = pos;\n  }\n\n  // ─── Incremental rebuild ────────────────────────────────────────────────────\n\n  /**\n   * O(count - fromIndex) incremental rebuild — used after measurement.\n   * Always resets dedup guards because measurements change layout.\n   */\n  function rebuildFrom(fromIndex: number): void {\n    if (!Number.isFinite(fromIndex) || fromIndex >= count) return;\n\n    prevStart = -1;\n    prevEnd = -1;\n    prevTotalSize = -1;\n\n    let pos = offsets[fromIndex] ?? 0;\n\n    for (let i = fromIndex; i < count; i++) {\n      offsets[i] = pos;\n      pos += sizeAt(i) + (i < count - 1 ? gap : 0);\n    }\n\n    offsets[count] = pos;\n    totalSize = pos;\n  }\n\n  // ─── Binary search ──────────────────────────────────────────────────────────\n\n  function findFirst(viewportStart: number): number {\n    let lo = 0;\n    let hi = count - 1;\n\n    while (lo < hi) {\n      const mid = (lo + hi) >> 1;\n\n      if (endAt(mid) <= viewportStart) lo = mid + 1;\n      else hi = mid;\n    }\n\n    return lo;\n  }\n\n  function findLast(viewportEnd: number, from: number): number {\n    let lo = from;\n    let hi = count - 1;\n\n    while (lo < hi) {\n      const mid = (lo + hi + 1) >> 1;\n\n      if (startAt(mid) < viewportEnd) lo = mid;\n      else hi = mid - 1;\n    }\n\n    return lo;\n  }\n\n  /**\n   * Compute the render range for a given viewport window and overscan values.\n   * Returns indices clamped to [0, count - 1].\n   */\n  function computeRange(\n    viewportStart: number,\n    viewportEnd: number,\n    overscanStart: number,\n    overscanEnd: number,\n  ): Axis1DRange {\n    const first = findFirst(viewportStart);\n    const last = findLast(viewportEnd, first);\n\n    return {\n      renderEnd: Math.min(count - 1, last + overscanEnd),\n      renderStart: Math.max(0, first - overscanStart),\n    };\n  }\n\n  // ─── Dedup helpers ──────────────────────────────────────────────────────────\n\n  /** Returns `true` when start/end/totalSize are all identical to the last commit. */\n  function isDedupSame(start: number, end: number): boolean {\n    return start === prevStart && end === prevEnd && totalSize === prevTotalSize;\n  }\n\n  function commitDedup(start: number, end: number): void {\n    prevStart = start;\n    prevEnd = end;\n    prevTotalSize = totalSize;\n  }\n\n  function resetDedup(): void {\n    prevStart = -1;\n    prevEnd = -1;\n    prevTotalSize = -1;\n  }\n\n  // ─── Microtask scheduling ───────────────────────────────────────────────────\n\n  /**\n   * Schedule an incremental rebuild on the next microtask, then call `onFlush`.\n   * Multiple calls before the microtask fires are coalesced into one rebuild.\n   * Returns without scheduling if a build is already pending.\n   */\n  function scheduleBuild(onFlush: () => void): void {\n    if (pendingBuild) return;\n\n    pendingBuild = true;\n    queueMicrotask(() => {\n      pendingBuild = false;\n\n      const from = minChangedIndex;\n\n      minChangedIndex = Infinity;\n      rebuildFrom(from);\n      onFlush();\n    });\n  }\n\n  /** Mark an item index as having a changed measurement. Drives incremental rebuilds. */\n  function markChanged(index: number): void {\n    if (index < minChangedIndex) minChangedIndex = index;\n  }\n\n  // ─── Item descriptor ────────────────────────────────────────────────────────\n\n  /** Build a VirtualItem for a given index using current offset table. */\n  function itemAt(index: number): VirtualItem {\n    const start = startAt(index);\n    const size = sizeAt(index);\n\n    return { end: start + size, index, size, start };\n  }\n\n  // ─── Returned object ────────────────────────────────────────────────────────\n\n  return {\n    commitDedup,\n    computeRange,\n    /**\n     * Atomically read and reset minChangedIndex to Infinity.\n     * Used by grid-virtualizer's coordinated flush so it can consume the\n     * changed-index without going through axis1d's own scheduleBuild.\n     */\n    consumeMinChangedIndex(): number {\n      const idx = minChangedIndex;\n\n      minChangedIndex = Infinity;\n\n      return idx;\n    },\n    get count(): number {\n      return count;\n    },\n    endAt,\n    findFirst,\n    findLast,\n    /** Current gap between items (pixels). Used by callers to dedup gap changes. */\n    get gap(): number {\n      return gap;\n    },\n    isDedupSame,\n    itemAt,\n    markChanged,\n    get minChangedIndex(): number {\n      return minChangedIndex;\n    },\n    get pendingBuild(): boolean {\n      return pendingBuild;\n    },\n    get prevEnd(): number {\n      return prevEnd;\n    },\n    get prevStart(): number {\n      return prevStart;\n    },\n    get prevTotalSize(): number {\n      return prevTotalSize;\n    },\n    rebuild,\n    rebuildFrom,\n    resetDedup,\n    scheduleBuild,\n    setCount(n: number): void {\n      count = n;\n    },\n    setGap(n: number): void {\n      gap = n;\n    },\n    sizeAt(i: number): number {\n      return sizeAt(i);\n    },\n    startAt,\n    get totalSize(): number {\n      return totalSize;\n    },\n  };\n}\n\nexport type Axis1D = ReturnType<typeof createAxis1D>;\n"],"mappings":"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"}

package/dist/_dev.cjs

@@ -0,0 +1,2 @@
+var e=!globalThis.__SCROLL_PROD__;function t(t){e&&console.warn(`[@vielzeug/scroll] ${t}`)}exports.warn=t;
+//# sourceMappingURL=_dev.cjs.map

package/dist/_dev.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.cjs","names":[],"sources":["../src/_dev.ts"],"sourcesContent":["const isDev = !(globalThis as { __SCROLL_PROD__?: boolean }).__SCROLL_PROD__;\n\n/** @internal @security Messages may include user-supplied data. */\nexport function warn(msg: string): void {\n  if (isDev) console.warn(`[@vielzeug/scroll] ${msg}`);\n}\n\n/** @internal — Run fn only in dev builds. Use when dev-only logic goes beyond a single warn() / error() call. */\nexport function devOnly(fn: () => void): void {\n  if (isDev) fn();\n}\n"],"mappings":"AAAA,IAAM,EAAQ,CAAE,WAA6C,gBAG7D,SAAgB,EAAK,EAAmB,CAClC,GAAO,QAAQ,KAAK,sBAAsB,GAAK,CACrD"}

package/dist/_dev.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=_dev.d.ts.map

package/dist/_dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.d.ts","sourceRoot":"","sources":["../src/_dev.ts"],"names":[],"mappings":""}

package/dist/_dev.js

@@ -0,0 +1,2 @@
+var e=!globalThis.__SCROLL_PROD__;function t(t){e&&console.warn(`[@vielzeug/scroll] ${t}`)}export{t as warn};
+//# sourceMappingURL=_dev.js.map

package/dist/_dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.js","names":[],"sources":["../src/_dev.ts"],"sourcesContent":["const isDev = !(globalThis as { __SCROLL_PROD__?: boolean }).__SCROLL_PROD__;\n\n/** @internal @security Messages may include user-supplied data. */\nexport function warn(msg: string): void {\n  if (isDev) console.warn(`[@vielzeug/scroll] ${msg}`);\n}\n\n/** @internal — Run fn only in dev builds. Use when dev-only logic goes beyond a single warn() / error() call. */\nexport function devOnly(fn: () => void): void {\n  if (isDev) fn();\n}\n"],"mappings":"AAAA,IAAM,EAAQ,CAAE,WAA6C,gBAG7D,SAAgB,EAAK,EAAmB,CAClC,GAAO,QAAQ,KAAK,sBAAsB,GAAK,CACrD"}

package/dist/_utils.cjs

@@ -0,0 +1,2 @@
+const e=require("./_dev.cjs");function t(){return new Map}var n=36,r=3;function i(e,t=0){return Number.isFinite(e)?Math.max(0,Math.floor(e)):t}function a(e,t){return!Number.isFinite(e)||e<=0||e>1e7?t:e}function o(e){return typeof Window<`u`&&e instanceof Window||typeof e.innerHeight==`number`&&typeof e.document==`object`}function s(e,t){if(typeof e==`number`){let n=i(e,t);return{end:n,start:n}}return{end:i(e?.end??t),start:i(e?.start??t)}}function c(e,t,n){let r=new ResizeObserver(e=>{for(let t of e)n(t)});return r.observe(t),e.addEventListener(`abort`,()=>r.disconnect(),{once:!0}),()=>r.disconnect()}function l(t,n){if(typeof t==`function`)return r=>{try{return a(t(r),n)}catch(t){return e.warn(`estimateSize threw for index ${r}: ${t}`),n}};let r=typeof t==`number`?a(t,n):n;return()=>r}exports.DEFAULT_ESTIMATE_SIZE=n,exports.DEFAULT_OVERSCAN=r,exports.createMeasurementCache=t,exports.isWindowTarget=o,exports.normalizeOverscan=s,exports.observeResize=c,exports.resolveEstimateFn=l,exports.toNonNegativeInt=i,exports.toPositiveNumber=a;
+//# sourceMappingURL=_utils.cjs.map

package/dist/_utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.cjs","names":[],"sources":["../src/_utils.ts"],"sourcesContent":["import { warn } from './_dev';\n\nexport type ScrollTarget = HTMLElement | Window;\n\nexport type VirtualKey = number | string;\n\n/** Shared measurement cache. Pass the same instance to multiple virtualizers\n *  for scroll restoration or SSR pre-measurement. */\nexport type MeasurementCache = Map<VirtualKey, number>;\n\n/** Create a new, empty measurement cache. */\nexport function createMeasurementCache(): MeasurementCache {\n  return new Map();\n}\n\nexport type Overscan = number | { end?: number; start?: number };\n\nexport const DEFAULT_ESTIMATE_SIZE = 36;\nexport const DEFAULT_OVERSCAN = 3;\n\n// ─── Numeric helpers ───────────────────────────────────────────────────────────\n\nexport function toNonNegativeInt(value: number, fallback = 0): number {\n  if (!Number.isFinite(value)) return fallback;\n\n  return Math.max(0, Math.floor(value));\n}\n\nexport function toPositiveNumber(value: number, fallback: number): number {\n  if (!Number.isFinite(value) || value <= 0 || value > 1e7) return fallback;\n\n  return value;\n}\n\nexport function isWindowTarget(target: ScrollTarget): target is Window {\n  return (\n    (typeof Window !== 'undefined' && target instanceof Window) ||\n    (typeof (target as Window).innerHeight === 'number' && typeof (target as Window).document === 'object')\n  );\n}\n\nexport function normalizeOverscan(overscan: Overscan | undefined, defaultVal: number): { end: number; start: number } {\n  if (typeof overscan === 'number') {\n    const n = toNonNegativeInt(overscan, defaultVal);\n\n    return { end: n, start: n };\n  }\n\n  return {\n    end: toNonNegativeInt(overscan?.end ?? defaultVal),\n    start: toNonNegativeInt(overscan?.start ?? defaultVal),\n  };\n}\n\n/**\n * Create a `ResizeObserver` that reports size changes on `el` via `onSize`, tied to\n * `signal` so it is disconnected automatically when the owning factory disposes —\n * even if the caller never calls the returned disconnect function.\n */\nexport function observeResize(\n  signal: AbortSignal,\n  el: HTMLElement,\n  onSize: (entry: ResizeObserverEntry) => void,\n): () => void {\n  const ro = new ResizeObserver((entries) => {\n    for (const entry of entries) onSize(entry);\n  });\n\n  ro.observe(el);\n  signal.addEventListener('abort', () => ro.disconnect(), { once: true });\n\n  return () => ro.disconnect();\n}\n\nexport function resolveEstimateFn(\n  estimate: number | ((index: number) => number) | undefined,\n  defaultSize: number,\n): (index: number) => number {\n  if (typeof estimate === 'function') {\n    return (index: number) => {\n      try {\n        return toPositiveNumber(estimate(index), defaultSize);\n      } catch (err) {\n        warn(`estimateSize threw for index ${index}: ${err}`);\n\n        return defaultSize;\n      }\n    };\n  }\n\n  const size = typeof estimate === 'number' ? toPositiveNumber(estimate, defaultSize) : defaultSize;\n\n  return () => size;\n}\n"],"mappings":"8BAWA,SAAgB,GAA2C,CACzD,OAAO,IAAI,GACb,CAIA,IAAa,EAAwB,GACxB,EAAmB,EAIhC,SAAgB,EAAiB,EAAe,EAAW,EAAW,CAGpE,OAFK,OAAO,SAAS,CAAK,EAEnB,KAAK,IAAI,EAAG,KAAK,MAAM,CAAK,CAAC,EAFA,CAGtC,CAEA,SAAgB,EAAiB,EAAe,EAA0B,CAGxE,MAFI,CAAC,OAAO,SAAS,CAAK,GAAK,GAAS,GAAK,EAAQ,IAAY,EAE1D,CACT,CAEA,SAAgB,EAAe,EAAwC,CACrE,OACG,OAAO,OAAW,KAAe,aAAkB,QACnD,OAAQ,EAAkB,aAAgB,UAAY,OAAQ,EAAkB,UAAa,QAElG,CAEA,SAAgB,EAAkB,EAAgC,EAAoD,CACpH,GAAI,OAAO,GAAa,SAAU,CAChC,IAAM,EAAI,EAAiB,EAAU,CAAU,EAE/C,MAAO,CAAE,IAAK,EAAG,MAAO,CAAE,CAC5B,CAEA,MAAO,CACL,IAAK,EAAiB,GAAU,KAAO,CAAU,EACjD,MAAO,EAAiB,GAAU,OAAS,CAAU,CACvD,CACF,CAOA,SAAgB,EACd,EACA,EACA,EACY,CACZ,IAAM,EAAK,IAAI,eAAgB,GAAY,CACzC,IAAK,IAAM,KAAS,EAAS,EAAO,CAAK,CAC3C,CAAC,EAKD,OAHA,EAAG,QAAQ,CAAE,EACb,EAAO,iBAAiB,YAAe,EAAG,WAAW,EAAG,CAAE,KAAM,EAAK,CAAC,MAEzD,EAAG,WAAW,CAC7B,CAEA,SAAgB,EACd,EACA,EAC2B,CAC3B,GAAI,OAAO,GAAa,WACtB,MAAQ,IAAkB,CACxB,GAAI,CACF,OAAO,EAAiB,EAAS,CAAK,EAAG,CAAW,CACtD,OAAS,EAAK,CAGZ,OAFA,EAAA,KAAK,gCAAgC,EAAM,IAAI,GAAK,EAE7C,CACT,CACF,EAGF,IAAM,EAAO,OAAO,GAAa,SAAW,EAAiB,EAAU,CAAW,EAAI,EAEtF,UAAa,CACf"}

package/dist/_utils.d.ts

@@ -0,0 +1,28 @@
+export type ScrollTarget = HTMLElement | Window;
+export type VirtualKey = number | string;
+/** Shared measurement cache. Pass the same instance to multiple virtualizers
+ *  for scroll restoration or SSR pre-measurement. */
+export type MeasurementCache = Map<VirtualKey, number>;
+/** Create a new, empty measurement cache. */
+export declare function createMeasurementCache(): MeasurementCache;
+export type Overscan = number | {
+    end?: number;
+    start?: number;
+};
+export declare const DEFAULT_ESTIMATE_SIZE = 36;
+export declare const DEFAULT_OVERSCAN = 3;
+export declare function toNonNegativeInt(value: number, fallback?: number): number;
+export declare function toPositiveNumber(value: number, fallback: number): number;
+export declare function isWindowTarget(target: ScrollTarget): target is Window;
+export declare function normalizeOverscan(overscan: Overscan | undefined, defaultVal: number): {
+    end: number;
+    start: number;
+};
+/**
+ * Create a `ResizeObserver` that reports size changes on `el` via `onSize`, tied to
+ * `signal` so it is disconnected automatically when the owning factory disposes —
+ * even if the caller never calls the returned disconnect function.
+ */
+export declare function observeResize(signal: AbortSignal, el: HTMLElement, onSize: (entry: ResizeObserverEntry) => void): () => void;
+export declare function resolveEstimateFn(estimate: number | ((index: number) => number) | undefined, defaultSize: number): (index: number) => number;
+//# sourceMappingURL=_utils.d.ts.map

package/dist/_utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.d.ts","sourceRoot":"","sources":["../src/_utils.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;qDACqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAEvD,6CAA6C;AAC7C,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAIlC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAIpE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,IAAI,MAAM,CAKrE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAWpH;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC3C,MAAM,IAAI,CASZ;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,EAC1D,WAAW,EAAE,MAAM,GAClB,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAgB3B"}

package/dist/_utils.js

@@ -0,0 +1,2 @@
+import{warn as e}from"./_dev.js";function t(){return new Map}var n=36,r=3;function i(e,t=0){return Number.isFinite(e)?Math.max(0,Math.floor(e)):t}function a(e,t){return!Number.isFinite(e)||e<=0||e>1e7?t:e}function o(e){return typeof Window<`u`&&e instanceof Window||typeof e.innerHeight==`number`&&typeof e.document==`object`}function s(e,t){if(typeof e==`number`){let n=i(e,t);return{end:n,start:n}}return{end:i(e?.end??t),start:i(e?.start??t)}}function c(e,t,n){let r=new ResizeObserver(e=>{for(let t of e)n(t)});return r.observe(t),e.addEventListener(`abort`,()=>r.disconnect(),{once:!0}),()=>r.disconnect()}function l(t,n){if(typeof t==`function`)return r=>{try{return a(t(r),n)}catch(t){return e(`estimateSize threw for index ${r}: ${t}`),n}};let r=typeof t==`number`?a(t,n):n;return()=>r}export{n as DEFAULT_ESTIMATE_SIZE,r as DEFAULT_OVERSCAN,t as createMeasurementCache,o as isWindowTarget,s as normalizeOverscan,c as observeResize,l as resolveEstimateFn,i as toNonNegativeInt,a as toPositiveNumber};
+//# sourceMappingURL=_utils.js.map

package/dist/_utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.js","names":[],"sources":["../src/_utils.ts"],"sourcesContent":["import { warn } from './_dev';\n\nexport type ScrollTarget = HTMLElement | Window;\n\nexport type VirtualKey = number | string;\n\n/** Shared measurement cache. Pass the same instance to multiple virtualizers\n *  for scroll restoration or SSR pre-measurement. */\nexport type MeasurementCache = Map<VirtualKey, number>;\n\n/** Create a new, empty measurement cache. */\nexport function createMeasurementCache(): MeasurementCache {\n  return new Map();\n}\n\nexport type Overscan = number | { end?: number; start?: number };\n\nexport const DEFAULT_ESTIMATE_SIZE = 36;\nexport const DEFAULT_OVERSCAN = 3;\n\n// ─── Numeric helpers ───────────────────────────────────────────────────────────\n\nexport function toNonNegativeInt(value: number, fallback = 0): number {\n  if (!Number.isFinite(value)) return fallback;\n\n  return Math.max(0, Math.floor(value));\n}\n\nexport function toPositiveNumber(value: number, fallback: number): number {\n  if (!Number.isFinite(value) || value <= 0 || value > 1e7) return fallback;\n\n  return value;\n}\n\nexport function isWindowTarget(target: ScrollTarget): target is Window {\n  return (\n    (typeof Window !== 'undefined' && target instanceof Window) ||\n    (typeof (target as Window).innerHeight === 'number' && typeof (target as Window).document === 'object')\n  );\n}\n\nexport function normalizeOverscan(overscan: Overscan | undefined, defaultVal: number): { end: number; start: number } {\n  if (typeof overscan === 'number') {\n    const n = toNonNegativeInt(overscan, defaultVal);\n\n    return { end: n, start: n };\n  }\n\n  return {\n    end: toNonNegativeInt(overscan?.end ?? defaultVal),\n    start: toNonNegativeInt(overscan?.start ?? defaultVal),\n  };\n}\n\n/**\n * Create a `ResizeObserver` that reports size changes on `el` via `onSize`, tied to\n * `signal` so it is disconnected automatically when the owning factory disposes —\n * even if the caller never calls the returned disconnect function.\n */\nexport function observeResize(\n  signal: AbortSignal,\n  el: HTMLElement,\n  onSize: (entry: ResizeObserverEntry) => void,\n): () => void {\n  const ro = new ResizeObserver((entries) => {\n    for (const entry of entries) onSize(entry);\n  });\n\n  ro.observe(el);\n  signal.addEventListener('abort', () => ro.disconnect(), { once: true });\n\n  return () => ro.disconnect();\n}\n\nexport function resolveEstimateFn(\n  estimate: number | ((index: number) => number) | undefined,\n  defaultSize: number,\n): (index: number) => number {\n  if (typeof estimate === 'function') {\n    return (index: number) => {\n      try {\n        return toPositiveNumber(estimate(index), defaultSize);\n      } catch (err) {\n        warn(`estimateSize threw for index ${index}: ${err}`);\n\n        return defaultSize;\n      }\n    };\n  }\n\n  const size = typeof estimate === 'number' ? toPositiveNumber(estimate, defaultSize) : defaultSize;\n\n  return () => size;\n}\n"],"mappings":"iCAWA,SAAgB,GAA2C,CACzD,OAAO,IAAI,GACb,CAIA,IAAa,EAAwB,GACxB,EAAmB,EAIhC,SAAgB,EAAiB,EAAe,EAAW,EAAW,CAGpE,OAFK,OAAO,SAAS,CAAK,EAEnB,KAAK,IAAI,EAAG,KAAK,MAAM,CAAK,CAAC,EAFA,CAGtC,CAEA,SAAgB,EAAiB,EAAe,EAA0B,CAGxE,MAFI,CAAC,OAAO,SAAS,CAAK,GAAK,GAAS,GAAK,EAAQ,IAAY,EAE1D,CACT,CAEA,SAAgB,EAAe,EAAwC,CACrE,OACG,OAAO,OAAW,KAAe,aAAkB,QACnD,OAAQ,EAAkB,aAAgB,UAAY,OAAQ,EAAkB,UAAa,QAElG,CAEA,SAAgB,EAAkB,EAAgC,EAAoD,CACpH,GAAI,OAAO,GAAa,SAAU,CAChC,IAAM,EAAI,EAAiB,EAAU,CAAU,EAE/C,MAAO,CAAE,IAAK,EAAG,MAAO,CAAE,CAC5B,CAEA,MAAO,CACL,IAAK,EAAiB,GAAU,KAAO,CAAU,EACjD,MAAO,EAAiB,GAAU,OAAS,CAAU,CACvD,CACF,CAOA,SAAgB,EACd,EACA,EACA,EACY,CACZ,IAAM,EAAK,IAAI,eAAgB,GAAY,CACzC,IAAK,IAAM,KAAS,EAAS,EAAO,CAAK,CAC3C,CAAC,EAKD,OAHA,EAAG,QAAQ,CAAE,EACb,EAAO,iBAAiB,YAAe,EAAG,WAAW,EAAG,CAAE,KAAM,EAAK,CAAC,MAEzD,EAAG,WAAW,CAC7B,CAEA,SAAgB,EACd,EACA,EAC2B,CAC3B,GAAI,OAAO,GAAa,WACtB,MAAQ,IAAkB,CACxB,GAAI,CACF,OAAO,EAAiB,EAAS,CAAK,EAAG,CAAW,CACtD,OAAS,EAAK,CAGZ,OAFA,EAAK,gCAAgC,EAAM,IAAI,GAAK,EAE7C,CACT,CACF,EAGF,IAAM,EAAO,OAAO,GAAa,SAAW,EAAiB,EAAU,CAAW,EAAI,EAEtF,UAAa,CACf"}

package/dist/dom-virtual-list.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs");require("./_utils.cjs");const t=require("./virtualizer.cjs");function n(){let e=new Map,t=new Map,n=[],r=!1;return{acquire(i,a){if(!r)return a();let o=e.get(i);if(o)return t.set(i,o),o;let s=n.pop()??a();return t.set(i,s),s},beginCycle(){t=new Map,r=!0},clear(){for(let t of e.values())t.remove();e.clear(),t.clear(),n.length=0,r=!1},endCycle(){if(r){r=!1;for(let[r,i]of e)t.has(r)||(i.remove(),n.push(i));e=t}}}}function r(r){let i=[],a=!1,o=new AbortController,s=r.listElement,c=n(),l=null;function u(e){let t=i[e];return t!==void 0&&r.getItemKey?r.getItemKey(e,t):e}function d(e){if(r.estimateSize===void 0)return 36;if(typeof r.estimateSize==`number`)return r.estimateSize;let t=i[e];return t===void 0?36:r.estimateSize(e,t)}function f(e){r.horizontal?(s.style.height=``,s.style.width=`${e}px`):(s.style.height=`${e}px`,s.style.width=``)}function p(t){let n=i[t.index];if(n===void 0)throw new e.ScrollRangeError(`toRenderItem: index ${t.index} is out of range (currentItems.length=${i.length})`);return{...t,data:n}}function m(e){f(e.totalSize),c.beginCycle();try{r.render({items:e.items.map(p),listEl:s,recycle:(e,t)=>c.acquire(e,t),stickyItems:e.stickyItems.map(p),totalSize:e.totalSize})}finally{c.endCycle()}}function h(){c.clear(),r.clear?r.clear(s):s.textContent=``,s.style.height=``,s.style.width=``,s.style.position=``,s.style.contain=``}function g(){l=t.createVirtualizer(r.scrollElement,{count:i.length,estimateSize:d,gap:r.gap,getItemKey:u,horizontal:r.horizontal,measurementCache:r.measurementCache,onChange:m,overscan:r.overscan??3,sticky:r.sticky?e=>{let t=i[e];return t!==void 0&&r.sticky(e,t)}:void 0}),s.style.position=`relative`,s.style.contain=`layout`}function _(){a||(a=!0,o.abort(),l?.dispose(),l=null,h())}return{get count(){return l?.count??0},get disposalSignal(){return o.signal},dispose:_,get disposed(){return a},invalidate(){a||l?.invalidate()},get isScrolling(){return l?.isScrolling??!1},get items(){return l?.items??[]},measure(e,t){a||l?.measure(e,t)},measureBatch(e){a||l?.measureBatch(e)},measureEl(e,t){return a?()=>{}:l?.measureEl(e,t)??(()=>{})},refresh(){a||l?.refresh()},get scrollOffset(){return l?.scrollOffset??0},scrollToBottom(e){a||l?.scrollToBottom(e)},scrollToIndex(e,t){a||l?.scrollToIndex(e,t)},scrollToOffset(e,t){a||l?.scrollToOffset(e,t)},scrollToTop(e){a||l?.scrollToTop(e)},setItems(e){if(a)return;if(i=e,e.length===0){l?.dispose(),l=null,h();return}if(!l){g();return}let t=e.length!==l.count;l.update({count:e.length}),t?r.getItemKey||l.invalidate():r.getItemKey?l.refresh():l.invalidate()},get stickyItems(){return l?.stickyItems??[]},[Symbol.dispose]:_,get totalSize(){return l?.totalSize??0}}}function i(e,t){let n=document.createElement(`div`);n.style.cssText=t.horizontal?`overflow: auto hidden; width: 100%; height: 100%;`:`overflow: hidden auto; width: 100%; height: 100%;`,t.containerClass&&(n.className=t.containerClass);let i=document.createElement(`div`);n.appendChild(i),e.appendChild(n);let a;try{a=r({...t,listElement:i,scrollElement:n})}catch(e){throw n.remove(),e}let o=a.dispose.bind(a);return Object.assign(a,{dispose(){o(),n.remove()},[Symbol.dispose](){o(),n.remove()}})}exports.createDomVirtualList=r,exports.createVirtualScroller=i;
+//# sourceMappingURL=dom-virtual-list.cjs.map

package/dist/dom-virtual-list.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-virtual-list.cjs","names":[],"sources":["../src/dom-virtual-list.ts"],"sourcesContent":["import { DEFAULT_ESTIMATE_SIZE, DEFAULT_OVERSCAN, type MeasurementCache, type Overscan } from './_utils';\nimport { ScrollRangeError } from './errors';\nimport {\n  createVirtualizer,\n  type ScrollToIndexOptions,\n  type VirtualItem,\n  type Virtualizer,\n  type VirtualizerState,\n  type VirtualKey,\n} from './virtualizer';\n\nexport type {\n  MeasurementCache,\n  Overscan,\n  ScrollToIndexOptions,\n  VirtualItem,\n  Virtualizer,\n  VirtualizerState,\n  VirtualKey,\n};\n\n// ─── Types ────────────────────────────────────────────────────────────────────\n\n/** A `VirtualItem` enriched with the corresponding data record. */\nexport type VirtualRenderItem<T> = VirtualItem & { readonly data: T };\n\n/**\n * Recycle a DOM node by key. If the pool has a live node for `key`, it is\n * returned and reused; otherwise `create()` is called to produce a new one.\n */\nexport type RecycleFn = (key: VirtualKey, create: () => HTMLElement) => HTMLElement;\n\nexport type DomVirtualListRenderArgs<T> = {\n  items: Array<VirtualRenderItem<T>>;\n  listEl: HTMLElement;\n  recycle: RecycleFn;\n  /** Sticky items from the underlying virtualizer, enriched with data. */\n  stickyItems: Array<VirtualRenderItem<T>>;\n  totalSize: number;\n};\n\nexport type DomVirtualListOptions<T> = {\n  /** Custom teardown that clears listEl. Defaults to `listEl.textContent = ''`. */\n  clear?: (listEl: HTMLElement) => void;\n  estimateSize?: number | ((index: number, item: T) => number);\n  gap?: number;\n  getItemKey?: (index: number, item: T) => VirtualKey;\n  horizontal?: boolean;\n  listElement: HTMLElement;\n  /** External measurement cache for scroll restoration. */\n  measurementCache?: MeasurementCache;\n  overscan?: Overscan;\n  render: (args: DomVirtualListRenderArgs<T>) => void;\n  scrollElement: HTMLElement | Window;\n  /** Mark items as sticky headers. Receives the item index and the item data. */\n  sticky?: (index: number, item: T) => boolean;\n};\n\n/**\n * R11: Controller extends Virtualizer so all methods (scrollToIndex, refresh,\n * scrollToOffset, etc.) are accessible directly on the controller without\n * needing to unwrap an inner virtualizer handle.\n *\n * `prepend` and `update` are omitted — use `setItems()` for item updates and\n * there is no direct `prepend` concept in DomVirtualList.\n */\nexport type DomVirtualListController<T> = Omit<Virtualizer, 'prepend' | 'update'> & {\n  setItems: (items: T[]) => void;\n};\n\nexport type VirtualScrollerOptions<T> = Omit<DomVirtualListOptions<T>, 'listElement' | 'scrollElement'> & {\n  /** Additional CSS class names on the generated scroll container. */\n  containerClass?: string;\n};\n\n// ─── Node pool ────────────────────────────────────────────────────────────────\n\nfunction createNodePool() {\n  let live = new Map<VirtualKey, HTMLElement>();\n  let nextLive = new Map<VirtualKey, HTMLElement>();\n  const stale: HTMLElement[] = [];\n  let inCycle = false;\n\n  return {\n    acquire(key: VirtualKey, create: () => HTMLElement): HTMLElement {\n      if (!inCycle) return create();\n\n      const existing = live.get(key);\n\n      if (existing) {\n        nextLive.set(key, existing);\n\n        return existing;\n      }\n\n      const node = stale.pop() ?? create();\n\n      nextLive.set(key, node);\n\n      return node;\n    },\n\n    beginCycle(): void {\n      nextLive = new Map();\n      inCycle = true;\n    },\n\n    clear(): void {\n      for (const node of live.values()) node.remove();\n\n      live.clear();\n      nextLive.clear();\n      stale.length = 0;\n      inCycle = false;\n    },\n\n    endCycle(): void {\n      if (!inCycle) return;\n\n      inCycle = false;\n\n      for (const [key, node] of live) {\n        if (!nextLive.has(key)) {\n          node.remove();\n          stale.push(node);\n        }\n      }\n\n      live = nextLive;\n    },\n  };\n}\n\n// ─── Implementation ────────────────────────────────────────────────────────────\n\nexport function createDomVirtualList<T>(options: DomVirtualListOptions<T>): DomVirtualListController<T> {\n  let currentItems: T[] = [];\n  let isDestroyed = false;\n  const ac = new AbortController();\n  const listEl = options.listElement;\n\n  // Pool must be declared before virtualizer since handleChange (passed as onChange)\n  // is invoked during createVirtualizer initialization via computeVisible.\n  const pool = createNodePool();\n\n  // Virtualizer is lazily created on the first non-empty setItems call.\n  let virtualizer: Virtualizer | null = null;\n\n  function resolveKey(index: number): VirtualKey {\n    const item = currentItems[index];\n\n    if (item !== undefined && options.getItemKey) return options.getItemKey(index, item);\n\n    return index;\n  }\n\n  function resolveEstimate(index: number): number {\n    if (options.estimateSize === undefined) return DEFAULT_ESTIMATE_SIZE;\n\n    if (typeof options.estimateSize === 'number') return options.estimateSize;\n\n    const item = currentItems[index];\n\n    return item !== undefined ? options.estimateSize(index, item) : DEFAULT_ESTIMATE_SIZE;\n  }\n\n  function applyListSize(totalSize: number): void {\n    if (options.horizontal) {\n      listEl.style.height = '';\n      listEl.style.width = `${totalSize}px`;\n    } else {\n      listEl.style.height = `${totalSize}px`;\n      listEl.style.width = '';\n    }\n  }\n\n  /**\n   * R10: Throw rather than silently produce `undefined as T`.\n   * This catches bugs where `vi.index` is out of range for `currentItems`.\n   */\n  function toRenderItem(vi: VirtualItem): VirtualRenderItem<T> {\n    const data = currentItems[vi.index];\n\n    if (data === undefined) {\n      throw new ScrollRangeError(\n        `toRenderItem: index ${vi.index} is out of range (currentItems.length=${currentItems.length})`,\n      );\n    }\n\n    return { ...vi, data };\n  }\n\n  function handleChange(state: VirtualizerState): void {\n    applyListSize(state.totalSize);\n\n    pool.beginCycle();\n\n    // R5: try/finally ensures endCycle() runs even if render() throws, keeping\n    // the pool in a consistent state.\n    try {\n      options.render({\n        items: state.items.map(toRenderItem),\n        listEl,\n        recycle: (key, create) => pool.acquire(key, create),\n        stickyItems: state.stickyItems.map(toRenderItem),\n        totalSize: state.totalSize,\n      });\n    } finally {\n      pool.endCycle();\n    }\n  }\n\n  function clearAndReset(): void {\n    pool.clear();\n\n    if (options.clear) {\n      options.clear(listEl);\n    } else {\n      listEl.textContent = '';\n    }\n\n    listEl.style.height = '';\n    listEl.style.width = '';\n    listEl.style.position = '';\n    listEl.style.contain = '';\n  }\n\n  function spawnVirtualizer(): void {\n    virtualizer = createVirtualizer(options.scrollElement, {\n      count: currentItems.length,\n      estimateSize: resolveEstimate,\n      gap: options.gap,\n      getItemKey: resolveKey,\n      horizontal: options.horizontal,\n      measurementCache: options.measurementCache,\n      onChange: handleChange,\n      overscan: options.overscan ?? DEFAULT_OVERSCAN,\n      sticky: options.sticky\n        ? (index) => {\n            const item = currentItems[index];\n\n            return item !== undefined && options.sticky!(index, item);\n          }\n        : undefined,\n    });\n\n    listEl.style.position = 'relative';\n    listEl.style.contain = 'layout';\n  }\n\n  function _dispose(): void {\n    if (isDestroyed) return;\n\n    isDestroyed = true;\n    ac.abort();\n    virtualizer?.dispose();\n    virtualizer = null;\n    clearAndReset();\n  }\n\n  return {\n    // ── Virtualizer passthrough (R11) ──────────────────────────────────────\n    get count() {\n      return virtualizer?.count ?? 0;\n    },\n\n    get disposalSignal() {\n      return ac.signal;\n    },\n\n    dispose: _dispose,\n\n    get disposed() {\n      return isDestroyed;\n    },\n\n    invalidate() {\n      if (isDestroyed) return;\n\n      virtualizer?.invalidate();\n    },\n\n    get isScrolling() {\n      return virtualizer?.isScrolling ?? false;\n    },\n\n    get items() {\n      return virtualizer?.items ?? [];\n    },\n\n    measure(index, size) {\n      if (isDestroyed) return;\n\n      virtualizer?.measure(index, size);\n    },\n\n    measureBatch(entries) {\n      if (isDestroyed) return;\n\n      virtualizer?.measureBatch(entries);\n    },\n\n    measureEl(index, el) {\n      if (isDestroyed) return () => {};\n\n      return virtualizer?.measureEl(index, el) ?? (() => {});\n    },\n\n    refresh() {\n      if (isDestroyed) return;\n\n      virtualizer?.refresh();\n    },\n\n    get scrollOffset() {\n      return virtualizer?.scrollOffset ?? 0;\n    },\n\n    scrollToBottom(scrollOptions) {\n      if (isDestroyed) return;\n\n      virtualizer?.scrollToBottom(scrollOptions);\n    },\n\n    scrollToIndex(index, scrollOptions) {\n      if (isDestroyed) return;\n\n      virtualizer?.scrollToIndex(index, scrollOptions);\n    },\n\n    scrollToOffset(offset, scrollOptions) {\n      if (isDestroyed) return;\n\n      virtualizer?.scrollToOffset(offset, scrollOptions);\n    },\n\n    scrollToTop(scrollOptions) {\n      if (isDestroyed) return;\n\n      virtualizer?.scrollToTop(scrollOptions);\n    },\n\n    // ── DomVirtualList-specific ────────────────────────────────────────────\n    setItems(items) {\n      if (isDestroyed) return;\n\n      currentItems = items;\n\n      if (items.length === 0) {\n        virtualizer?.dispose();\n        virtualizer = null;\n        clearAndReset();\n\n        return;\n      }\n\n      if (!virtualizer) {\n        spawnVirtualizer();\n\n        return;\n      }\n\n      const countChanged = items.length !== virtualizer.count;\n\n      // Only count needs explicit update — estimateSize and getItemKey are\n      // closures that already reflect the latest currentItems automatically.\n      virtualizer.update({ count: items.length });\n\n      // When count changed, update() already triggered rebuild + computeVisible().\n      // Only force re-emission when count is unchanged (data changed, count same).\n      if (!countChanged) {\n        // refresh() re-emits with current sizes for stable keys;\n        // invalidate() clears position-based measurements when no stable keys.\n        if (options.getItemKey) {\n          virtualizer.refresh();\n        } else {\n          virtualizer.invalidate();\n        }\n      } else if (!options.getItemKey) {\n        // Count changed AND no stable keys: position-based measurements are now\n        // stale. Clear them so the next render remeasures from fresh estimates.\n        virtualizer.invalidate();\n      }\n    },\n\n    get stickyItems() {\n      return virtualizer?.stickyItems ?? [];\n    },\n\n    [Symbol.dispose]: _dispose,\n\n    get totalSize() {\n      return virtualizer?.totalSize ?? 0;\n    },\n  };\n}\n\n// ─── F5: createVirtualScroller ────────────────────────────────────────────────\n\n/**\n * High-level factory that creates the scroll container and inner list element,\n * appends them to `container`, and returns a fully wired `DomVirtualListController`.\n *\n * @example\n * ```ts\n * const list = createVirtualScroller(document.getElementById('root')!, {\n *   render({ items, listEl, recycle }) { … },\n * });\n * list.setItems(data);\n * ```\n */\nexport function createVirtualScroller<T>(\n  container: HTMLElement,\n  options: VirtualScrollerOptions<T>,\n): DomVirtualListController<T> {\n  const scrollEl = document.createElement('div');\n\n  scrollEl.style.cssText = options.horizontal\n    ? 'overflow: auto hidden; width: 100%; height: 100%;'\n    : 'overflow: hidden auto; width: 100%; height: 100%;';\n\n  if (options.containerClass) scrollEl.className = options.containerClass;\n\n  const listEl = document.createElement('div');\n\n  scrollEl.appendChild(listEl);\n  container.appendChild(scrollEl);\n\n  let ctrl: DomVirtualListController<T>;\n\n  try {\n    ctrl = createDomVirtualList<T>({\n      ...options,\n      listElement: listEl,\n      scrollElement: scrollEl,\n    });\n  } catch (e) {\n    // Remove the scroll container if construction fails so we don't leak DOM nodes.\n    scrollEl.remove();\n    throw e;\n  }\n\n  // Override dispose and [Symbol.dispose] to also remove the scroll container.\n  // Capture the original dispose before overwriting so there's no self-reference.\n  const innerDispose = ctrl.dispose.bind(ctrl);\n\n  return Object.assign(ctrl, {\n    dispose() {\n      innerDispose();\n      scrollEl.remove();\n    },\n    [Symbol.dispose]() {\n      innerDispose();\n      scrollEl.remove();\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/dom-virtual-list.d.ts

@@ -0,0 +1,66 @@
+import { type MeasurementCache, type Overscan } from './_utils';
+import { type ScrollToIndexOptions, type VirtualItem, type Virtualizer, type VirtualizerState, type VirtualKey } from './virtualizer';
+export type { MeasurementCache, Overscan, ScrollToIndexOptions, VirtualItem, Virtualizer, VirtualizerState, VirtualKey, };
+/** A `VirtualItem` enriched with the corresponding data record. */
+export type VirtualRenderItem<T> = VirtualItem & {
+    readonly data: T;
+};
+/**
+ * Recycle a DOM node by key. If the pool has a live node for `key`, it is
+ * returned and reused; otherwise `create()` is called to produce a new one.
+ */
+export type RecycleFn = (key: VirtualKey, create: () => HTMLElement) => HTMLElement;
+export type DomVirtualListRenderArgs<T> = {
+    items: Array<VirtualRenderItem<T>>;
+    listEl: HTMLElement;
+    recycle: RecycleFn;
+    /** Sticky items from the underlying virtualizer, enriched with data. */
+    stickyItems: Array<VirtualRenderItem<T>>;
+    totalSize: number;
+};
+export type DomVirtualListOptions<T> = {
+    /** Custom teardown that clears listEl. Defaults to `listEl.textContent = ''`. */
+    clear?: (listEl: HTMLElement) => void;
+    estimateSize?: number | ((index: number, item: T) => number);
+    gap?: number;
+    getItemKey?: (index: number, item: T) => VirtualKey;
+    horizontal?: boolean;
+    listElement: HTMLElement;
+    /** External measurement cache for scroll restoration. */
+    measurementCache?: MeasurementCache;
+    overscan?: Overscan;
+    render: (args: DomVirtualListRenderArgs<T>) => void;
+    scrollElement: HTMLElement | Window;
+    /** Mark items as sticky headers. Receives the item index and the item data. */
+    sticky?: (index: number, item: T) => boolean;
+};
+/**
+ * R11: Controller extends Virtualizer so all methods (scrollToIndex, refresh,
+ * scrollToOffset, etc.) are accessible directly on the controller without
+ * needing to unwrap an inner virtualizer handle.
+ *
+ * `prepend` and `update` are omitted — use `setItems()` for item updates and
+ * there is no direct `prepend` concept in DomVirtualList.
+ */
+export type DomVirtualListController<T> = Omit<Virtualizer, 'prepend' | 'update'> & {
+    setItems: (items: T[]) => void;
+};
+export type VirtualScrollerOptions<T> = Omit<DomVirtualListOptions<T>, 'listElement' | 'scrollElement'> & {
+    /** Additional CSS class names on the generated scroll container. */
+    containerClass?: string;
+};
+export declare function createDomVirtualList<T>(options: DomVirtualListOptions<T>): DomVirtualListController<T>;
+/**
+ * High-level factory that creates the scroll container and inner list element,
+ * appends them to `container`, and returns a fully wired `DomVirtualListController`.
+ *
+ * @example
+ * ```ts
+ * const list = createVirtualScroller(document.getElementById('root')!, {
+ *   render({ items, listEl, recycle }) { … },
+ * });
+ * list.setItems(data);
+ * ```
+ */
+export declare function createVirtualScroller<T>(container: HTMLElement, options: VirtualScrollerOptions<T>): DomVirtualListController<T>;
+//# sourceMappingURL=dom-virtual-list.d.ts.map

package/dist/dom-virtual-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-virtual-list.d.ts","sourceRoot":"","sources":["../src/dom-virtual-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzG,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,UAAU,GACX,CAAC;AAIF,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,KAAK,WAAW,CAAC;AAEpF,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI;IACxC,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,SAAS,CAAC;IACnB,wEAAwE;IACxE,WAAW,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,UAAU,CAAC;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACpD,aAAa,EAAE,WAAW,GAAG,MAAM,CAAC;IACpC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;CAC9C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC,GAAG;IAClF,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,aAAa,GAAG,eAAe,CAAC,GAAG;IACxG,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAoQtG;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,wBAAwB,CAAC,CAAC,CAAC,CA0C7B"}

package/dist/dom-virtual-list.js

@@ -0,0 +1,2 @@
+import{ScrollRangeError as e}from"./errors.js";import"./_utils.js";import{createVirtualizer as t}from"./virtualizer.js";function n(){let e=new Map,t=new Map,n=[],r=!1;return{acquire(i,a){if(!r)return a();let o=e.get(i);if(o)return t.set(i,o),o;let s=n.pop()??a();return t.set(i,s),s},beginCycle(){t=new Map,r=!0},clear(){for(let t of e.values())t.remove();e.clear(),t.clear(),n.length=0,r=!1},endCycle(){if(r){r=!1;for(let[r,i]of e)t.has(r)||(i.remove(),n.push(i));e=t}}}}function r(r){let i=[],a=!1,o=new AbortController,s=r.listElement,c=n(),l=null;function u(e){let t=i[e];return t!==void 0&&r.getItemKey?r.getItemKey(e,t):e}function d(e){if(r.estimateSize===void 0)return 36;if(typeof r.estimateSize==`number`)return r.estimateSize;let t=i[e];return t===void 0?36:r.estimateSize(e,t)}function f(e){r.horizontal?(s.style.height=``,s.style.width=`${e}px`):(s.style.height=`${e}px`,s.style.width=``)}function p(t){let n=i[t.index];if(n===void 0)throw new e(`toRenderItem: index ${t.index} is out of range (currentItems.length=${i.length})`);return{...t,data:n}}function m(e){f(e.totalSize),c.beginCycle();try{r.render({items:e.items.map(p),listEl:s,recycle:(e,t)=>c.acquire(e,t),stickyItems:e.stickyItems.map(p),totalSize:e.totalSize})}finally{c.endCycle()}}function h(){c.clear(),r.clear?r.clear(s):s.textContent=``,s.style.height=``,s.style.width=``,s.style.position=``,s.style.contain=``}function g(){l=t(r.scrollElement,{count:i.length,estimateSize:d,gap:r.gap,getItemKey:u,horizontal:r.horizontal,measurementCache:r.measurementCache,onChange:m,overscan:r.overscan??3,sticky:r.sticky?e=>{let t=i[e];return t!==void 0&&r.sticky(e,t)}:void 0}),s.style.position=`relative`,s.style.contain=`layout`}function _(){a||(a=!0,o.abort(),l?.dispose(),l=null,h())}return{get count(){return l?.count??0},get disposalSignal(){return o.signal},dispose:_,get disposed(){return a},invalidate(){a||l?.invalidate()},get isScrolling(){return l?.isScrolling??!1},get items(){return l?.items??[]},measure(e,t){a||l?.measure(e,t)},measureBatch(e){a||l?.measureBatch(e)},measureEl(e,t){return a?()=>{}:l?.measureEl(e,t)??(()=>{})},refresh(){a||l?.refresh()},get scrollOffset(){return l?.scrollOffset??0},scrollToBottom(e){a||l?.scrollToBottom(e)},scrollToIndex(e,t){a||l?.scrollToIndex(e,t)},scrollToOffset(e,t){a||l?.scrollToOffset(e,t)},scrollToTop(e){a||l?.scrollToTop(e)},setItems(e){if(a)return;if(i=e,e.length===0){l?.dispose(),l=null,h();return}if(!l){g();return}let t=e.length!==l.count;l.update({count:e.length}),t?r.getItemKey||l.invalidate():r.getItemKey?l.refresh():l.invalidate()},get stickyItems(){return l?.stickyItems??[]},[Symbol.dispose]:_,get totalSize(){return l?.totalSize??0}}}function i(e,t){let n=document.createElement(`div`);n.style.cssText=t.horizontal?`overflow: auto hidden; width: 100%; height: 100%;`:`overflow: hidden auto; width: 100%; height: 100%;`,t.containerClass&&(n.className=t.containerClass);let i=document.createElement(`div`);n.appendChild(i),e.appendChild(n);let a;try{a=r({...t,listElement:i,scrollElement:n})}catch(e){throw n.remove(),e}let o=a.dispose.bind(a);return Object.assign(a,{dispose(){o(),n.remove()},[Symbol.dispose](){o(),n.remove()}})}export{r as createDomVirtualList,i as createVirtualScroller};
+//# sourceMappingURL=dom-virtual-list.js.map