@aiquants/virtualscroll 3.0.0 → 3.1.0

package/src/residualQuantizer.ts

@@ -0,0 +1,133 @@
+/**
+ * @module residualQuantizer
+ * @description Residual-carrying delta quantizer for consumers that snap scroll positions to a
+ * fixed quantum (row height, column width). High-resolution trackpads emit many sub-quantum
+ * deltas; a consumer that rounds each delta independently rounds every one of them to zero and
+ * the list never moves. This accumulator carries the sub-quantum remainder across events and
+ * emits whole quanta as soon as they accumulate.
+ *
+ * @description スクロール位置を固定の量子 (行高・列幅) へスナップする消費側のための、
+ * 残差持ち越し型のデルタ量子化器。高解像度トラックパッドは 1 量子未満のデルタを大量に発行するため、
+ * イベントごとに独立して丸める消費側では**すべてが 0 に丸められ、ゆっくり撫でると 1px も動かない**。
+ * 本量子化器は量子未満の余りをイベントを跨いで持ち越し、貯まった分だけ量子単位で放出する。
+ *
+ * ❗ **時間は扱わない (意図的)。** アイドルタイムアウトでの残差破棄は「いつ捨てるか」の方針が
+ * 消費側の UI ごとに異なり、内蔵すると幽霊スクロール (古い残差が後から発火) か不感帯のどちらかを
+ * パッケージが押し付けることになる。時間起点の破棄が要る消費側は、自前のタイマーから
+ * {@link ResidualQuantizer.reset} を呼ぶこと。既定の防御は**方向反転での残差破棄**のみで、
+ * これは時間に依存せず「逆へ動かし始めたのに古い残差が先に順方向へ発火する」事故だけを塞ぐ。
+ */
+
+/**
+ * Options for {@link createResidualQuantizer}.
+ * {@link createResidualQuantizer} のオプション。
+ */
+export type ResidualQuantizerOptions = {
+    /**
+     * Quantum (px) each emission is a multiple of. Must be finite and positive — anything else
+     * throws at creation time (fail fast; a silent default would hide the caller's bug).
+     * 放出量の単位となる量子 (px)。有限かつ正であること — それ以外は生成時に throw する
+     * (Fail Fast。既定値へ黙って読み替えると呼び出し側のバグを隠す)。
+     */
+    quantum: number
+    /**
+     * Drop the carried residue when the incoming delta's direction opposes it (default: `true`).
+     * Without this, scrolling +20px (quantum 24, nothing emitted) and then reversing emits the
+     * first reverse quantum "late" — the stale forward residue eats part of the reverse motion.
+     * 入力デルタの向きが持ち越し残差と逆のとき残差を捨てる (既定 `true`)。捨てないと、
+     * +20px (量子 24 で未放出) の後に反転したとき、古い順方向残差が逆方向の動きを食い、
+     * 最初の逆方向量子の発火が「遅れて」体感される。
+     */
+    resetOnDirectionChange?: boolean
+}
+
+/**
+ * A quantizer instance. One instance per quantized axis — sharing one across axes mixes residues.
+ * 量子化器インスタンス。量子化する軸ごとに 1 つ持つこと — 軸間で共有すると残差が混線する。
+ */
+export type ResidualQuantizer = {
+    /**
+     * Accumulates `delta` and returns the emission: a multiple of the quantum (possibly 0),
+     * signed toward the accumulated direction. Non-finite deltas AND deltas whose magnitude
+     * exceeds `Number.MAX_SAFE_INTEGER` emit 0 and leave the residue untouched — beyond 2^53
+     * the float product stops being an EXACT multiple of the quantum, which is precisely the
+     * property a grid-snapping consumer relies on.
+     * `delta` を蓄積し、放出量 (量子の倍数。0 のこともある) を蓄積方向の符号で返す。
+     * 非有限のデルタ、および絶対値が `Number.MAX_SAFE_INTEGER` を超えるデルタは 0 を返し
+     * 残差を汚さない — 2^53 超では浮動小数点積が量子の**正確な**倍数でなくなり、グリッド
+     * スナップ消費側が依拠する性質そのものが壊れるため。
+     *
+     * @param delta - Incoming delta (px) / 入力デルタ (px)
+     * @returns Emitted amount (multiple of the quantum) / 放出量 (量子の倍数)
+     */
+    push: (delta: number) => number
+    /**
+     * Returns the carried residue without mutating it (|residue| < quantum).
+     * 持ち越し中の残差を変更せずに返す (|残差| < 量子)。
+     *
+     * @returns Current residue (px) / 現在の残差 (px)
+     */
+    peekResidue: () => number
+    /**
+     * Clears the residue. Call from consumer-side idle timers, on pointer leave, or when the
+     * quantized target (row/column layout) changes under the accumulator.
+     * 残差を破棄する。消費側のアイドルタイマー・ポインタ離脱・量子化対象 (行/列レイアウト) の
+     * 変更時に呼ぶ。
+     */
+    reset: () => void
+}
+
+/**
+ * Creates a residual-carrying delta quantizer.
+ * 残差持ち越し型のデルタ量子化器を生成する処理。
+ *
+ * ```ts
+ * const quantizer = createResidualQuantizer({ quantum: rowHeight })
+ * const handleWheelVertical = (deltaY: number) => {
+ *     const emitted = quantizer.push(deltaY)
+ *     if (emitted !== 0) {
+ *         snapScrollBy(emitted) // 常に量子の倍数
+ *     }
+ * }
+ * ```
+ *
+ * @param options - Quantizer options / 量子化器のオプション
+ * @returns A new quantizer instance / 新しい量子化器インスタンス
+ * @throws {TypeError} When `quantum` is not a finite positive number / `quantum` が有限の正数でない場合
+ */
+export const createResidualQuantizer = (options: ResidualQuantizerOptions): ResidualQuantizer => {
+    const { quantum, resetOnDirectionChange = true } = options
+    // Fail Fast: 不正な量子は生成時に拒否する (押すたび NaN を配る量子化器を作らせない)
+    if (!(Number.isFinite(quantum) && quantum > 0)) {
+        throw new TypeError(`[createResidualQuantizer] quantum must be a finite positive number, received ${quantum}`)
+    }
+
+    let residue = 0
+
+    return {
+        push: (delta: number): number => {
+            // 非有限デルタは残差を汚さず 0 を返す (蓄積器に NaN が入ると以後全放出が死ぬ)。
+            // ❗ |delta| > Number.MAX_SAFE_INTEGER も同じ契約で見送る: 2^53 超では
+            // trunc(residue / quantum) * quantum が浮動小数点丸めで「量子の正確な倍数」で
+            // なくなり、グリッドスナップ消費側へ桁ずれした放出を渡してしまう (実測:
+            // quantum 3 に対し 1e17 % 3 === 1)。残差は常に |残差| < 量子で汚染されない
+            if (!Number.isFinite(delta) || Math.abs(delta) > Number.MAX_SAFE_INTEGER) {
+                return 0
+            }
+            // 方向反転で古い残差を捨てる (逆方向の動き出しを古い順方向残差に食わせない)
+            if (resetOnDirectionChange && residue !== 0 && delta !== 0 && Math.sign(delta) !== Math.sign(residue)) {
+                residue = 0
+            }
+            residue += delta
+            // trunc は 0 方向への切り捨てなので、正負どちらの蓄積でも「量子に満たない分」が残差に残る。
+            // ❗ 末尾の + 0 は -0 の正規化 (負方向の空放出は -0 になり、Object.is 比較や表示を汚す)
+            const emitted = Math.trunc(residue / quantum) * quantum + 0
+            residue -= emitted
+            return emitted
+        },
+        peekResidue: () => residue,
+        reset: () => {
+            residue = 0
+        },
+    }
+}

package/src/styles/virtualscroll.css

@@ -333,3 +333,18 @@
   position: absolute;
   width: 100%;
 }
+
+/* 支援技術専用ライブリージョン (liveRegion prop)。標準の visually-hidden パターン:
+   絶対配置 + 1px クリップで視覚とレイアウトから完全に消しつつ、AT からは読める。
+   display:none / visibility:hidden にすると aria-live ごと無効化されるため使えない */
+.aqvs-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}