@aiquants/virtualscroll 1.18.0 → 1.18.3

package/README.md

@@ -10,6 +10,7 @@ High-performance virtual scrolling component for React with variable item height
 - 🎯 **Precise Scrolling**: Accurate scroll positioning and smooth navigation
 <!-- - 🔄 **LRU Caching**: Built-in cache for optimal memory usage -->
 - 📱 **Touch Support**: Full support for touch devices
+- ↔️ **Horizontal Delegation**: Opt-in `onWheelHorizontal` hands horizontal wheel / trackpad (and shift+wheel) gestures to the parent — build frozen-column data grids
 - 🎨 **Customizable**: Flexible styling and theming options
 - 🌀 **Ultrafast Tap Scroll**: Adaptive tap scroll circle that scales speed up to 120× for massive datasets
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
@@ -24,9 +25,28 @@ yarn add @aiquants/virtualscroll
 pnpm add @aiquants/virtualscroll
 ```
 
+> **Note:** the `virtualscroll demo` CLI is for source checkouts only — the demo app is not bundled in the published npm package. To run it, clone the repository and run `pnpm install && pnpm dev` inside `demo/`.
+
 ## Basic Usage
 
+> **Required:** import the package stylesheet once in your app. The components rely on
+> the `.aqvs-*` layout classes shipped in this file — without it the list overflows its
+> viewport and the scrollbar is mislaid.
+> 必須: パッケージの CSS を一度だけ読み込んでください。レイアウトは `.aqvs-*` クラスに
+> 依存するため、未読み込みだとビューポート外にはみ出し正しく表示されません。
+>
+> ```ts
+> // In your app entry (JS/TS)
+> import '@aiquants/virtualscroll/styles/virtualscroll.css'
+> ```
+> ```css
+> /* or from your global CSS (e.g. with Tailwind) */
+> @import '@aiquants/virtualscroll/styles/virtualscroll.css' layer(components);
+> ```
+
 ```tsx
+// Load the stylesheet once, e.g. in your app entry point
+import '@aiquants/virtualscroll/styles/virtualscroll.css'
 import { VirtualScroll } from '@aiquants/virtualscroll'
 import { useCallback } from 'react'
 
