@aiquants/spreadsheet 0.11.0 → 0.13.0

package/src/model/validationMessages.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Built-in data-validation verdict messages per UI chrome locale — the table that
+ * validateCellText reads when a rule carries no `errorMessage`. INTERNAL: not exported from the
+ * package barrel; the public override stays the per-rule `errorMessage`. Pure, React-free.
+ *
+ * Contract (pinned by validationMessages.spec.ts and dataValidation.spec.ts):
+ * - One frozen ValidationMessageCatalog per SpreadsheetLocale; every template takes the bounds
+ *   already normalised by dataValidation.ts (number / date bounds trimmed, textLength bounds
+ *   stringified, checkbox strings defaulted) and never re-normalises them.
+ * - Templates are WHOLE SENTENCES per (rule type, op): Japanese puts the bound before the
+ *   predicate, so a fragment table ("greater than" + bound) cannot express it.
+ * - `en` is byte-identical to the pre-i18n English summaries ("Value must be a number greater
+ *   than 5." etc.); `ja` follows the workspace Japanese spacing rule (a half-width space around
+ *   ASCII alphanumerics, 「」 exempt).
+ * - between / notBetween receive `b` only for complete rules: an incomplete rule is inert and
+ *   never produces a message.
+ *
+ * UI クロームロケール別の組込みデータ検証メッセージ — 規則に `errorMessage` が無いとき
+ * validateCellText が読む表。内部専用 (パッケージの barrel からは export しない — 公開の上書き手段は
+ * 規則毎の `errorMessage`)。純関数・React 非依存。
+ * 契約: SpreadsheetLocale 毎に凍結した ValidationMessageCatalog を 1 つ持ち、各テンプレートは
+ * dataValidation.ts が正規化済みの境界 (number / date は trim、textLength は文字列化、checkbox は既定
+ * 適用済み) を受け取り再正規化しない。テンプレートは (規則型, op) 毎の文全体 (日本語は境界が述語より
+ * 前に来るため、断片表では表現不能)。`en` は i18n 以前の英語要約とバイト単位で同一、`ja` は
+ * ワークスペースの和文スペース規則 (半角英数字の前後に半角スペース、「」内は対象外) に従う。
+ * between / notBetween の `b` は完全な規則でだけ渡る (不完全な規則は不活性でメッセージを作らない)。
+ */
+
+import type { ValidationCompareOp, ValidationTextOp } from "./dataValidation.ts"
+import type { SpreadsheetLocale } from "./labels.ts"
+
+/**
+ * Whole-sentence templates of one ordered rule family (number / textLength / date), one per
+ * comparison op; `b` is the upper bound for between / notBetween and unused by the other six.
+ * 順序規則族 (number / textLength / date) 1 つ分の文全体テンプレート (比較 op 毎に 1 つ)。`b` は
+ * between / notBetween の上限で、他の 6 op では未使用。
+ */
+type CompareTemplates = { readonly [K in ValidationCompareOp]: (a: string, b: string | undefined) => string }
+
+/**
+ * The built-in verdict messages of one locale: a sentence for `list`, per-op templates for the
+ * three ordered families, per-op templates for `text` (the four needle ops take the needle; the
+ * two shape checks are fixed sentences), and templates for `checkbox` and `custom`.
+ * 1 ロケール分の組込み判定メッセージ。list の文、順序 3 族の op 別テンプレート、text の op 別
+ * テンプレート (needle 系 4 op は探索文字列を受け取り、形式検査 2 op は固定文)、checkbox と custom の
+ * テンプレート。
+ */
+export type ValidationMessageCatalog = {
+    readonly list: string
+    readonly number: CompareTemplates
+    readonly textLength: CompareTemplates
+    readonly date: CompareTemplates
+    readonly text: {
+        readonly contains: (v: string) => string
+        readonly notContains: (v: string) => string
+        readonly startsWith: (v: string) => string
+        readonly endsWith: (v: string) => string
+        readonly isEmail: string
+        readonly isUrl: string
+    }
+    readonly checkbox: (checked: string, unchecked: string) => string
+    readonly custom: (formula: string) => string
+}
+
+/** Compile-time proof that the `text` templates are keyed by exactly the ValidationTextOp vocabulary (a new op without a message, or a stray key, turns tsc red). / text テンプレートのキーが ValidationTextOp 語彙と完全一致することの型水準の証明 (メッセージの無い新 op や余分なキーは tsc が赤)。 */
+const textTemplatesMatchTextOps: [keyof ValidationMessageCatalog["text"]] extends [ValidationTextOp] ? ([ValidationTextOp] extends [keyof ValidationMessageCatalog["text"]] ? true : never) : never = true
+void textTemplatesMatchTextOps
+
+/** English wording of the four ordered ops of one family (the other four are shared). / 規則族 1 つ分の順序 4 op の英語の言い回し (残る 4 つは共通)。 */
+type OrderWords = { readonly gt: string; readonly gte: string; readonly lt: string; readonly lte: string }
+
+/** English 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" }
+
+/** English wording for date messages. / date メッセージの英語の言い回し。 */
+const DATE_WORDS: OrderWords = { gt: "after", gte: "on or after", lt: "before", lte: "on or before" }
+
+/**
+ * English phrase for an ordered op with the family wording: "greater than 5", "between 1 and 9", ...
+ * 規則族の語彙を使った順序 op の英語句 ("greater than 5"、"between 1 and 9" など)。
+ *
+ * @param op - The comparison op / 比較 op
+ * @param a - The normalised lower (or only) bound / 正規化済みの下限 (または唯一の境界)
+ * @param b - The normalised upper bound for between / notBetween / between 系の正規化済み上限
+ * @param words - The family wording of the four ordered ops / 順序 4 op の規則族別の言い回し
+ * @returns The comparison phrase without subject or full stop / 主語と句点を含まない比較句
+ */
+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 (語彙外の op は dataValidation.ts の assertRuleShape が先に拒否済み)
+            return `not between ${a} and ${b}`
+    }
+}
+
+/**
+ * Builds the English templates of one ordered family as `${subject} ${phrase}.`, e.g.
+ * "Value must be a number greater than 5.".
+ * 順序規則族 1 つ分の英語テンプレートを `${subject} ${phrase}.` の形で構築 (例:
+ * "Value must be a number greater than 5.")。
+ *
+ * @param subject - The sentence head before the comparison phrase / 比較句の前に置く文頭
+ * @param words - The family wording of the four ordered ops / 順序 4 op の規則族別の言い回し
+ * @returns The frozen per-op templates / op 別の凍結テンプレート
+ */
+const englishCompareTemplates = (subject: string, words: OrderWords): CompareTemplates => {
+    const sentence =
+        (op: ValidationCompareOp) =>
+        (a: string, b: string | undefined): string =>
+            `${subject} ${comparePhrase(op, a, b, words)}.`
+    return Object.freeze({
+        gt: sentence("gt"),
+        gte: sentence("gte"),
+        lt: sentence("lt"),
+        lte: sentence("lte"),
+        eq: sentence("eq"),
+        neq: sentence("neq"),
+        between: sentence("between"),
+        notBetween: sentence("notBetween"),
+    })
+}
+
+/** The English catalog — byte-identical to the pre-i18n built-in summaries. / 英語カタログ — i18n 以前の組込み要約とバイト単位で同一。 */
+const EN: ValidationMessageCatalog = Object.freeze({
+    list: "Value must be one of the list items.",
+    number: englishCompareTemplates("Value must be a number", NUMERIC_WORDS),
+    textLength: englishCompareTemplates("Text length must be", NUMERIC_WORDS),
+    date: englishCompareTemplates("Value must be a date", DATE_WORDS),
+    text: Object.freeze({
+        contains: (v: string) => `Value must contain "${v}".`,
+        notContains: (v: string) => `Value must not contain "${v}".`,
+        startsWith: (v: string) => `Value must start with "${v}".`,
+        endsWith: (v: string) => `Value must end with "${v}".`,
+        isEmail: "Value must be a valid email address.",
+        isUrl: "Value must be a valid URL.",
+    }),
+    checkbox: (checked: string, unchecked: string) => `Value must be "${checked}" or "${unchecked}".`,
+    custom: (formula: string) => `Value does not satisfy the formula ${formula}.`,
+})
+
+/** The Japanese catalog — whole sentences with the bound first. / 日本語カタログ — 境界を先に置いた文全体。 */
+const JA: ValidationMessageCatalog = Object.freeze({
+    list: "リストの項目のいずれかを入力してください。",
+    number: Object.freeze({
+        gt: (a: string) => `${a} より大きい数値を入力してください。`,
+        gte: (a: string) => `${a} 以上の数値を入力してください。`,
+        lt: (a: string) => `${a} より小さい数値を入力してください。`,
+        lte: (a: string) => `${a} 以下の数値を入力してください。`,
+        eq: (a: string) => `${a} に等しい数値を入力してください。`,
+        neq: (a: string) => `${a} 以外の数値を入力してください。`,
+        between: (a: string, b: string | undefined) => `${a} から ${b} までの数値を入力してください。`,
+        notBetween: (a: string, b: string | undefined) => `${a} から ${b} までの範囲外の数値を入力してください。`,
+    }),
+    textLength: Object.freeze({
+        gt: (a: string) => `${a} 文字より長いテキストを入力してください。`,
+        gte: (a: string) => `${a} 文字以上のテキストを入力してください。`,
+        lt: (a: string) => `${a} 文字より短いテキストを入力してください。`,
+        lte: (a: string) => `${a} 文字以下のテキストを入力してください。`,
+        eq: (a: string) => `${a} 文字のテキストを入力してください。`,
+        neq: (a: string) => `${a} 文字以外の長さのテキストを入力してください。`,
+        between: (a: string, b: string | undefined) => `${a} 文字から ${b} 文字までのテキストを入力してください。`,
+        notBetween: (a: string, b: string | undefined) => `${a} 文字から ${b} 文字までの範囲外の長さのテキストを入力してください。`,
+    }),
+    date: Object.freeze({
+        gt: (a: string) => `${a} より後の日付を入力してください。`,
+        gte: (a: string) => `${a} 以降の日付を入力してください。`,
+        lt: (a: string) => `${a} より前の日付を入力してください。`,
+        lte: (a: string) => `${a} 以前の日付を入力してください。`,
+        eq: (a: string) => `${a} の日付を入力してください。`,
+        neq: (a: string) => `${a} 以外の日付を入力してください。`,
+        between: (a: string, b: string | undefined) => `${a} から ${b} までの日付を入力してください。`,
+        notBetween: (a: string, b: string | undefined) => `${a} から ${b} までの範囲外の日付を入力してください。`,
+    }),
+    text: Object.freeze({
+        contains: (v: string) => `「${v}」を含む値を入力してください。`,
+        notContains: (v: string) => `「${v}」を含まない値を入力してください。`,
+        startsWith: (v: string) => `「${v}」で始まる値を入力してください。`,
+        endsWith: (v: string) => `「${v}」で終わる値を入力してください。`,
+        isEmail: "有効なメールアドレスを入力してください。",
+        isUrl: "有効な URL を入力してください。",
+    }),
+    checkbox: (checked: string, unchecked: string) => `「${checked}」または「${unchecked}」を入力してください。`,
+    custom: (formula: string) => `数式 ${formula} を満たす値を入力してください。`,
+})
+
+/**
+ * The built-in verdict messages per UI chrome locale (frozen at every level). Keyed by exactly the
+ * SpreadsheetLocale set, so validateCellText checks a locale by own-key membership here.
+ * UI クロームロケール別の組込み判定メッセージ (全階層で凍結)。キーは SpreadsheetLocale 集合と完全一致
+ * するため、validateCellText はここへの自身のキーの所属でロケールを検査する。
+ */
+export const VALIDATION_MESSAGE_CATALOGS: Readonly<Record<SpreadsheetLocale, ValidationMessageCatalog>> = Object.freeze({ en: EN, ja: JA })

