@aiquants/virtualscroll 3.8.2 → 3.9.0

package/dist/VirtualScroll.d.ts

@@ -1,4 +1,5 @@
 import { default as React, ReactNode } from 'react';
+import { DevicePixelSnapEdge } from './devicePixelGrid.ts';
 import { VirtualScrollLabelOverrides, VirtualScrollLocale } from './labels.ts';
 import { ScrollPaneProps } from './ScrollPane.tsx';
 import { useFenwickMapTree } from './useFenwickMapTree.ts';
@@ -21,6 +22,42 @@ export type VirtualScrollRange = {
     /** Total height of the scroll content / スクロールコンテンツの総高さ */
     totalHeight: number;
 };
+/**
+ * Why VirtualScroll moved its scroll position on its own (see `VirtualScrollProps["onScrollAdjust"]`).
+ *
+ * - `"item-resize"`: `updateItemSize` changed the height of a row above the first visible row, and the position moved by
+ *   the same delta, so the visible rows stay where they were.
+ * - `"reconciliation"`: a render found that `getItemHeight` returns a new height for a rendered row above the first
+ *   visible row; the height reconciliation that follows the render (a microtask) moved the position by the same delta.
+ * - `"drift"`: after a size change (content, viewport, item count or insets) the pending alignment of the last
+ *   `scrollToIndex` (or of `initialScrollAnchor`) was pinned again, in an effect after the commit.
+ * - `"re-issue"`: a compensation that the pane clamped against the previous content size was issued again once the new
+ *   content size had committed, in an effect after the commit.
+ *
+ * VirtualScroll が自分でスクロール位置を動かした理由 (`VirtualScrollProps["onScrollAdjust"]` を参照)。
+ *
+ * - `"item-resize"`: `updateItemSize` が先頭の可視行より上の行の高さを変え、位置を同じ差だけ動かした (見えている行はその場に
+ *   留まる)。
+ * - `"reconciliation"`: 描画が、描いた行のうち先頭の可視行より上の行について `getItemHeight` の新しい高さを見つけ、描画の後の
+ *   高さの照合 (マイクロタスク) が位置を同じ差だけ動かした。
+ * - `"drift"`: 寸法の変化 (中身・ビューポート・件数・インセット) の後、最後の `scrollToIndex` (または `initialScrollAnchor`)
+ *   の保留中の揃えを、確定の後の effect で留め直した。
+ * - `"re-issue"`: ペインが前の中身の寸法でクランプした補正を、新しい中身の寸法が確定した後の effect でもう一度発行した。
+ */
+export type VirtualScrollAdjustmentCause = "item-resize" | "reconciliation" | "drift" | "re-issue";
+/**
+ * One position change VirtualScroll made on its own (the argument of `VirtualScrollProps["onScrollAdjust"]`).
+ *
+ * VirtualScroll が自分で行った 1 回の位置の変化 (`VirtualScrollProps["onScrollAdjust"]` の引数)。
+ */
+export type VirtualScrollAdjustment = {
+    /** The LOGICAL scroll position after the change — what `getScrollPosition()` returns at that moment / 変化の後の論理スクロール位置 (その時点の `getScrollPosition()` の値) */
+    readonly position: number;
+    /** The applied change in LOGICAL px: `position` minus the position before the change; never 0 / 適用した変化 (論理 px)。`position` から変化の前の位置を引いた値で、0 にはならない */
+    readonly delta: number;
+    /** Why the position moved / 位置が動いた理由 */
+    readonly cause: VirtualScrollAdjustmentCause;
+};
 /**
  * Imperative handle of VirtualScroll. Every position it accepts or returns is in the
  * LOGICAL coordinate space (content px, insets excluded) — the same space as onScroll /
@@ -94,7 +131,15 @@ export type VirtualScrollHandle = {
     getContentSize: () => number;
     /** Viewport size / ビューポートの高さ。未接続時は -1 */
     getViewportSize: () => number;