@@ -76,21 +96,75 @@ function App() {
 }
 ```
 
+## Horizontal Scrolling
+
+`VirtualScroll` virtualizes and scrolls the **vertical** axis only. To add a horizontal axis — e.g. a
+data grid whose columns extend past the viewport — pass `onWheelHorizontal`. Horizontal-dominant
+wheel / trackpad gestures (and shift+wheel) are then delegated to your handler, which drives a
+horizontal offset you own. Vertical scrolling is untouched, and omitting the prop keeps the exact
+previous behavior (backward compatible).
+
+A common pattern freezes a left column and translates the remaining columns via a shared CSS
+variable (so rows don't re-render on horizontal scroll), reusing the package's `ScrollBar` with the
+`horizontal` prop for the bottom bar:
+
+```tsx
+import { ScrollBar, VirtualScroll } from '@aiquants/virtualscroll'
+import { useCallback, useState } from 'react'
+
+const clamp = (v: number, max: number) => Math.max(0, Math.min(v, max))
+
+function Grid() {
+  const [hscroll, setHscroll] = useState(0)
+  const maxHScroll = /* contentWidth - visibleWidth */ 632
+  const onWheelHorizontal = useCallback((dx: number) => setHscroll((h) => clamp(h + dx, maxHScroll)), [maxHScroll])
+
+  // `--hx` on the container is inherited by every row; numeric tracks translate via CSS only.
+  return (
+    <div style={{ ['--hx' as string]: `${hscroll}px`, display: 'flex', flexDirection: 'column' }}>
+      <div style={{ height: 440 }}>
+        <VirtualScroll itemCount={rows.length} getItem={getItem} getItemHeight={getItemHeight} viewportSize={440} onWheelHorizontal={onWheelHorizontal}>
+          {(row) => (
+            <div style={{ display: 'flex' }}>
+              <div style={{ width: 180, flexShrink: 0 }}>{row.label}{/* frozen column */}</div>
+              <div style={{ flex: 1, overflow: 'hidden' }}>
+                <div style={{ transform: 'translateX(calc(-1 * var(--hx)))' }}>{/* numeric columns */}</div>
+              </div>
+            </div>
+          )}
+        </VirtualScroll>
+      </div>
+      <ScrollBar
+        horizontal
+        contentSize={1200}
+        viewportSize={568}
+        scrollPosition={hscroll}
+        onScroll={(next) => { const c = clamp(typeof next === 'function' ? next(hscroll) : next, maxHScroll); setHscroll(c); return c }}
+      />
+    </div>
+  )
+}
+```
+
+A runnable version lives in the demo at **`/horizontal`** (`pnpm demo:dev`), and
+[`@aiquants/directory-tree`](../directory-tree)'s TreeGrid mode uses this exact pattern in production.
+
 ## API Reference
 
 ### VirtualScroll Props
 
 | Prop | Type | Required | Description |
-| ------ | ------ | ---------- | ------------- |
+| --- | --- | --- | --- |
 | `children` | `(item: T, index: number) => ReactNode` | ✅ | Render function for items |
 | `itemCount` | `number` | ✅ | Total number of items |
 | `getItem` | `(index: number) => T` | ✅ | Function to get item at index |
 | `getItemHeight` | `(index: number) => number` | ✅ | Function to get item height |
 | `viewportSize` | `number` | ✅ | Height of the visible area |
-| `overscanCount` | `number` | ❌ | Number of items to render outside viewport (default: 5) |
+| `overscanCount` | `number` | ❌ | Number of items to render outside viewport (default: 15) |
 | `className` | `string` | ❌ | CSS class name |
 | `onScroll` | `(position: number, totalHeight: number) => void` | ❌ | Scroll event handler |
 | `onRangeChange` | `(range: VirtualScrollRange) => void` | ❌ | Range change handler |
+| `onWheelHorizontal` | `(deltaX: number) => void` | ❌ | Opt-in horizontal wheel delegation. When set, horizontal-dominant wheel / trackpad gestures (and shift+wheel) are delegated to this handler so the parent can implement horizontal scrolling; vertical behavior is unchanged, and it is a no-op when omitted (fully backward compatible). See [Horizontal Scrolling](#horizontal-scrolling). |
 | `background` | `ReactNode` | ❌ | Background element |
 | `initialScrollIndex` | `number` | ❌ | Initial scroll index |
 | `initialScrollOffset` | `number` | ❌ | Initial scroll offset |
@@ -103,7 +177,7 @@ function App() {
 ### VirtualScrollScrollBarOptions
 
 | Property | Type | Description |
-| ---------- | ------ | ------------- |
+| --- | --- | --- |
 | `width` | `number` | Width of the scrollbar |
 | `enableThumbDrag` | `boolean` | Enable dragging the scrollbar thumb |
 | `enableTrackClick` | `boolean` | Enable clicking the scrollbar track |
@@ -115,7 +189,7 @@ function App() {
 ### VirtualScrollBehaviorOptions
 
 | Property | Type | Description |
-| ---------- | ------ | ------------- |
+| --- | --- | --- |
 | `enablePointerDrag` | `boolean` | Enable dragging the content area to scroll |
 | `enableKeyboardNavigation` | `boolean` | Enable keyboard navigation (default: true) |
 | `wheelSpeedMultiplier` | `number` | Multiplier for mouse wheel scrolling speed |
@@ -126,7 +200,7 @@ function App() {
 ### VirtualScrollHandle Methods
 
 | Method | Type | Description |
-| -------- | ------ | ------------- |
+| --- | --- | --- |
 | `scrollTo` | `(position: number) => void` | Scroll to specific position |
 | `scrollToIndex` | `(index: number, options?: { align?: "top" \| "bottom" \| "center"; offset?: number }) => void` | Scroll to specific item index with optional alignment and offset |
 | `getScrollPosition` | `() => number` | Get current scroll position |
@@ -138,7 +212,7 @@ function App() {
 ### VirtualScrollRange
 
 | Property | Type | Description |
-| ---------- | ------ | ------------- |
+| --- | --- | --- |
 | `renderingStartIndex` | `number` | Index of the first item being rendered (including overscan) |
 | `renderingEndIndex` | `number` | Index of the last item being rendered (including overscan) |
 | `visibleStartIndex` | `number` | Index of the first fully or partially visible item |
@@ -151,7 +225,9 @@ function App() {
 ### With Ref and Scroll Control
 
 ```tsx
