@aiquants/virtualscroll 3.8.2 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollBar.tsx

@@ -6,6 +6,7 @@
 import type { CSSProperties, ReactNode } from "react"
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import { snapToDevicePixelGrid, usePaintingDevicePixelRatio } from "./devicePixelGrid.ts"
 import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { capturePointer, releaseCapturedPointer } from "./pointerCapture.ts"
@@ -20,7 +21,8 @@ import { getAxisScale, minmax } from "./utils.ts"
 type OrientationConfig = {
     mainSizeKey: "width" | "height"
     crossSizeKey: "width" | "height"
-    positionKey: "left" | "top"
+    /** The transform function that moves the thumb along the bar / つまみをバーに沿って動かす変換の関数 */
+    thumbTranslateFunction: "translateX" | "translateY"
     selectDelta: (deltaX: number, deltaY: number) => number
     getPointerCoordinate: (point: { clientX: number; clientY: number }) => number
     arrowIcons: [string, string]
@@ -302,7 +304,7 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
         return {
             mainSizeKey: "width",
             crossSizeKey: "height",
-            positionKey: "left",
+            thumbTranslateFunction: "translateX",
             selectDelta: (deltaX: number, _deltaY: number) => deltaX,
             getPointerCoordinate: ({ clientX }) => clientX,
             arrowIcons: ["◀", "▶"],
@@ -314,7 +316,7 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
     return {
         mainSizeKey: "height",
         crossSizeKey: "width",
-        positionKey: "top",
+        thumbTranslateFunction: "translateY",
         selectDelta: (_deltaX: number, deltaY: number) => deltaY,
         getPointerCoordinate: ({ clientY }) => clientY,
         arrowIcons: ["▲", "▼"],
@@ -633,9 +635,15 @@ export const computeAutoTapScrollMaxSpeedMultiplier = (itemCount?: number) => {
 }
 
 /**
- * A custom scrollbar component.
+ * A custom scrollbar component. The thumb wrapper stays at the start of the track (`top: 0; left: 0`) and moves along it
+ * by a 2D translate snapped to the device-pixel grid of the window that paints it, so a scroll step rewrites only that
+ * transform and runs no layout. `thumbPosition` in the overlay props stays the exact, unsnapped offset. Rendering into a
+ * document without a window throws when the thumb attaches (there is no device-pixel ratio to snap to).
  *
- * カスタムスクロールバーコンポーネント。
+ * カスタムスクロールバーコンポーネント。つまみの器はトラックの始端 (`top: 0; left: 0`) に置いたまま、描くウィンドウの装置の
+ * 画素の格子へ揃えた 2D の平行移動でトラックに沿って動くので、スクロールの 1 段が書き換えるのはその transform だけで、
+ * レイアウトは走らない。オーバーレイの props の `thumbPosition` は揃える前の厳密なオフセットのまま。ウィンドウを持たない
+ * 文書へ描くと、つまみの取り付けで例外を投げる (揃える装置の画素比が無い)。
  */
 export const ScrollBar = ({
     contentSize,
@@ -714,7 +722,7 @@ export const ScrollBar = ({
         onScroll,
         scrollPosition,
     })
-    const { mainSizeKey, crossSizeKey, positionKey, selectDelta, getPointerCoordinate, arrowIcons, directionClass, orientation } = orientationConfig
+    const { mainSizeKey, crossSizeKey, thumbTranslateFunction, selectDelta, getPointerCoordinate, arrowIcons, directionClass, orientation } = orientationConfig
     const effectiveTapMaxDistance = Math.max(tapCircleMaxDistance, 1)
     // 表示領域に対するコンテンツの比率
     const scrollRatio = viewportSize / contentSize
@@ -730,6 +738,11 @@ export const ScrollBar = ({
     // サムがトラック外へはみ出さないよう、レンダー時に [0, effectiveTrackLength] へクランプする。
     const thumbPosition = maxScrollPosition <= 0 || effectiveTrackLength <= 0 ? 0 : minmax((scrollPosition / maxScrollPosition) * effectiveTrackLength, 0, effectiveTrackLength)
     const thumbCenter = thumbPosition + thumbSize / 2
+    const { ratio: thumbPaintingRatio, attach: attachThumbWrapper } = usePaintingDevicePixelRatio("[ScrollBar] the thumb")
+    // ❗ つまみは top / left ではなく平行移動で動かす。top / left の書き換えは、描画の窓を変えないスクロールの 1 段にも文書の根からの
+    // レイアウトを 1 回足す (実測: 40px の段 60 回で Layout 60 → 30 回、13.9 → 9.1 ms)。平行移動は装置の画素の格子へ揃えて縁を
+    // 滲ませず、つまみの長さはどの位置でも同じ装置の画素の数になる
+    const thumbTranslate = thumbPaintingRatio === null ? thumbPosition : snapToDevicePixelGrid(thumbPosition, thumbPaintingRatio, "none")
 
     // スクロールバーが表示されるかどうか
     const scrollBarVisible = contentSize > viewportSize || isDragging
@@ -1581,11 +1594,14 @@ export const ScrollBar = ({
                 {/* DOMの再生成を防ぐため、常にレンダリングしてスタイルで表示制御を行う */}
                 <div
                     key="thumb-wrapper"
+                    ref={attachThumbWrapper}
                     className="aqvs-scrollbar-thumb-wrapper"
                     style={{
                         [mainSizeKey]: thumbSize,
-                        [positionKey]: thumbPosition,
-                        ...(horizontal ? { top: 0, bottom: 0 } : { left: 0, right: 0 }),
+                        top: 0,
+                        left: 0,
+                        ...(horizontal ? { bottom: 0 } : { right: 0 }),
+                        transform: `${thumbTranslateFunction}(${thumbTranslate}px)`,
                     }}
                     // ルート同様、非表示はパッケージ CSS の [data-visible="false"] が担う
                     data-visible={scrollBarVisible || isDragging ? "true" : "false"}