@aiquants/spreadsheet 0.11.0 → 0.13.0

package/src/model/labels.ts

@@ -1,38 +1,71 @@
 /**
- * @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.
+ * @fileoverview UI label vocabulary (v0.8 §1.6 / §4.1.17) — the ONE label bag of the package, now
+ * per UI chrome locale ("en" default, "ja" second). The v0.7 `sinkAriaLabel` / `rootAriaLabel`
+ * props are folded into it (clean cut-over: no alias props remain), joined by the popover strings
+ * of the rich-cell UI and by the seven engine chrome strings of `@aiquants/virtualscroll`
+ * (scroll arrows, scroll-to-edge pills, "No items"), which are REUSED from
+ * `VIRTUAL_SCROLL_LABEL_CATALOGS` and never re-typed here. 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
+ * - `SpreadsheetLocale` is the engine's locale set (`VirtualScrollLocale`); it is the UI chrome
+ *   language and a different axis from `formats.locale` (BCP-47 value formatting).
+ * - `SpreadsheetLabels` is the closed 28-key set (7 engine keys + 21 own keys);
+ *   `SPREADSHEET_LABEL_CATALOGS` supplies a frozen catalog per locale. Count-aware keys are typed
+ *   `string | ((n: number) => string)`.
+ * - `resolveLabels(locale, overrides)` is the single fold point: the locale is resolved by
+ *   `resolveVirtualScrollLocale` (undefined ⇒ "en", unknown ⇒ RangeError); `undefined` overrides
+ *   return the catalog by identity; otherwise the overrides must be a plain object (prototype
+ *   `Object.prototype` or `null`) read by own properties only, unknown keys are a RangeError, the engine subset is
+ *   resolved by `resolveVirtualScrollLabels` and an own key takes its override when it is not
+ *   `undefined`, then `assertLabels` runs on the result, which is frozen.
+ * - `assertLabels`: every non-count own key is a non-blank string, a count key is a non-blank
+ *   string or a function, and `sinkAriaLabel` MUST mention "Escape" (WCAG 2.1.2 escape-method
  *   advisement, spec 00 §10-4) — otherwise a RangeError, thrown at mount by the root.
+ * - `pickEngineLabels(labels)` hands the 7 engine keys to the embedded VirtualGrid.
  * - `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、文字列はそのまま)。
+ * UI ラベル語彙 (v0.8 §1.6 / §4.1.17) — パッケージ唯一のラベル集合で、UI クロームロケール別
+ * ("en" が既定、"ja" が第 2 ロケール)。v0.7 の `sinkAriaLabel` / `rootAriaLabel` prop を畳み込み
+ * (クリーンカットオーバー: 別名 prop は残さない)、リッチセル UI のポップオーバー文言と
+ * `@aiquants/virtualscroll` の 7 つのエンジンクローム文言 (スクロール矢印、端スクロールピル、
+ * "No items") を加える。エンジン文言は `VIRTUAL_SCROLL_LABEL_CATALOGS` を再利用し、ここでは再記述
+ * しない。純関数・React 非依存。
+ * 契約: `SpreadsheetLocale` はエンジンのロケール集合 (UI クローム言語で、値書式の `formats.locale`
+ * とは別軸)。`SpreadsheetLabels` は閉じた 28 キー (エンジン 7 + 固有 21)、`SPREADSHEET_LABEL_CATALOGS`
+ * はロケール別の凍結カタログ、件数キーは `string | ((n: number) => string)`。`resolveLabels` が唯一の
+ * 畳込み点 (ロケールは `resolveVirtualScrollLocale` で解決 — undefined は "en"、未知は RangeError。
+ * override 未指定はカタログを identity で返却。それ以外は override を素の object (プロトタイプが
+ * `Object.prototype` か `null`) に限り自身のプロパティだけを読み、未知キーを RangeError、エンジン部分は
+ * `resolveVirtualScrollLabels` で解決、固有キーは undefined でない override を採用し、`assertLabels`
+ * 検証の後に凍結)。`assertLabels` は固有キーの非空白文字列性 (件数キーは関数も可) と
+ * `sinkAriaLabel` の "Escape" 告知 (spec 00 §10-4) を検証し、違反はマウント時 RangeError。
+ * `pickEngineLabels` は埋込み VirtualGrid へ渡すエンジン 7 キーの抽出。`resolveLabel` が唯一の
+ * 読み出し点 (関数値は n 必須 — 省略は RangeError、文字列はそのまま)。
  */
 
