@aiquants/spreadsheet 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -4,6 +4,8 @@ import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { ScrollBarTapCircleOptions } from '@aiquants/virtualscroll';
 import { TapScrollCircleRenderProps } from '@aiquants/virtualscroll';
+import { VirtualScrollLabels } from '@aiquants/virtualscroll';
+import { VirtualScrollLocale } from '@aiquants/virtualscroll';
 
 /** Border colour when `CellBorder.color` is absent (a stated default, not a fallback). / 罫線色の宣言済み既定 (fallback ではなく仕様上の既定)。 */
 export declare const BORDER_DEFAULT_COLOR = "#000000";
@@ -481,17 +483,6 @@ export declare const DEFAULT_CUSTOM_COLORS: readonly string[];
 /** Default band palette (plan §1.9) — the same values the `.aqsp-root` CSS variables fall back to. / 既定の帯パレット (計画 §1.9) — `.aqsp-root` の CSS 変数既定と同値。 */
 export declare const DEFAULT_HIGHLIGHT_COLORS: HighlightColors;
 
-/**
- * English defaults for every key. `sinkAriaLabel` / `rootAriaLabel` are byte-identical to the
- * v0.7 prop defaults (the fold is DOM-identical); `noteEscapeHint` = "Escape saves and closes"
- * and its v0.10 viewer counterpart `noteViewerHint` = "Escape closes without saving";
- * `commentCount` and `listMore` pluralise ("1 comment" / "n comments", "1 more value" / "n more values"). Frozen.
- * 全キーの英語既定。`sinkAriaLabel` / `rootAriaLabel` は v0.7 の prop 既定と byte 同一 (畳込みは
- * DOM 恒等)、`noteEscapeHint` = "Escape saves and closes" とその v0.10 ビューア対応
- * `noteViewerHint` = "Escape closes without saving"、`commentCount` / `listMore` は単複を区別。凍結済み。
- */
-export declare const DEFAULT_LABELS: SpreadsheetLabels;
-
 /**
  * Default chords per command, derived from the `command === K` rows of BUILTIN_ROWS in table
  * order (`[]` = unbound by default: hideColumns and every extension command). Validates under
@@ -1043,11 +1034,22 @@ export declare type ReadOnlyRejection = {
     readonly cellCount: number;
 };
 
-/** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
+/**
+ * Public custom cell renderer context (ADR-8). `text` is the RAW canonical `getCellText`
+ * string; `displayText` (v0.12) is the value-format display string — the exact string the
+ * default rendering, the AT announcement, the HTML clipboard and autofit all share (equals
+ * `text` when the format capability is absent). A custom cell that should look like the
+ * default renders `displayText`.
+ * 公開セルレンダラーの ctx (ADR-8)。`text` は素の正準 `getCellText` 文字列。`displayText`
+ * (v0.12) は値書式の表示文字列 — 既定描画・AT 読み上げ・HTML クリップボード・autofit が共有
+ * する同一文字列 (書式能力なしは `text` と同値)。既定と同じ見た目にしたいカスタムセルは
+ * `displayText` を描く。
+ */
 export declare type RenderCellContext = {
     row: number;
     col: number;
     text: string;
+    displayText: string;
 };
 
 /**
@@ -1056,9 +1058,44 @@ export declare type RenderCellContext = {
  * returned as-is and ignores `n`.
  * 唯一の読み出し点: ラベル 1 件を表示文字列へ解決。関数値は n で呼ぶ (n 省略は呼び手バグとして
  * RangeError — 黙って 0 にしない)、文字列値はそのまま (n は無視)。
+ *
+ * @param labels - The resolved label bag / 解決済みラベル集合
+ * @param key - The label key to read / 読み出すラベルキー
+ * @param n - The count for a count-aware (function-valued) label / 件数キー (関数値) に渡す件数
+ * @returns The display string / 表示文字列
+ * @throws {RangeError} When the label is a function and `n` is omitted / 関数値で n を省略した場合
  */
 export declare const resolveLabel: (labels: SpreadsheetLabels, key: keyof SpreadsheetLabels, n?: number) => string;
 