-    /** Scrolls to a specific item index / 指定したアイテムインデックスへスクロール */
+    /**
+     * Scrolls to a specific item index, landing exactly on the aligned position (clamped to the content). A `"top"`
+     * (default) or `"bottom"` alignment is remembered at that position, so the device-pixel snap of the items wrapper
+     * keeps the aligned edge there (see the README's device-pixel snapping section).
+     *
+     * 指定したアイテムインデックスへスクロールする処理。揃えた位置 (中身の範囲へクランプ) へ厳密に着地する。`"top"` (既定) と
+     * `"bottom"` の揃えはその位置で覚えるので、そこでは行ラッパーの装置の画素への揃えが揃えた端を守る (README の装置の画素への
+     * 揃えの節を参照)。
+     */
     scrollToIndex: (index: number, options?: {
         align?: "top" | "bottom" | "center";
         offset?: number;
@@ -123,10 +168,15 @@ export type VirtualScrollHandle = {
      * `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.
+     * When the item lies above the first visible row, the scroll position moves by the size change
+     * before this returns (layout-shift compensation), and `onScrollAdjust` reports it with the cause
+     * `"item-resize"`.
      *
      * 特定のアイテムのサイズを手動で更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を
      * 返すこと。`getItemHeight` が正であるため、旧値を返し続けると描画ウィンドウ (オーバースキャン
-     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。
+     * 含む) 内の行は次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。アイテムが先頭の可視行より
+     * 上にあるときは、戻る前にスクロール位置をサイズの変化だけ動かし (レイアウトシフトの補正)、
+     * `onScrollAdjust` が理由 `"item-resize"` で知らせる。
      */
     updateItemSize: (index: number, size: number) => void;
 };
@@ -329,6 +379,33 @@ export type VirtualScrollProps<T> = {
     testId?: string;
     onScroll?: (scrollPosition: number, totalHeight: number) => void;
     onRangeChange?: (range: VirtualScrollRange) => void;
+    /**
+     * Called synchronously, without throttling, each time VirtualScroll moves its scroll position on its own: a
+     * layout-shift compensation (`"item-resize"`, `"reconciliation"`), the re-pinning of a pending alignment
+     * (`"drift"`) or the second stage of a clamped compensation (`"re-issue"`) — see `VirtualScrollAdjustmentCause`.
+     * It runs after the change is complete, so `getScrollPosition()` and `getScrollAnchor()` read inside it already
+     * see the adjusted position and row heights. It never runs for scrolls that the user or the host start (wheel,
+     * drag, scrollbar, inertia, keyboard row navigation, `scrollTo` / `scrollBy` / `scrollToIndex` / `applyWheel`),
+     * nor for a change that leaves `getScrollPosition()` where it was.
+     *
+     * `onScroll` and `onRangeChange` report every position, but throttled and one frame later. A host that keeps its
+     * own scroll anchor by item identity (re-finding the first visible item by key after a list change) records that
+     * anchor from the range report and from its own scrolls; it must also record it from here, or a list change
+     * committed before the next range report restores a position VirtualScroll has already moved.
+     *
+     * VirtualScroll が自分でスクロール位置を動かすたびに、間引かず同期で呼ぶ関数。レイアウトシフトの補正
+     * (`"item-resize"`・`"reconciliation"`)、保留中の揃えの留め直し (`"drift"`)、クランプされた補正の二段目
+     * (`"re-issue"`) が対象 (`VirtualScrollAdjustmentCause` を参照)。変化を終えてから呼ぶので、中で読む
+     * `getScrollPosition()` と `getScrollAnchor()` は動かした後の位置と行の高さを返す。利用者やホストが始めた
+     * スクロール (ホイール・ドラッグ・スクロールバー・慣性・行のキーボード移動・`scrollTo` / `scrollBy` /
+     * `scrollToIndex` / `applyWheel`) と、`getScrollPosition()` を変えない変化では呼ばない。
+     *
+     * `onScroll` と `onRangeChange` はどの位置も知らせるが、間引いたうえで 1 フレーム遅れる。項目の同一性で自前の
+     * スクロールの錨を持つホスト (一覧の変化の後に先頭の可視項目をキーで探し直す) は、範囲の知らせと自分のスクロールで
+     * 錨を記録するが、ここでも記録すること。さもないと、次の範囲の知らせより前に確定した一覧の変化が、VirtualScroll が
+     * 既に動かした位置を巻き戻す。
+     */
+    onScrollAdjust?: (adjustment: VirtualScrollAdjustment) => void;
     /**
      * Opt-in `aria-live` region announcing the visible range to assistive technology (default:
      * none rendered). Virtualization removes off-screen rows from the DOM, so a screen-reader
@@ -534,26 +611,52 @@ export declare const MAX_RENDERED_ITEMS = 2000;
  */
 export declare const ANCHOR_REBASE_DISTANCE = 1048576;
 /**
- * Snaps a CSS-px offset to the device-pixel grid of a window: the nearest offset whose device-px value is a
- * whole number, `Math.round(cssPx × ratio) / ratio` (an exact half rounds toward +∞, as `Math.round` does). The items-wrapper translate goes through it: a composited layer moved by a fraction of a
- * device pixel is resampled as a whole (2-px outlines, gaps and rings smear across neighbouring device rows and
- * text blurs), while fractional layout positions inside the layer are painted on whole pixels already.
- * Idempotent: a snapped value snaps to itself. A non-finite `cssPx` propagates (`NaN` in, `NaN` out).
- * Module-level export (NOT in the package barrel).
+ * The viewport edge VirtualScroll aligned a row to, and the pane position at which that alignment holds. Module-level
+ * export (NOT in the package barrel), the parameter type of `resolveItemsWrapperSnapEdge`.
+ *
+ * VirtualScroll が行を揃えた表示域の端と、その揃えが成り立つペイン位置。モジュールレベル export (バレル非公開)。
+ * `resolveItemsWrapperSnapEdge` の引数の型。
+ */
+export type AlignedEdge = {
+    /** `"start"` for a top alignment, `"end"` for a bottom alignment / 上端揃えは `"start"`、下端揃えは `"end"` */
+    readonly edge: "start" | "end";
+    /** Pane position (PANE coordinates) where the aligned row sits at that edge / 揃えた行がその端にあるペイン位置 (ペイン座標) */
+    readonly panePosition: number;
+};
+/**
+ * Chooses the edge the items-wrapper translate keeps when it is snapped to the device-pixel grid
+ * (`snapToDevicePixelGrid`), so that aligned content never loses part of its edge gutter to the snap:
+ *
+ * - `"start"` while the pane rests at position 0: the first row and the top inset keep their place.
+ * - `"end"` while the pane rests at its maximum position: the last row and the bottom inset keep theirs.
+ * - The edge of the remembered alignment while the pane is at the position where it holds: a row revealed by
+ *   `scrollToIndex` with `align: "top"` (or the default) or `align: "bottom"`, kept through layout-shift compensation and
+ *   drift correction.
+ * - `"none"` (nearest) everywhere else.
+ *
+ * Position 0 wins over the maximum position (a list that does not scroll stays top-aligned), and both win over a
+ * remembered alignment, since a clamp means that alignment was not reached. A position within `EDGE_POSITION_TOLERANCE`
+ * of one of these counts as that position. Module-level export (NOT in the package barrel).
+ *
+ * 行ラッパーの平行移動を装置の画素の格子へ揃えるとき (`snapToDevicePixelGrid`) に守る端を選ぶ処理。揃えた中身の端の余白を
+ * 丸めが削らないようにする。
+ *
+ * - ペインが位置 0 に止まっている間は `"start"`。最初の行と上のインセットがその場に留まる。
+ * - ペインが最大位置に止まっている間は `"end"`。最後の行と下のインセットがその場に留まる。
+ * - 覚えた揃えが成り立つ位置にペインがある間は、その揃えの端。`scrollToIndex` が `align: "top"` (既定を含む) か
+ *   `align: "bottom"` で見せた行で、レイアウトシフトの補正とドリフト補正を通して保つ。
+ * - それ以外は `"none"` (最も近い格子点)。
  *
- * CSS px のオフセットをウィンドウの装置の画素の格子へ揃える処理。装置 px で整数になる最も近いオフセット
- * `Math.round(cssPx × ratio) / ratio` (ちょうど半分は `Math.round` どおり +∞ 側)。
- * 行ラッパーの平行移動はここを通す — 合成層を装置の画素の端数だけ動かすとブラウザは層全体を再標本化し
- * (2px の輪郭・隙間・輪が隣の装置の行へ滲み、文字もぼける)、層の中の端数のレイアウト位置は描画が既に画素へ
- * 揃えるため。冪等 (揃えた値はそのまま)。有限でない `cssPx` はそのまま伝わる (`NaN` は `NaN`)。
- * モジュールレベル export (バレル非公開)。
+ * 位置 0 は最大位置に勝ち (スクロールしない一覧は上端揃えのまま)、どちらも覚えた揃えに勝つ (クランプは揃えが届かなかった
+ * ことを意味する)。これらの位置から `EDGE_POSITION_TOLERANCE` 以内の位置はその位置とみなす。モジュールレベル export
+ * (バレル非公開)。
  *
- * @param cssPx - Offset in CSS px; negative and fractional values included / CSS px のオフセット (負・小数を含む)
- * @param ratio - Device px per CSS px of the window that paints the offset (its `devicePixelRatio`); a finite number > 0 / オフセットを描くウィンドウの CSS px あたりの装置 px (そのウィンドウの `devicePixelRatio`。0 より大きい有限数)
- * @returns The snapped offset in CSS px / 揃えたオフセット (CSS px)
- * @throws {RangeError} When `ratio` is not a finite number greater than 0 / `ratio` が 0 より大きい有限数でないとき
+ * @param panePosition - The pane position the wrapper is rendered at (PANE coordinates) / ラッパーを描くペイン位置 (ペイン座標)
+ * @param maxPanePosition - The pane's maximum position: content plus insets minus the viewport / ペインの最大位置 (中身とインセットの和からビューポートを引いた値)
+ * @param alignedEdge - The remembered alignment, or `null` / 覚えた揃え (無ければ `null`)
+ * @returns The edge the snapped translate keeps / 揃えた平行移動が守る端
  */
-export declare const snapToDevicePixelGrid: (cssPx: number, ratio: number) => number;
+export declare const resolveItemsWrapperSnapEdge: (panePosition: number, maxPanePosition: number, alignedEdge: AlignedEdge | null) => DevicePixelSnapEdge;
 /**
  * Retrieves a high-resolution timestamp when available.
  *

package/dist/VirtualScroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualScroll.d.ts","sourceRoot":"","sources":["../src/VirtualScroll.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAc,KAAK,SAAS,EAAiH,MAAM,OAAO,CAAA;AACxK,OAAO,EAA8B,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEpH,OAAO,EAAmE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAA;IAC3B,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,CAAA;IACzB,6FAA6F;IAC7F,iBAAiB,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,KAAK,MAAM,CAAA;IACnE;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnC;;;;;;;;OAQG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;IAC1C;;;OAGG;IACH,iBAAiB,EAAE,MAAM,MAAM,CAAA;IAC/B,gHAAgH;IAChH,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,yCAAyC;IACzC,eAAe,EAAE,MAAM,MAAM,CAAA;IAC7B,8DAA8D;IAC9D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC1G,sFAAsF;IACtF,yBAAyB,EAAE,MAAM,MAAM,CAAA;IACvC,6EAA6E;IAC7E,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,qEAAqE;IACrE,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAChF,kEAAkE;IAClE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;IAClC;;;;OAIG;IACH,eAAe,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjE;;;;;;;;;OASG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACxD,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GAAG;IACxC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,yGAAyG;IACzG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,+FAA+F;IAC/F,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAA;IAC1D,0HAA0H;IAC1H,sBAAsB,CAAC,EAAE,eAAe,CAAC,wBAAwB,CAAC,CAAA;CACrE,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,eAAe,CAAC,mBAAmB,CAAC,CAAA;IACxD,wBAAwB,CAAC,EAAE,OAAO,CAAA;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,cAAc,CAAC,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAA;IAClD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAA;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAA;CACvC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACvC,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAA;IACzB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG;IACzC;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,4BAA4B,KAAK,MAAM,CAAA;IACvD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAA;IAC7B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,GAAG,CAAA;IACzC;;;;;;;;;;;;;OAaG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iMAAiM;IACjM,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;IAChE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAA;IACnD;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,8BAA8B,CAAA;IAC3C;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,2BAA2B,CAAA;IACpC,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IAC/C,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,aAAa,CAAC,EAAE,eAAe,CAAC,eAAe,CAAC,CAAA;IAChD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,gBAAgB,CAAC,EAAE,6BAA6B,CAAA;IAChD,eAAe,CAAC,EAAE,4BAA4B,CAAA;IAC9C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,mBAAmB,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACxC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;CACjD,CAAA;AAuBD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AAEzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,UAAY,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MAKpE,CAAA;AAsYD;;;;GAIG;AACH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,gBAAgB,MAAM,EAAE,cAAc,MAAM,EAAE,eAAe,MAAM,EAAE,UAAU,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,aAAa,UAAU,CAAC,OAAO,iBAAiB,CAAC,EAAE,aAAa,MAAM;;;;;CAgI7O,CAAA;AA6vDD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAqC,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;CAAE,KAAK,KAAK,CAAC,YAAY,CAAA"}
+{"version":3,"file":"VirtualScroll.d.ts","sourceRoot":"","sources":["../src/VirtualScroll.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAc,KAAK,SAAS,EAA2F,MAAM,OAAO,CAAA;AAClJ,OAAO,EAAE,KAAK,mBAAmB,EAAsD,MAAM,sBAAsB,CAAA;AACnH,OAAO,EAA8B,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEpH,OAAO,EAAmE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAA;IAC3B,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,CAAA;IACzB,6FAA6F;IAC7F,iBAAiB,EAAE,MAAM,CAAA;IACzB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,4BAA4B,GAAG,aAAa,GAAG,gBAAgB,GAAG,OAAO,GAAG,UAAU,CAAA;AAElG;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAClC,yJAAyJ;IACzJ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sJAAsJ;IACtJ,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAA;CAC/C,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,KAAK,MAAM,CAAA;IACnE;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnC;;;;;;;;OAQG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;IAC1C;;;OAGG;IACH,iBAAiB,EAAE,MAAM,MAAM,CAAA;IAC/B,gHAAgH;IAChH,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,yCAAyC;IACzC,eAAe,EAAE,MAAM,MAAM,CAAA;IAC7B;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC1G,sFAAsF;IACtF,yBAAyB,EAAE,MAAM,MAAM,CAAA;IACvC,6EAA6E;IAC7E,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,qEAAqE;IACrE,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAChF,kEAAkE;IAClE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;IAClC;;;;OAIG;IACH,eAAe,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjE;;;;;;;;;;;;;;OAcG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACxD,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GAAG;IACxC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,yGAAyG;IACzG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,+FAA+F;IAC/F,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAA;IAC1D,0HAA0H;IAC1H,sBAAsB,CAAC,EAAE,eAAe,CAAC,wBAAwB,CAAC,CAAA;CACrE,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,eAAe,CAAC,mBAAmB,CAAC,CAAA;IACxD,wBAAwB,CAAC,EAAE,OAAO,CAAA;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,cAAc,CAAC,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAA;IAClD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAA;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAA;CACvC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACvC,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAA;IACzB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG;IACzC;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,4BAA4B,KAAK,MAAM,CAAA;IACvD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAA;IAC7B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,GAAG,CAAA;IACzC;;;;;;;;;;;;;OAaG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iMAAiM;IACjM,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;IAChE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAA;IACnD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC9D;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,8BAA8B,CAAA;IAC3C;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,2BAA2B,CAAA;IACpC,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IAC/C,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,aAAa,CAAC,EAAE,eAAe,CAAC,eAAe,CAAC,CAAA;IAChD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,gBAAgB,CAAC,EAAE,6BAA6B,CAAA;IAChD,eAAe,CAAC,EAAE,4BAA4B,CAAA;IAC9C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,mBAAmB,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACxC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;CACjD,CAAA;AAuBD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AAEzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,UAAY,CAAA;AAe/C;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAA;IAC9B,0GAA0G;IAC1G,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAChC,CAAA;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,2BAA2B,GAAI,cAAc,MAAM,EAAE,iBAAiB,MAAM,EAAE,aAAa,WAAW,GAAG,IAAI,KAAG,mBAW5H,CAAA;AA8PD;;;;GAIG;AACH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,gBAAgB,MAAM,EAAE,cAAc,MAAM,EAAE,eAAe,MAAM,EAAE,UAAU,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,aAAa,UAAU,CAAC,OAAO,iBAAiB,CAAC,EAAE,aAAa,MAAM;;;;;CAgI7O,CAAA;AA43DD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAqC,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;CAAE,KAAK,KAAK,CAAC,YAAY,CAAA"}

package/dist/devicePixelGrid.d.cts

@@ -0,0 +1,78 @@
+/**
+ * The edge a snapped offset keeps when the exact offset falls between two grid points, for an offset that translates
+ * content along an axis (a positive offset moves the content toward the end):
+ *
+ * - `"none"`: the nearest grid point, `Math.round` (an exact half rounds toward +∞).
+ * - `"end"`: the grid point at or before the exact offset, `Math.floor`. The content never moves toward the viewport end,
+ *   so content aligned to the end (the last row at the maximum position, a row revealed with `align: "bottom"`) never
+ *   crosses it.
+ * - `"start"`: the grid point at or after the exact offset, `Math.ceil`. The content never moves toward the viewport start,
+ *   so content aligned to the start (the first row at position 0, a row revealed with `align: "top"`) never crosses it.
+ *
+ * 正確なオフセットが 2 つの格子点の間にあるとき、揃えたオフセットがどちらの端を守るか (中身を軸に沿って動かすオフセット。
+ * 正のオフセットは中身を終端側へ動かす)。
+ *
+ * - `"none"`: 最も近い格子点 (`Math.round`。ちょうど半分は +∞ 側)。
+ * - `"end"`: 正確なオフセット以下の格子点 (`Math.floor`)。中身は表示域の終端側へ動かないので、終端に揃えた中身
+ *   (最大位置の最後の行・`align: "bottom"` で見せた行) は終端を越えない。
+ * - `"start"`: 正確なオフセット以上の格子点 (`Math.ceil`)。中身は表示域の始端側へ動かないので、始端に揃えた中身
+ *   (位置 0 の最初の行・`align: "top"` で見せた行) は始端を越えない。
+ */
+export type DevicePixelSnapEdge = "none" | "start" | "end";
+/**
+ * Snaps a CSS-px offset to the device-pixel grid of a window toward `edge`: an offset whose device-px value is a whole
+ * number, at most one device pixel from the exact one (`"none"`: at most half a device pixel). A product within
+ * `ON_GRID_TOLERANCE_DEVICE_PX` of a whole number is on the grid already, whatever the edge, so the snap is idempotent
+ * for every edge and floating-point residue never moves the content by a whole device pixel. A non-finite `cssPx`
+ * propagates (`NaN` in, `NaN` out).
+ *
+ * CSS px のオフセットをウィンドウの装置の画素の格子へ `edge` の側で揃える処理。装置 px の値が整数になるオフセットで、
+ * 正確な値から装置の画素 1 つ未満 (`"none"` は半分以内)。整数から `ON_GRID_TOLERANCE_DEVICE_PX` 以内の積はどの端でも
+ * 既に格子上とみなすので、どの端でも冪等で、浮動小数点の残差が中身を装置の画素 1 つ分動かすことはない。有限でない
+ * `cssPx` はそのまま伝わる (`NaN` は `NaN`)。
+ *
+ * @param cssPx - Offset in CSS px; negative and fractional values included / CSS px のオフセット (負・小数を含む)
+ * @param ratio - Device px per CSS px of the window that paints the offset (its `devicePixelRatio`); a finite number > 0 / オフセットを描くウィンドウの CSS px あたりの装置 px (そのウィンドウの `devicePixelRatio`。0 より大きい有限数)
+ * @param edge - The edge the snapped offset keeps (see `DevicePixelSnapEdge`) / 揃えたオフセットが守る端 (`DevicePixelSnapEdge` を参照)
+ * @returns The snapped offset in CSS px / 揃えたオフセット (CSS px)
+ * @throws {RangeError} When `ratio` is not a finite number greater than 0 / `ratio` が 0 より大きい有限数でないとき
+ */
+export declare const snapToDevicePixelGrid: (cssPx: number, ratio: number, edge: DevicePixelSnapEdge) => number;
+/**
+ * The painting window's device-pixel ratio and the ref callback that confirms that window (see `usePaintingDevicePixelRatio`).
+ *
+ * 描くウィンドウの装置の画素比と、そのウィンドウを確かめる ref コールバック (`usePaintingDevicePixelRatio` を参照)。
+ */
+export type PaintingDevicePixelRatio = {
+    /** The ratio, or `null` while no window is known (server rendering and hydration) / 比 (ウィンドウが分からない間 = サーバー描画とハイドレーションは `null`) */
+    readonly ratio: number | null;
+    /** Ref callback for the translated element / 平行移動する要素の ref コールバック */
+    readonly attach: (element: Element | null) => void;
+};
+/**
+ * Reads, during render, the device-pixel ratio of the window that paints an element, for snapping the element's translate
+ * (`snapToDevicePixelGrid`). Rule: the translate that reaches the screen is always snapped with the ratio of the window
+ * that paints the element. Render reads the ratio through `useSyncExternalStore` from the expected painting window — the
+ * realm's window (`readRealmWindow`) until the element has attached, since render cannot see the target document. The
+ * attach (`attach`, the element's ref callback) confirms it with the element's own window (`windowOf`): when they agree
+ * (an element rendered into its own window's document), the first commit is already snapped and nothing is scheduled in
+ * the commit phase; when they differ (an iframe or an opened window), the attach switches to that window; the update is
+ * scheduled in the commit phase, so React re-renders synchronously before the browser paints. Ratio changes re-render
+ * through the store subscription (`subscribeToDevicePixelRatio`), outside the commit phase. The server snapshot is
+ * `null`: server HTML and hydration carry the exact offset, replaced by the snapped one right after hydration.
+ *
+ * 要素の平行移動を揃えるため (`snapToDevicePixelGrid`)、要素を描くウィンドウの装置の画素比を描画の中で読むフック。規則は
+ * 「画面へ届く平行移動は、常に要素を描くウィンドウの比で揃っている」。描画は `useSyncExternalStore` で、描くと見込む
+ * ウィンドウから比を読む — 描画からは挿入先の文書が見えないので、要素が取り付くまではレルムのウィンドウ
+ * (`readRealmWindow`)。取り付け (`attach`。要素の ref コールバック) が要素自身のウィンドウ (`windowOf`) と突き合わせて
+ * 確かめ、一致すれば (自分のウィンドウの文書に描いた要素) 最初の確定から揃っていて確定の段では何も予約しない。違えば
+ * (iframe・開いたウィンドウ) 取り付けがそのウィンドウへ切り替え、この更新は確定の段で予約されるので、React はブラウザの
+ * paint の前に同期で描き直す。比の変化はストアの購読 (`subscribeToDevicePixelRatio`) で確定の段の外から描き直す。
+ * サーバーのスナップショットは `null` で、サーバーの HTML とハイドレーションは厳密なオフセットを持ち、ハイドレーションの
+ * 直後に揃えた値へ置き換わる。
+ *
+ * @param part - The element's name for the error, with the owning component (e.g. `"[VirtualScroll] the items wrapper"`) / 誤りに使う要素の名前 (持ち主の部品を含む)
+ * @returns The ratio and the ref callback / 比と ref コールバック
+ * @throws {Error} When the element attaches to a document without a window (see `windowOf`) / ウィンドウを持たない文書へ取り付いたとき (`windowOf` を参照)
+ */
+export declare const usePaintingDevicePixelRatio: (part: string) => PaintingDevicePixelRatio;

package/dist/devicePixelGrid.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The edge a snapped offset keeps when the exact offset falls between two grid points, for an offset that translates
+ * content along an axis (a positive offset moves the content toward the end):
+ *
+ * - `"none"`: the nearest grid point, `Math.round` (an exact half rounds toward +∞).
+ * - `"end"`: the grid point at or before the exact offset, `Math.floor`. The content never moves toward the viewport end,
+ *   so content aligned to the end (the last row at the maximum position, a row revealed with `align: "bottom"`) never
+ *   crosses it.
+ * - `"start"`: the grid point at or after the exact offset, `Math.ceil`. The content never moves toward the viewport start,
+ *   so content aligned to the start (the first row at position 0, a row revealed with `align: "top"`) never crosses it.
+ *
+ * 正確なオフセットが 2 つの格子点の間にあるとき、揃えたオフセットがどちらの端を守るか (中身を軸に沿って動かすオフセット。
+ * 正のオフセットは中身を終端側へ動かす)。
+ *
+ * - `"none"`: 最も近い格子点 (`Math.round`。ちょうど半分は +∞ 側)。
+ * - `"end"`: 正確なオフセット以下の格子点 (`Math.floor`)。中身は表示域の終端側へ動かないので、終端に揃えた中身
+ *   (最大位置の最後の行・`align: "bottom"` で見せた行) は終端を越えない。
+ * - `"start"`: 正確なオフセット以上の格子点 (`Math.ceil`)。中身は表示域の始端側へ動かないので、始端に揃えた中身
+ *   (位置 0 の最初の行・`align: "top"` で見せた行) は始端を越えない。
+ */
+export type DevicePixelSnapEdge = "none" | "start" | "end";
+/**
+ * Snaps a CSS-px offset to the device-pixel grid of a window toward `edge`: an offset whose device-px value is a whole
+ * number, at most one device pixel from the exact one (`"none"`: at most half a device pixel). A product within
+ * `ON_GRID_TOLERANCE_DEVICE_PX` of a whole number is on the grid already, whatever the edge, so the snap is idempotent
+ * for every edge and floating-point residue never moves the content by a whole device pixel. A non-finite `cssPx`
+ * propagates (`NaN` in, `NaN` out).
+ *
+ * CSS px のオフセットをウィンドウの装置の画素の格子へ `edge` の側で揃える処理。装置 px の値が整数になるオフセットで、
+ * 正確な値から装置の画素 1 つ未満 (`"none"` は半分以内)。整数から `ON_GRID_TOLERANCE_DEVICE_PX` 以内の積はどの端でも
+ * 既に格子上とみなすので、どの端でも冪等で、浮動小数点の残差が中身を装置の画素 1 つ分動かすことはない。有限でない
+ * `cssPx` はそのまま伝わる (`NaN` は `NaN`)。
+ *
+ * @param cssPx - Offset in CSS px; negative and fractional values included / CSS px のオフセット (負・小数を含む)
+ * @param ratio - Device px per CSS px of the window that paints the offset (its `devicePixelRatio`); a finite number > 0 / オフセットを描くウィンドウの CSS px あたりの装置 px (そのウィンドウの `devicePixelRatio`。0 より大きい有限数)
+ * @param edge - The edge the snapped offset keeps (see `DevicePixelSnapEdge`) / 揃えたオフセットが守る端 (`DevicePixelSnapEdge` を参照)
+ * @returns The snapped offset in CSS px / 揃えたオフセット (CSS px)
+ * @throws {RangeError} When `ratio` is not a finite number greater than 0 / `ratio` が 0 より大きい有限数でないとき
+ */
+export declare const snapToDevicePixelGrid: (cssPx: number, ratio: number, edge: DevicePixelSnapEdge) => number;
+/**
+ * The painting window's device-pixel ratio and the ref callback that confirms that window (see `usePaintingDevicePixelRatio`).
+ *
+ * 描くウィンドウの装置の画素比と、そのウィンドウを確かめる ref コールバック (`usePaintingDevicePixelRatio` を参照)。
+ */
+export type PaintingDevicePixelRatio = {
+    /** The ratio, or `null` while no window is known (server rendering and hydration) / 比 (ウィンドウが分からない間 = サーバー描画とハイドレーションは `null`) */
+    readonly ratio: number | null;
+    /** Ref callback for the translated element / 平行移動する要素の ref コールバック */
+    readonly attach: (element: Element | null) => void;
+};
+/**
+ * Reads, during render, the device-pixel ratio of the window that paints an element, for snapping the element's translate
+ * (`snapToDevicePixelGrid`). Rule: the translate that reaches the screen is always snapped with the ratio of the window
+ * that paints the element. Render reads the ratio through `useSyncExternalStore` from the expected painting window — the
+ * realm's window (`readRealmWindow`) until the element has attached, since render cannot see the target document. The
+ * attach (`attach`, the element's ref callback) confirms it with the element's own window (`windowOf`): when they agree
+ * (an element rendered into its own window's document), the first commit is already snapped and nothing is scheduled in
+ * the commit phase; when they differ (an iframe or an opened window), the attach switches to that window; the update is
+ * scheduled in the commit phase, so React re-renders synchronously before the browser paints. Ratio changes re-render
+ * through the store subscription (`subscribeToDevicePixelRatio`), outside the commit phase. The server snapshot is
+ * `null`: server HTML and hydration carry the exact offset, replaced by the snapped one right after hydration.
+ *
+ * 要素の平行移動を揃えるため (`snapToDevicePixelGrid`)、要素を描くウィンドウの装置の画素比を描画の中で読むフック。規則は
+ * 「画面へ届く平行移動は、常に要素を描くウィンドウの比で揃っている」。描画は `useSyncExternalStore` で、描くと見込む
+ * ウィンドウから比を読む — 描画からは挿入先の文書が見えないので、要素が取り付くまではレルムのウィンドウ
+ * (`readRealmWindow`)。取り付け (`attach`。要素の ref コールバック) が要素自身のウィンドウ (`windowOf`) と突き合わせて
+ * 確かめ、一致すれば (自分のウィンドウの文書に描いた要素) 最初の確定から揃っていて確定の段では何も予約しない。違えば
+ * (iframe・開いたウィンドウ) 取り付けがそのウィンドウへ切り替え、この更新は確定の段で予約されるので、React はブラウザの
+ * paint の前に同期で描き直す。比の変化はストアの購読 (`subscribeToDevicePixelRatio`) で確定の段の外から描き直す。
+ * サーバーのスナップショットは `null` で、サーバーの HTML とハイドレーションは厳密なオフセットを持ち、ハイドレーションの
+ * 直後に揃えた値へ置き換わる。
+ *
+ * @param part - The element's name for the error, with the owning component (e.g. `"[VirtualScroll] the items wrapper"`) / 誤りに使う要素の名前 (持ち主の部品を含む)
+ * @returns The ratio and the ref callback / 比と ref コールバック
+ * @throws {Error} When the element attaches to a document without a window (see `windowOf`) / ウィンドウを持たない文書へ取り付いたとき (`windowOf` を参照)
+ */
+export declare const usePaintingDevicePixelRatio: (part: string) => PaintingDevicePixelRatio;
+//# sourceMappingURL=devicePixelGrid.d.ts.map

package/dist/devicePixelGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devicePixelGrid.d.ts","sourceRoot":"","sources":["../src/devicePixelGrid.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAA;AAc1D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,mBAAmB,KAAG,MAU/F,CAAA;AAgKD;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,kIAAkI;IAClI,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAA;CACrD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,KAAG,wBAmC1D,CAAA"}