\n )}\n \n \n )\n}\n```\n\n## Sizing\n\n`viewportSize` is **optional and best omitted**. When it is absent the component measures its own band\n(the content element, via `ResizeObserver`) and every derived value follows automatically.\n\n```tsx\n// The host owns the height; VirtualScroll fills it.\n
\n {renderRow}\n
\n```\n\n**The host must establish a definite height** (`h-full`, `flex-1` + `min-h-0`, an explicit px height,\n`position: absolute`, ā¦). With an auto-height host the band stays 0 and the package logs a warning ā\nthere is nothing to measure. In self-measured mode the root carries `data-self-measured=\"true\"` and the\npackaged rule `.aqvs-scroll-pane[data-self-measured=\"true\"] { height: 100% }` stretches it to the host,\nso the stylesheet import is required for this mode as well.\n\n**Pass `viewportSize` only when the band is known by calculation, not measurement** ā a dropdown whose\nheight comes from row count Ć row height, for example. If you pass a value that disagrees with the real\nband by more than 1px, the package warns: the clip window, the max scroll position, the thumb mapping,\nthe rendered row count and scrollability all derive from it, so all five would be silently wrong (rows\nspilling over the next element, a dead band at the bottom, an end you can never reach, a thumb that\nleaves the viewport, or a list that ignores the wheel entirely).\n\n## Horizontal Scrolling\n\n`VirtualScroll` virtualizes and scrolls the **vertical** axis only. To add a horizontal axis ā e.g. a\ndata grid whose columns extend past the viewport ā pass `onWheelHorizontal`. Horizontal-dominant\nwheel / trackpad gestures (and shift+wheel) are then delegated to your handler, which drives a\nhorizontal offset you own. Vertical scrolling is untouched. When `onWheelHorizontal` is omitted,\nhorizontal gestures and shift+wheel bypass vertical scroll interception so parent native scrolling\n(e.g., `overflow-x: auto`) works seamlessly without being consumed.\n\nA common pattern freezes a left column and translates the remaining columns via a shared CSS\nvariable (so rows don't re-render on horizontal scroll), reusing the package's `ScrollBar` with the\n`horizontal` prop for the bottom bar:\n\n```tsx\nimport { ScrollBar, VirtualScroll } from '@aiquants/virtualscroll'\nimport { useCallback, useState } from 'react'\n\nconst clamp = (v: number, max: number) => Math.max(0, Math.min(v, max))\n\nfunction Grid() {\n const [hscroll, setHscroll] = useState(0)\n const maxHScroll = /* contentWidth - visibleWidth */ 632\n const onWheelHorizontal = useCallback((dx: number) => setHscroll((h) => clamp(h + dx, maxHScroll)), [maxHScroll])\n\n // `--hx` on the container is inherited by every row; numeric tracks translate via CSS only.\n return (\n
\n
\n \n {(row) => (\n
\n
{row.label}{/* frozen column */}
\n
\n
{/* numeric columns */}
\n
\n
\n )}\n \n
\n { const c = clamp(typeof next === 'function' ? next(hscroll) : next, maxHScroll); setHscroll(c); return c }}\n />\n
\n )\n}\n```\n\nA runnable version lives in the demo at **`/horizontal`** (`pnpm demo:dev`), and\n[`@aiquants/directory-tree`](../directory-tree)'s TreeGrid mode uses this exact pattern in production.\n\n## Bridging input from outside the pane\n\nThe wheel listener lives on `.aqvs-scroll-pane` only, so anything you render **outside** it ā a frozen\ncolumn header, a sticky footer, the horizontal scrollbar row, an empty-state panel ā is a wheel dead\nzone. Data tables pin the header outside the virtual list by convention, so this gap is the norm, not\nan edge case.\n\nUse `useWheelBridge`: it gives that element the pane's own wheel semantics.\n\n```tsx\nimport { useRef } from 'react'\nimport { useWheelBridge, VirtualScroll, type VirtualScrollHandle } from '@aiquants/virtualscroll'\n\nconst listRef = useRef(null)\nconst headerRef = useWheelBridge(listRef)\n\n
frozen header ā outside the pane
\n{renderRow}\n```\n\n**The hook takes no configuration that affects wheel semantics, and that is the point.** Wheel speed, the horizontal sink, whether\nthe list can scroll, inertia and axis resolution all live behind the handle, in one function\n(`applyWheel`) that the pane's own listener goes through too. Give the bridge its own settings and the\nsame grid ends up scrolling at one speed over the rows and another over the header ā we measured exactly that\nā 30px vs 10px for one wheel tick at `wheelSpeedMultiplier: 3` ā in a work-in-progress build that did give\nthe bridge its own settings. With a single home for the rules, that\nmismatch is not expressible. The hook's job is `{ passive: false }` registration, teardown, and the\n`enableBridge` on/off switch ā nothing else. Deciding whether an event was already applied belongs to\n`applyWheel`, which tracks the events **this package** consumed (see below).\n\nIts one option is `enableBridge` (default `true`) ā a plain on/off switch, not a semantic knob. Pass\n`{ enableBridge: false }` to stop bridging without unmounting the element:\n\n```tsx\nconst headerRef = useWheelBridge(listRef, { enableBridge: !isEditing })\n```\n\nIt works with `ScrollPane` directly too: the parameter is typed against `WheelBridgeTarget`\n(`{ applyWheel }`), which both `VirtualScrollHandle` and `ScrollPaneHandle` satisfy.\n\nComposing with your own ref is safe ā the hook keeps a per-element ledger and skips re-attaching to an\nelement it already holds, so the common inline merge cannot pile up listeners (without it, four\nre-renders leave five live wheel listeners on one element). Return the hook's value so React 19 can run\nits cleanup on unmount:\n\n```tsx\n
{ myRef.current = node; return headerRef(node) }} />\n```\n\nDropping that `return` still works ā the ledger keeps it correct ā but the listener then stays on the\nelement until the element itself is garbage-collected.\n\nThe ledger is keyed **per element**, so one hook can serve several bands (a header and a footer) without\nthem fighting over a single slot.\n\n**Wheel scrolling chains to the page at the edges** (like a native scroll container). A vertical wheel\nthat cannot move the list any further in its own direction is left to the ancestors, so a user wheeling\ndown a long page passes through the list instead of getting trapped. The notch that *reaches* the edge\nis consumed (partial movement, stops exactly at the edge); the *next* notch chains ā the same stepping a\nnative scroller has. Set `behaviorOptions.overscrollBehavior: \"contain\"` to keep the pre-2.7.0 trapping\n(e.g. a list inside a modal where the page behind must never move).\n\nā ļø **`onWheel` cannot do this.** React 19 registers `onWheel` as a passive listener, so `preventDefault()`\nis ignored and the page scrolls instead. The hook attaches a `{ passive: false }` listener itself.\n\nā ļø **Only bridge elements OUTSIDE the pane.** Anything inside the pane is already covered by the pane's\nown listener, so bridging it is a redundant registration ā the consumed-event mark keeps it from being\napplied twice, but the extra listener is pure overhead on the wheel hot path.\n\nā ļø **Do not bridge with `scrollTo`.** It is a *jump* API: it floors the absolute position (sub-pixel\ntrackpad deltas vanish entirely) and pins a scroll anchor (every later size change re-pins the list to\nthat row, so filtering a list makes it jump back to where it used to be). `scrollBy` is the delta API and\ntakes the pane's own path. Also never write `scrollTo(handle.getScrollPosition() + delta)` ā the getter\nreturns the `-1` sentinel while the pane is unconnected.\n\n### Horizontal scrolling from the keyboard\n\nWith `onWheelHorizontal` wired **and `behaviorOptions.enableKeyboardNavigation` left on** (the default),\n`horizontalKeyInputs` lets a focused row emit horizontal deltas too:\n\n| Value | Keys | Use it when |\n| --- | --- | --- |\n| `[]` (default) | ā | Never steal the row's own arrow handling |\n| `[\"arrow\"]` | `ā/ā` | Lists that want keyboard access to the horizontal axis |\n\n`Shift + ā/ā` is **never** consumed (the `\"shift-arrow\"` input was removed in 3.0.0): in the browser it\nextends the text selection, and the 2.x \"yield only while a selection exists\" detection had structural\ndefects ā selections inside Shadow DOM are invisible to `document.getSelection()` (the guard silently\nfails), and `Ctrl+A` makes every row intersect the selection, locking horizontal keys out until the\nselection is cleared. Shift-flavored horizontal input remains available via `shift + wheel`, which does\nnot conflict with selection. The prop stays an array (one vocabulary entry today) to match\n`behaviorOptions.pointerDragInputs` and to keep future additions non-breaking.\n\nThe default is empty on purpose: the package's row key handler runs in the **capture** phase, ahead of\nyour row's own handler. When it consumes a key it calls `preventDefault()` only and deliberately does\n**not** stop propagation ā `stopPropagation()` would delete the event from `document` and `window`\nbubble listeners too, breaking global hotkey libraries and keydown telemetry. Check `defaultPrevented`\nin your own handler, exactly as you would for the vertical arrows.\n\nIt also fires only when the row **itself** is the event target. Focus sitting on something inside the\nrow ā a `role=\"slider\"` cell, a link, a nested `overflow-x:auto` region ā is never hijacked, so you do\nnot have to avoid `[\"arrow\"]` just because your rows contain arrow-key widgets.\n\n`horizontalKeyStep` (default 40) must be finite and positive; anything\nelse logs a warning and leaves the key untouched rather than silently substituting the default.\n\nā ļø **This does nothing when `enableKeyboardNavigation` is `false`** ā the row key handler is what reads\nthese keys, and turning navigation off removes it. The package emits a `Logger.warn` when it sees that\ncombination. Note the next section tells `listbox` / `tree` / `grid` authors to turn navigation off; if\nyou follow both, your arrow keys are dead. Pick one.\n\nā ļø **Rows are not in the page tab sequence** (`tabIndex={-1}`). This feature fires only while a row has\nfocus, so if you want keyboard-only users to reach it, give them an entry point ā for example call\n`handle.focusItemAtIndex(0)` when the list receives focus.\n\nā ļø **Wrappers that own the horizontal axis should seal these too.** If you re-export VirtualScroll with\n`Omit`, add `onPanHorizontal` (3.2.0), `horizontalKeyInputs`\nand `horizontalKeyStep` to that same `Omit`. All four sit at the top level, next to each other,\nprecisely so one `Omit` closes the whole horizontal seam.\n\n## Escape row-return\n\nRows are not in the tab order (`tabIndex={-1}`), so once focus enters a link or widget inside a\nrow there is by default no keyboard way back to the row ā the anchor for arrow-key navigation.\n`behaviorOptions.enableEscapeRowReturn` (default: `false`) makes `Escape` return focus to the row\nwrapper (scrolling it into view if needed).\n\nIt is off by default because `Escape` is the most overloaded key on the page (closing modals and\ndropdowns, cancelling IME composition, clearing selection). The feature therefore listens in the\n**bubble** phase ā a dropdown opened inside a cell handles its own `Escape` first and can keep it\nwith `stopPropagation()` or `preventDefault()` ā skips IME composition (`isComposing`), leaves\n**editable targets** (`input` / `textarea` / `select` / `contentEditable`) entirely alone (their\nnative `Escape` default actions, like Blink/WebKit clearing an ``, never show\nup in `defaultPrevented` and would otherwise be silently suppressed), and never acts while the row\nitself has focus (an `Escape` on the row means whatever *you* decide ā e.g. deselect). When it\ndoes act it calls `preventDefault()` only and does not stop propagation, the same contract as the\narrow keys.\n\n## Screen-reader live region\n\nVirtualization removes off-screen rows from the DOM, so a screen-reader user scrolling the list\ngets no feedback about where they are. The opt-in `liveRegion` prop renders a visually hidden\n`role=\"status\"` element (polite, atomic) next to the pane and updates it after the visible range\nsettles:\n\n```tsx\n `rows ${visibleStartIndex + 1}-${visibleEndIndex + 1} of ${itemCount}`,\n debounceMs: 400, // default; trailing ā announces once after the last range change\n }}\n ...\n/>\n```\n\nThe package ships **no built-in strings** ā wording and language are yours (`format` returning the\nsame string leaves the DOM untouched; `\"\"` clears the region). An invalid `debounceMs` (negative /\nnon-finite) logs a warning and disables announcements instead of silently substituting the\ndefault. ā ļø If your app already maintains its own live region for the list, keep using\n`onRangeChange` instead ā two regions double-announce.\n\n## VirtualGrid (2D ā trillion-scale columns, v3.2.0)\n\n`VirtualGrid` composes the proven row axis (an embedded `VirtualScroll`) with a symmetric\nhorizontal column engine built from the SAME machinery: a second sparse Fenwick width tree,\nthe shared rendering-range computation (BigInt huge branch included), quantized column-anchor\nrebasing at the shared `ANCHOR_REBASE_DISTANCE`, and synthetic scrolling ā total-size pixels\nnever land in the DOM, so `colCount` inherits the full row-axis profile (`<= 2^53 - 1`; ten\ntrillion columns sit comfortably inside).\n\n```tsx\n\n rowCount={1_000_000_000_000}\n colCount={1_000_000_000_000}\n getRowHeight={() => 24}\n getColWidth={() => 100}\n getCell={(row, col) => `${row}:${col}`}\n contentProps={{ role: \"grid\" }} // composite role belongs to the consumer\n getCellProps={(row, col) => ({ role: \"gridcell\" })}\n onRenderTruncated={(info) => console.warn(info)} // the cell cap is never silent\n>\n {(cell) => {cell}}\n\n```\n\nContracts (see the design plan under `docs/plans/` for the full bounding theorem):\n\n- `getRowHeight` / `getColWidth` return integer px, `0` = hidden, `<= MAX_TRACK_SIZE`\n (2^18 px) ā oversized tracks fail fast with a `RangeError` (a single unbounded track would\n pierce the measured browser layout wall at 2^25 px).\n- Per-axis overscan defaults to 3 (a deliberate, documented deviation from the bare\n `VirtualScroll` default of 15 ā the bounding contract's window-span term is\n overscan-proportional). With the defaults, ancestor `scale(z)` stays in the full-precision\n band up to z ā 5.3.\n- The handle mirrors the row contracts: logical coordinates, `-1` sentinels pre-attach,\n `scrollBy`/`scrollTo` return the applied clamped position synchronously, `applyWheel`\n returns a boolean for `useWheelBridge`, and `{index, offset}` anchors\n (`getScrollAnchor` / `initialScrollAnchor`) replace raw-px restore.\n- Header sync: derive the window origin (`offsetOf(renderingColStart)`) from YOUR geometry\n source, position header cells window-relative, and translate the header track by\n `origin - scrollX` per `onScroll` ā the same scheme the row-side headers use. LTR only (v1).\n- Row-side parity carries: `horizontalKeyInputs` / `horizontalKeyStep` (arrow keys reach the\n grid-owned horizontal axis), `contentInsets`, `background`, `onRowFocus` /\n `focusRowAtIndex`, and `behaviorOptions.defaultColWidth` (explicit Fenwick baseValue ā skips\n width sampling). The full member-by-member classification lives in\n `docs/specs/2026.09.01 [AI] virtualscroll-virtual-grid.md`.\n- Frozen leading columns (v3.3.0): `frozenLeadingCols` pins the first F columns as a static\n band OUTSIDE the anchor machinery (direct tree-absolute lefts; scroll cells live inside a\n static clip whose inner carries the `residual - W_F` origin-shift transform). Integer in\n `[0, MAX_FROZEN_LEADING_COLS]` (128) ā `RangeError` otherwise; values beyond the current\n `colCount` freeze every column (documented dynamic clamp). `scrollToCell` /\n `initialScrollAnchor` targeting a frozen column are horizontal no-ops (always visible), and\n `getFrozenSize()` reports the effective `{cols, width, rows, height, trailingCols,\n trailingRows, trailingWidth, trailingHeight, trailingVisibleWidth, trailingVisibleHeight}`\n (both axes, both ends ā the `rows`/`height` fields are a non-breaking v3.4.0 addition and\n the six `trailing*` fields a non-breaking v3.5.0 addition; `trailingWidth`/`trailingHeight`\n are TREE px, the `trailingVisible*` pair is the viewport clip `min(tree, max(0, viewport -\n leading))`) for consumer hit-test partitioning.\n Frozen cells precede the scroll band in row DOM (logical column order for AT / tabbing), and\n an all-frozen grid reports the scroll band as the canonical EMPTY window (`renderingColStart\n > renderingColEnd` ā inclusive loops run zero iterations). `frozenLeadingCols` of `0` (the\n default) is structurally identical to the pre-frozen DOM.\n- Frozen leading rows (v3.4.0): `frozenLeadingRows` pins the first R rows as a grid-owned band\n ABOVE the scroll pane (out-of-pane band + index shift: the embedded row axis only ever sees\n the shifted space `rowCount - R`, so the vertical bar maps the scroll band naturally ā no\n bar inset needed). Band rows reuse the normal row renderer, so frozen columns keep working\n inside them (the frozen-rows x frozen-cols 4-quadrant corner comes for free). Integer in\n `[0, MAX_FROZEN_LEADING_ROWS]` (128) ā `RangeError` otherwise; values beyond the current\n `rowCount` freeze every row (documented dynamic clamp ā the scroll rows then report the\n canonical EMPTY window `renderingRowStart > renderingRowEnd`), as does a degenerate band\n (H_F fills the measured viewport ā zero scroll-row DOM). `scrollToCell` /\n `initialScrollAnchor` targeting a frozen row are vertical no-ops (always visible),\n `contentInsets.top` remains leading blank space INSIDE the scroll band (a pinned band is not\n an inset), and `frozenLeadingRows` of `0` (the default) is structurally identical to the\n pre-frozen DOM. Changing `frozenLeadingRows` at runtime rebuilds the embedded row tree\n (remount) and preserves the visible-top viewpoint across the toggle.\n- Frozen trailing columns / rows (v3.5.0): `frozenTrailingCols` pins the last T columns in a\n right-anchored clip outside the anchor machinery (band-local lefts; the scroll band\n generalizes to `viewport - W_F - W_T` with a right clip inset driven by\n `--aqvs-grid-trailing-width` ā written only while T > 0, `0px` fallback otherwise), and\n `frozenTrailingRows` pins the last T rows as a second grid-owned band BELOW the scroll pane\n (clip height = the visible size `min(H_T, max(0, viewport - H_F))`, inner bottom-anchored at\n the tree height H_T). Band rows reuse the normal row renderer, so every corner of the\n 3 x 3 region grid comes for free. Integers in `[0, MAX_FROZEN_TRAILING_COLS]` /\n `[0, MAX_FROZEN_TRAILING_ROWS]` (128) ā `RangeError` otherwise; the dynamic clamp is\n `min(T, count - effectiveLeading)`: the LEADING band wins the count space (ADR-19-1), and\n when the leading + trailing extents exceed the viewport, occluded trailing cells cannot be\n scrolled into view (a documented clamp ā `scrollToCell` / `initialScrollAnchor` targeting a\n trailing track stay no-ops on that axis, the column no-op leaving any armed column anchor in\n place). Changing `frozenTrailingCols`/`frozenTrailingRows` at runtime does NOT remount the\n embedded row axis (the tail-only itemCount change keeps the viewpoint for free; a pending\n row anchor whose target enters the band clamps to the last scroll row), and a value of `0`\n (the default) is structurally identical to the pre-trailing DOM.\n\n## Residual quantizer for snapping consumers\n\nConsumers that snap positions to a fixed quantum (row height, column width) lose sub-quantum\ndeltas: a high-resolution trackpad emits many small deltas, each rounds to zero rows, and a slow\nswipe never moves. `createResidualQuantizer` carries the remainder across events:\n\n```tsx\nimport { createResidualQuantizer } from \"@aiquants/virtualscroll\"\n\nconst quantizer = createResidualQuantizer({ quantum: ROW_HEIGHT })\nconst onWheelVertical = (deltaY: number) => {\n const emitted = quantizer.push(deltaY) // always a multiple of the quantum (possibly 0)\n if (emitted !== 0) snapScrollBy(emitted)\n}\n```\n\nBy default the residue is dropped on direction reversal (so a stale forward remainder cannot delay\nthe first backward step); call `reset()` from your own idle timer or when the snapped layout\nchanges. `quantum` must be finite and positive (anything else throws ā fail fast). Non-finite\ndeltas and deltas beyond `Number.MAX_SAFE_INTEGER` emit 0 without poisoning the accumulator ā\npast 2^53 the float product stops being an *exact* multiple of the quantum, the very property a\nsnapping consumer relies on. The quantizer is deliberately time-free: idle expiry policies differ\nper UI, so they stay on your side of the seam.\n\n## Suspended transitions (React 18/19 `startTransition` + `Suspense`)\n\nScroll state is judged against the **last committed** dimensions, never against a render that got\ndiscarded. While a transition that shrinks or grows the list is suspended (the old list stays on\nscreen), the wheel keeps working and every jump/clamp uses the sizes the user can actually see ā\na pending shrink cannot snap the list to the top, and a pending grow cannot let you overscroll into\nspace that does not exist yet. Once the transition commits, positions re-clamp against the new sizes\nas usual. Manual scrolling during the pending window also detaches a pending `scrollTo`/`scrollToIndex`\nanchor exactly like it does outside a transition, so the commit does not yank the list back.\n\n(Regression-tested in jsdom and real Chromium: `src/transitionClamp.spec.tsx`,\n`tests/e2e/transition-scroll.spec.ts`.)\n\n## Composite widget roles (listbox / tree / grid)\n\nBuilding a `listbox`, `tree` or `grid` on top of VirtualScroll? Put the role on **`contentProps`**,\nnot on a wrapper around ``:\n\n```tsx\n options[i]}\n getItemHeight={() => 36}\n viewportSize={300}\n contentProps={{ id: listboxId, role: \"listbox\", \"aria-label\": \"Warehouses\" }}\n // Required: with keyboard navigation ON, every row wrapper gets tabIndex={-1}. That does not add a\n // tab stop, but it makes the wrappers focusable ā VirtualScroll then moves real DOM focus onto a row\n // ā and it makes them opaque to the owned-element relationship.\n // ā ļø This also disables `horizontalKeyInputs` ā the row key handler goes away with it.\n behaviorOptions={{ enableKeyboardNavigation: false }}>\n {(option) =>
{option.label}
}\n\n```\n\n**Why the content element and not the root.** The root also contains the custom scrollbar, whose\n`role=\"scrollbar\"` is not an allowed owned child of `listbox` ā ARIA permits only `option` and\n`group`. The content element owns exactly the rendered rows; the scrollbar and any overlay are its\nsiblings. Passing `id` here also overrides the generated one, so the scrollbar's `aria-controls`\nkeeps pointing at the same element.\n\nThe wrappers between the content element and your rows carry no role, no global ARIA attribute and\nno `tabindex`, so they are transparent to the owned-element relationship ā **but only while\n`enableKeyboardNavigation` is `false`**. That is what a consumer driving selection through\n`aria-activedescendant` should be doing anyway: with it on, VirtualScroll moves real DOM focus onto\na row, which the APG combobox/listbox patterns forbid.\n\nFor a virtualized list you must also publish `aria-setsize` (the full count) and `aria-posinset`\n(the absolute 1-based index) on every row ā a browser cannot infer them when only a window of rows\nexists in the DOM.\n\n## API Reference\n\n### VirtualScroll Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `children` | `(item: T, index: number) => ReactNode` | ā | Render function for items |\n| `itemCount` | `number` | ā | Total number of items |\n| `getItem` | `(index: number) => T` | ā | Function to get item at index |\n| `getItemHeight` | `(index: number) => number` | ā | Function to get item height |\n| `viewportSize` | `number` | ā | Height of the visible band. **Omit it** ā the component then measures its host with a `ResizeObserver`. Pass it only when you know the band by calculation rather than measurement (e.g. a dropdown sized from row count Ć row height). See [Sizing](#sizing) |\n| `overscanCount` | `number` | ā | Number of items to render outside viewport (default: 15) |\n| `className` | `string` | ā | CSS class name. Lands on the scroll root (`.aqvs-scroll-pane`) ā see [Custom Scrollbar Styling](#custom-scrollbar-styling) |\n| `getItemKey` | `(index: number) => React.Key` | ā | Stable React key per index (defaults to the index) |\n| `testId` | `string` | ā | Emitted as `data-testid` on the scroll root. DOM hooks should use `data-*`, never class selectors |\n| `onScroll` | `(position: number, totalHeight: number) => void` | ā | Scroll event handler |\n| `onRangeChange` | `(range: VirtualScrollRange) => void` | ā | Range change handler |\n| `onWheelHorizontal` | `(deltaX: number) => void` | ā | Opt-in horizontal delegation. Horizontal-dominant wheel / trackpad gestures (and shift+wheel) are delegated to this handler so the parent can implement horizontal scrolling. ā ļø **Keyboard deltas arrive here too** when `horizontalKeyInputs` is set. When omitted, horizontal gestures bypass vertical scrolling so parent native scrolling works. See [Horizontal Scrolling](#horizontal-scrolling). |\n| `onPanHorizontal` | `(deltaX: number) => void` | ā | Opt-in delegation of the horizontal component of pointer pans (touch / pen drags) ā the pan twin of `onWheelHorizontal` with the same sign convention, per-move increments divided by the press-time x-axis ancestor scale (3.2.0). When set, purely horizontal pans also activate the drag. Same seal family as `onWheelHorizontal` ā wrappers sealing the horizontal axis must `Omit` this name too. |\n| `horizontalKeyInputs` | `readonly \"arrow\"[]` | ā | Keyboard gestures that emit a horizontal delta through `onWheelHorizontal` (default: `[]`, so row-level arrow handling is never stolen). `Shift + ā/ā` is never consumed. Fires only when the row itself is the event target. ā ļø Requires `behaviorOptions.enableKeyboardNavigation` (default `true`) ā with it off the rows have no key handler at all and this prop does nothing (the package warns) |\n| `horizontalKeyStep` | `number` | ā | Pixels per horizontal arrow press (default: 40). Must be finite and positive; anything else warns and leaves the key untouched |\n| `background` | `ReactNode` | ā | Background element |\n| `initialScrollIndex` | `number` | ā | Initial scroll index |\n| `initialScrollOffset` | `number` | ā | Initial scroll offset (**logical** px). Not suitable for restoring positions of variable-height lists across remounts ā use `initialScrollAnchor` |\n| `initialScrollAnchor` | `{ index: number; offsetPx?: number }` | ā | Anchor-based initial position (1.25.0): starts with row `index` scrolled `offsetPx` px past the viewport top, exact from the first commit. Save side: `getScrollAnchor()`. Precedence: anchor > `initialScrollIndex` > `initialScrollOffset` |\n| `contentInsets` | `ScrollPaneContentInsets` | ā | Insets for the content area |\n| `callbackThrottleMs` | `number` | ā | Throttle time for scroll callbacks (default: 5ms) |\n| `onItemFocus` | `(index: number) => void` | ā | Callback when an item is focused |\n| `scrollBarOptions` | `VirtualScrollScrollBarOptions` | ā | Options for the scrollbar |\n| `behaviorOptions` | `VirtualScrollBehaviorOptions` | ā | Options for scrolling behavior |\n| `liveRegion` | `VirtualScrollLiveRegionOptions` | ā | Opt-in screen-reader live region announcing the visible range (nothing rendered when omitted). See [Screen-reader live region](#screen-reader-live-region) |\n| `contentProps` | `React.AriaAttributes & { id?: string; role?: React.AriaRole }` | ā | ARIA / identity attributes for the scrollable **content** element ā the correct host for a composite widget role. See [Composite widget roles](#composite-widget-roles-listbox--tree--grid). |\n\n### VirtualScrollScrollBarOptions\n\n| Property | Type | Description |\n| --- | --- | --- |\n| `width` | `number` | Width of the scrollbar (default: 12) |\n| `enableThumbDrag` | `boolean` | Enable dragging the scrollbar thumb (default: true) |\n| `enableTrackClick` | `boolean` | Enable clicking the scrollbar track (default: true) |\n| `enableArrowButtons` | `boolean` | Enable arrow buttons on the scrollbar (default: true) |\n| `enableScrollToTopBottomButtons` | `boolean` | Enable \"Scroll to Top\" and \"Scroll to Bottom\" buttons (default: false) |\n| `renderThumbOverlay` | `(props: ScrollBarThumbOverlayRenderProps) => ReactNode` | Render prop to anchor custom UI near the scrollbar thumb |\n| `tapScrollCircleOptions` | `ScrollBarTapCircleOptions` | Customization for the auxiliary tap scroll circle |\n\n### VirtualScrollBehaviorOptions\n\n| Property | Type | Description |\n| --- | --- | --- |\n| `enablePointerDrag` | `boolean` | Enable dragging the content area to scroll (default: true). ā ļø Setting this to `false` removes the only way to scroll on touch devices ā the pane is transform-based and has no native scroller. Use `pointerDragInputs` to exclude a single pointer type instead. |\n| `pointerDragInputs` | `readonly (\"mouse\" \\| \"pen\" \\| \"touch\")[]` | Pointer types allowed to drag-scroll the content area (default: all three). `touch-action: none` is applied only when `\"touch\"` or `\"pen\"` is included. |\n| `enableKeyboardNavigation` | `boolean` | Enable keyboard navigation (default: true). Arrow / Page keys move row focus. ā ļø They fire **only when the row wrapper itself is the event target** ā focus inside a row (a `role=\"slider\"` cell, a link, a nested scroll region) keeps its own keys |\n| `enableEscapeRowReturn` | `boolean` | Opt-in (default: false): pressing `Escape` while focus sits on an element **inside** a row returns focus to the row wrapper. Listens in the bubble phase and respects `preventDefault` / `stopPropagation` / IME composition, so widgets inside the row keep first claim on their own `Escape`. Requires `enableKeyboardNavigation` |\n| `wheelSpeedMultiplier` | `number` | Multiplier for mouse wheel scrolling speed (default: 1) |\n| `inertiaOptions` | `ScrollPaneInertiaOptions` | Physics tuning for drag inertia |\n| `overscrollBehavior` | `\"auto\" \\| \"contain\"` | Wheel behavior at the edges (default `\"auto\"` = chain to ancestors like a native scroller; `\"contain\"` = keep consuming, pre-2.7.0 trapping) |\n| `clipItemHeight` | `boolean` | Whether to clip item height (default: false) |\n| `resetOnGetItemHeightChange` | `boolean` | Whether to reset internal height cache when `getItemHeight` changes (default: false) |\n\n### VirtualScrollHandle Methods\n\n| Method | Type | Description |\n| --- | --- | --- |\n| `scrollTo` | `(position: number \\| ((prev: number) => number)) => number` | **Jump** to a **logical** position (updater receives the current logical position). Returns the applied **logical** position (2.0.0). ā ļø Not for bridging continuous input ā see [Bridging input from outside the pane](#bridging-input-from-outside-the-pane) |\n| `scrollBy` | `(delta: number) => number` | Scroll **by a delta** with the pane's own wheel semantics (float accumulation, no anchor). Use this ā not `scrollTo` ā to bridge continuous input from outside the pane. Returns the applied **logical** position |\n| `applyWheel` | `(event: WheelEvent) => boolean` | Apply one wheel event with the pane's own rules; returns whether it was consumed. The single entry point for wheel input originating outside the pane ā normally reached through `useWheelBridge` |\n| *(ScrollPaneHandle only)* `scrollTo` | `(pos, dimsOverride?)` | The pane-level jump. `dimsOverride` is an explicit clamp-space for callers that know **fresher-than-committed** dims (the layout-shift compensation passes `committed + delta`). Do not pass it casually ā a wrong override clamps against dims that are not on screen |\n| `scrollToIndex` | `(index: number, options?: { align?: \"top\" \\| \"bottom\" \\| \"center\"; offset?: number }) => void` | Scroll to specific item index with optional alignment and offset |\n| `getScrollPosition` | `() => number` | Get current **logical** scroll position (2.0.0; `-1` when the pane is not connected) |\n| `getContentSize` | `() => number` | Get total content size (insets included). Returns the `-1` sentinel while the pane is unconnected |\n| `getViewportSize` | `() => number` | Get viewport size. Returns the `-1` sentinel while the pane is unconnected |\n| `focusItemAtIndex` | `(index: number, options?: { ensureVisible?: boolean }) => void` | Focus item at specific index |\n| `getRange` | `() => VirtualScrollRange` | Get current range information (updated one render behind) |\n| `getScrollAnchor` | `() => { index: number; offsetPx: number } \\| null` | Capture the current top visible row anchor for exact restore via `initialScrollAnchor` (`null` when `itemCount` is 0) |\n| `getFenwickTreeTotalHeight` | `() => number` | Total content height managed by the Fenwick tree (insets excluded) |\n| `getFenwickSize` | `() => number` | Item count managed by the Fenwick tree |\n| `updateItemSize` | `(index: number, size: number) => void` | Manually update one item's size (with layout-shift compensation). `getItemHeight(index)` must return the same value afterwards |\n\n**Coordinate system (2.0.0)**: every position the handle and callbacks accept or return is\n**logical** (content px, insets excluded) ā `onScroll` / `onRangeChange` / `initialScroll*` /\n`getScrollAnchor` / `scrollTo` (input AND return) / `getScrollPosition` all share one space, so no\nconversion code is ever needed in consumers. Pane coordinates (insets included) are an internal\ndetail; only `ScrollPane`'s own handle speaks pane-space (it IS the pane). Logical 0 maps to\npane 0 internally (true top, top inset visible; unified in 1.24.0).\n\n### VirtualScrollRange\n\n| Property | Type | Description |\n| --- | --- | --- |\n| `renderingStartIndex` | `number` | Index of the first item being rendered (including overscan) |\n| `renderingEndIndex` | `number` | Index of the last item being rendered (including overscan) |\n| `visibleStartIndex` | `number` | Index of the first fully or partially visible item |\n| `visibleEndIndex` | `number` | Index of the last fully or partially visible item |\n| `scrollPosition` | `number` | Current scroll position in pixels |\n| `totalHeight` | `number` | Total height of the scroll content |\n\n## Advanced Usage\n\n### With Ref and Scroll Control\n\n```tsx\n// Load the stylesheet once, e.g. in your app entry point (see the styling note above)\nimport '@aiquants/virtualscroll/styles/virtualscroll.standalone.css'\nimport { ScrollBarThumbOverlayRenderProps, VirtualScroll, VirtualScrollHandle, VirtualScrollRange } from '@aiquants/virtualscroll'\nimport { useCallback, useRef, useState } from 'react'\n\nconst items = Array.from({ length: 100000 }, (_, index) => ({\n id: index,\n text: `Item ${index}`,\n height: (index % 20) * 2 + 30,\n}))\n\nconst getItem = (index: number) => items[index]\nconst getItemHeight = (index: number) => items[index].height\n\nfunction AdvancedExample() {\n const virtualScrollRef = useRef(null)\n const [visibleStartIndex, setVisibleStartIndex] = useState(0)\n\n const scrollToTop = () => {\n virtualScrollRef.current?.scrollTo(0)\n }\n\n const scrollToIndex = (index: number) => {\n // Scroll to item 500, aligning it to the center of the viewport\n virtualScrollRef.current?.scrollToIndex(index, { align: \"center\" })\n }\n\n const handleRangeChange = useCallback((range: VirtualScrollRange) => {\n setVisibleStartIndex(range.visibleStartIndex)\n }, [])\n\n const renderThumbOverlay = useCallback((props: ScrollBarThumbOverlayRenderProps) => {\n if (!(props.isDragging || props.isTapScrollActive)) {\n return null\n }\n const activeItem = items[visibleStartIndex]\n const label = activeItem ? activeItem.text : `Item ${visibleStartIndex}`\n\n return (\n \n \n {label}\n
\n \n )\n }, [visibleStartIndex])\n\n return (\n
\n
\n \n \n
\n \n {(item, index) => }\n \n
\n )\n}\n```\n\n### Custom Scrollbar Styling\n\n`className` lands on the **scroll root** (`.aqvs-scroll-pane`). The bar, its track, thumb, arrow buttons\nand the Top/Bottom pills are all descendants of that element, so one wrapper class reaches every part:\n\n```tsx\n\n {(item, index) => }\n\n```\n\n```css\n/* The bar and its track. The stripe you see behind the thumb is the track. */\n.custom-virtual-scroll .aqvs-scrollbar { background-color: #f0f0f0; }\n.custom-virtual-scroll .aqvs-scrollbar-track { background-color: #e8e8e8; }\n\n/* The thumb. Restate the states you want to keep ā see \"State rules are replaced\" below. */\n.custom-virtual-scroll .aqvs-scrollbar-thumb { background-color: #007acc; }\n.custom-virtual-scroll .aqvs-scrollbar-thumb[data-thumb-state=\"hover\"] { background-color: #3399dd; }\n.custom-virtual-scroll .aqvs-scrollbar-thumb[data-thumb-state=\"dragging\"] { background-color: #005c99; }\n.custom-virtual-scroll .aqvs-scrollbar-thumb[data-thumb-state=\"disabled\"] { background-color: #b0c4d4; }\n\n/* Arrow buttons and the Top/Bottom pills. */\n.custom-virtual-scroll .aqvs-scrollbar-arrow-button { background-color: #e8e8e8; color: #007acc; }\n.custom-virtual-scroll .aqvs-scrollbar-arrow-button:enabled:hover { background-color: #cfe8f7; }\n.custom-virtual-scroll .aqvs-scroll-to-edge-button { background-color: rgba(0, 122, 204, 0.85); }\n.custom-virtual-scroll .aqvs-scroll-to-edge-button:hover { background-color: rgba(0, 92, 153, 0.9); }\n```\n\nThe packaged rules live in `@layer components` in **both** artifacts, so an ordinary (unlayered) rule in\nyour app wins regardless of specificity and regardless of import order ā no `!important`, no deeper\nselector. Keep your rules unlayered: written inside a `@layer components { ā¦ }` block of your own you\nre-enter the package's layer, and ordinary specificity ā then source order ā decides again. The example\nabove still wins there (every selector is prefixed with your wrapper class), but an unprefixed\n`.aqvs-scrollbar-thumb { ā¦ }` in that layer loses on hover and while dragging, and an equally specific\nrule loses outright if your stylesheet is ordered before the package's.\n\nThree consequences are worth knowing:\n\n- **State rules are replaced, not merged.** The thumb publishes `data-thumb-state` (`idle` / `hover` /\n `dragging` / `disabled`; `disabled` whenever `scrollBarOptions.enableThumbDrag` is `false`). A single\n flat `.aqvs-scrollbar-thumb { background-color: ā¦ }` freezes the thumb at that one colour, and the same\n applies to `.aqvs-scrollbar-arrow-button:enabled:hover` and `.aqvs-scroll-to-edge-button:hover`. The\n shape feedback survives untouched: `scaleX(1.06)` / `scaleX(1.12)` on a vertical bar, `scaleY(ā¦)` on a\n horizontal one ā and the same state rules pull the cross-axis edges from `1.5px` to `-0.5px`, which is\n most of the growth at the default `width: 12`.\n- **Inline styles still outrank your rule.** Every size and position ā the bar's width, the arrow buttons,\n the thumb geometry ā plus the thumb's `border-radius` / `cursor` and the track's `border-radius` are\n written inline from `scrollBarOptions.width`, `viewportSize` and the scroll position. Change sizing\n through the props; to re-round the corners use `!important`.\n- **Do not hand-roll the hidden state.** When the content fits the viewport, the bar and the thumb wrapper\n carry `data-visible=\"false\"` and the packaged rule hides them (`opacity: 0; pointer-events: none`). If\n you override `opacity` on `.aqvs-scrollbar`, scope it to `[data-visible=\"true\"]`. The same applies to the\n auto-hiding Top/Bottom pills ā and there the hidden state is more than styling: `.aqvs-scroll-to-edge-overlay`\n carries `inert` while hidden (and the pill `tabindex=\"-1\"`) so it is not a phantom tab stop for keyboard\n users. Forcing `opacity: 1` on the hidden overlay therefore paints a pill that cannot be clicked or focused.\n Scope such rules to `[data-visible=\"true\"]` as well.\n\nThe parts you are most likely to target: `.aqvs-scroll-pane` (root), `.aqvs-scroll-pane-content` (row\nviewport), `.aqvs-scrollbar` (+ `-vertical` / `-horizontal`), `.aqvs-scrollbar-track`,\n`.aqvs-scrollbar-thumb-wrapper`, `.aqvs-scrollbar-thumb` (+ `-vertical` / `-horizontal`),\n`.aqvs-scrollbar-arrow-button`, `.aqvs-scroll-to-edge-overlay` / `-button`, `.aqvs-tap-scroll-circle`,\n`.aqvs-item-container`.\n\n### Tap Scroll Circle Configuration\n\nThe auxiliary tap scroll circle can replace the native scrollbar for large datasets while remaining easy to control:\n\n- **Adaptive speed scaling** automatically ramps up to a `120Ć` multiplier as `itemCount` grows (trillions supported).\n- **Manual overrides** let you clamp or extend speed via `maxSpeedMultiplier` when you need deterministic behavior.\n- **Speed shaping** with `maxSpeedCurve` controls how quickly the speed ramps up as you pull the circle, blending gentle near-threshold drag with high-speed travel at extended distances. The ceiling itself does not depend on the drag distance: `exponentialSteepness` shapes the ramp, and `exponentialScale` caps the ceiling (its effective value is `min(exponentialScale, maxSpeedMultiplier)`).\n - ā ļø `easedOffset` is **a fraction of the whole `[minSpeed, maxSpeed]` range applied at zero drag**, not a small nudge. With a large `maxSpeedMultiplier` (including the automatic `itemCount`-derived one) even `0.1` starts the list at several viewports per second and costs you the low-speed resolution. Raise `minSpeedMultiplier` instead when you only want a faster floor.\n- **Per-pointer drag control**: `behaviorOptions.pointerDragInputs` restricts content drag-scrolling to specific pointer types, e.g. `[\"pen\", \"touch\"]` to keep touch scrolling while freeing the mouse for text selection. Do **not** use `enablePointerDrag: false` for that ā the pane has no native scroller, so disabling drag removes the only way to scroll on touch devices.\n- **Full layout control** (`size`, `offsetX`, `offsetY`) keeps the circle accessible on both desktop and touch devices.\n- **Visibility tuning** exposes an `opacity` knob so you can match subdued or high-contrast UI themes.\n\n```tsx\nimport { VirtualScroll } from \"@aiquants/virtualscroll\"\n\nconst items = Array.from({ length: 1_000_000_000_000 }, (_, index) => ({\n id: index,\n text: `Record ${index}`,\n height: 42,\n}))\n\nexport function UltraFastExample() {\n return (\n items[index]}\n getItemHeight={() => 42}\n scrollBarOptions={{\n tapScrollCircleOptions: {\n maxSpeedMultiplier: 80, // Optional: override adaptive speed when needed\n maxSpeedCurve: {\n exponentialSteepness: 6,\n exponentialScale: 80,\n },\n offsetX: -96,\n opacity: 0.85,\n }\n }}\n >\n {(item) =>
{item.text}
}\n \n )\n}\n```\n\n## Performance Tips\n\n1. **Memoize callback functions**: Use `useCallback` for `getItem` and `getItemHeight`\n2. **Optimize item rendering**: Memoize item components when possible\n3. **Adjust overscan count**: Balance between smooth scrolling and memory usage\n4. **Consider item height consistency**: More consistent heights provide better performance\n\n## Browser Support\n\n- Chrome 88+\n- Firefox 87+\n- Safari 14+\n- Edge 88+\n\n## License\n\nMIT\n","readmeFilename":""}