+/**
+ * The single fold point of the `locale` + `labels` props. The locale is resolved by
+ * `resolveVirtualScrollLocale` (undefined ⇒ "en"). `undefined` overrides return
+ * SPREADSHEET_LABEL_CATALOGS[locale] by identity. Otherwise: the overrides must be a plain object
+ * (prototype `Object.prototype` or `null`) whose own keys all belong to LABEL_KEYS, and only its
+ * own properties are read; the engine subset is resolved by `resolveVirtualScrollLabels` (the
+ * engine's own validation); an own key takes its override when it is not `undefined`
+ * (destructuring-default semantics of the folded v0.7 props) and the catalog value otherwise; the
+ * result is validated by assertLabels and frozen. Inputs are never mutated.
+ * `locale` + `labels` prop の唯一の畳込み点。ロケールは `resolveVirtualScrollLocale` で解決
+ * (undefined は "en")。override 未指定は SPREADSHEET_LABEL_CATALOGS[locale] を identity で返却。
+ * それ以外は、override は自身のキーがすべて LABEL_KEYS に属する素の object (プロトタイプが
+ * `Object.prototype` か `null`) で、読むのは自身のプロパティのみ。エンジン部分は
+ * `resolveVirtualScrollLabels` (エンジン自身の検証) で解決、固有キーは undefined でない override を採用し
+ * それ以外はカタログ値 (畳み込んだ v0.7 prop の分割代入既定の意味論)、結果は assertLabels で検証し凍結。
+ * 入力は変更しない。
+ *
+ * @param locale - UI chrome locale, or `undefined` for the default "en" / UI クロームロケール (`undefined` で既定の "en")
+ * @param overrides - Per-key overrides, or `undefined` for none / キー単位の上書き (`undefined` で上書きなし)
+ * @returns The resolved, frozen label bag / 解決済みの凍結ラベル集合
+ * @throws {RangeError} When the locale is unsupported, the overrides are `null` / not an object,
+ * the overrides are not a plain object (an array, a class instance, an object inheriting from
+ * another object), an own key is not a label key (including the removed validationRejected /
+ * indicator* keys), or a value violates its key's rule / ロケールが非対応、override が `null` /
+ * 非 object、override が素の object でない (配列・クラスインスタンス・他 object 継承)、自身のキーが
+ * ラベルキー外 (削除済みの validationRejected / indicator* を含む)、または値がキーの規則に違反した場合
+ */
+export declare const resolveLabels: (locale: SpreadsheetLocale | undefined, overrides: SpreadsheetLabelOverrides | undefined) => SpreadsheetLabels;
+
 /** One colour-scale point; `value` omitted = the range extremum from `getRangeExtrema` (min / max) or the arithmetic midpoint (mid). / 色スケールの 1 点。value 省略 = getRangeExtrema のレンジ極値 (min / max) か算術中点 (mid)。 */
 export declare type ScalePoint = {
     color: string;
@@ -1156,6 +1193,16 @@ export declare type ShortcutOverrides = {
  */
 export declare const Spreadsheet: ForwardRefExoticComponent<SpreadsheetProps & SpreadsheetTestProps & RefAttributes<SpreadsheetHandle>>;
 
+/**
+ * Frozen full catalogs per locale (outer record and every entry frozen): each entry is the engine
+ * catalog `VIRTUAL_SCROLL_LABEL_CATALOGS[locale]` (reused by value — single source of truth for
+ * the 7 chrome strings) overlaid by the own-key catalog of the same locale.
+ * ロケール別の凍結済み完全カタログ (外側のレコードと各エントリを凍結): 各エントリはエンジンカタログ
+ * `VIRTUAL_SCROLL_LABEL_CATALOGS[locale]` (値を再利用 — 7 クローム文言の単一の真実源) に同ロケールの
+ * 固有キーカタログを重ねたもの。
+ */
+export declare const SPREADSHEET_LABEL_CATALOGS: Readonly<Record<SpreadsheetLocale, SpreadsheetLabels>>;
+
 /**
  * Reserved chords for EVERY command: the exact chords of `rebindable: false` rows consulted in
  * the idle column (`"idle" | "both"` — every command is consulted there). Editing-only rows
@@ -1271,10 +1318,12 @@ export declare type SpreadsheetDataAdapter = {
      * string only — editing keeps the raw getCellText (Excel semantics) and copy/TSV carry the raw
      * value too (a DELIBERATE deviation from Excel, which copies the display — raw preserves the
      * numeric round-trip). Autofit measures the FORMATTED display, and screen-reader
-     * announcements receive both the raw text and the display string. `renderCell` (a prop)
-     * takes precedence over the built-in VALUE format (raw text flows to the custom renderer),
-     * but the resolved ALIGNMENT and paint are cell properties that still apply under
-     * renderCell. Every format is fail-soft: a non-numeric value in a numeric format, an
+     * announcements receive both the raw text and the display string. A `renderCell` (prop)
+     * cell that returns custom output shows that output instead of the built-in VALUE format
+     * (raw `text` and the formatted `displayText` both flow to the custom renderer); a cell whose
+     * renderCell returns `undefined` falls back to the formatted default (v0.12 per-cell opt-out),
+     * and the resolved ALIGNMENT and paint are cell properties that apply under renderCell
+     * regardless. Every format is fail-soft: a non-numeric value in a numeric format, an
      * invalid date, an out-of-range Intl option or an unparseable colour renders / paints
      * nothing for that key. Return a shared/interned CellFormat per column (or per cell object)
      * to avoid per-cell allocation and to keep the paint intern stable; because return values
@@ -1288,9 +1337,10 @@ export declare type SpreadsheetDataAdapter = {
      * **塗り書式** (この base ⊕ 条件付き書式)。値書式は表示文字列にのみ適用し、編集は素の
      * getCellText (Excel 意味論)、コピー / TSV も素の値を運ぶ (Excel は表示を写すため**意図的な
      * 逸脱** — 素値は数値の往復を保つ)。autofit は**整形後の表示**を計測し、読み上げには素の
-     * text と表示文字列の両方を渡す。`renderCell` (prop) は組み込み「値書式」に優先する (素の
-     * text がカスタムレンダラーへ) が、解決済み「揃え」と塗りはセル固有属性として renderCell 下
-     * でも効く。全書式は fail-soft — 数値書式の非数値・無効な日付・範囲外 Intl オプション・解釈
+     * text と表示文字列の両方を渡す。`renderCell` (prop) がカスタム出力を返したセルは組み込み
+     * 「値書式」の代わりにその出力を描く (素の text と整形後 displayText の両方がカスタム
+     * レンダラーへ)。undefined を返したセルは整形済みの既定描画へ降りる (v0.12 のセル単位
+     * オプトアウト)。解決済み「揃え」と塗りはセル固有属性として renderCell 下でも常に効く。全書式は fail-soft — 数値書式の非数値・無効な日付・範囲外 Intl オプション・解釈
      * 不能な色はそのキーだけ何も描かない。列毎 (またはセル object 毎) に共有 CellFormat を返すと
      * セル毎の確保を避け塗りの intern も安定する。戻り値は (getCellText 同様) 再スライス時のみ
      * 再読込されるため、書式変更の反映は dataVersion 増分 (またはアダプタ差替) で行う。
@@ -1403,6 +1453,31 @@ export declare type SpreadsheetDataAdapter = {
      * (getCellText と同格、描画パスでも呼ばれるため)。未宣言 = 全セル編集可 = 従来挙動とバイト同一。
      */
     isCellReadOnly?: (row: number, col: number) => boolean;
+    /**
+     * OPTIONAL capability (v0.12): host-owned `data-*` attributes for one cell, merged verbatim
+     * onto the PACKAGE-OWNED cell element (`[data-aqsp-cell]`) so host CSS can target cell
+     * state, `:hover` and theme tokens without wrapper elements inside the cell. The package
+     * never interprets the values. Validated fail-fast at render (RangeError): the return must
+     * be a plain record or `null` (a JS host's `undefined` / array / Map is rejected by name,
+     * never a bare TypeError), every key must be a lowercase `data-*` name
+     * (`data-[a-z0-9-]+`), the package- and engine-emitted cell attributes (`data-aqsp*`,
+     * `data-aqvs*`, `data-row`, `data-col`) are reserved, and every value must be a string
+     * (React would otherwise stringify objects or drop `undefined` silently). Read once per
+     * painted cell per slice (the `getCellText` cost budget — keep it O(1)); publish changes
+     * via `dataVersion`. `null` = no extra attributes for this cell. Absence = the previous
+     * version's cell DOM byte-identically.
+     * 任意能力 (v0.12): セル 1 つへのホスト所有 `data-*` 属性 — パッケージ所有のセル要素
+     * (`[data-aqsp-cell]`) へそのまま載せる継ぎ目。セル内に器 (ラッパー要素) を敷かずにホスト
+     * CSS がセル状態・`:hover`・テーマトークンを掴むための口で、値の解釈はパッケージが
+     * 持たない。render 時 fail-fast 検証 (RangeError): 戻りはプレーンな record か `null`
+     * (JS ホストの `undefined` / 配列 / Map は名指しで拒否 — 生 TypeError にしない)、キーは
+     * 小文字 `data-*` (`data-[a-z0-9-]+`) のみ、パッケージ / エンジン放出のセル属性
+     * (`data-aqsp*` / `data-aqvs*` / `data-row` / `data-col`) は予約、値は string のみ (React の
+     * 暗黙文字列化や `undefined` の無言脱落を許さない)。描画セル毎・スライス毎に 1 読み
+     * (getCellText と同格の予算 — O(1) に保つ)。変更は dataVersion で公開。null = このセルに
+     * 追加属性なし。未宣言 = 従来のセル DOM とバイト同一。
+     */
+    getCellAttributes?: (row: number, col: number) => Readonly<Record<string, string>> | null;
     /**
      * OPTIONAL capability (v0.8): the numeric minimum / maximum over a range, for colorScale
      * rules whose end points omit `value`; null = the range holds no numeric value. Memoised by
@@ -1488,48 +1563,22 @@ export declare type SpreadsheetHandle = {
 
 /**
  * The `labels` prop shape: any subset of SpreadsheetLabels (an omitted or `undefined` key keeps
- * the default). Keys are closed to SpreadsheetLabels.
- * `labels` prop の形: SpreadsheetLabels の任意の部分集合 (省略 / undefined は既定のまま)。キーは
- * SpreadsheetLabels に閉じる。
+ * the catalog value of the chosen locale). Keys are closed to SpreadsheetLabels.
+ * `labels` prop の形: SpreadsheetLabels の任意の部分集合 (省略 / undefined は選択ロケールのカタログ値の
+ * まま)。キーは SpreadsheetLabels に閉じる。
  */
 export declare type SpreadsheetLabelOverrides = {
     readonly [K in keyof SpreadsheetLabels]?: SpreadsheetLabels[K];
 };
 
 /**
- * @fileoverview UI label vocabulary (v0.8 §1.6 / §4.1.17) — the ONE label bag of the package.
- * The v0.7 `sinkAriaLabel` / `rootAriaLabel` props are folded into it (clean cut-over: no alias
- * props remain), joined by the popover / indicator strings of the rich-cell UI. Pure, React-free.
- *
- * Contract (each clause is pinned by labels.spec.ts):
- * - `SpreadsheetLabels` is the closed key set; `DEFAULT_LABELS` supplies an English default for
- *   every key. Count-aware keys are typed `string | ((n: number) => string)`.
- * - `resolveLabels(overrides)` is the single fold point: a key takes its override when the
- *   override is not `undefined` and the default otherwise (exactly the destructuring-default
- *   semantics the two folded props had in v0.7), then `assertLabels` runs on the result.
- *   `undefined` overrides resolve to `DEFAULT_LABELS` by identity.
- * - `assertLabels`: `sinkAriaLabel` MUST be a string mentioning "Escape" (WCAG 2.1.2 escape-method
- *   advisement, spec 00 §10-4) — otherwise a RangeError, thrown at mount by the root.
- * - `resolveLabel(labels, key, n)` is the single read point: a function-valued label receives `n`
- *   (omitting `n` for a function value is a RangeError — never a silent 0), a string is returned
- *   as-is (`n` ignored, so a consumer may override a count key with a plain string).
- *
- * UI ラベル語彙 (v0.8 §1.6 / §4.1.17) — パッケージ唯一のラベル集合。v0.7 の `sinkAriaLabel` /
- * `rootAriaLabel` prop を畳み込み (クリーンカットオーバー: 別名 prop は残さない)、リッチセル UI の
- * ポップオーバー / インジケータ文言を加える。純関数・React 非依存。
- * 契約: `SpreadsheetLabels` は閉じたキー集合、`DEFAULT_LABELS` は全キーの英語既定、件数キーは
- * `string | ((n: number) => string)`。`resolveLabels` が唯一の畳込み点 (undefined でない override を
- * 採用、それ以外は既定 — 畳み込んだ 2 prop が v0.7 で持っていた分割代入既定と同じ意味論。
- * override 未指定は `DEFAULT_LABELS` を identity で返却) で、続けて `assertLabels`
- * (`sinkAriaLabel` は "Escape" を含む文字列であること — spec 00 §10-4、違反はマウント時 RangeError)。
- * `resolveLabel` が唯一の読み出し点 (関数値は n 必須 — 省略は RangeError、文字列はそのまま)。
- */
-/**
- * The closed label vocabulary. Every key has a default in DEFAULT_LABELS; consumers override any
- * subset through the `labels` prop (SpreadsheetLabelOverrides).
- * 閉じたラベル語彙。全キーが DEFAULT_LABELS に既定を持ち、消費者は `labels` prop で任意の部分集合を上書き。
- */
-export declare type SpreadsheetLabels = {
+ * The closed label vocabulary: the 7 engine chrome keys of `@aiquants/virtualscroll` plus the 21
+ * own keys of the spreadsheet. Every key has a value in each SPREADSHEET_LABEL_CATALOGS entry;
+ * consumers override any subset through the `labels` prop (SpreadsheetLabelOverrides).
+ * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクローム 7 キーとスプレッドシート固有の 21 キー。
+ * 全キーが SPREADSHEET_LABEL_CATALOGS の各ロケールに値を持ち、消費者は `labels` prop で任意の部分集合を上書き。
+ */
+export declare type SpreadsheetLabels = VirtualScrollLabels & {
     /** Accessible name of the sink (grid input receptor); MUST mention "Escape" (spec 00 §10-4). / シンクのアクセシブルネーム ("Escape" 必須)。 */
     sinkAriaLabel: string;
     /** Accessible name of the root role="group" landing point. / root 着地点のアクセシブルネーム。 */
@@ -1570,18 +1619,21 @@ export declare type SpreadsheetLabels = {
     listMore: string | ((n: number) => string);
     /** Message popover heading. / メッセージポップオーバーの見出し。 */
     messageTitle: string;
-    /** Message shown when a strict validation rule rejects the typed value. / 厳格検証で拒否されたときの文言。 */
-    validationRejected: string;
     /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
     popoverClose: string;
-    /** Accessible label of the note indicator on a cell. / ノートインジケータのラベル。 */
-    indicatorNote: string;
-    /** Accessible label of the comment indicator on a cell. / コメントインジケータのラベル。 */
-    indicatorComment: string;
-    /** Accessible label of the invalid-value indicator on a cell. / 無効値インジケータのラベル。 */
-    indicatorInvalid: string;
 };
 
+/**
+ * The UI chrome language of the spreadsheet ("en" | "ja") — the engine's locale set, so the grid
+ * body and the embedded scroll chrome always speak one language. A different axis from
+ * `formats.locale`, which is the BCP-47 locale of value formatting (numbers / dates); a BCP-47 tag
+ * such as "ja-JP" is NOT a SpreadsheetLocale.
+ * スプレッドシートの UI クローム言語 ("en" | "ja") — エンジンのロケール集合そのもので、グリッド本体と
+ * 埋込みスクロールクロームが常に同一言語。値書式 (数値 / 日付) の BCP-47 ロケールである
+ * `formats.locale` とは別軸 ("ja-JP" のような BCP-47 タグは SpreadsheetLocale ではない)。
+ */
+export declare type SpreadsheetLocale = VirtualScrollLocale;
+
 /**
  * Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
  * gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
@@ -1681,16 +1733,27 @@ export declare type SpreadsheetProps = {
     /**
      * 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).
+     * engine's one-frame rendering-window lag during fast scrolling (the blank-band remedy).
+     * Overscan counts ROWS — hidden 0-height rows consume slots too — so the px slack per edge
+     * is overscan × row height only where rows are uniform and visible. Undefined ⇒ the engine
+     * default (3). The engine does not validate overscan (a negative value silently shrinks the
+     * rendering window), so THIS surface owns the fail-fast: a non-integer or negative value
+     * throws a RangeError at render. Cost multiplies with the column axis, and the engine
+     * TRUNCATES rather than bounds: a window beyond its per-axis row budget or its total cell
+     * cap keeps the LEADING side and drops the trailing side — the row-budget case has no
+     * callback (the engine only logs a warning), the cell-cap case (columns dropped) reports
+     * through `onRenderTruncated`. Values of
+     * hundreds of rows per side approach that budget on tall viewports; keep overscan to the
+     * slack you need.
      * 行軸 overscan の素通し (VirtualGrid `overscanRows`。ライブ prop): 縦 viewport 端の外側へ
-     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策 —
-     * 余裕 px は片端あたり overscan × 行高)。undefined はエンジン既定 (3)。エンジンは不正値を
-     * 無言クランプするため fail-fast は本層所有 — 非整数・負値は render 時 RangeError。費用は
-     * 列軸との積で増幅 (エンジンのセル上限で有界)。
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策)。
+     * overscan は**行数**で数える (非表示の 0px 行も枠を消費) ため、片端の余裕 px が overscan ×
+     * 行高になるのは行が一様に可視のときだけ。undefined はエンジン既定 (3)。エンジンは overscan を
+     * 検証しない (負値は描画窓を無言で縮める) ため fail-fast は本層所有 — 非整数・負値は render 時
+     * RangeError。費用は列軸との積で増幅し、エンジンは有界化でなく**打切り**で応じる: 軸毎の行予算
+     * や総セル上限を超えた窓は先頭側を残し末尾側を落とす — 行予算超過はコールバック無し (エンジンは
+     * warn ログのみ)、セル上限超過 (列の脱落) は `onRenderTruncated` で通知。片側数百行の値は高い viewport で予算に迫るため、必要な
+     * 余裕にとどめる。
      */
     overscanRows?: number;
     /**
@@ -1707,18 +1770,55 @@ export declare type SpreadsheetProps = {
      * 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.
+     * not to row-aligned gridlines. The layer spans the full width of the scroll rows — the
+     * frozen-COLUMN region included (frozen columns live inside the scroll rows) — but not the
+     * frozen row bands. Identity-stable contract (same as `renderCell`): an inline element here
+     * pierces the GridBody memo boundary on every host re-render (the engine's render bodies
+     * re-run; cells stay memoized) — hoist the node or `useMemo` it.
      * スクロール帯行の背後・エンジンコンテンツ要素内に描画する背景レイヤー (VirtualGrid
      * `background` の素通し。ライブ prop)。viewport 固定: エンジンが translate するのは行
      * ラッパーだけで、この層はスクロール量に追従しない — 周期的な行罫線を置くとスクロール中に
      * 実際の行へ対して滑る。overscan が尽きた帯で「まだ到着中」と読める静的テクスチャ向きで、
-     * 行整合の罫線には不向き。
+     * 行整合の罫線には不向き。層はスクロール行の全幅 — 凍結**列**域を含む (凍結列はスクロール行の
+     * 内側に居る) — に広がり、凍結行帯には広がらない。identity 安定契約 (`renderCell` と同じ):
+     * インライン要素はホスト再レンダー毎に GridBody の memo 境界を貫通する (エンジンの render 本体が
+     * 再実行、セルは memo 維持) — ノードは hoist するか `useMemo` で保つ。
      */
     background?: ReactNode;
+    /**
+     * Rendering-truncation signal pass-through (the VirtualGrid `onRenderTruncated` callback):
+     * fires when the engine drops trailing columns to stay under its total cell cap
+     * (`MAX_RENDERED_CELLS`) — the cells actually rendered and the columns dropped. The engine's
+     * doctrine is that truncation is never silent; an oversized `overscanCols` × row span is the
+     * typical cause. Undefined ⇒ no callback (engine default).
+     * 描画打切り通知の素通し (VirtualGrid `onRenderTruncated`): エンジンが総セル上限
+     * (`MAX_RENDERED_CELLS`) を守るため末尾列を落としたときに、実描画セル数と脱落列数で発火する。
+     * 「打切りは無言にしない」がエンジン教義で、過大な `overscanCols` × 行スパンが典型原因。
+     * undefined = 通知なし (エンジン既定)。
+     */
+    onRenderTruncated?: (info: {
+        renderedCells: number;
+        droppedCols: number;
+    }) => void;
     /**
      * 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).
-     * identity 安定契約 — インライン関数は memo を無効化し毎レンダー全再スライスになる。
+     * Per-cell opt-out (v0.12): returning `undefined` from one cell lands that cell on the
+     * package default rendering (value-format engine included) — "custom where needed, default
+     * elsewhere" without wrapper elements. ONLY `undefined` opts out — `null`, `false` (the
+     * `cond && <X/>` idiom) and every other ReactNode are custom output, i.e. an empty custom
+     * cell. `ctx.text` is the RAW canonical string; `ctx.displayText` (v0.12) is the value-format
+     * display — the exact string the default rendering, the AT announcement, the HTML clipboard
+     * and autofit share, so a custom cell that renders it can never drift from what gets copied.
+     * Autofit stays a whole-grid no-op while `renderCell` is set (custom DOM width is unknowable).
+     * identity 安定契約 — インライン関数は memo を無効化し毎レンダー全再スライスになる。セル単位
+     * オプトアウト (v0.12): `undefined` を返したセルはパッケージ既定描画 (値書式エンジン込み) へ
+     * 降りる — 「要る列だけカスタム、残りは既定」を器なしで構成できる。オプトアウトは
+     * `undefined` **だけ** — `null` / `false` (`cond && <X/>` 慣用) / 他の ReactNode はカスタム
+     * 出力 (= 空のカスタムセル)。`ctx.text` は素の正準文字列、`ctx.displayText` (v0.12) は値書式の
+     * 表示文字列 — 既定描画・AT 読み上げ・HTML クリップボード・autofit と同一なので、これを描く
+     * カスタムセルはコピー結果と食い違わない。autofit は `renderCell` 指定中はグリッド全体
+     * no-op のまま (カスタム DOM の幅は測れない)。
      */
     renderCell?: (ctx: RenderCellContext) => ReactNode;
     /**
@@ -1726,11 +1826,16 @@ export declare type SpreadsheetProps = {
      * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
      * with ONE documented in-drag firing point: the header subtract reservation converts to a
      * real press on the first movement, firing the deferred press replace mid-drag (total fire
-     * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. Independent
-     * of the live region's 200ms debounce (firing point: the §6.9-1 setSelection wrapper).
+     * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. ONE host-driven
+     * fire point outside gestures (ADR-33): a same-adapter rowCount / colCount shrink that moved
+     * the selection fires once from a layout effect of that commit — not a user gesture.
+     * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
+     * wrapper).
      * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
      * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
-     * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。
+     * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。ジェスチャ外のホスト起点発火点が
+     * 1 つ (ADR-33): 同一 adapter の rowCount / colCount 縮小で選択が動いたとき、その commit の
+     * layout effect から 1 回発火する (ユーザー操作ではない)。
      */
     onSelectionChange?: (selection: SelectionState) => void;
     /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
@@ -1834,9 +1939,11 @@ export declare type SpreadsheetProps = {
     enableResizeUI?: boolean;
     /**
      * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
-     * is the RAW canonical getCellText; `displayText` is what a sighted user sees (the
+     * is the RAW canonical getCellText; `displayText` is the value-format display string (the
      * getCellFormat-formatted string — equals `text` when the cell has no format), so AT can
-     * hear "87.0%" for a cell whose raw value is "0.87". `readOnly` (v0.10) is
+     * hear "87.0%" for a cell whose raw value is "0.87". It is the same string a custom
+     * `renderCell` cell receives as `ctx.displayText` (v0.12) — what a sighted user sees unless
+     * the host deliberately renders something else. `readOnly` (v0.10) is
      * declaration-gated three-valued: the key is ABSENT when the adapter does not declare
      * `isCellReadOnly` (payload byte-identical to v0.9), `false` = declared editable, `true` =
      * declared read-only — the navigation-time read-only channel (DOM focus stays on the sink,
@@ -1874,14 +1981,30 @@ export declare type SpreadsheetProps = {
         command: SpreadsheetCommand;
         state: boolean | null;
     }) => string;
+    /**
+     * UI chrome language ("en" | "ja"; default "en"): selects the label catalog, the built-in
+     * data-validation messages, and is forwarded to the grid scrollbars (arrow labels,
+     * scroll-to-edge pills, "No items"). An unsupported value throws a RangeError during render —
+     * there is no language negotiation: hosts map `navigator.language` themselves. Unrelated to
+     * `formats.locale`, which is the BCP-47 value-formatting locale ("ja-JP" is NOT a valid value
+     * here).
+     * UI クローム言語 ("en" | "ja"、既定 "en"): ラベルカタログと組み込みデータ検証メッセージを選び、
+     * グリッドのスクロールバー (矢印ラベル・端スクロールピル・"No items") へ素通し。非対応値は render 中
+     * RangeError — 言語ネゴシエーションなし (`navigator.language` の写像はホスト側)。値書式の BCP-47
+     * ロケールである `formats.locale` とは無関係 ("ja-JP" はここでは不正値)。
+     */
+    locale?: SpreadsheetLocale;
     /**
      * UI label vocabulary (v0.8 §1.6) — folds the former `sinkAriaLabel` / `rootAriaLabel` props
-     * (clean cut-over). An omitted or explicitly `undefined` key keeps the English default. The
-     * resolved `sinkAriaLabel` MUST mention "Escape" (WCAG 2.1.2 escape advisement, §10-4) — a
-     * RangeError is thrown during render otherwise.
+     * (clean cut-over). 28 keys = the 7 engine chrome keys (scrollUp / scrollDown / scrollLeft /
+     * scrollRight / scrollToTop / scrollToBottom / noItems) + 21 own keys. An omitted prop or an
+     * explicitly `undefined` key keeps the value of the `locale` catalog. An unknown key or an
+     * empty / blank value throws a RangeError during render, and the resolved `sinkAriaLabel` MUST
+     * mention "Escape" (WCAG 2.1.2 escape advisement, §10-4).
      * UI ラベル語彙 (v0.8 §1.6) — 旧 sinkAriaLabel / rootAriaLabel prop を畳込み (クリーンカットオーバー)。
-     * 省略 / 明示 undefined は英語既定。解決後の sinkAriaLabel は "Escape" を含むこと (違反は render 中
-     * RangeError — §10-4)。
+     * 28 キー = エンジンクローム 7 キー (scrollUp / scrollDown / scrollLeft / scrollRight / scrollToTop /
+     * scrollToBottom / noItems) + 固有 21 キー。prop 省略 / 明示 undefined のキーは `locale` のカタログ値。
+     * 未知キー・空 / 空白値は render 中 RangeError、解決後の sinkAriaLabel は "Escape" を含むこと (§10-4)。
      */
     labels?: SpreadsheetLabelOverrides;
     /**
@@ -1948,7 +2071,7 @@ export declare type SpreadsheetProps = {
     onClipChange?: (clip: ClipInfo | null) => void;
     /** Hyperlink navigation seam (Alt+Enter, the link popover's Open button, and Ctrl / Meta+click on a link cell — spec 08 §11 D-53) — undeclared ⇒ no navigation, no Open button, no pointer gesture. / ハイパーリンク遷移シーム (Alt+Enter / Open ボタン / リンクセルへの Ctrl / Meta+クリック — 分冊 08 §11 D-53)。未宣言 = 遷移なし・Open ボタンなし・ポインタジェスチャなし。 */
     onHyperlinkOpen?: (url: string, cell: CellCoord) => void;
-    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。 */
+    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. `message` is `rule.errorMessage` when declared, otherwise the built-in message in the active `locale`. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。`message` は `rule.errorMessage` 宣言時はそれ、未宣言なら現在の `locale` の組み込みメッセージ。 */
     onValidationRejected?: (ctx: {
         cell: CellCoord;
         rule: DataValidationRule;
@@ -2022,6 +2145,15 @@ declare type SpreadsheetTestProps = {
      * では渡さない (未指定 = 呼出しゼロ — `__onCellRender` と同じ品行)。
      */
     __onVirtualKeyboardRaise?: () => void;
+    /**
+     * Test-only rendered-cell cap forwarded to the engine's `__maxRenderedCells` seam so the
+     * `onRenderTruncated` pass-through can be pinned without materializing 32,768 cells. Never
+     * passed in production (unset = the engine's MAX_RENDERED_CELLS — the `__onCellRender` conduct).
+     * テスト専用の描画セル上限 (エンジンの `__maxRenderedCells` シームへ素通し) — `onRenderTruncated`
+     * 素通しを 32,768 セルの実体化なしでピンするため。production では渡さない (未指定 = エンジンの
+     * MAX_RENDERED_CELLS — `__onCellRender` と同じ品行)。
+     */
+    __maxRenderedCells?: number;
 };
 
 export { TapScrollCircleRenderProps }
@@ -2060,65 +2192,30 @@ export declare type TextValidationRule = {
 export declare const toR1C1: (formula: string, origin: CellCoord) => string;
 
 /**
- * Validates committed text against a rule. Blank always passes; `custom` is evaluated only when
- * the caller passes `evaluate` (commit time — paint omits it); an incomplete rule (unparseable
- * bound, missing `b` / `value`) is inert; a rule outside the vocabulary throws RangeError.
- * Message = `rule.errorMessage` when set, else a built-in English summary of the rule.
- * 確定テキストの規則検証。空文字は常に合格、custom は呼び手が evaluate を渡すとき (確定時 — 描画は
- * 渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は不活性、語彙外の規則は
- * RangeError。メッセージは errorMessage があればそれ、無ければ組込みの英語要約。
- */
-export declare const validateCellText: (rule: DataValidationRule, text: string, evaluate?: ValidationEvaluate) => ValidationVerdict;
-
-/**
- * @fileoverview Data-validation rule vocabulary and the pure verdict engine (v0.8 — the
- * getCellValidation capability, ADR-13). The consumer declares a per-cell DataValidationRule
- * via the optional adapter capability getCellValidation(row, col); the editor asks
- * validateCellText at COMMIT (passing the adapter's formula evaluator for `custom` rules) and
- * the grid asks isVisiblyInvalid at PAINT (never evaluating a formula) to draw the invalid
- * indicator. React-free and total.
- *
- * Engine contract (each clause is load-bearing and mutation-gated — spec 01 §8.3):
- * - BLANK IS ALWAYS VALID: the empty string satisfies every rule (Excel "ignore blank"), so a
- *   validated cell can always be cleared; `custom` is not even evaluated for a blank.
- * - EXACT decimal comparison for `number` rules: the cell text and both bounds are parsed with
- *   the SAME strict-decimal grammar as cellFormat.ts (`[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d{1,4})?`,
- *   trimmed, no hex / grouping / ±Infinity) and compared as normalised sign / significant-digit /
- *   point-position triples — never through a binary double — so "9007199254740993" is greater
- *   than "9007199254740992" and "0.30000000000000004" is not equal to "0.3".
- * - TIMEZONE-FREE dates for `date` rules: the pure-calendar grammar of cellFormat.ts
- *   ("YYYY-MM-DD[ T HH:mm[:ss]]" or "/" separated, leap-aware ranges, no Date object), compared
- *   as (year, month, day, hour, minute, second) tuples; `between` / `notBetween` are inclusive.
- * - INERT INCOMPLETE RULES: a bound that does not parse (`a` / `b` for number / date, a
- *   non-finite `a` / `b` for textLength, a missing `b` for between / notBetween, a missing `value`
- *   for the needle text ops) makes the rule accept everything — a half-written rule never locks a
- *   cell. Bounds are never swapped: `between 10 and 5` accepts nothing but blank.
- * - FAIL-FAST on a rule OUTSIDE the vocabulary: an unknown `type` or `op` is a consumer bug and
- *   throws RangeError regardless of the text (fail-soft would silently disable validation).
- * - INTERNED list Sets per rule object (WeakMap identity), so the paint-time `list` check is O(1)
- *   even for a 10k-item list; a fresh rule object interns a fresh Set.
- * - MESSAGE resolution: `errorMessage` when the consumer set it (an empty string is honoured as
- *   is), else a built-in English summary of the rule.
- * - `custom` needs the caller's `evaluate`; without it the rule is not evaluated (verdict ok), and
- *   truth = `true` or a finite non-zero number (the conditionalFormat customFormula convention).
- * - Matching is exact (case-sensitive, untrimmed) for `list` / `text` / `checkbox`; textLength
- *   counts Unicode code points. `isEmail` is the WHATWG valid-e-mail grammar with a mandatory
- *   dotted domain; `isUrl` is a WHATWG-parsable absolute http(s) URL.
+ * Validates committed text against a rule. The locale is checked FIRST (before the rule and the
+ * text), so an unsupported locale fails fast even for a passing text — this pure function has no
+ * hidden default locale. Blank always passes; `custom` is evaluated only when the caller passes
+ * `evaluate` (commit time — paint omits it); an incomplete rule (unparseable bound, missing `b` /
+ * `value`) is inert; a rule outside the vocabulary throws RangeError. Message = `rule.errorMessage`
+ * when set (the empty string included), else the built-in summary in the given locale.
+ * 確定テキストの規則検証。ロケールを最初に (規則と text より前に) 検査するため、非対応ロケールは
+ * 合格する text でも fail-fast (純関数に隠れた既定ロケールは無い)。空文字は常に合格、custom は呼び手が
+ * evaluate を渡すとき (確定時 — 描画は渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は
+ * 不活性、語彙外の規則は RangeError。メッセージは errorMessage があればそれ (空文字も含む)、無ければ
+ * 指定ロケールの組込み要約。
  *
- * データ検証の規則語彙と純関数の判定エンジン (v0.8 — getCellValidation 能力、ADR-13)。
- * consumer が任意能力 getCellValidation(row, col) で規則を宣言し、エディタが確定時に
- * validateCellText (custom 規則にはアダプタの数式評価器を渡す)、グリッドが描画時に
- * isVisiblyInvalid (数式は決して評価しない) を呼んで不正インジケータを描く。React 非依存・全域関数。
- * エンジン契約 (全て変異検証で封印 — spec 01 §8.3): 空文字は常に有効 (Excel の「空白を無視」—
- * 検証セルは必ず消去できる、custom も評価しない)、number は cellFormat.ts と同じ厳密 10 進文法で
- * 符号 / 有効数字 / 小数点位置の正規形として正確比較 (double 非経由)、date は Date 非依存の純暦文法を
- * タプル比較 (between は両端含み)、不完全な規則 (解釈不能な境界・between の b 欠落・needle 欠落) は
- * 不活性 = 全受理 (書きかけの規則でセルを閉じ込めない、境界の入替もしない)、語彙外の type / op は
- * consumer バグとして text に依らず RangeError、list の Set は規則 object 毎に WeakMap intern、
- * メッセージは errorMessage (空文字も尊重) が無ければ組込みの英語要約、custom は evaluate 無しなら
- * 未評価 (ok)・真 = true か有限非 0 数、照合は完全一致 (大文字小文字区別・trim 無し)、textLength は
- * コードポイント数、isEmail は WHATWG 文法 + ドット付きドメイン必須、isUrl は WHATWG 絶対 http(s) URL。
- */
+ * @param rule - The cell's data-validation rule / セルのデータ検証規則
+ * @param text - The committed text / 確定テキスト
+ * @param locale - The UI chrome locale of the built-in message ("en" | "ja"; required) / 組込みメッセージの UI クロームロケール ("en" | "ja"、必須)
+ * @param evaluate - The consumer's formula evaluator for `custom` rules (omit to leave them unevaluated) / custom 規則用の consumer の数式評価器 (省略で未評価)
+ * @returns The frozen shared ok verdict, or a rejection carrying the resolved message / 共有の凍結 ok 判定、または解決済みメッセージ付きの拒否
+ * @throws {RangeError} When `locale` is not a supported SpreadsheetLocale (`undefined`, `null`,
+ * `"EN"`, `"ja-JP"`, ...), or the rule's `type` / `op` is outside the vocabulary / `locale` が
+ * 対応 SpreadsheetLocale でない場合 (`undefined`、`null`、`"EN"`、`"ja-JP"` など)、または規則の
+ * type / op が語彙外の場合
+ */
+export declare const validateCellText: (rule: DataValidationRule, text: string, locale: SpreadsheetLocale, evaluate?: ValidationEvaluate) => ValidationVerdict;
+
 /** Ordered comparison vocabulary shared by number / textLength / date rules; between / notBetween include both bounds. / number / textLength / date 規則が共有する比較語彙。between / notBetween は両端含み。 */
 export declare type ValidationCompareOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "notBetween";