-import { ScrollBarThumbOverlayRenderProps, VirtualScroll, VirtualScrollHandle } from '@aiquants/virtualscroll'
+// Load the stylesheet once, e.g. in your app entry point
+import '@aiquants/virtualscroll/styles/virtualscroll.css'
+import { ScrollBarThumbOverlayRenderProps, VirtualScroll, VirtualScrollHandle, VirtualScrollRange } from '@aiquants/virtualscroll'
 import { useCallback, useRef, useState } from 'react'
 
 const items = Array.from({ length: 100000 }, (_, index) => ({
@@ -176,15 +252,8 @@ function AdvancedExample() {
     virtualScrollRef.current?.scrollToIndex(index, { align: "center" })
   }
 
-  const handleRangeChange = useCallback((
-    _renderingStartIndex: number,
-    _renderingEndIndex: number,
-    visibleStart: number,
-    _visibleEndIndex: number,
-    _scrollPosition: number,
-    _totalHeight: number,
-  ) => {
-    setVisibleStartIndex(visibleStart)
+  const handleRangeChange = useCallback((range: VirtualScrollRange) => {
+    setVisibleStartIndex(range.visibleStartIndex)
   }, [])
 
   const renderThumbOverlay = useCallback((props: ScrollBarThumbOverlayRenderProps) => {

package/dist/ScrollBar.d.cts

@@ -0,0 +1,100 @@
+import { ReactNode } from 'react';
+import { TapScrollCircleRenderProps } from './TapScrollCircle.cjs';
+/**
+ * Options to customize the auxiliary tap scroll circle.
+ *
+ * タップスクロール用サークルをカスタマイズするためのオプション。
+ */
+export type ScrollBarTapCircleOptions = {
+    /** Enable or disable the tap scroll circle. / タップサークルを有効化または無効化。 */
+    enabled?: boolean;
+    /** Circle diameter in pixels. / サークルの直径 (ピクセル)。 */
+    size?: number;
+    /** Horizontal offset in pixels. / 水平方向オフセット (ピクセル)。 */
+    offsetX?: number;
+    /** Vertical offset in pixels. / 垂直方向オフセット (ピクセル)。 */
+    offsetY?: number;
+    /** Additional class names for the circle. / サークルの追加クラス名。 */
+    className?: string;
+    /** Maximum drag distance used for visual feedback. / ビジュアルフィードバックに利用する最大ドラッグ距離。 */
+    maxVisualDistance?: number;
+    /** Maximum speed multiplier relative to viewport size. / ビューポートサイズに対する最大速度倍率。 */
+    maxSpeedMultiplier?: number;
+    /** Minimum speed multiplier relative to viewport size. / ビューポートサイズに対する最小速度倍率。 */
+    minSpeedMultiplier?: number;
+    /** Base opacity multiplier for the circle visuals. / サークル表示の基準透明度倍率。 */
+    opacity?: number;
+    /** Custom visual renderer for the tap circle. / タップサークルのカスタムビジュアルのレンダラー。 */
+    renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode;
+    /** Optional exponential cap configuration for max speed. / 最大速度に指数関数的な上限を設定するためのオプション設定。 */
+    maxSpeedCurve?: {
+        /** Steepness factor for the exponential curve. / 指数関数の急峻さを決定する要素。 */
+        exponentialSteepness: number;
+        /** Scale factor for the exponential curve. / 指数関数のスケールファクター。 */
+        exponentialScale?: number;
+        /** Additional eased offset to apply to the curve. / 曲線に適用する追加のイーズドオフセット。 */
+        easedOffset?: number;
+    };
+};
+/** Custom event name emitted when external interactions should cancel tap scrolling. / 外部操作によってタップスクロールをキャンセルすべき際に発行されるカスタムイベント名。 */
+export declare const TAP_SCROLL_CANCEL_EVENT = "virtualscroll:tap-scroll-cancel";
+/**
+ * Props for the ScrollBar component.
+ *
+ * ScrollBar コンポーネントの Props。
+ */
+export type ScrollBarThumbOverlayRenderProps = {
+    orientation: "vertical" | "horizontal";
+    scrollPosition: number;
+    maxScrollPosition: number;
+    contentSize: number;
+    viewportSize: number;
+    thumbSize: number;
+    thumbPosition: number;
+    thumbCenter: number;
+    trackSize: number;
+    isDragging: boolean;
+    isTapScrollActive: boolean;
+    visibleStartIndex?: number;
+    visibleEndIndex?: number;
+};
+export type ScrollBarProps = {
+    /** The total size of the content. / コンテンツの総サイズ。 */
+    contentSize: number;
+    /** The size of the visible area. / 表示領域のサイズ。 */
+    viewportSize: number;
+    /** The current scroll position. / 現在のスクロール位置。 */
+    scrollPosition: number;
+    /** A callback function invoked to adjust scroll position. Accepts next position or updater. / スクロール位置を調整するためのコールバック。次位置または更新関数を受け取る。 */
+    onScroll?: (scrollPosition: number | ((prevPosition: number) => number), prevPosition?: number) => number | undefined;
+    /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
+    enableThumbDrag?: boolean;
+    /** Whether clicking on the track moves the scrollbar. / スクロールバーのトラッククリック操作を許可するかどうか。 */
+    enableTrackClick?: boolean;
+    /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
+    enableArrowButtons?: boolean;
+    /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
+    horizontal?: boolean;
+    /** The width of the scrollbar. / スクロールバーの幅。 */
+    scrollBarWidth?: number;
+    /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
+    className?: string;
+    /** The ID of the element that the scrollbar controls. / スクロールバーが制御する要素の ID。 */
+    ariaControls?: string;
+    /** Configuration for the tap scroll circle. / タップサークルの設定。 */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions;
+    /** Total number of scrollable items (optional). / スクロール対象アイテムの総数（任意）。 */
+    itemCount?: number;
+    /** Optional renderer for thumb-adjacent overlays. / サム付近に重ねるオーバーレイのレンダラー。 */
+    renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => ReactNode;
+    /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */
+    visibleStartIndex?: number;
+    /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
+    visibleEndIndex?: number;
+};
+/**
+ * A custom scrollbar component.
+ *
+ * カスタムスクロールバーコンポーネント。
+ */
+export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, }: ScrollBarProps) => import("react").JSX.Element;

package/dist/ScrollBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollBar.d.ts","sourceRoot":"","sources":["../src/ScrollBar.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAIrD,OAAO,EAA8E,KAAK,0BAA0B,EAAE,MAAM,uBAAuB,CAAA;AAiEnJ;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACpC,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,SAAS,CAAA;IAC/D,4FAA4F;IAC5F,aAAa,CAAC,EAAE;QACZ,qEAAqE;QACrE,oBAAoB,EAAE,MAAM,CAAA;QAC5B,gEAAgE;QAChE,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,4EAA4E;QAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;KACvB,CAAA;CACJ,CAAA;AAaD,qIAAqI;AACrI,eAAO,MAAM,uBAAuB,oCAAoC,CAAA;AAExE;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC3C,WAAW,EAAE,UAAU,GAAG,YAAY,CAAA;IACtC,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,MAAM,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;IACnB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;IACpB,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAA;IACtB,wIAAwI;IACxI,QAAQ,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IACrH,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,sBAAsB,CAAC,EAAE,yBAAyB,CAAA;IAClD,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,SAAS,CAAA;IAC3E,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAwND;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,iQAiBvB,cAAc,gCAm9BhB,CAAA"}

package/dist/ScrollPane.d.cts

@@ -0,0 +1,93 @@
+import { ScrollBarTapCircleOptions, ScrollBarThumbOverlayRenderProps } from './ScrollBar.cjs';
+/**
+ * Props for the ScrollPane component.
+ *
+ * ScrollPane コンポーネントの Props。
+ */
+export type ScrollPaneContentInsets = {
+    top?: number;
+    bottom?: number;
+};
+export type ScrollPaneProps = {
+    /**
+     * A function that renders the content of the scroll pane.
+     * It receives the current scroll position as an argument.
+     *
+     * スクロールペインのコンテンツをレンダリングする関数です。
+     * 現在のスクロール位置を引数として受け取ります。
+     */
+    children: (scrollPosition: number) => React.ReactNode;
+    /** The total size of the content. / コンテンツの総サイズ。 */
+    contentSize: number;
+    /** The size of the visible area. / 表示領域のサイズ。 */
+    viewportSize: number;
+    /** The width of the scrollbar. / スクロールバーの幅。 */
+    scrollBarWidth?: number;
+    /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
+    enableThumbDrag?: boolean;
+    /** A callback function that is called when the scroll position changes. / スクロール位置が変更されたときに呼び出されるコールバック関数。 */
+    onScroll?: (scrollPosition: number, prevPosition: number) => void;
+    /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
+    className?: string;
+    /** Custom styles for the component. / コンポーネントのカスタムスタイル。 */
+    style?: React.CSSProperties;
+    /** A background element to be rendered behind the content. / コンテンツの背後にレンダリングされる背景要素。 */
+    background?: React.ReactNode;
+    /** Configuration for the tap scroll circle. / タップサークルの設定。 */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions;
+    /** Configuration for inertia scroll behavior. / 慣性スクロールの設定。 */
+    inertiaOptions?: ScrollPaneInertiaOptions;
+    /** Total number of scrollable items (optional). / スクロール対象アイテムの総数（任意）。 */
+    itemCount?: number;
+    /** Whether clicking the scrollbar track moves the thumb. / スクロールバートラックのクリック操作を許可するかどうか。 */
+    enableTrackClick?: boolean;
+    /** Whether arrow buttons control the scroll position. / 矢印ボタンのスクロール操作を許可するかどうか。 */
+    enableArrowButtons?: boolean;
+    /** Whether dragging the content area scrolls the pane. / コンテンツ領域のドラッグでスクロールさせるかどうか。 */
+    enablePointerDrag?: boolean;
+    /** Optional renderer for thumb overlays. / サム付近に表示するオーバーレイのレンダラー。 */
+    renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => React.ReactNode;
+    /** Multiplier applied to wheel delta for faster or slower scrolling. / スクロール速度を調整するためのホイールデルタの倍率。 */
+    wheelSpeedMultiplier?: number;
+    /**
+     * Callback delegating horizontal wheel/trackpad delta to an upstream owner.
+     * When provided, horizontal-dominant (or shift+wheel) gestures are consumed here
+     * (preventDefault + delegate) instead of being ignored; vertical behavior is unchanged.
+     * 横方向ホイール/トラックパッド量を上流へ委譲するコールバック。指定時のみ横成分を処理する。
+     */
+    onWheelHorizontal?: (deltaX: number) => void;
+    /** Insets applied to the scrollable content area. / スクロール可能領域に適用するインセット。 */
+    contentInsets?: ScrollPaneContentInsets;
+    /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */
+    visibleStartIndex?: number;
+    /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
+    visibleEndIndex?: number;
+    /** A function to render an overlay on top of the scroll pane. / スクロールペインの上にオーバーレイをレンダリングする関数。 */
+    renderOverlay?: () => React.ReactNode;
+    /** Initial scroll position. / 初期のスクロール位置。 */
+    initialScrollPosition?: number;
+};
+export type ScrollPaneInertiaOptions = {
+    /** Maximum velocity applied when inertia starts. / 慣性開始時に適用する最大速度。 */
+    maxVelocity?: number;
+    /** Minimum velocity threshold to continue inertia. / 慣性を継続するための最小速度しきい値。 */
+    minVelocity?: number;
+    /** Deceleration applied on every frame. / 各フレームで適用される減速度。 */
+    deceleration?: number;
+    /** Sampling window in milliseconds for pointer velocity calculation. / ポインタの速度計算に用いるミリ秒単位のサンプリング期間。 */
+    velocitySampleWindow?: number;
+    /** Minimum velocity required to start inertia. / 慣性を開始するために必要な最小速度。 */
+    startVelocityThreshold?: number;
+};
+export type ScrollPaneHandle = {
+    scrollTo: (newPosition: number | ((prev: number) => number)) => number;
+    getScrollPosition: () => number;
+    getContentSize: () => number;
+    getViewportSize: () => number;
+};
+/**
+ * A component that provides a scrollable view with a custom scrollbar.
+ *
+ * カスタムスクロールバーを備えたスクロール可能なビューを提供するコンポーネントです。
+ */
+export declare const ScrollPane: import('react').ForwardRefExoticComponent<ScrollPaneProps & import('react').RefAttributes<ScrollPaneHandle>>;

package/dist/ScrollPane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollPane.d.ts","sourceRoot":"","sources":["../src/ScrollPane.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,yBAAyB,EAAE,KAAK,gCAAgC,EAA2B,MAAM,iBAAiB,CAAA;AAG3I;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAA;IACrD,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6GAA6G;IAC7G,QAAQ,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IACjE,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,wFAAwF;IACxF,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,6DAA6D;IAC7D,sBAAsB,CAAC,EAAE,yBAAyB,CAAA;IAClD,+DAA+D;IAC/D,cAAc,CAAC,EAAE,wBAAwB,CAAA;IACzC,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,KAAK,CAAC,SAAS,CAAA;IACjF,qGAAqG;IACrG,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C,4EAA4E;IAC5E,aAAa,CAAC,EAAE,uBAAuB,CAAA;IACvC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,KAAK,CAAC,SAAS,CAAA;IACrC,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,MAAM,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uGAAuG;IACvG,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,uEAAuE;IACvE,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAClC,CAAA;AA4CD,MAAM,MAAM,gBAAgB,GAAG;IAC3B,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,KAAK,MAAM,CAAA;IACtE,iBAAiB,EAAE,MAAM,MAAM,CAAA;IAC/B,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,eAAe,EAAE,MAAM,MAAM,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,8GA2vBtB,CAAA"}

package/dist/TapScrollCircle.d.cts

@@ -0,0 +1,62 @@
+import { CSSProperties, ReactNode } from 'react';
+export type TapScrollCircleDragState = {
+    /** Whether the pointer is actively dragging. / ポインターがドラッグ中かどうか。 */
+    active: boolean;
+    /** Signed horizontal offset from the circle center. / サークル中心からの符号付き水平方向オフセット。 */
+    offsetX: number;
+    /** Signed vertical offset from the circle center. / サークル中心からの符号付き垂直オフセット。 */
+    offsetY: number;
+    /** Absolute distance between pointer and center. / ポインターと中心の距離。 */
+    distance: number;
+    /** Drag direction relative to the circle. / サークルに対するドラッグ方向。 */
+    direction: -1 | 0 | 1;
+    /** The ID of the pointer that initiated the drag. / ドラッグを開始したポインターの ID。 */
+    pointerId: number | null;
+};
+export type TapScrollCircleProps = {
+    /** Called whenever the drag state updates. / ドラッグ状態が更新された際に呼び出されるコールバック。 */
+    onDragChange: (state: TapScrollCircleDragState) => void;
+    /** Additional class names for styling. / 追加のスタイル用クラス名。 */
+    className?: string;
+    /** Maximum distance used for visual stretching. / 視覚的な伸縮に使用する最大距離。 */
+    maxVisualDistance?: number;
+    /** Diameter of the circle in pixels. / サークルの直径 (ピクセル)。 */
+    size?: number;
+    /** Additional inline styles. / 追加のインラインスタイル。 */
+    style?: CSSProperties;
+    /** Base opacity applied to the circle. / サークル全体に適用する基準透明度。 */
+    opacity: number;
+    /** Custom rendering logic for the visual contents. / ビジュアル内容を描画するカスタムロジック。 */
+    renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode;
+};
+export type TapScrollCircleHandle = {
+    /**
+     * Resets the drag state and releases pointer capture if active.
+     *
+     * ドラッグ状態をリセットし、必要に応じてポインタキャプチャを解除する。
+     */
+    reset: () => void;
+    /**
+     * Returns the underlying DOM element of the tap circle.
+     *
+     * タップサークルの DOM 要素を返す。
+     */
+    getElement: () => HTMLDivElement | null;
+};
+export type TapScrollCircleRenderProps = {
+    /** Current drag state snapshot. / 現在のドラッグ状態のスナップショット。 */
+    dragState: TapScrollCircleDragState;
+    /** Normalized distance within [0, 1]. / 正規化距離 (0 から 1 の範囲)。 */
+    normalizedDistance: number;
+    /** Relative scale based on size. / サイズに基づく相対スケール。 */
+    sizeScale: number;
+    /** Circle diameter in pixels. / サークル直径 (ピクセル)。 */
+    size: number;
+    /** Applied opacity value. / 適用中の不透明度値。 */
+    opacity: number;
+};
+/**
+ * A circular touch handle that stretches toward the drag direction.
+ * タップした方向へ伸縮するタッチ操作用サークル。
+ */
+export declare const TapScrollCircle: import('react').NamedExoticComponent<TapScrollCircleProps & import('react').RefAttributes<TapScrollCircleHandle>>;

package/dist/TapScrollCircle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TapScrollCircle.d.ts","sourceRoot":"","sources":["../src/TapScrollCircle.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAqC,MAAM,OAAO,CAAA;AAIxF,MAAM,MAAM,wBAAwB,GAAG;IACnC,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAA;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IAC/B,4EAA4E;IAC5E,YAAY,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,SAAS,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;CAC1C,CAAA;AAcD,MAAM,MAAM,0BAA0B,GAAG;IACrC,yDAAyD;IACzD,SAAS,EAAE,wBAAwB,CAAA;IACnC,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,mHAqP3B,CAAA"}

package/dist/VirtualScroll.d.cts

@@ -0,0 +1,155 @@
+import { default as React, ReactNode } from 'react';
+import { ScrollPaneHandle, ScrollPaneProps } from './ScrollPane.cjs';
+import { useFenwickMapTree } from './useFenwickMapTree.cjs';
+/**
+ * Represents the current state of the rendered range and scroll metrics.
+ *
+ * 現在のレンダリング範囲とスクロールメトリクスの状態を表します。
+ */
+export type VirtualScrollRange = {
+    /** Start index for rendering (includes overscan) / 描画開始インデックス（オーバースキャン含む） */
+    renderingStartIndex: number;
+    /** End index for rendering (includes overscan) / 描画終了インデックス（オーバースキャン含む） */
+    renderingEndIndex: number;
+    /** Index of the first item strictly visible in the viewport / ビューポート内に見えている最初のアイテムのインデックス */
+    visibleStartIndex: number;
+    /** Index of the last item strictly visible in the viewport / ビューポート内に見えている最後のアイテムのインデックス */
+    visibleEndIndex: number;
+    /** Current logical scroll position / 現在の論理スクロール位置 */
+    scrollPosition: number;
+    /** Total height of the scroll content / スクロールコンテンツの総高さ */
+    totalHeight: number;
+};
+/**
+ * Handle interface for controlling the VirtualScroll component externally.
+ *
+ * 外部から VirtualScroll コンポーネントを制御するためのハンドルインターフェース。
+ */
+export type VirtualScrollHandle = ScrollPaneHandle & {
+    /** Scrolls to a specific item index / 指定したアイテムインデックスへスクロール */
+    scrollToIndex: (index: number, options?: {
+        align?: "top" | "bottom" | "center";
+        offset?: number;
+    }) => void;
+    /** Gets the total height managed by the Fenwick Tree / Fenwick Tree で管理されている総高さを取得 */
+    getFenwickTreeTotalHeight: () => number;
+    /** Gets the number of items in the Fenwick Tree / Fenwick Tree 内のアイテム数を取得 */
+    getFenwickSize: () => number;
+    /** Focuses an item at the specified index / 指定したインデックスのアイテムにフォーカス */
+    focusItemAtIndex: (index: number, options?: {
+        ensureVisible?: boolean;
+    }) => void;
+    /** Gets the current scroll range information / 現在のスクロール範囲情報を取得 */
+    getRange: () => VirtualScrollRange;
+    /**
+     * Manually updates the size of a specific item. Contract: after calling this,
+     * `getItemHeight(index)` must return the same `size`; `getItemHeight` is the source of truth,
+     * so if it keeps returning the old value, rows inside the current rendering window (including
+     * overscan) are reverted to the `getItemHeight` value by height reconciliation on the next render.
+     *
+     * 特定のアイテムのサイズを手動で更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を
+     * 返すこと。`getItemHeight` が正であるため、旧値を返し続けると描画ウィンドウ (オーバースキャン
+     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。
+     */
+    updateItemSize: (index: number, size: number) => void;
+};
+export type VirtualScrollScrollBarOptions = {
+    width?: number;
+    enableThumbDrag?: boolean;
+    enableTrackClick?: boolean;
+    enableArrowButtons?: boolean;
+    enableScrollToTopBottomButtons?: boolean;
+    renderThumbOverlay?: ScrollPaneProps["renderThumbOverlay"];
+    tapScrollCircleOptions?: ScrollPaneProps["tapScrollCircleOptions"];
+};
+export type VirtualScrollBehaviorOptions = {
+    enablePointerDrag?: boolean;
+    enableKeyboardNavigation?: boolean;
+    wheelSpeedMultiplier?: number;
+    inertiaOptions?: ScrollPaneProps["inertiaOptions"];
+    clipItemHeight?: boolean;
+    /**
+     * When `true`, the underlying Fenwick tree fully re-samples on every `getItemHeight` change
+     * instead of applying an incremental tail resize.
+     *
+     * Set this to `true` whenever an `itemCount` change may represent a middle insertion/deletion
+     * (not just a tail append/remove): an incremental resize assumes items are added/removed at the
+     * tail and keeps each existing index's measured height, so a middle insert would leave the
+     * `getItemHeight` index↔height mapping applied to the wrong rows. Alternatively, remount
+     * VirtualScroll with a new `key` when the list structure changes.
+     *
+     * `true` のとき、内部 Fenwick 木は `getItemHeight` 変更のたびに増分的な末尾リサイズではなく全面
+     * 再サンプリングを行う。`itemCount` の変更が末尾追記/削除ではなく中間挿入/削除を含みうる場合は
+     * `true` にすること。増分リサイズは要素が末尾で増減する前提で各既存インデックスの実測高さを保持する
+     * ため、中間挿入があると `getItemHeight` の index↔高さ 対応が誤った行に適用されてしまう。代替として、
+     * リスト構造が変わるときに新しい `key` で VirtualScroll を再マウントしてもよい。
+     */
+    resetOnGetItemHeightChange?: boolean;
+};
+/**
+ * Props for the VirtualScroll component.
+ *
+ * VirtualScroll コンポーネントの Props。
+ */
+export type VirtualScrollProps<T> = {
+    itemCount: number;
+    getItem: (index: number) => T;
+    getItemKey?: (index: number) => React.Key;
+    /**
+     * Returns the height of the item at `index`. The index↔height mapping must be stable for a
+     * given list ordering: when `itemCount` grows/shrinks, VirtualScroll assumes items are
+     * appended to / removed from the tail and preserves the measured height of each existing index.
+     * If a list mutation inserts or removes items in the middle (shifting later indices), enable
+     * `behaviorOptions.resetOnGetItemHeightChange` or remount with a new `key`; otherwise cached
+     * heights stay attached to indices that now point at different items.
+     *
+     * `index` のアイテム高さを返す。index↔高さ の対応は同じ並び順の間は安定である必要がある。`itemCount`
+     * が増減するとき VirtualScroll は要素が末尾で追加/削除されると仮定し、既存インデックスの実測高さを
+     * 保持する。中間挿入/削除 (以降のインデックスがずれる) を伴うリスト変更では
+     * `behaviorOptions.resetOnGetItemHeightChange` を有効化するか新しい `key` で再マウントすること。
+     * さもないとキャッシュ済み高さが別のアイテムを指すインデックスに残る。
+     */
+    getItemHeight: (index: number) => number;
+    viewportSize: number;
+    overscanCount?: number;
+    className?: string;
+    onScroll?: (scrollPosition: number, totalHeight: number) => void;
+    onRangeChange?: (range: VirtualScrollRange) => void;
+    background?: ReactNode;
+    children: (item: T, index: number) => ReactNode;
+    initialScrollIndex?: number;
+    initialScrollOffset?: number;
+    callbackThrottleMs?: number;
+    contentInsets?: ScrollPaneProps["contentInsets"];
+    onItemFocus?: (index: number) => void;
+    scrollBarOptions?: VirtualScrollScrollBarOptions;
+    behaviorOptions?: VirtualScrollBehaviorOptions;
+    /** Delegates horizontal wheel/trackpad delta to an upstream owner (e.g. a frozen-column grid). / 横ホイール量を上流へ委譲する。 */
+    onWheelHorizontal?: (deltaX: number) => void;
+};
+/**
+ * Retrieves a high-resolution timestamp when available.
+ *
+ * 高精度タイムスタンプを可能なら取得。
+ */
+/**
+ * Calculates rendering boundaries from current scroll metrics.
+ *
+ * 現在のスクロール情報から描画範囲を算出。
+ */
+export declare const computeRenderingRanges: (scrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number) => {
+    renderingStartIndex: number;
+    renderingEndIndex: number;
+    visibleStartIndex: number;
+    visibleEndIndex: number;
+};
+/**
+ * A highly performant virtual scroll component that supports variable item heights.
+ * Uses a Fenwick Tree (Binary Indexed Tree) for efficient offset calculation and range queries.
+ *
+ * 可変のアイテム高さをサポートする高性能な仮想スクロールコンポーネント。
+ * オフセット計算と範囲クエリを効率化するために Fenwick Tree (Binary Indexed Tree) を使用しています。
+ */
+export declare const VirtualScroll: <T>(props: VirtualScrollProps<T> & {
+    ref?: React.Ref<VirtualScrollHandle>;
+}) => React.ReactElement;