@aiquants/spreadsheet 0.11.0 → 0.13.0

package/src/grid/GridBody.tsx

@@ -28,6 +28,10 @@
  * helper (ADR-31 — no package CSS; capability absent ⇒ O(1) false ⇒ keys absent ⇒ the DOM
  * stays byte-identical).
  *
+ * UI chrome locale: the resolved `locale` and the value-stable engine subset `scrollLabels` are
+ * forwarded to VirtualGrid, which localizes the embedded vertical bar, the horizontal bar and the
+ * degenerate-band "No items" — no lang attribute, no new data-* hook.
+ *
  * グリッド本体。VirtualGrid 結線 (両軸) とセルレンダラーを所有する。v0.4 から横軸は VirtualGrid
  * の所有 (量子化列アンカー + 残差 transform + 横バー) — v0.3 の列スタック (useColumnWindow /
  * --aqsp-hx CSS 変数 / 軸原点絶対 left / 自前 HScrollBar) は設計計画 §7-1 に従い削除。
@@ -50,17 +54,21 @@
  * v0.10 読み取り専用セル (計画 §6.5、S1): `getCellProps` が塗られた読み取り専用セルへ
  * `aria-readonly="true"` + `data-aqsp-readonly=""` を `isReadOnlyCell` ヘルパ経由で条件スタンプ
  * する (ADR-31 — パッケージ CSS なし。能力未宣言 = O(1) false = キー不在 = DOM バイト同一)。
+ *
+ * UI クロームロケール: 解決済み `locale` と値安定なエンジン部分集合 `scrollLabels` を VirtualGrid へ
+ * 素通しし、埋込み縦バー・横バー・退化帯の "No items" を現地化する (lang 属性・新規 data-* フックなし)。
  */
 
