@aiquants/spreadsheet 0.10.0 → 0.12.0

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/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 の根拠