@aiquants/spreadsheet 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/spreadsheet",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
   "sideEffects": [
     "**/*.css"

package/src/Spreadsheet.tsx

@@ -217,6 +217,43 @@ export type SpreadsheetProps = {
      * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
      */
     tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /**
+     * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
+     * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
+     * engine's one-frame rendering-window lag during fast scrolling (the blank-band remedy —
+     * the slack in px is overscan × row height per edge). Undefined ⇒ the engine default (3).
+     * The engine clamps invalid values silently, so THIS surface owns the fail-fast: a
+     * non-integer or negative value throws a RangeError at render. Cost multiplies with the
+     * column axis (bounded by the engine cell cap).
+     * 行軸 overscan の素通し (VirtualGrid `overscanRows`。ライブ prop): 縦 viewport 端の外側へ
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策 —
+     * 余裕 px は片端あたり overscan × 行高)。undefined はエンジン既定 (3)。エンジンは不正値を
+     * 無言クランプするため fail-fast は本層所有 — 非整数・負値は render 時 RangeError。費用は
+     * 列軸との積で増幅 (エンジンのセル上限で有界)。
+     */
+    overscanRows?: number
+    /**
+     * Column-axis overscan pass-through (the VirtualGrid `overscanCols` knob; LIVE prop) — the
+     * column twin of `overscanRows`, same validation contract (non-negative integer or
+     * RangeError; undefined ⇒ engine default 3).
+     * 列軸 overscan の素通し (VirtualGrid `overscanCols`。ライブ prop) — `overscanRows` の
+     * 列双子。検証契約は同文 (非負整数、それ以外 RangeError。undefined ⇒ エンジン既定 3)。
+     */
+    overscanCols?: number
+    /**
+     * Background layer rendered behind the scroll-band rows, inside the engine content element
+     * (the VirtualGrid `background` pass-through; LIVE prop). VIEWPORT-PINNED: the engine
+     * translates only its row wrapper, so this layer does NOT follow the scroll offset —
+     * periodic row ruling placed here slides against the real rows while scrolling. Suited to
+     * a static texture that reads as "content still arriving" in the overscan-exhausted band,
+     * not to row-aligned gridlines.
+     * スクロール帯行の背後・エンジンコンテンツ要素内に描画する背景レイヤー (VirtualGrid
+     * `background` の素通し。ライブ prop)。viewport 固定: エンジンが translate するのは行
+     * ラッパーだけで、この層はスクロール量に追従しない — 周期的な行罫線を置くとスクロール中に
+     * 実際の行へ対して滑る。overscan が尽きた帯で「まだ到着中」と読める静的テクスチャ向きで、
+     * 行整合の罫線には不向き。
+     */
+    background?: ReactNode
     /**
      * Identity-stable contract (same as adapter): an inline arrow here defeats the CellView memo
      * and turns every host re-render into a full visible re-slice (~800 cells at 16k columns).
@@ -473,6 +510,21 @@ const ZOOM_MAX = 4
  * fail-fast — Math.min/max は NaN を素通しし、全 ÷z 境界の汚染と同値バウンド無効化 (NaN 同士は
  * 不一致) による onZoomChange(NaN) 連射を招くため。
  */
+/**
+ * Validates one overscan prop and returns it unchanged (fail-fast — the engine clamps invalid
+ * overscan silently, so rejection is owned by this surface). Undefined is the declared absence
+ * signal (engine default) and is exempt. Throws RangeError on a non-integer or negative value.
+ * overscan prop 1 つの検証 (値はそのまま返す。fail-fast — エンジンは不正 overscan を無言
+ * クランプするため拒否は本層所有)。undefined は宣言不在信号 (エンジン既定) で対象外。非整数・
+ * 負値は RangeError。
+ */
+const validateOverscan = (name: "overscanRows" | "overscanCols", value: number | undefined): number | undefined => {
+    if (value !== undefined && !(Number.isInteger(value) && value >= 0)) {
+        throw new RangeError(`[spreadsheet] ${name} must be a non-negative integer (got ${value})`)
+    }
+    return value
+}
+
 const clampZoom = (value: number): number => {
     if (!Number.isFinite(value)) {
         throw new RangeError(`[spreadsheet] zoom must be a finite number (got ${value})`)
@@ -619,6 +671,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         frozenTrailingColumns = 0,
         frozenTrailingRows = 0,
         tapScrollCircleOptions,
+        overscanRows,
+        overscanCols,
+        background,
         renderCell,
         onSelectionChange,
         onCellContextMenu,
@@ -2577,6 +2632,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         frozenTrailingColumns={frozenTrailingColumns}
                         frozenTrailingRows={frozenTrailingRows}
                         tapScrollCircleOptions={tapScrollCircleOptions}
+                        overscanRows={validateOverscan("overscanRows", overscanRows)}
+                        overscanCols={validateOverscan("overscanCols", overscanCols)}
+                        background={background}
                         renderCell={renderCell}
                         onScroll={onScroll}
                         onRangeChange={onRangeChange}

package/src/grid/GridBody.tsx

@@ -318,6 +318,22 @@ type GridBodyProps = {
      * キー同乗のままエンジン宣言の不在信号 (エンジン既定) — この層での値フォールバックなし。
      */
     tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /**
+     * Row-axis overscan (the engine `overscanRows` pass-through; the Spreadsheet surface owns
+     * the fail-fast validation — the engine clamps silently). Undefined ⇒ engine default (3).
+     * 行軸 overscan (エンジン `overscanRows` の素通し。fail-fast 検証は Spreadsheet 面所有 —
+     * エンジンは無言クランプ)。undefined ⇒ エンジン既定 (3)。
+     */
+    overscanRows?: number
+    /** Column-axis overscan — the column twin of `overscanRows`, same contract. / 列軸 overscan — `overscanRows` の列双子 (同契約)。 */
+    overscanCols?: number
+    /**
+     * Background layer behind the scroll-band rows (the engine `background` pass-through;
+     * viewport-pinned — the engine translates only its row wrapper).
+     * スクロール帯行背後の背景レイヤー (エンジン `background` の素通し。viewport 固定 —
+     * エンジンが translate するのは行ラッパーのみ)。
+     */
+    background?: ReactNode
 }
 
 /**
@@ -348,6 +364,9 @@ const GridBodyInner = ({
     cfMemoRef,
     isPointing,
     tapScrollCircleOptions,
+    overscanRows,
+    overscanCols,
+    background,
 }: GridBodyProps): ReactNode => {
     const internalBodyRef = useRef<HTMLDivElement | null>(null)
     // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -517,6 +536,9 @@ const GridBodyInner = ({
                 contentProps={contentProps}
                 behaviorOptions={behaviorOptions}
                 scrollBarOptions={scrollBarOptions}
+                overscanRows={overscanRows}
+                overscanCols={overscanCols}
+                background={background}
                 callbackThrottleMs={0}
                 onScroll={onScroll}
                 onRangeChange={onRangeChange}