+import { resolveVirtualScrollLabels, resolveVirtualScrollLocale, VIRTUAL_SCROLL_LABEL_CATALOGS, VIRTUAL_SCROLL_LABEL_KEYS, type VirtualScrollLabelOverrides, type VirtualScrollLabels, type VirtualScrollLocale } from "@aiquants/virtualscroll"
+
+/**
+ * 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 type SpreadsheetLocale = VirtualScrollLocale
+
 /**
- * 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 で任意の部分集合を上書き。
+ * 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 type SpreadsheetLabels = {
+export 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 着地点のアクセシブルネーム。 */
@@ -73,32 +106,24 @@ export 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 `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 type SpreadsheetLabelOverrides = { readonly [K in keyof SpreadsheetLabels]?: SpreadsheetLabels[K] }
 
 /**
- * Every label key, in declaration order — the iteration source of the fold and the census list
- * for docs / tests. Compile-time proof below that it covers EVERY SpreadsheetLabels key.
- * 全ラベルキー (宣言順) — 畳込みの走査元と docs / テストの census 表。直下で全キー網羅を型水準で証明。
+ * The 21 own (non-engine) keys, in declaration order — the iteration source of the own-key fold and
+ * of assertLabels.
+ * 固有 (エンジン外) の 21 キー (宣言順) — 固有キー畳込みと assertLabels の走査元。
  */
-export const LABEL_KEYS = [
+const OWN_LABEL_KEYS = [
     "sinkAriaLabel",
     "rootAriaLabel",
     "noteTitle",
@@ -119,93 +144,256 @@ export const LABEL_KEYS = [
     "listEmpty",
     "listMore",
     "messageTitle",
-    "validationRejected",
     "popoverClose",
-    "indicatorNote",
-    "indicatorComment",
-    "indicatorInvalid",
 ] as const satisfies readonly (keyof SpreadsheetLabels)[]
 
+/**
+ * Every label key: the 7 engine keys (VIRTUAL_SCROLL_LABEL_KEYS, in engine order) followed by the
+ * 21 own keys — the closed key set that overrides are validated against, and the census list for
+ * docs / tests. Compile-time proofs below that it covers EVERY SpreadsheetLabels key and that the
+ * own keys never shadow an engine key.
+ * 全ラベルキー: エンジン 7 キー (VIRTUAL_SCROLL_LABEL_KEYS、エンジン順) に固有 21 キーを続けたもの —
+ * override 検証の閉じたキー集合で docs / テストの census 表。直下で全キー網羅と、固有キーが
+ * エンジンキーを覆い隠さないことを型水準で証明。
+ */
+export const LABEL_KEYS = [...VIRTUAL_SCROLL_LABEL_KEYS, ...OWN_LABEL_KEYS] as const satisfies readonly (keyof SpreadsheetLabels)[]
+
 /** Compile-time proof that LABEL_KEYS lists EVERY SpreadsheetLabels key (a key added to the type but not to the list would never be folded). / LABEL_KEYS が SpreadsheetLabels の全キーを網羅することの型水準の証明 (型に増えたキーが表に無いと畳込みから漏れる)。 */
 const labelKeysCoverEveryKey: [Exclude<keyof SpreadsheetLabels, (typeof LABEL_KEYS)[number]>] extends [never] ? true : never = true
 void labelKeysCoverEveryKey
 
+/** Compile-time proof that no own key is also an engine key (an overlap would let the own-key fold bypass the engine's validation of that key). / 固有キーがエンジンキーと重ならないことの型水準の証明 (重なると固有キー畳込みがそのキーのエンジン検証を迂回する)。 */
+const ownLabelKeysAreDisjointFromEngine: [Extract<(typeof OWN_LABEL_KEYS)[number], keyof VirtualScrollLabels>] extends [never] ? true : never = true
+void ownLabelKeysAreDisjointFromEngine
+
 /**
- * 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 const DEFAULT_LABELS: SpreadsheetLabels = Object.freeze({
-    sinkAriaLabel: "Spreadsheet grid. Press Escape to move focus out of the grid.",
-    rootAriaLabel: "Spreadsheet",
-    noteTitle: "Note",
-    noteSave: "Save",
-    noteEscapeHint: "Escape saves and closes",
-    noteRejectedHint: "The note was rejected. Press Ctrl+Enter to retry or Escape to close without saving",
-    noteViewerHint: "Escape closes without saving",
-    commentTitle: "Comments",
-    commentReply: "Reply",
-    commentPost: "Post",
-    commentCount: (n: number): string => (n === 1 ? "1 comment" : `${n} comments`),
-    linkTitle: "Link",
-    linkTextField: "Text",
-    linkUrlField: "URL",
-    linkOpen: "Open",
-    linkSave: "Save",
-    listTitle: "Choose a value",
-    listEmpty: "No matching values",
-    listMore: (n: number): string => (n === 1 ? "1 more value — keep typing to narrow" : `${n} more values — keep typing to narrow`),
-    messageTitle: "Data validation",
-    validationRejected: "The value does not satisfy this cell's validation rule",
-    popoverClose: "Close",
-    indicatorNote: "Has a note",
-    indicatorComment: "Has comments",
-    indicatorInvalid: "Invalid value",
+ * Per-locale values of the 21 own keys. `en` is byte-identical to the pre-i18n English defaults
+ * (`sinkAriaLabel` / `rootAriaLabel` equal the v0.7 prop defaults, so the fold is DOM-identical);
+ * `commentCount` / `listMore` pluralise in `en` and use the counter 件 in `ja`. Frozen.
+ * 固有 21 キーのロケール別の値。`en` は i18n 化前の英語既定と byte 同一 (`sinkAriaLabel` /
+ * `rootAriaLabel` は v0.7 の prop 既定と同じで畳込みは DOM 恒等)、`commentCount` / `listMore` は
+ * `en` で単複を区別し `ja` では助数詞「件」。凍結済み。
+ */
+const OWN_LABEL_CATALOGS: Readonly<Record<SpreadsheetLocale, Omit<SpreadsheetLabels, keyof VirtualScrollLabels>>> = Object.freeze({
+    en: Object.freeze({
+        sinkAriaLabel: "Spreadsheet grid. Press Escape to move focus out of the grid.",
+        rootAriaLabel: "Spreadsheet",
+        noteTitle: "Note",
+        noteSave: "Save",
+        noteEscapeHint: "Escape saves and closes",
+        noteRejectedHint: "The note was rejected. Press Ctrl+Enter to retry or Escape to close without saving",
+        noteViewerHint: "Escape closes without saving",
+        commentTitle: "Comments",
+        commentReply: "Reply",
+        commentPost: "Post",
+        commentCount: (n: number): string => (n === 1 ? "1 comment" : `${n} comments`),
+        linkTitle: "Link",
+        linkTextField: "Text",
+        linkUrlField: "URL",
+        linkOpen: "Open",
+        linkSave: "Save",
+        listTitle: "Choose a value",
+        listEmpty: "No matching values",
+        listMore: (n: number): string => (n === 1 ? "1 more value — keep typing to narrow" : `${n} more values — keep typing to narrow`),
+        messageTitle: "Data validation",
+        popoverClose: "Close",
+    }),
+    ja: Object.freeze({
+        sinkAriaLabel: "スプレッドシートのグリッド。Escape キーでグリッドの外へフォーカスを移動します。",
+        rootAriaLabel: "スプレッドシート",
+        noteTitle: "メモ",
+        noteSave: "保存",
+        noteEscapeHint: "Escape で保存して閉じます",
+        noteRejectedHint: "メモは拒否されました。Ctrl+Enter で再試行、Escape で保存せずに閉じます",
+        noteViewerHint: "Escape で保存せずに閉じます",
+        commentTitle: "コメント",
+        commentReply: "返信",
+        commentPost: "投稿",
+        commentCount: (n: number): string => `${n} 件のコメント`,
+        linkTitle: "リンク",
+        linkTextField: "表示テキスト",
+        linkUrlField: "URL",
+        linkOpen: "開く",
+        linkSave: "保存",
+        listTitle: "値を選択",
+        listEmpty: "一致する値がありません",
+        listMore: (n: number): string => `ほかに ${n} 件 — 入力して絞り込んでください`,
+        messageTitle: "データの入力規則",
+        popoverClose: "閉じる",
+    }),
 })
 
 /**
- * Mount-time check of a resolved label bag: `sinkAriaLabel` must be a string that mentions
- * "Escape" (case-sensitive — the WCAG 2.1.2 escape-method advisement of spec 00 §10-4). Anything
- * else is a consumer configuration error ⇒ RangeError (fail-fast, never silently repaired).
- * 解決済みラベル集合のマウント時検証: `sinkAriaLabel` は "Escape" を含む文字列であること
- * (大文字小文字を区別 — spec 00 §10-4 の WCAG 2.1.2 脱出告知)。それ以外は消費者の設定誤りとして
- * RangeError (fail-fast、黙って修復しない)。
+ * 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 const SPREADSHEET_LABEL_CATALOGS: Readonly<Record<SpreadsheetLocale, SpreadsheetLabels>> = Object.freeze({
+    en: Object.freeze({ ...VIRTUAL_SCROLL_LABEL_CATALOGS.en, ...OWN_LABEL_CATALOGS.en }),
+    ja: Object.freeze({ ...VIRTUAL_SCROLL_LABEL_CATALOGS.ja, ...OWN_LABEL_CATALOGS.ja }),
+})
+
+/**
+ * Describes a rejected value for a RangeError message without ever throwing: a JSON string for
+ * strings, "null" for `null`, otherwise the typeof name. It never calls `String()` /
+ * `JSON.stringify` on an arbitrary value, so BigInt, Symbol, function and null-prototype inputs
+ * still produce the documented RangeError with an accurate description. The ONE describer of every
+ * label and data-validation RangeError message of the package (assertLabels, resolveLabels,
+ * validateCellText's locale and rule-shape checks).
+ * RangeError メッセージ用の拒否値の説明 (例外を投げない): 文字列は JSON 表現、`null` は "null"、それ以外は
+ * typeof 名。任意値へ `String()` / `JSON.stringify` を適用しないため、BigInt・Symbol・関数・null プロトタイプの
+ * 入力でも文書どおりの RangeError と正確な説明を維持。パッケージのラベル / データ検証の全 RangeError
+ * メッセージ (assertLabels、resolveLabels、validateCellText のロケール検査と規則形状検査) の唯一の説明器。
+ *
+ * @param value - The rejected value / 拒否された値
+ * @returns A printable, non-throwing description / 表示用の説明文字列 (例外なし)
+ */
+export const describeLabelValue = (value: unknown): string => {
+    if (typeof value === "string") {
+        return JSON.stringify(value)
+    }
+    return value === null ? "null" : typeof value
+}
+
+/**
+ * Whether a label key is count-aware (`commentCount` / `listMore`), i.e. may hold a function.
+ * ラベルキーが件数キー (`commentCount` / `listMore`) — 関数値を許すキー — かどうか。
+ *
+ * @param key - The own label key / 固有ラベルキー
+ * @returns `true` for a count-aware key / 件数キーなら `true`
+ */
+const isCountLabelKey = (key: (typeof OWN_LABEL_KEYS)[number]): key is "commentCount" | "listMore" => key === "commentCount" || key === "listMore"
+
+/**
+ * Mount-time check of a resolved label bag's own keys (the 7 engine keys are validated by
+ * `resolveVirtualScrollLabels`): `sinkAriaLabel` must be a string that mentions "Escape"
+ * (case-sensitive — the WCAG 2.1.2 escape-method advisement of spec 00 §10-4); every other
+ * non-count own key must be a string with non-whitespace content; `commentCount` / `listMore` must
+ * be such a string or a function. Anything else is a consumer configuration error ⇒ RangeError
+ * naming the key (fail-fast, never silently repaired).
+ * 解決済みラベル集合の固有キーのマウント時検証 (エンジン 7 キーは `resolveVirtualScrollLabels` が検証):
+ * `sinkAriaLabel` は "Escape" を含む文字列 (大文字小文字を区別 — spec 00 §10-4 の WCAG 2.1.2 脱出告知)、
+ * その他の件数以外の固有キーは空白以外を含む文字列、`commentCount` / `listMore` はその文字列か関数で
+ * あること。それ以外は消費者の設定誤りとしてキー名入りの RangeError (fail-fast、黙って修復しない)。
+ *
+ * @param labels - The resolved label bag / 解決済みラベル集合
+ * @returns Nothing; returns normally when every own key is valid / なし (全固有キーが妥当なら正常終了)
+ * @throws {RangeError} When an own key violates its rule / 固有キーが規則に違反した場合
  */
 export const assertLabels = (labels: SpreadsheetLabels): void => {
-    const sink = labels.sinkAriaLabel
-    // 文字列以外 (JS 呼び手) と Escape 告知の欠落は同じ設定誤り
+    const sink: unknown = labels.sinkAriaLabel
+    // 文字列以外 (JS 呼び手) と Escape 告知の欠落は同じ設定誤り — 既存メッセージを保つため汎用検査より先に判定
     if (typeof sink !== "string" || !sink.includes("Escape")) {
-        throw new RangeError(`[spreadsheet] labels.sinkAriaLabel must be a string mentioning "Escape" (WCAG 2.1.2 escape advisement, spec 00 §10-4); got ${JSON.stringify(sink)}`)
+        throw new RangeError(`[spreadsheet] labels.sinkAriaLabel must be a string mentioning "Escape" (WCAG 2.1.2 escape advisement, spec 00 §10-4); got ${describeLabelValue(sink)}`)
+    }
+    for (const key of OWN_LABEL_KEYS) {
+        const value: unknown = labels[key]
+        if (isCountLabelKey(key) && typeof value === "function") {
+            continue
+        }
+        // 空白だけの文字列は描画上は空のアクセシブルネーム / 見出しになるため空文字列と同じ誤り
+        if (typeof value !== "string" || value.trim() === "") {
+            const expected = isCountLabelKey(key) ? "a non-blank string or a function" : "a non-blank string"
+            throw new RangeError(`[spreadsheet] labels.${key} must be ${expected}; got ${describeLabelValue(value)}`)
+        }
     }
 }
 
-/** Writes one resolved label; generic so the union-typed key of the fold loop type-checks against the per-key value type. / 解決済みラベルを 1 件書く (畳込みループの union キーをキー毎の値型と突き合わせるための総称関数)。 */
-const putLabel = <K extends keyof SpreadsheetLabels>(target: SpreadsheetLabels, key: K, value: SpreadsheetLabels[K]): void => {
+/**
+ * Copies the engine subset of an overrides object (only the OWN keys of VIRTUAL_SCROLL_LABEL_KEYS
+ * whose value is not `undefined` — an inherited property is never read); `undefined` when none is
+ * present, so the engine returns its catalog by identity.
+ * override のエンジン部分 (VIRTUAL_SCROLL_LABEL_KEYS のうち値が undefined でない自身のキーのみ —
+ * 継承プロパティは読まない) の複製。1 つも無ければ `undefined` (エンジンがカタログを identity で返すため)。
+ *
+ * @param overrides - The consumer's overrides / 消費者の上書き
+ * @returns The engine overrides, or `undefined` when none is present / エンジン上書き (無ければ `undefined`)
+ */
+const pickEngineOverrides = (overrides: SpreadsheetLabelOverrides): VirtualScrollLabelOverrides | undefined => {
+    const picked: { -readonly [K in keyof VirtualScrollLabels]?: VirtualScrollLabels[K] } = {}
+    let present = false
+    for (const key of VIRTUAL_SCROLL_LABEL_KEYS) {
+        // Object.prototype 汚染で継承されたラベルキーを上書きとして拾わない
+        const value = Object.hasOwn(overrides, key) ? overrides[key] : undefined
+        if (value !== undefined) {
+            picked[key] = value
+            present = true
+        }
+    }
+    return present ? picked : undefined
+}
+
+/**
+ * Writes one resolved own label; generic so the union-typed key of the fold loop type-checks
+ * against the per-key value type.
+ * 解決済みの固有ラベルを 1 件書く (畳込みループの union キーをキー毎の値型と突き合わせるための総称関数)。
+ *
+ * @param target - The label bag under construction / 構築中のラベル集合
+ * @param key - The own key to write / 書き込む固有キー
+ * @param value - The value to write / 書き込む値
+ * @returns Nothing / なし
+ */
+const putLabel = <K extends (typeof OWN_LABEL_KEYS)[number]>(target: SpreadsheetLabels, key: K, value: SpreadsheetLabels[K]): void => {
     target[key] = value
 }
 
 /**
- * The single fold point of the `labels` prop: every key takes the override when it is not
- * `undefined`, the default otherwise (destructuring-default semantics of the folded v0.7 props);
- * the result is validated by assertLabels and frozen. `undefined` overrides return DEFAULT_LABELS
- * by identity. Inputs are never mutated.
- * `labels` prop の唯一の畳込み点: 各キーは override が undefined でなければ override、さもなくば
- * 既定 (畳み込んだ v0.7 prop の分割代入既定の意味論)。結果は assertLabels で検証し凍結。override
- * 未指定は DEFAULT_LABELS を identity で返す。入力は変更しない。
+ * 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 const resolveLabels = (overrides: SpreadsheetLabelOverrides | undefined): SpreadsheetLabels => {
-    // override なしは既定そのもの (identity 安定 — 消費者の useMemo 再計算でも同一 object)
+export const resolveLabels = (locale: SpreadsheetLocale | undefined, overrides: SpreadsheetLabelOverrides | undefined): SpreadsheetLabels => {
+    const resolvedLocale = resolveVirtualScrollLocale(locale)
+    // override なしはカタログそのもの (identity 安定 — 消費者の useMemo 再計算でも同一 object)
     if (overrides === undefined) {
-        return DEFAULT_LABELS
+        return SPREADSHEET_LABEL_CATALOGS[resolvedLocale]
+    }
+    if (overrides === null || typeof overrides !== "object") {
+        throw new RangeError(`[spreadsheet] labels must be an object; got ${describeLabelValue(overrides)}`)
+    }
+    // 既知キー検査は自身のキーしか見ないため、継承経路を持つ入力 (配列・クラスインスタンス・
+    // 他 object 継承) を許すと継承側の綴り誤りが無言で無視される
+    const prototype: unknown = Object.getPrototypeOf(overrides)
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new RangeError(`[spreadsheet] labels must be a plain object (prototype Object.prototype or null); got ${Array.isArray(overrides) ? "an array" : "an object with a non-plain prototype"}`)
     }
-    const resolved: SpreadsheetLabels = { ...DEFAULT_LABELS }
-    // 明示 undefined は「未指定」= 既定のまま (分割代入既定と同じ)
-    for (const key of LABEL_KEYS) {
-        const value = overrides[key]
+    // 未知キーを黙って捨てると削除済みキーや綴り誤りの設定が無言で効かなくなる
+    for (const key of Object.keys(overrides)) {
+        if (!(LABEL_KEYS as readonly string[]).includes(key)) {
+            throw new RangeError(`[spreadsheet] labels.${key} is not a known label key; expected one of ${LABEL_KEYS.join(", ")}`)
+        }
+    }
+    const engine = resolveVirtualScrollLabels(resolvedLocale, pickEngineOverrides(overrides))
+    const resolved: SpreadsheetLabels = { ...engine, ...OWN_LABEL_CATALOGS[resolvedLocale] }
+    // 明示 undefined は「未指定」= カタログ値のまま (分割代入既定と同じ)
+    for (const key of OWN_LABEL_KEYS) {
+        // Object.prototype 汚染で継承されたラベルキーを上書きとして拾わない
+        const value = Object.hasOwn(overrides, key) ? overrides[key] : undefined
         if (value !== undefined) {
             putLabel(resolved, key, value)
         }
@@ -214,12 +402,36 @@ export const resolveLabels = (overrides: SpreadsheetLabelOverrides | undefined):
     return Object.freeze(resolved)
 }
 
+/**
+ * Extracts the 7 engine chrome keys of a resolved label bag as a new frozen VirtualScrollLabels
+ * object — the `labels` handed to the embedded VirtualGrid.
+ * 解決済みラベル集合からエンジンクローム 7 キーを新しい凍結 VirtualScrollLabels object として抽出 —
+ * 埋込み VirtualGrid へ渡す `labels`。
+ *
+ * @param labels - The resolved label bag / 解決済みラベル集合
+ * @returns A new frozen object holding exactly the 7 engine keys / エンジン 7 キーだけを持つ新しい凍結 object
+ */
+export const pickEngineLabels = (labels: SpreadsheetLabels): VirtualScrollLabels => {
+    const engine: { -readonly [K in keyof VirtualScrollLabels]?: VirtualScrollLabels[K] } = {}
+    for (const key of VIRTUAL_SCROLL_LABEL_KEYS) {
+        engine[key] = labels[key]
+    }
+    // ループは VIRTUAL_SCROLL_LABEL_KEYS 全件を書くため (網羅はエンジン側の型証明が保証) 全キー存在が確定
+    return Object.freeze(engine as VirtualScrollLabels)
+}
+
 /**
  * The single read point: resolves one label to its display string. A function-valued label is
  * called with `n` (a missing `n` is a caller bug ⇒ RangeError — no silent 0); a string label is
  * 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 const resolveLabel = (labels: SpreadsheetLabels, key: keyof SpreadsheetLabels, n?: number): string => {
     const value = labels[key]