@aiquants/spreadsheet 0.8.0

package/src/model/cellFormat.ts

@@ -0,0 +1,562 @@
+/**
+ * @fileoverview Built-in cell display formatting (v0.7 — the getCellFormat capability). Pure,
+ * React-free value→string engine + horizontal-alignment resolver. The consumer declares a
+ * per-cell CellFormat via the optional adapter capability getCellFormat(row, col); the grid
+ * applies the value format to the DISPLAY string (editing / copy / TSV keep the raw
+ * getCellText) and the alignment to the flex cell's justify-content.
+ *
+ * Engine contract (each clause is load-bearing and mutation-gated — spec 07 §5.8):
+ * - EXACT decimal rendering: the validated raw string is handed to Intl.NumberFormat AS A
+ *   STRING (NumberFormat v3 mathematical values), never converted through a binary double —
+ *   so "1.45" with {type:"percent", scale:false, decimals:1} renders "1.5%" (not the drifted
+ *   "1.4%") and integers beyond 2^53 keep every digit. percent scale:false divides by 100 as
+ *   a pure string exponent shift, again without touching floating point. Literal exponents
+ *   are grammar-bounded to 4 digits (±9999) — past ICU's own limits, inputs stay raw.
+ * - INTERNED formatters: Intl.NumberFormat instances are cached per exact option tuple
+ *   (construction FAILURES are interned too) behind an identity WeakMap tier keyed on the
+ *   value-format object (an identity-stable adapter answer skips even the key build), so
+ *   per-cell rendering and autofit measurement never re-pay the ~40µs construction cost — nor
+ *   the per-cell key-build cost — per cell per slice.
+ * - Negative-zero suppression via signDisplay:"negative" (a value that rounds to zero never
+ *   shows a minus sign) — locale-proof, including non-ASCII numbering systems.
+ * - TOTAL fail-soft: a non-numeric string in a numeric format, an invalid date, or an
+ *   out-of-range Intl option (bad decimals / currency / locale) renders the raw text
+ *   unchanged — a header/label never breaks.
+ * - TRULY timezone-free dates: parsing/validation/rendering is pure integer calendar math
+ *   (leap-year aware) — no Date object is ever constructed, so host TZ, DST gaps, and the
+ *   two-digit-year remapping cannot affect which dates format or how.
+ * - Alignment "unset" is AUTO by the VALUE, not the declared format: text that actually
+ *   parses under the cell's numeric/date format (or as a strict decimal with no format)
+ *   resolves right, labels resolve left — the Excel / Google Sheets render-time default.
+ *
+ * 組み込みセル表示形式 (v0.7 — getCellFormat 能力)。純関数・React 非依存の値→文字列エンジン +
+ * 水平揃え解決。エンジン契約 (全て変異検証で封印 — spec 07 §5.8):
+ * 正確十進 (検証済み素文字列を Intl へ**文字列のまま**渡し二進浮動小数を経由しない —
+ * percent scale:false の ÷100 も文字列指数シフト)、interned フォーマッタ (構築失敗も
+ * インターンし、値書式 object キーの identity WeakMap 層でキー構築も省き、セル毎の Intl 構築
+ * コストを排除)、signDisplay:"negative" による負ゼロ抑止
+ * (非 ASCII 数字体系でも成立)、全経路 fail-soft (非数値 / 無効日付 / 範囲外オプションは素の
+ * text)、Date 非依存の純整数暦検証 (ホスト TZ / DST / 2 桁年写像の影響が構造的にゼロ)、
+ * align 未指定は**値による自動** — 実際に解釈できる値だけ右、ラベルは左 (Excel / Sheets の描画時既定)。
+ *
+ * v0.8 (rich cells) widens CellFormat to the full declarative cell format — vertical alignment,
+ * wrap, background / text colour, bold / italic / underline / strikethrough, font family / size
+ * (pt) and per-side borders — and adds the pure FORMAT ALGEBRA the commands and the clipboard
+ * share: canonicalizeFormat (the structural normal form — false booleans / undefined keys /
+ * empty borders dropped, every object emitted with SORTED keys so JSON.stringify of a canonical
+ * form is a deterministic interning key), mergeFormat (patch application with null = clear,
+ * identity-preserving when nothing changes so an unchanged cell emits no edit) and
+ * formatEquals (structural equality on canonical forms, key-order independent). Painting
+ * (CSS / attributes) lives in cellPaint.ts; this module stays a value model.
+ *
+ * v0.8 (リッチセル) は CellFormat を宣言的セル書式の全体 (縦揃え・折返し・背景 / 文字色・太字 /
+ * 斜体 / 下線 / 取消線・フォント族 / サイズ (pt)・辺毎の罫線) へ拡張し、コマンドとクリップボード
+ * が共有する純関数の書式代数を追加: canonicalizeFormat (構造的正準形 — false 真偽値 / undefined
+ * キー / 空 borders を落とし、全 object をキー辞書順で出力するため JSON.stringify がそのまま
+ * 決定的 intern キー)、mergeFormat (null = 消去のパッチ適用、無変化なら base を identity で返し
+ * 無変化セルは edit を出さない)、formatEquals (正準形の構造等価・キー順非依存)。塗り (CSS /
+ * 属性) は cellPaint.ts、本モジュールは値モデルに留まる。
+ */
+
+/** Horizontal cell alignment. / セルの水平揃え。 */
+export type CellAlign = "left" | "center" | "right"
+
+/** Vertical cell alignment (undefined = middle, the cell's flex centring). / セルの垂直揃え (undefined = 中央 = セルの flex 中央)。 */
+export type CellVerticalAlign = "top" | "middle" | "bottom"
+
+/** Border line style vocabulary (Excel / Sheets subset). / 罫線種の語彙 (Excel / Sheets 部分集合)。 */
+export type CellBorderStyle = "thin" | "medium" | "thick" | "dashed" | "dotted" | "double" | "hair"
+
+/** One border side: line style plus an optional colour (absent = BORDER_DEFAULT_COLOR). / 罫線 1 辺: 線種 + 任意の色 (省略 = BORDER_DEFAULT_COLOR)。 */
+export type CellBorder = { style: CellBorderStyle; color?: string }
+
+/** Per-side borders of a cell (absent side = no border). / セルの辺毎の罫線 (辺の省略 = 罫線なし)。 */
+export type CellBorders = { top?: CellBorder; right?: CellBorder; bottom?: CellBorder; left?: CellBorder }
+
+/** Border colour when `CellBorder.color` is absent (a stated default, not a fallback). / 罫線色の宣言済み既定 (fallback ではなく仕様上の既定)。 */
+export const BORDER_DEFAULT_COLOR = "#000000"
+
+/**
+ * A value display format (type-based — "simple formats"). All fields optional beyond `type`,
+ * except `currency.currency` which is REQUIRED (a currency is meaningless without its code —
+ * the package stays host-agnostic and never assumes a region default).
+ * 値の表示形式 (型ベース・簡易形式)。`type` 以外は基本任意だが `currency.currency` のみ必須
+ * (通貨コードなしの通貨書式は無意味・パッケージは地域既定を仮定しないホスト非依存設計)。
+ */
+export type CellValueFormat =
+    | { type: "number"; decimals?: number; grouping?: boolean; locale?: string }
+    | { type: "percent"; decimals?: number; scale?: boolean; locale?: string }
+    | { type: "currency"; currency: string; decimals?: number; locale?: string }
+    | { type: "scientific"; decimals?: number; locale?: string }
+    | { type: "date"; pattern?: string }
+    | { type: "text" }
+
+/**
+ * A cell's declared display format, returned per-cell by the adapter's getCellFormat capability
+ * (v0.8 — the full rich-cell vocabulary): value format (undefined = raw text), horizontal
+ * alignment (undefined = auto by the value), vertical alignment (undefined = middle), wrap,
+ * background / text colour (any CSS colour text — normalised by the paint engine, unparseable =
+ * ignored), bold / italic / underline / strikethrough (absent = false), font family, font size
+ * in POINTS (painted as pt × 4 / 3 px) and per-side borders. Every key is optional; the
+ * canonical form (canonicalizeFormat) is what the package writes back through CellEdit.format.
+ * セルの宣言済み表示形式 — アダプタの getCellFormat 能力がセル毎に返す (v0.8 — リッチセルの
+ * 全語彙): 値書式 (undefined = 素の文字列)・水平揃え (undefined = 値による自動)・垂直揃え
+ * (undefined = 中央)・折返し・背景 / 文字色 (任意の CSS 色文字列 — 塗りエンジンが正規化、解釈
+ * 不能は無視)・太字 / 斜体 / 下線 / 取消線 (不在 = false)・フォント族・フォントサイズ (pt 単位、
+ * pt × 4 / 3 px で描画)・辺毎の罫線。全キー任意。パッケージが CellEdit.format で書き戻すのは
+ * 正準形 (canonicalizeFormat)。
+ */
+export type CellFormat = {
+    value?: CellValueFormat
+    align?: CellAlign
+    verticalAlign?: CellVerticalAlign
+    wrap?: boolean
+    background?: string
+    color?: string
+    bold?: boolean
+    italic?: boolean
+    underline?: boolean
+    strikethrough?: boolean
+    fontFamily?: string
+    fontSize?: number
+    borders?: CellBorders
+}
+
+/**
+ * Command / handle input ONLY — never crosses the adapter. A key set to `null` CLEARS it, an
+ * omitted / undefined key leaves the base value untouched, any other value replaces it (borders
+ * are replaced as a whole set — callers spread the base sides to change one side).
+ * コマンド / handle 入力専用 — アダプタを跨がない。`null` のキーは消去、省略 / undefined は
+ * base の値を保持、それ以外は置換 (borders は辺の集合ごと置換 — 1 辺だけ変えるときは呼び手が
+ * base の辺を展開する)。
+ */
+export type CellFormatPatch = { readonly [K in keyof CellFormat]?: CellFormat[K] | null }
+
+/** The Intl-numeric subset of CellValueFormat (everything the formatter cache serves). / 数値系サブセット (キャッシュ対象)。 */
+type NumericCellValueFormat = Exclude<CellValueFormat, { type: "date" } | { type: "text" }>
+
+/** Intl fraction-digit options for a fixed decimals count (empty = the style's Intl default). / 固定小数桁の Intl オプション。 */
+const fractionDigits = (decimals: number | undefined): Intl.NumberFormatOptions => (decimals === undefined ? {} : { minimumFractionDigits: decimals, maximumFractionDigits: decimals })
+
+/**
+ * Fraction-digit ceiling for {type:"number"} with decimals omitted. Intl's own default (max 3)
+ * silently rounds typed input and can render a nonzero value as "0" ("0.000001" → "0"); 20 is
+ * Intl's guaranteed-accepted maximum, so typed fraction digits are preserved DOWN TO the 20th
+ * place ("1e-20" renders in full; a value below 1e-20 still rounds to "0" — Intl offers no
+ * larger ceiling, and the raw value stays intact for editing/copy).
+ * decimals 省略時の {type:"number"} の小数桁上限。Intl 既定 (最大 3) は入力を黙って丸め
+ * "0.000001" を "0" に見せる。20 は Intl が保証する最大受理値で、入力小数桁を**第 20 位まで**
+ * 保持する ("1e-20" は全桁表示。1e-20 未満は "0" に丸まる — Intl にこれ以上の上限は無く、
+ * 素の値は編集 / コピーで無傷)。
+ */
+const MAX_GENERAL_FRACTION_DIGITS = 20
+
+/** Formatter-cache overflow guard: format vocabularies are per-column finite, so this is never reached in real use. / キャッシュ安全弁 (書式語彙は列単位で有限 — 実運用で到達しない)。 */
+const FORMATTER_CACHE_LIMIT = 256
+
+/** Interned Intl.NumberFormat per exact option tuple; null = construction failed (fail-soft, memoized). / オプションタプル毎の interned フォーマッタ。null = 構築失敗のインターン。 */
+const formatterCache = new Map<string, Intl.NumberFormat | null>()
+
+/** Identity tier of the formatter intern, keyed on the value-format OBJECT (mirrors internCellStyle's tier 1): GC-bounded, so the size valve of the keyed tier never touches it. / 値書式 object をキーとする intern の identity 層 (internCellStyle の第 1 層と同形): GC 有界のためキー層の安全弁の対象外。 */
+const formatterByValue = new WeakMap<NumericCellValueFormat, Intl.NumberFormat | null>()
+
+/**
+ * Parses text as a finite strict decimal ("[+-]digits[.digits][e±digits]" — rejects hex/binary
+ * literals, blank, ±Infinity overflow) and returns the TRIMMED canonical string, or null.
+ * The string (not a double) is what Intl later formats, keeping the pipeline exact. The return
+ * carries Intl's StringNumericLiteral brand — the regex IS the validator of exactly that
+ * grammar, so this is the single honest cast point.
+ * 厳密 10 進として解釈できれば trim 済み正準文字列を返す (16 / 2 進・空・±Infinity 溢れは null)。
+ * 後段の Intl へは double でなくこの文字列を渡すことで正確十進を貫く。戻り値の
+ * StringNumericLiteral ブランドは正規表現がまさにその文法の検証器であることに基づく唯一の cast 点。
+ * Exported (v0.8) so conditionalFormat.ts and selfCalc.ts reuse the SAME grammar (single source
+ * of "what is a number" for comparison rules and self-calc).
+ * v0.8 で export — conditionalFormat.ts / selfCalc.ts が**同一文法**を再利用する (比較規則と
+ * 自己計算の「数値とは何か」の単一真実源)。
+ */
+export const parseNumber = (text: string): Intl.StringNumericLiteral | null => {
+    const t = text.trim()
+    // 10 進 (任意符号・小数・指数) のみ受理 — 0x/0b/0o・空文字・Infinity は数値と見なさない。
+    // 指数部は最大 4 桁 (±9999) に文法水準で制限する: double が 0 へ underflow して有限判定を
+    // すり抜ける巨大負指数 ("1e-1000000000") は ICU が |指数| ≥ 1e9 で throw するため、表示上
+    // 意味のある全域 (double は ±e308) を保ちつつ構造的に遮断する (fail-soft の穴を作らない)
+    if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d{1,4})?$/.test(t)) {
+        return null
+    }
+    // 指数溢れ ("1e999" → ±Infinity) は数値と見なさない (グロテスクな 1000 桁表示の遮断)
+    return Number.isFinite(Number(t)) ? (t as Intl.StringNumericLiteral) : null
+}
+
+/** Shifts a validated decimal string's exponent (exact ÷/× powers of ten with NO floating point). / 検証済み 10 進文字列の指数シフト (浮動小数を経由しない正確な 10 の冪乗除)。 */
+const shiftExponent = (decimal: Intl.StringNumericLiteral, shift: number): Intl.StringNumericLiteral => {
+    const at = decimal.search(/[eE]/)
+    // 指数が無ければ付与、有れば数値部を加算 (指数は短い整数 — 文字列長で安全)。連結結果も
+    // 同文法に留まるためブランドを維持する
+    return (at < 0 ? `${decimal}e${shift}` : `${decimal.slice(0, at)}e${Number(decimal.slice(at + 1)) + shift}`) as Intl.StringNumericLiteral
+}
+
+/** Per-type Intl options (signDisplay:"negative" suppresses the sign of anything that ROUNDS to zero — the locale-proof negative-zero guard); null for an unknown future type (runtime fail-soft). / 型別 Intl オプション。signDisplay:"negative" が「丸め後ゼロ」の符号を全 locale で抑止。未知型は null。 */
+const numericOptions = (value: NumericCellValueFormat): Intl.NumberFormatOptions | null => {
+    switch (value.type) {
+        case "number":
+            return { signDisplay: "negative", useGrouping: value.grouping ?? false, ...(value.decimals === undefined ? { maximumFractionDigits: MAX_GENERAL_FRACTION_DIGITS } : fractionDigits(value.decimals)) }
+        case "percent":
+            return { signDisplay: "negative", style: "percent", ...fractionDigits(value.decimals) }
+        case "currency":
+            return { signDisplay: "negative", style: "currency", currency: value.currency, ...fractionDigits(value.decimals) }
+        case "scientific":
+            return { signDisplay: "negative", notation: "scientific", ...fractionDigits(value.decimals) }
+        default: {
+            // 到達不能 (数値系 4 種を網羅) — 将来の型追加を型エラーで検出しつつ実行時は fail-soft
+            const exhaustive: never = value
+            void exhaustive
+            return null
+        }
+    }
+}
+
+/**
+ * Returns the interned Intl.NumberFormat for a numeric value format through two tiers: an
+ * identity WeakMap keyed on the value-format object (an identity-stable adapter answer skips
+ * the JSON key build entirely — the per-cell display-path hoist), falling through to the keyed
+ * cache on identity miss (a fresh-but-equal object converges on the SAME formatter there),
+ * constructing on first sight. Construction failures — out-of-range decimals, an invalid
+ * currency code or locale — are interned as null, so a broken column pays ONE throw total, not
+ * one per cell per frame. `scale` is deliberately absent from the key (it shifts the INPUT, not
+ * the formatter). Value formats are immutable values (the contract cellPaint's intern already
+ * relies on): an in-place mutation must hand out a new object to take effect.
+ * 数値書式の interned フォーマッタを 2 層で返す: 値書式 object をキーとする identity WeakMap
+ * (identity 安定なアダプタ答えは JSON キー構築ごと省略 — セル毎表示経路の巻き上げ)、identity
+ * miss はキー層へ (内容同値の新規 object はそこで同一フォーマッタに合流)、初見で構築。構築失敗
+ * (範囲外 decimals / 不正 currency / 不正 locale) も null でインターンし、壊れた列の throw は
+ * 全体で 1 回に抑える。`scale` は入力側のシフトでありフォーマッタに影響しないためキーから除外。
+ * 値書式は不変値 (cellPaint の intern が既に依拠する契約) — in-place 変更は新 object で初めて効く。
+ */
+const numericFormatter = (value: NumericCellValueFormat): Intl.NumberFormat | null => {
+    const byIdentity = formatterByValue.get(value)
+    // null も「構築失敗」の登録済み答え — undefined だけが未登録
+    if (byIdentity !== undefined) {
+        return byIdentity
+    }
+    // キーは型 + 全オプションの null 番兵タプル。decimals は String() 符号化 — JSON.stringify は
+    // NaN / Infinity を null に落とすため素のままだと「未指定」キーと衝突し、NaN 先行時に健全な
+    // 既定構成へ構築失敗 (null) を毒として注入してしまう ("NaN" / "Infinity" / "7" は衝突不能)
+    const key = JSON.stringify([value.type, value.locale ?? null, value.decimals === undefined ? null : String(value.decimals), value.type === "number" ? (value.grouping ?? false) : null, value.type === "currency" ? value.currency : null])
+    const cached = formatterCache.get(key)
+    if (cached !== undefined) {
+        formatterByValue.set(value, cached)
+        return cached
+    }
+    // 安全弁: 上限到達で全消去 (LRU 不要 — 実運用の書式語彙は列単位で有限)
+    if (formatterCache.size >= FORMATTER_CACHE_LIMIT) {
+        formatterCache.clear()
+    }
+    const options = numericOptions(value)
+    let formatter: Intl.NumberFormat | null = null
+    if (options !== null) {
+        try {
+            formatter = new Intl.NumberFormat(value.locale, options)
+        } catch {
+            formatter = null
+        }
+    }
+    formatterCache.set(key, formatter)
+    formatterByValue.set(value, formatter)
+    return formatter
+}
+
+/** A wall-clock date-time parsed by pure calendar math (never a Date object). / 純暦計算で解釈した壁時計日時 (Date 非経由)。 */
+type ParsedDate = { year: number; month: number; day: number; hour: number; minute: number; second: number }
+
+/** Days in a month with proleptic-Gregorian leap rules (÷4, except ÷100 unless ÷400). / 月の日数 (グレゴリオ暦の閏年規則)。 */
+const monthDays = (year: number, month: number): number => {
+    switch (month) {
+        case 2:
+            return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28
+        case 4:
+        case 6:
+        case 9:
+        case 11:
+            return 30
+        default:
+            return 31
+    }
+}
+
+/**
+ * Parses ISO-ish "YYYY-MM-DD[ T HH:mm[:ss]]" (or "/" separated — the SAME separator on both
+ * sides) with pure integer range validation: month 1-12, day within the leap-aware month,
+ * hour<24 / minute<60 / second<60. NO Date object is involved, so rollover ("2026-13-45"),
+ * host-timezone DST gaps, and the Date constructor's two-digit-year remapping (years 0001-0099)
+ * can never corrupt or reject a real calendar date. Null on any violation or trailing garbage.
+ * 先頭末尾固定・両側同一区切り・純整数の範囲検証 (月 1-12・閏年対応の月内日・時<24 / 分<60 /
+ * 秒<60) の日付解析。Date を一切構築しないため、ロールオーバー・ホスト TZ の DST ギャップ・
+ * 2 桁年写像 (年 0001-0099) の影響が構造的に存在しない。違反・末尾ゴミは null。
+ */
+const parseDate = (text: string): ParsedDate | null => {
+    const m = /^(\d{4})([-/])(\d{1,2})\2(\d{1,2})(?:[ T](\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?$/.exec(text.trim())
+    if (m === null) {
+        return null
+    }
+    const year = Number(m[1])
+    const month = Number(m[3])
+    const day = Number(m[4])
+    const hour = m[5] === undefined ? 0 : Number(m[5])
+    const minute = m[6] === undefined ? 0 : Number(m[6])
+    const second = m[7] === undefined ? 0 : Number(m[7])
+    // 純整数の暦検証 — 範囲外は無効日として null (黙ったロールオーバー変換を作らない)
+    if (month < 1 || month > 12 || day < 1 || day > monthDays(year, month) || hour > 23 || minute > 59 || second > 59) {
+        return null
+    }
+    return { year, month, day, hour, minute, second }
+}
+
+/** Formats a parsed date via a token pattern (yyyy MM dd HH mm ss, zero-padded — year to 4); raw text if unparseable/invalid. / トークンパターンで日付整形 (年は 4 桁 0 詰め)、解析不能 / 無効は素の text。 */
+const formatDate = (text: string, pattern: string): string => {
+    const d = parseDate(text)
+    if (d === null) {
+        return text
+    }
+    const pad = (n: number, width: number): string => String(n).padStart(width, "0")
+    // 単一パス置換 (置換結果が未置換トークンを含まないため衝突なし)。トークン集合は正規表現の
+    // 選択肢と全単射 — default は "ss" (未知トークンは正規表現が拾わないため到達し得ない)
+    return pattern.replace(/yyyy|MM|dd|HH|mm|ss/g, (token) => {
+        switch (token) {
+            case "yyyy":
+                return pad(d.year, 4)
+            case "MM":
+                return pad(d.month, 2)
+            case "dd":
+                return pad(d.day, 2)
+            case "HH":
+                return pad(d.hour, 2)
+            case "mm":
+                return pad(d.minute, 2)
+            default:
+                return pad(d.second, 2)
+        }
+    })
+}
+
+/**
+ * Formats the raw canonical text for DISPLAY per a value format. undefined / {type:"text"} /
+ * empty text pass through unchanged; a non-numeric string in a numeric format, an invalid date,
+ * or an out-of-range Intl option fails soft to the raw text. The validated decimal STRING is
+ * handed to Intl (exact — no double conversion), and percent scale:false pre-divides by 100 via
+ * a string exponent shift. Editing / copy never call this (they use the raw text).
+ * 素の正準文字列を値書式に従い表示用へ整形。undefined / {type:"text"} / 空文字は無変更で素通し。
+ * 数値書式の非数値・無効日付・範囲外 Intl オプションは素の text へ fail-soft。検証済み 10 進は
+ * **文字列のまま** Intl へ (double 変換なしの正確十進)、percent scale:false は文字列指数シフトで
+ * ÷100。編集 / コピーは呼ばない (素の値)。
+ */
+export const formatCellValue = (text: string, value: CellValueFormat | undefined): string => {
+    if (value === undefined || value.type === "text" || text === "") {
+        return text
+    }
+    if (value.type === "date") {
+        return formatDate(text, value.pattern ?? "yyyy/MM/dd")
+    }
+    // 数値系: 厳密 10 進解釈。非数値は素の text へ fail-soft (ラベル / 見出しを壊さない)
+    const decimal = parseNumber(text)
+    if (decimal === null) {
+        return text
+    }
+    const formatter = numericFormatter(value)
+    if (formatter === null) {
+        return text
+    }
+    // percent scale=false は「値が既に ×100 のパーセント」— 指数シフトで正確に ÷100 して相殺
+    return formatter.format(value.type === "percent" && value.scale === false ? shiftExponent(decimal, -2) : decimal)
+}
+
+/**
+ * Resolves the effective horizontal alignment. Explicit align wins; otherwise AUTO by the
+ * ACTUAL value: under a date format, text that parses as a date resolves right; under a
+ * numeric format or no format, text that parses as a strict decimal resolves right; everything
+ * else — labels, {type:"text"}, unparseable input — resolves left. The mirror with
+ * formatCellValue runs over the PARSERS (parseNumber/parseDate): a "Total" label in a currency
+ * column is left-aligned raw text, never a right-aligned impostor (the Excel / Google Sheets
+ * render-time default). When only the Intl OPTIONS are broken (bad currency code), the raw
+ * numeric text shows and stays right-aligned — consistent with the no-format auto rule.
+ * 実効の水平揃えを解決。明示 align 優先、なければ**実際の値**で自動 — date 書式は日付として
+ * 解釈できる文字列だけ右、数値系書式 / 書式なしは厳密 10 進だけ右、それ以外 (ラベル /
+ * {type:"text"} / 解釈不能) は左。formatCellValue との鏡映は**パーサ水準** (parseNumber /
+ * parseDate) — 通貨列の「Total」は左寄せの素テキストになる (Excel / Sheets の描画時既定)。
+ * Intl オプションだけが壊れた場合 (不正通貨コード) は数値の素文字列が表示され右寄せのまま —
+ * 書式なしの自動則と整合。
+ */
+export const resolveAlign = (align: CellAlign | undefined, value: CellValueFormat | undefined, text: string): CellAlign => {
+    if (align !== undefined) {
+        return align
+    }
+    if (value !== undefined && value.type === "text") {
+        return "left"
+    }
+    if (value !== undefined && value.type === "date") {
+        return parseDate(text) !== null ? "right" : "left"
+    }
+    // 数値系書式 or 書式なし: 厳密 10 進として解釈できる素文字列だけ右寄せ (fail-soft と対)
+    return parseNumber(text) !== null ? "right" : "left"
+}
+
+/** Maps an alignment to the flex cell's justify-content. / 揃えを flex セルの justify-content へ写す。 */
+export const alignToJustify = (align: CellAlign): "flex-start" | "center" | "flex-end" => (align === "center" ? "center" : align === "right" ? "flex-end" : "flex-start")
+
+/**
+ * Every CellFormat key in canonical (sorted, UTF-16 code unit) order, `satisfies`-checked so each
+ * entry IS a key; the coverage constant below proves the converse at compile time. The canonical
+ * form is built by walking THIS list, which is what makes `JSON.stringify(canonicalizeFormat(f))`
+ * a deterministic interning key and drops unknown keys structurally.
+ * CellFormat の全キーを正準 (辞書 = UTF-16 コード単位) 順に並べた表。`satisfies` で各要素がキーで
+ * あることを、下の網羅定数で逆 (全キーが載っていること) をコンパイル時に証明。正準形はこの表の
+ * 走査で組み立てるため `JSON.stringify(canonicalizeFormat(f))` が決定的 intern キーになり、
+ * 未知キーは構造的に落ちる。
+ */
+const FORMAT_KEYS = ["align", "background", "bold", "borders", "color", "fontFamily", "fontSize", "italic", "strikethrough", "underline", "value", "verticalAlign", "wrap"] as const satisfies readonly (keyof CellFormat)[]
+
+/** Compile-time proof that FORMAT_KEYS lists EVERY CellFormat key (a key added to the type but not to the list would be silently dropped by canonicalization). / FORMAT_KEYS が CellFormat の全キーを網羅することの型水準の証明 (型に増えたキーが表に無いと正準化で黙って落ちる)。 */
+const formatKeysCoverEveryKey: [Exclude<keyof CellFormat, (typeof FORMAT_KEYS)[number]>] extends [never] ? true : never = true
+void formatKeysCoverEveryKey
+
+/** Border sides in canonical (sorted) order, with the same two-way compile-time coverage proof. / 罫線の辺の正準 (辞書) 順、同じ双方向のコンパイル時網羅証明つき。 */
+const BORDER_SIDES = ["bottom", "left", "right", "top"] as const satisfies readonly (keyof CellBorders)[]
+const borderSidesCoverEverySide: [Exclude<keyof CellBorders, (typeof BORDER_SIDES)[number]>] extends [never] ? true : never = true
+void borderSidesCoverEverySide
+
+/** Writes one key of a format under construction (generic so a union-typed key stays assignable without a cast). / 構築中の書式へ 1 キー書込 (総称型で union キーの代入を cast なしに通す)。 */
+const setKey = <K extends keyof CellFormat>(target: CellFormat, key: K, value: CellFormat[K]): void => {
+    target[key] = value
+}
+
+/**
+ * Shallow rebuild of a flat object with undefined keys removed and the remaining keys in sorted
+ * order (value formats and border sides are flat — every field is a primitive). The rebuild keeps
+ * every defined key of T, which is what makes the return cast structurally honest.
+ * 平坦な object を undefined キー除去 + キー辞書順で浅く再構築 (値書式と罫線の辺は平坦 — 全
+ * フィールドが原始値)。T の定義済みキーを全て保つため戻り値の cast は構造的に正直。
+ */
+const sortedShallow = <T extends object>(source: T): T => {
+    const record = source as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(record).sort()) {
+        // undefined のキーは「不在」— 正準形には現れない
+        if (record[key] !== undefined) {
+            out[key] = record[key]
+        }
+    }
+    return out as T
+}
+
+/** Canonical borders: undefined sides dropped, each side rebuilt (color undefined dropped, keys sorted), sides in sorted order; undefined when no side survives. / 正準 borders: undefined の辺を落とし、各辺を再構築 (color undefined 除去・キー辞書順)、辺は辞書順。辺が残らなければ undefined。 */
+const canonicalizeBorders = (borders: CellBorders | undefined): CellBorders | undefined => {
+    if (borders === undefined) {
+        return undefined
+    }
+    const out: CellBorders = {}
+    for (const side of BORDER_SIDES) {
+        const border = borders[side]
+        // 辺 undefined は不在。辺 object は color undefined を除きキー辞書順 (color, style) で再構築
+        if (border !== undefined) {
+            out[side] = sortedShallow(border)
+        }
+    }
+    return Object.keys(out).length === 0 ? undefined : out
+}
+
+/**
+ * Structural normal form of a format, or undefined when nothing survives: `undefined` keys and
+ * `false` booleans are dropped (absent = default), border sides whose value is undefined are
+ * dropped and an empty `borders` disappears, unknown keys are dropped, nested objects (value /
+ * borders / each side) are rebuilt with undefined keys removed, and every object is emitted with
+ * its keys in SORTED order so `JSON.stringify` of the result is a deterministic interning key
+ * (copy dictionary, command memo). Values are NOT validated — an unparseable colour or a
+ * non-positive font size is kept verbatim and ignored fail-soft by the paint engine:
+ * canonicalization is about structure, not meaning. Always returns a fresh object (the input is
+ * never mutated) and is idempotent.
+ * 書式の構造的正準形 (何も残らなければ undefined)。undefined キーと false 真偽値は落とす (不在 =
+ * 既定)、値 undefined の辺は落とし空の borders は消え、未知キーは落ち、入れ子 (value / borders /
+ * 各辺) は undefined キーを除いて再構築、全 object をキー辞書順で出力するため `JSON.stringify`
+ * がそのまま決定的 intern キー (copy 辞書・コマンド memo)。値の検証はしない — 解釈不能な色や
+ * 非正のフォントサイズはそのまま残し塗りエンジンが fail-soft に無視: 正準化は意味でなく構造の話。
+ * 常に新規 object を返し (入力は不変)、冪等。
+ */
+export const canonicalizeFormat = (format: CellFormat): CellFormat | undefined => {
+    const out: CellFormat = {}
+    for (const key of FORMAT_KEYS) {
+        // 入れ子 2 種は専用の再構築、それ以外は素の値
+        const raw = key === "borders" ? canonicalizeBorders(format.borders) : key === "value" ? (format.value === undefined ? undefined : sortedShallow(format.value)) : format[key]
+        // undefined と false は「不在 = 既定」— 正準形には現れない (空 borders も undefined へ畳まれて落ちる)
+        if (raw !== undefined && raw !== false) {
+            setKey(out, key, raw)
+        }
+    }
+    return Object.keys(out).length === 0 ? undefined : out
+}
+
+/**
+ * Deep structural equality of two CANONICAL values (objects compared key-by-key in emitted order,
+ * which canonical forms make comparable; primitives by SameValue so NaN equals NaN).
+ * 正準値 2 つの深い構造等価 (object は出力順のキー毎 — 正準形なら比較可能、原始値は SameValue で
+ * NaN 同士も等しい)。
+ */
+const canonicalEquals = (a: unknown, b: unknown): boolean => {
+    if (Object.is(a, b)) {
+        return true
+    }
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+        return false
+    }
+    const keysA = Object.keys(a)
+    const keysB = Object.keys(b)
+    if (keysA.length !== keysB.length) {
+        return false
+    }
+    const recordA = a as Record<string, unknown>
+    const recordB = b as Record<string, unknown>
+    for (let i = 0; i < keysA.length; i += 1) {
+        // 正準形はキー順が固定なので位置毎に同じキーでなければ不等
+        const key = keysA[i]
+        if (key !== keysB[i] || !canonicalEquals(recordA[key], recordB[key])) {
+            return false
+        }
+    }
+    return true
+}
+
+/**
+ * Structural equality of two formats on their canonical forms — key order, undefined keys,
+ * false booleans and empty borders never matter; every value (including each border side and
+ * the nested value format) must match. `undefined` equals any format whose canonical form is
+ * empty.
+ * 正準形上の構造等価 — キー順・undefined キー・false 真偽値・空 borders は無関係、全値 (罫線の
+ * 各辺・入れ子の値書式を含む) が一致すること。`undefined` は正準形が空の書式と等しい。
+ */
+export const formatEquals = (a: CellFormat | undefined, b: CellFormat | undefined): boolean => {
+    if (a === b) {
+        return true
+    }
+    return canonicalEquals(a === undefined ? undefined : canonicalizeFormat(a), b === undefined ? undefined : canonicalizeFormat(b))
+}
+
+/**
+ * Applies a patch to a base format: `null` clears a key, `undefined` (or an omitted key) keeps
+ * the base value, anything else replaces it (borders as a whole set). Returns the CANONICAL
+ * merged format — or `base` BY IDENTITY when the result is structurally unchanged (so callers
+ * skip the edit for an unchanged cell), or `undefined` when everything has been cleared. The
+ * base is never mutated.
+ * base 書式へパッチを適用: `null` はキー消去、`undefined` (省略) は base の値を保持、それ以外は
+ * 置換 (borders は集合ごと)。戻り値は**正準**の合成書式 — 構造的に無変化なら `base` を
+ * **identity で**返し (無変化セルの edit を呼び手が省ける)、全て消えれば `undefined`。base は
+ * 変更しない。
+ */
+export const mergeFormat = (base: CellFormat | undefined, patch: CellFormatPatch): CellFormat | undefined => {
+    const merged: CellFormat = {}
+    for (const key of FORMAT_KEYS) {
+        const next = patch[key]
+        // undefined = 不変 (base の値を保つ)、null = 消去、それ以外 = 上書き
+        setKey(merged, key, next === undefined ? base?.[key] : next === null ? undefined : next)
+    }
+    const canonical = canonicalizeFormat(merged)
+    // 無変化 (正準形が等しい) なら base を identity で返す — 無変化セルは edit を出さない契約の根拠
+    return canonicalEquals(canonical, base === undefined ? undefined : canonicalizeFormat(base)) ? base : canonical
+}