package/src/popover/usePopovers.ts

@@ -120,8 +120,8 @@ export type PopoverController = {
     isKindEnabled: (kind: PopoverKind) => boolean
     /** Opens a kind on the ACTIVE cell; RangeError when the kind is disabled or its capability undeclared. / active セルで kind を開く。無効 / 能力未宣言は RangeError。 */
     open: (kind: PopoverKind, options?: PopoverOpenOptions) => void
-    /** Closes the interactive popover (idempotent) and returns focus to the sink. / 対話ポップオーバーを閉じ (冪等) シンクへフォーカスを返す。 */
-    close: () => void
+    /** Closes the interactive popover (idempotent) and returns focus to the sink — unless `{ restoreFocus: false }`, which the host-driven count-shrink seam passes while focus sits outside the grid (a filter input) so the host's keystrokes are not stolen; the sink is re-armed when idle either way. / 対話ポップオーバーを閉じ (冪等) シンクへフォーカスを返す — `{ restoreFocus: false }` なら返さない (ホスト起点の行数縮小シームが、フォーカスがグリッド外 (絞り込み入力欄) にある間に渡す — ホストの打鍵先を奪わない)。idle なら再武装はどちらでも行う。 */
+    close: (options?: { restoreFocus: boolean }) => void
     /** The open interactive kind or null. / 開いている対話 kind か null。 */
     isOpen: () => PopoverKind | null
     /** rAF-coalesced hover entry for the note tip by cell (null = pointer left the cells); the body's own pointermove path queues the client point and hit-tests inside the frame. / note tip のセル指定ホバー入口 (rAF 合流。null = セル領域から離脱)。body の pointermove 経路は client 座標を積みフレーム内でヒットテストする。 */
@@ -458,20 +458,26 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
     const hideTip = useCallback((): boolean => hideTipNow(), [hideTipNow])
 
     /** Closes the interactive popover (idempotent) and returns focus to the sink. / 対話ポップオーバーを閉じ (冪等) フォーカスをシンクへ返す。 */
-    const close = useCallback(() => {
-        if (openKindRef.current === null) {
-            return
-        }
-        const p = paramsRef.current
-        openKindRef.current = null
-        setContext(null)
-        writeAnchors({ interactive: null })
-        // フォーカス復帰 (スクロールさせない) + idle なら再武装 (編集セッションの値は守る)
-        p.focusSink({ preventScroll: true })
-        if (!p.isEditing()) {
-            p.rearmSink()
-        }
-    }, [writeAnchors])
+    const close = useCallback(
+        (options?: { restoreFocus: boolean }) => {
+            if (openKindRef.current === null) {
+                return
+            }
+            const p = paramsRef.current
+            openKindRef.current = null
+            setContext(null)
+            writeAnchors({ interactive: null })
+            // フォーカス復帰 (スクロールさせない) — ホスト起点の閉鎖 (行数縮小) がグリッド外の打鍵先を守るときだけ省く。
+            // idle なら再武装 (編集セッションの値は守る) はどちらでも行う (rearm はフォーカス中立)
+            if (options === undefined || options.restoreFocus) {
+                p.focusSink({ preventScroll: true })
+            }
+            if (!p.isEditing()) {
+                p.rearmSink()
+            }
+        },
+        [writeAnchors],
+    )
 
     /** Places `ctx` on the interactive anchor (replacing whatever was open). / ctx を対話アンカーへ載せる (開いていたものは置換)。 */
     const present = useCallback(

package/src/selection/selectionState.ts

@@ -11,7 +11,7 @@
  * の (c) は pressCell 1×1 を再構築するため等価でも新オブジェクト — ラッパーの構造 bail が受ける。
  */
 
-import { type CellCoord, type CellRange, coordEquals, makeRange, rangeContains, type SpreadsheetDirection } from "../model/cellCoord.ts"
+import { type CellCoord, type CellRange, clampCoord, coordEquals, makeRange, rangeContains, type SpreadsheetDirection } from "../model/cellCoord.ts"
 
 /** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
 export type SelectionState = {
@@ -38,6 +38,33 @@ const rangeEquals = (a: CellRange, b: CellRange): boolean => a.startRow === b.st
  */
 export const selectionStateEquals = (a: SelectionState, b: SelectionState): boolean => a.ranges.length === b.ranges.length && a.ranges.every((range, i) => rangeEquals(range, b.ranges[i])) && coordEquals(a.anchor, b.anchor) && coordEquals(a.active, b.active)
 
+/**
+ * Clamps a selection into a NON-EMPTY grid whose counts shrank under it (same adapter — a
+ * filter / category / period change removed rows): every range corner, the anchor and the
+ * active cell are pulled onto the last row / column, and a range that lay entirely beyond the
+ * edge collapses onto it. Returns the INPUT object when nothing was out of bounds (identity
+ * contract → the §6.9-1 wrapper's Object.is bail = no notification) and keeps the identity of
+ * every range that was inside. Throws RangeError on an empty grid (the caller owns the empty
+ * path — 0 rows have no A1).
+ * 縮小した非空グリッドへ選択を畳む (同一アダプタ — 絞り込み / カテゴリ / 期間の変更で行が減った):
+ * 各レンジの隅・anchor・active を末尾行 / 列へ引き寄せ、丸ごと外にあったレンジは端へ潰れる。範囲外が
+ * 無ければ入力 object をそのまま返し (identity 契約 → §6.9-1 ラッパーの Object.is bail = 通知なし)、
+ * 範囲内のレンジは identity を保つ。空グリッドは RangeError (空経路は呼び手所有 — 0 行に A1 は無い)。
+ */
+export const clampSelectionToGrid = (state: SelectionState, rowCount: number, colCount: number): SelectionState => {
+    const inside = (cell: CellCoord): boolean => cell.row < rowCount && cell.col < colCount
+    const rangeInside = (range: CellRange): boolean => range.endRow < rowCount && range.endCol < colCount
+    if (inside(state.anchor) && inside(state.active) && state.ranges.every(rangeInside)) {
+        return state
+    }
+    const clamp = (cell: CellCoord): CellCoord => clampCoord(cell, rowCount, colCount)
+    return {
+        ranges: state.ranges.map((range) => (rangeInside(range) ? range : makeRange(clamp({ row: range.startRow, col: range.startCol }), clamp({ row: range.endRow, col: range.endCol })))),
+        anchor: inside(state.anchor) ? state.anchor : clamp(state.anchor),
+        active: inside(state.active) ? state.active : clamp(state.active),
+    }
+}
+
 /** Replaces the tail range, preserving identity when unchanged. / 現在レンジのみ置換 (等価なら入力を返す)。 */
 const replaceCurrentRange = (state: SelectionState, next: CellRange): SelectionState => {
     // identity 保存契約 (冒頭): 無変化なら新オブジェクトを作らない — §6.9-1 の Object.is bail の根拠