-import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange } from "@aiquants/virtualscroll"
+import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels } from "@aiquants/virtualscroll"
 import { type HTMLAttributes, memo, type ProfilerOnRenderCallback, type ReactNode, type RefObject, useCallback, useMemo, useRef, useSyncExternalStore } from "react"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
 import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
 import { alignToJustify, type CellAlign, type CellValueFormat, formatCellValue } from "../model/cellFormat.ts"
 import { type CellPaint, resolveCellPaint } from "../model/cellPaint.ts"
 import { type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "../model/conditionalFormat.ts"
-import { isReadOnlyCell, lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { isReadOnlyCell, lazyCellText, resolveCellAlign, resolveCellAttributes, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { isVisiblyInvalid } from "../model/dataValidation.ts"
+import type { SpreadsheetLocale } from "../model/labels.ts"
 import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
 import { CellView, type RenderCellContext } from "./CellView.tsx"
 
@@ -291,6 +299,8 @@ type GridBodyProps = {
     testId?: string
     /** Test-only CellView re-render counter seam (§8.2). / テスト専用の再レンダー計数シーム。 */
     __onCellRender?: ProfilerOnRenderCallback
+    /** Test-only rendered-cell cap (engine `__maxRenderedCells` seam pass-through); undefined in production. / テスト専用の描画セル上限 (エンジン `__maxRenderedCells` シームの素通し)。production では undefined。 */
+    __maxRenderedCells?: number
     /**
      * v0.8 capability (with `cfMemoRef`): the root-built conditional-format index, rebuilt per
      * (rules identity, renderVersion) and read fresh at every slice. Absent ⇒ the painted format
@@ -334,6 +344,25 @@ type GridBodyProps = {
      * エンジンが translate するのは行ラッパーのみ)。
      */
     background?: ReactNode
+    /** Rendering-truncation signal (engine `onRenderTruncated` pass-through — trailing columns dropped under the cell cap). / 描画打切り通知 (エンジン `onRenderTruncated` の素通し — セル上限下の末尾列脱落)。 */
+    onRenderTruncated?: (info: { renderedCells: number; droppedCols: number }) => void
+    /**
+     * The RESOLVED UI chrome locale (never undefined — the root resolves the `locale` prop through
+     * `resolveVirtualScrollLocale`), forwarded to VirtualGrid's `locale`.
+     * 解決済みの UI クロームロケール (undefined にならない — root が `locale` prop を
+     * `resolveVirtualScrollLocale` で解決)。VirtualGrid の `locale` へ素通し。
+     */
+    locale: SpreadsheetLocale
+    /**
+     * The resolved engine chrome strings (the 7 VirtualScrollLabels keys: scroll arrows,
+     * scroll-to-edge pills, "No items"), forwarded to VirtualGrid's `labels`. MUST be value-stable:
+     * its identity may change only when one of the 7 strings changes, otherwise every shell render
+     * pierces the memo boundary.
+     * 解決済みエンジンクローム文言 (VirtualScrollLabels の 7 キー: スクロール矢印・端スクロールピル・
+     * "No items")。VirtualGrid の `labels` へ素通し。値安定であること (7 文字列のどれかが変わった時だけ
+     * identity が変わる — さもなくば shell 再レンダー毎に memo 境界を貫通)。
+     */
+    scrollLabels: VirtualScrollLabels
 }
 
 /**
@@ -360,6 +389,7 @@ const GridBodyInner = ({
     requestCommit,
     testId,
     __onCellRender,
+    __maxRenderedCells,
     cfIndexRef,
     cfMemoRef,
     isPointing,
@@ -367,6 +397,9 @@ const GridBodyInner = ({
     overscanRows,
     overscanCols,
     background,
+    onRenderTruncated,
+    locale,
+    scrollLabels,
 }: GridBodyProps): ReactNode => {
     const internalBodyRef = useRef<HTMLDivElement | null>(null)
     // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -427,6 +460,11 @@ const GridBodyInner = ({
                 // 宣言ホストは塗りセル毎 1 述語読み (ADR-31 の登記コスト)
                 ...(isReadOnlyCell(adapter, row, col) ? { "aria-readonly": "true", "data-aqsp-readonly": "" } : {}),
             }
+            // v0.12 ホスト属性の継ぎ目: resolveCellAttributes が予約キー (data-aqsp* / data-row /
+            // data-col) と非 data-* を fail-fast 済みなのでパッケージ属性と衝突しない。未宣言は
+            // O(1) null = v0.11 のセル DOM とバイト同一
+            const hostAttrs = resolveCellAttributes(adapter, row, col)
+            const stamped = hostAttrs === null ? base : { ...base, ...hostAttrs }
             const rich = resolveRichCellProps(adapter, rowAxis, colAxis, cf, row, col)
             // 掛け金は毎セル更新 (v0.1 恒等の null でも座標を進める — children が消費するのは書式能力下だけ)
             const latch = displayLatchRef.current
@@ -434,9 +472,9 @@ const GridBodyInner = ({
             latch.col = col
             latch.value = rich === null ? undefined : rich.value
             if (rich === null) {
-                return base as HTMLAttributes<HTMLDivElement>
+                return stamped as HTMLAttributes<HTMLDivElement>
             }
-            return (rich.style === null ? { ...base, ...rich.attrs } : { ...base, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
+            return (rich.style === null ? { ...stamped, ...rich.attrs } : { ...stamped, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
         },
         [adapter, rowAxis, colAxis, cf],
     )
@@ -463,15 +501,17 @@ const GridBodyInner = ({
         (text: string, row: number, col: number): ReactNode => {
             // renderVersion は識別子として参照する (identity-bust — 値そのものは使わない)
             void renderVersion
-            // v0.7 表示形式: renderCell 指定時は素の text を素通し (escape hatch・組み込み値書式に優先)、
-            // 未指定時のみ値書式を表示文字列へ適用 (編集 / コピーは素の値のまま)。値書式は直前の
-            // getCellProps が掛け金へ置いた塗り書式の value (= base の value — CF 語彙に value は無い) で、
-            // アダプタは再読しない (書式能力なしは掛け金にも触れない v0.7 恒等)
+            // v0.7 表示形式 / v0.12 オプトアウト: 値書式は renderCell の有無に依らず書式能力下で
+            // 常に解決する — カスタムセルは ctx.displayText として受け取り (読み上げ / クリップ
+            // ボード / autofit と同一文字列)、undefined 返しのオプトアウトセルは既定描画がこれを
+            // 描く。値は直前の getCellProps が掛け金へ置いた塗り書式の value (= base の value —
+            // CF 語彙に value は無い) で、アダプタは再読しない (書式能力なしは掛け金にも触れない
+            // v0.7 恒等)
             let display = text
-            if (renderCell === undefined && adapter.getCellFormat !== undefined) {
+            if (adapter.getCellFormat !== undefined) {
                 display = formatCellValue(text, takeLatchedValue(displayLatchRef.current, row, col))
             }
-            return <CellView row={row} col={col} text={display} renderCell={renderCell} __onCellRender={__onCellRender} />
+            return <CellView row={row} col={col} text={text} display={display} renderCell={renderCell} __onCellRender={__onCellRender} />
         },
         [renderVersion, renderCell, __onCellRender, adapter],
     )
@@ -539,6 +579,10 @@ const GridBodyInner = ({
                 overscanRows={overscanRows}
                 overscanCols={overscanCols}
                 background={background}
+                onRenderTruncated={onRenderTruncated}
+                __maxRenderedCells={__maxRenderedCells}
+                locale={locale}
+                labels={scrollLabels}
                 callbackThrottleMs={0}
                 onScroll={onScroll}
                 onRangeChange={onRangeChange}

package/src/index.ts

@@ -36,7 +36,7 @@
  * (分冊 00 §5.2)。
  */
 
-// 統合タップサークル (エンジン v3.6.0 — ADR-33 縮小形): tapScrollCircleOptions prop (v0.10 H2) と
+// 統合タップサークル (エンジン v3.6.0 — エンジン ADR-33 縮小形): tapScrollCircleOptions prop (v0.10 H2) と
 // renderVisual をエンジン直接依存なしで型付ける型のみ再 export。値面 (tapScrollCircleSampleVisual) は
 // 意図的に非再 export — エンジン所有のまま
 export type { ScrollBarTapCircleOptions, TapScrollCircleRenderProps } from "@aiquants/virtualscroll"
@@ -110,7 +110,7 @@ export {
     validateCellText,
 } from "./model/dataValidation.ts"
 export { fromR1C1, shiftFormula, toR1C1 } from "./model/formulaRefs.ts"
-export { DEFAULT_LABELS, resolveLabel, type SpreadsheetLabelOverrides, type SpreadsheetLabels } from "./model/labels.ts"
+export { resolveLabel, resolveLabels, SPREADSHEET_LABEL_CATALOGS, type SpreadsheetLabelOverrides, type SpreadsheetLabels, type SpreadsheetLocale } from "./model/labels.ts"
 export { DEFAULT_HIGHLIGHT_COLORS, type HighlightColors, type HighlightState } from "./overlay/SelectionOverlay.tsx"
 // 既定ポップオーバー 6 種 — renderPopover の部品 (kind 別に差し替え、残りは既定を組み合わせる)
 export { CommentPopover, type CommentPopoverProps } from "./popover/CommentPopover.tsx"

package/src/keyboard/useGridKeyboard.ts

@@ -66,7 +66,7 @@ import { type RefObject, useEffect, useRef } from "react"
 import type { PasteOptions } from "../clipboard/pasteSpecial.ts"
 import type { PointingSeams } from "../editor/useCellEditor.ts"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
-import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import { type CellCoord, type CellRange, clampCoord, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
 import { aspectCapabilities, type CellEdit, type EditRejection, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { colToViewportX, rowToViewportY } from "../model/frozenPartition.ts"
 import { reduceActiveCycle, type SelectionState } from "../selection/selectionState.ts"
@@ -450,16 +450,21 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
                         const reference = pointing.getReferenceCursor()
                         if (reference !== null) {
                             event.preventDefault()
+                            // トークン由来の座標は生存セッションが行数 / 列数の縮小 (ADR-33) を跨いだあと範囲外
+                            // になり得る (手打ち "=A999" も同じ) — moveActive の入力 clamp と同じ規律で消費点に
+                            // 畳んでから歩く (軸の範囲外読みは Fenwick が fail-fast する)
+                            const cursor = clampCoord(reference.cursor, p.rowAxis.count, p.colAxis.count)
+                            const origin = clampCoord(reference.origin, p.rowAxis.count, p.colAxis.count)
                             // Ctrl はデータ端 (idle の Ctrl+Arrow と同じ導出)、素は可視 1 歩。active は動かさない
-                            const next = ctrl ? dataEdgeTarget(reference.cursor, direction) : arrowStep(reference.cursor, direction)
+                            const next = ctrl ? dataEdgeTarget(cursor, direction) : arrowStep(cursor, direction)
                             p.ensureCellVisible(next)
                             // Shift はトークン起点とのレンジへ置換、素はカーソル単独
-                            pointing.insertReference(event.shiftKey ? makeRange(reference.origin, next) : next, reference.axis)
+                            pointing.insertReference(event.shiftKey ? makeRange(origin, next) : next, reference.axis)
                             // 指し先の参照矩形 (§2.7): 挿入したトークンと同じ範囲を "point" 矩形で描く
                             // (Excel / Sheets のキーボード指し枠)。帯参照 (A:C / 2:5) は軸全域へ展開 —
                             // トークンの意味する範囲そのもの。能力分岐: writer 未配線 = 矩形なし (参照書換のみ)
                             if (p.onPointFrame !== undefined) {
-                                const rect = event.shiftKey ? makeRange(reference.origin, next) : makeRange(next, next)
+                                const rect = event.shiftKey ? makeRange(origin, next) : makeRange(next, next)
                                 p.onPointFrame(
                                     reference.axis === "columns"
                                         ? makeRange({ row: 0, col: rect.startCol }, { row: p.rowAxis.count - 1, col: rect.endCol })

package/src/model/dataAdapter.ts

@@ -266,10 +266,12 @@ export 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
@@ -283,9 +285,10 @@ export 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 増分 (またはアダプタ差替) で行う。
@@ -398,6 +401,31 @@ export 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
@@ -553,6 +581,69 @@ export const readOnlyDeclared = (adapter: SpreadsheetDataAdapter): boolean => ad
  */
 export const isReadOnlyCell = (adapter: SpreadsheetDataAdapter, row: number, col: number): boolean => adapter.isCellReadOnly?.(row, col) === true
 
+/** Host cell-attribute key grammar (v0.12): lowercase `data-*` only. / ホストセル属性キーの文法 (v0.12): 小文字 `data-*` のみ。 */
+const CELL_ATTRIBUTE_KEY = /^data-[a-z0-9-]+$/
+
+/**
+ * Whether a value is a plain record (object literal or null-prototype object — not an array,
+ * Map, class instance or primitive): the only shape `getCellAttributes` may return besides null.
+ * プレーンな record (object リテラルか null プロトタイプ object — 配列 / Map / class インスタンス /
+ * プリミティブではない) か: `getCellAttributes` が null 以外で返してよい唯一の形。
+ */
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false
+    }
+    const proto = Object.getPrototypeOf(value)
+    return proto === Object.prototype || proto === null
+}
+
+/**
+ * Resolves the host cell-attribute capability for one cell: `null` in O(1) without calling
+ * anything when the capability is absent (the byte-identity lever), otherwise the host's record
+ * verbatim after fail-fast validation — the return must be a plain record (a JS host's
+ * `undefined` / array / Map / primitive is rejected by name, never a bare TypeError), every key
+ * must be a lowercase `data-*` name that does not shadow a package- or engine-emitted cell
+ * attribute (`data-aqsp*` / `data-aqvs*` / `data-row` / `data-col` — the engine spreads its own
+ * `data-aqvs-*` band stamps AFTER the host props, so a colliding host key would win in the
+ * scroll band and lose in the frozen bands), and every value must be a string. Throws a
+ * RangeError naming the offending shape / key. A throw from the host callback is a host bug and
+ * propagates (no try/catch — Strict No-Fallback).
+ * セル 1 つのホスト属性能力の解決: 能力未宣言なら何も呼ばず O(1) で null (バイト恒等の支点)。
+ * 宣言時は fail-fast 検証 — 戻りはプレーンな record (JS ホストの `undefined` / 配列 / Map /
+ * プリミティブは名指しで拒否、生 TypeError にしない)、キーは小文字 `data-*` かつパッケージ /
+ * エンジン放出のセル属性 (`data-aqsp*` / `data-aqvs*` / `data-row` / `data-col`) を影書きしない
+ * (エンジンは自身の `data-aqvs-*` 帯スタンプをホスト props の**後**に spread するため、衝突キーは
+ * スクロール帯では勝ち凍結帯では負ける)、値は string のみ — の後、ホストの record をそのまま
+ * 返す。違反は形 / キーを名指しの RangeError。ホスト callback の throw はホストのバグとして
+ * 素通し (try/catch しない)。
+ */
+export const resolveCellAttributes = (adapter: SpreadsheetDataAdapter, row: number, col: number): Readonly<Record<string, string>> | null => {
+    if (adapter.getCellAttributes === undefined) {
+        return null
+    }
+    const attrs = adapter.getCellAttributes(row, col)
+    if (attrs === null) {
+        return null
+    }
+    // 型外の戻り (JS ホスト) は Object.keys の生 TypeError や Map の無言「空属性」でなく名指しで拒否する
+    if (!isPlainRecord(attrs)) {
+        throw new RangeError(`[spreadsheet] getCellAttributes must return a plain data-* record or null (got ${Object.prototype.toString.call(attrs)})`)
+    }
+    for (const [key, value] of Object.entries(attrs)) {
+        if (!CELL_ATTRIBUTE_KEY.test(key)) {
+            throw new RangeError(`[spreadsheet] getCellAttributes key must be a lowercase data-* name (got ${JSON.stringify(key)})`)
+        }
+        if (key.startsWith("data-aqsp") || key.startsWith("data-aqvs") || key === "data-row" || key === "data-col") {
+            throw new RangeError(`[spreadsheet] getCellAttributes key ${JSON.stringify(key)} shadows a package- or engine-emitted cell attribute`)
+        }
+        if (typeof value !== "string") {
+            throw new RangeError(`[spreadsheet] getCellAttributes value for ${JSON.stringify(key)} must be a string (got ${typeof value})`)
+        }
+    }
+    return attrs
+}
+
 /**
  * Whether a grid-clamped rect contains at least one read-only cell: rectangular walk with
  * short-circuit on first hit; `false` in O(1) when the capability is absent. For the

package/src/model/dataValidation.ts

@@ -26,7 +26,8 @@
  * - 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.
+ *   is), else the built-in summary of the rule in the caller's REQUIRED `locale`
+ *   (validationMessages.ts); an unsupported locale throws RangeError before any verdict.
  * - `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
@@ -43,11 +44,15 @@
  * タプル比較 (between は両端含み)、不完全な規則 (解釈不能な境界・between の b 欠落・needle 欠落) は
  * 不活性 = 全受理 (書きかけの規則でセルを閉じ込めない、境界の入替もしない)、語彙外の type / op は
  * consumer バグとして text に依らず RangeError、list の Set は規則 object 毎に WeakMap intern、
- * メッセージは errorMessage (空文字も尊重) が無ければ組込みの英語要約、custom は evaluate 無しなら
+ * メッセージは errorMessage (空文字も尊重) が無ければ呼び手必須の locale による組込み要約
+ * (validationMessages.ts — 非対応ロケールは判定前に RangeError)、custom は evaluate 無しなら
  * 未評価 (ok)・真 = true か有限非 0 数、照合は完全一致 (大文字小文字区別・trim 無し)、textLength は
  * コードポイント数、isEmail は WHATWG 文法 + ドット付きドメイン必須、isUrl は WHATWG 絶対 http(s) URL。
  */
 
+import { describeLabelValue, type SpreadsheetLocale } from "./labels.ts"
+import { VALIDATION_MESSAGE_CATALOGS, type ValidationMessageCatalog } from "./validationMessages.ts"
+
 /** Ordered comparison vocabulary shared by number / textLength / date rules; between / notBetween include both bounds. / number / textLength / date 規則が共有する比較語彙。between / notBetween は両端含み。 */
 export type ValidationCompareOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "notBetween"
 
@@ -127,15 +132,6 @@ type Ordering = -1 | 0 | 1
 /** Resolved bounds of an ordered rule; `b` is null when the op does not use it. / 順序規則の解決済み境界。op が使わないとき b は null。 */
 type Bounds<T> = { a: T; b: T | null }
 
-/** Rule-family wording for the four ordered ops (the other four are shared). / 順序 4 op の規則族別の言い回し (残る 4 つは共通)。 */
-type OrderWords = { readonly gt: string; readonly gte: string; readonly lt: string; readonly lte: string }
-
-/** Wording for number / textLength messages. / number / textLength メッセージの言い回し。 */
-const NUMERIC_WORDS: OrderWords = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
-
-/** Wording for date messages. / date メッセージの言い回し。 */
-const DATE_WORDS: OrderWords = { gt: "after", gte: "on or after", lt: "before", lte: "on or before" }
-
 /**
  * Parses a strict decimal string into its exact normalised form: trims, applies the
  * cellFormat.ts grammar (hex / grouping / empty rejected, exponent overflow to ±Infinity
@@ -367,9 +363,16 @@ const checkboxStrings = (rule: CheckboxValidationRule): { checked: string; unche
 
 /**
  * Rejects a rule outside the vocabulary (unknown `type`, or an unknown `op` on number /
- * textLength / date / text) with RangeError — a consumer bug surfaces regardless of the text.
+ * textLength / date / text) with RangeError — a consumer bug surfaces regardless of the text. The
+ * rejected value is described by `describeLabelValue`, so a Symbol / null-prototype `type` or `op`
+ * still yields the RangeError (never a TypeError from the message itself).
  * 語彙外の規則 (未知 type、number / textLength / date / text の未知 op) を RangeError で拒否 —
- * consumer バグは text に依らず表面化。
+ * consumer バグは text に依らず表面化。拒否値は `describeLabelValue` で説明するため、Symbol / null
+ * プロトタイプの type や op でもメッセージ組立て自体が TypeError を投げず RangeError のまま。
+ *
+ * @param rule - The rule to check / 検査する規則
+ * @returns Nothing; returns normally for an in-vocabulary rule / なし (語彙内の規則なら正常終了)
+ * @throws {RangeError} When the rule's `type` / `op` is outside the vocabulary / 規則の type / op が語彙外の場合
  */
 const assertRuleShape = (rule: DataValidationRule): void => {
     switch (rule.type) {
@@ -381,16 +384,16 @@ const assertRuleShape = (rule: DataValidationRule): void => {
         case "textLength":
         case "date":
             if (!COMPARE_OPS.has(rule.op)) {
-                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "${rule.type}"`)
+                throw new RangeError(`[spreadsheet] unknown data-validation op ${describeLabelValue(rule.op)} for type "${rule.type}"`)
             }
             return
         case "text":
             if (!TEXT_OPS.has(rule.op)) {
-                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "text"`)
+                throw new RangeError(`[spreadsheet] unknown data-validation op ${describeLabelValue(rule.op)} for type "text"`)
             }
             return
         default:
-            throw new RangeError(`[spreadsheet] unknown data-validation rule type "${String((rule as { type: unknown }).type)}"`)
+            throw new RangeError(`[spreadsheet] unknown data-validation rule type ${describeLabelValue((rule as { type: unknown }).type)}`)
     }
 }
 
@@ -427,68 +430,61 @@ const accepts = (rule: DataValidationRule, text: string, evaluate: ValidationEva
     return text === "" || ruleHolds(rule, text, evaluate)
 }
 
-/** Phrase for an ordered op with the family wording: "greater than 5", "between 1 and 9", ... / 順序 op の言い回し (規則族の語彙付き)。 */
-const comparePhrase = (op: ValidationCompareOp, a: string, b: string | undefined, words: OrderWords): string => {
-    switch (op) {
-        case "gt":
-        case "gte":
-        case "lt":
-        case "lte":
-            return `${words[op]} ${a}`
-        case "eq":
-            return `equal to ${a}`
-        case "neq":
-            return `not equal to ${a}`
-        case "between":
-            return `between ${a} and ${b}`
-        default:
-            // 残る順序 op は notBetween
-            return `not between ${a} and ${b}`
-    }
-}
-
 /** Trims an optional bound string for display. / 表示用に任意の境界文字列を trim。 */
 const trimBound = (bound: string | undefined): string | undefined => (bound === undefined ? undefined : bound.trim())
 
-/** Built-in English summary of a rule, used when the consumer set no `errorMessage`. / consumer が errorMessage を置かないときの組込み英語要約。 */
-const defaultMessage = (rule: DataValidationRule): string => {
+/**
+ * Built-in summary of a rule in one locale's catalog, used when the consumer set no
+ * `errorMessage`. The bounds are normalised here (number / date bounds trimmed, textLength bounds
+ * stringified, checkbox strings defaulted) so every locale's template sees the same values.
+ * consumer が errorMessage を置かないときの、1 ロケールのカタログによる規則の組込み要約。境界の正規化
+ * (number / date は trim、textLength は文字列化、checkbox は既定適用) をここで行い、全ロケールの
+ * テンプレートが同じ値を受け取る。
+ *
+ * @param rule - The shape-checked rule that rejected the text / text を拒否した形検査済みの規則
+ * @param catalog - The message catalog of the verdict's locale / 判定ロケールのメッセージカタログ
+ * @returns The built-in message / 組込みメッセージ
+ */
+const messageOf = (rule: DataValidationRule, catalog: ValidationMessageCatalog): string => {
     switch (rule.type) {
         case "list":
-            return "Value must be one of the list items."
+            return catalog.list
         case "number":
-            return `Value must be a number ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), NUMERIC_WORDS)}.`
+            return catalog.number[rule.op](rule.a.trim(), trimBound(rule.b))
         case "textLength":
-            return `Text length must be ${comparePhrase(rule.op, String(rule.a), rule.b === undefined ? undefined : String(rule.b), NUMERIC_WORDS)}.`
+            return catalog.textLength[rule.op](String(rule.a), rule.b === undefined ? undefined : String(rule.b))
         case "date":
-            return `Value must be a date ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), DATE_WORDS)}.`
+            return catalog.date[rule.op](rule.a.trim(), trimBound(rule.b))
         case "text":
-            return textMessage(rule)
+            return textMessageOf(rule, catalog.text)
         case "checkbox": {
             const strings = checkboxStrings(rule)
-            return `Value must be "${strings.checked}" or "${strings.unchecked}".`
+            return catalog.checkbox(strings.checked, strings.unchecked)
         }
         default:
             // 残る規則種別は custom
-            return `Value does not satisfy the formula ${rule.formula}.`
+            return catalog.custom(rule.formula)
     }
 }
 
-/** Built-in summary of a text rule. / text 規則の組込み要約。 */
-const textMessage = (rule: TextValidationRule): string => {
+/**
+ * Built-in summary of a text rule from a catalog's `text` templates (needle ops embed `value`; the
+ * shape checks are fixed sentences).
+ * カタログの text テンプレートによる text 規則の組込み要約 (needle 系は value を埋め込み、形式検査は固定文)。
+ *
+ * @param rule - The shape-checked text rule / 形検査済みの text 規則
+ * @param templates - The `text` templates of the verdict's locale / 判定ロケールの text テンプレート
+ * @returns The built-in message / 組込みメッセージ
+ */
+const textMessageOf = (rule: TextValidationRule, templates: ValidationMessageCatalog["text"]): string => {
     switch (rule.op) {
-        case "contains":
-            return `Value must contain "${rule.value}".`
-        case "notContains":
-            return `Value must not contain "${rule.value}".`
-        case "startsWith":
-            return `Value must start with "${rule.value}".`
-        case "endsWith":
-            return `Value must end with "${rule.value}".`
         case "isEmail":
-            return "Value must be a valid email address."
+            return templates.isEmail
+        case "isUrl":
+            return templates.isUrl
         default:
-            // 残る text op は isUrl
-            return "Value must be a valid URL."
+            // needle 系は value 欠落なら不活性で拒否に至らないため、ここへ来るとき value は常にある
+            return templates[rule.op](rule.value as string)
     }
 }
 
@@ -513,20 +509,41 @@ export const listValuesOf = (rule: ListValidationRule): ReadonlySet<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 があればそれ、無ければ組込みの英語要約。
+ * 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 があればそれ (空文字も含む)、無ければ
+ * 指定ロケールの組込み要約。
+ *
+ * @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 const validateCellText = (rule: DataValidationRule, text: string, evaluate?: ValidationEvaluate): ValidationVerdict => {
+export const validateCellText = (rule: DataValidationRule, text: string, locale: SpreadsheetLocale, evaluate?: ValidationEvaluate): ValidationVerdict => {
+    // 型を外れた呼び手 (JS・as キャスト) の undefined を "en" へ黙って寄せると、言語の取り違えが表面化しない
+    if (typeof locale !== "string" || !Object.hasOwn(VALIDATION_MESSAGE_CATALOGS, locale)) {
+        const allowed = Object.keys(VALIDATION_MESSAGE_CATALOGS)
+            .map((candidate) => JSON.stringify(candidate))
+            .join(", ")
+        throw new RangeError(`[spreadsheet] validateCellText locale must be one of ${allowed}; got ${describeLabelValue(locale)}`)
+    }
     if (accepts(rule, text, evaluate)) {
         return VALID
     }
     // errorMessage は「置かれているか」だけを見る (空文字も consumer の意思として尊重)
-    return { ok: false, message: rule.errorMessage === undefined ? defaultMessage(rule) : rule.errorMessage }
+    return { ok: false, message: rule.errorMessage === undefined ? messageOf(rule, VALIDATION_MESSAGE_CATALOGS[locale]) : rule.errorMessage }
 }
 
 /** Whether a rule can be judged at paint time without a formula evaluator (every type but `custom`). / 数式評価器なしに描画時判定できる規則か (custom 以外の全型)。 */