@aiquants/spreadsheet 0.8.0

package/src/model/axisModel.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Row/column-symmetric axis size model on top of FenwickMapTree (integer-px contract).
+ * Positions are logical px from the axis origin; sizes are non-negative integers (0 = hidden).
+ *
+ * FenwickMapTree 上の行・列対称寸法モデル (整数 px 契約)。位置は軸原点からの論理 px、
+ * サイズは非負整数 (0 = 非表示)。
+ */
+
+import { FenwickMapTree } from "@aiquants/virtualscroll"
+import { useRef } from "react"
+
+/** Axis size/offset/hit-test contract. / 軸の寸法・オフセット・ヒットテスト契約。 */
+export type AxisModel = {
+    count: number
+    sizeOf: (index: number) => number
+    /** Start offset from the axis origin in logical px. / 軸原点からの開始オフセット。 */
+    offsetOf: (index: number) => number
+    /** Logical position to index (right-open, zero-width skip, edge snap to nearest positive). / 論理座標 → index。 */
+    indexAt: (position: number) => number
+    totalSize: () => number
+    /** Resize (rounded to integer; negative / non-finite throws; 0 hides). / サイズ変更。 */
+    resize: (index: number, size: number) => void
+    /**
+     * Hidden-track total, maintained O(1) at BOTH write points (the eager construction loop —
+     * initialSizeOf bypasses resize — and the resize seam) on the ROUNDED stored size
+     * (resize(0.4) stores 0 = hidden; comparing the raw argument would miss it). Backs the
+     * §5.4(b) row-axis UI gate; box-rebuild resets it automatically (counter lives in the box).
+     * 非表示トラック総数 (§5.4(b))。書込 2 点 (eager 構築ループ — initialSizeOf は resize を
+     * 通らない第 2 の書込点 — と resize シーム) で丸め後の格納サイズに対し O(1) 維持。
+     * カウンタは軸ボックス内在のため再構築リセットは自動。
+     */
+    hiddenCount: () => number
+}
+
+/**
+ * Builds the Fenwick tree with numeric base + eager per-index application.
+ * 数値ベース + eager 適用で木を構築するモジュールレベル純関数 (レンダー中に呼んでも副作用なし)。
+ *
+ * ❗ 関数を FenwickMapTree の valueOrFn に渡してはならない — 関数初期値は「baseValue 推定の
+ * サンプリング (100 点以下、mode / median)」であり per-index 値は materialize 経由でしか
+ * 具現化されない。渡すと初期幅が一様値へ黙って化ける (§6.2.2-1)。
+ */
+const buildAxisTree = (count: number, defaultSize: number, initialSizeOf?: (index: number) => number): { tree: FenwickMapTree; initialHidden: number } => {
+    const built = new FenwickMapTree(count, defaultSize)
+    let initialHidden = 0
+    if (initialSizeOf) {
+        // eager 適用: 非 default 値だけが差分 Map に載りメモリはスパースなまま。
+        // O(count) の関数評価が掛かるため、巨大グリッド (10 万行超) では initialSizeOf を
+        // 渡さず必要行だけ後から resize する (props docstring に明記)
+        for (let i = 0; i < count; i += 1) {
+            const v = Math.round(initialSizeOf(i))
+            if (v !== defaultSize) {
+                built.update(i, v)
+            }
+            // hiddenCount の第 2 の書込点 (§5.4(b) — initialSizeOf は resize シームを通らない)
+            if (v === 0) {
+                initialHidden += 1
+            }
+        }
+    }
+    return { tree: built, initialHidden }
+}
+
+/** Constructs the model + tree pair for one key. / 1 キーぶんのモデル + 木を構築。 */
+const buildAxisBox = (count: number, defaultSize: number, initialSizeOf?: (index: number) => number): { key: string; model: AxisModel } => {
+    const { tree, initialHidden } = buildAxisTree(count, defaultSize, initialSizeOf)
+    // 非表示総数はボックス内在 (再構築で自動リセット)。判定は常に丸め後の格納サイズ (§5.4(b))
+    let hidden = initialHidden
+    const offsetOf = (index: number): number => {
+        // prefixSum は自身を含む累積 (inclusive) — 開始オフセットは自身の寸法を引いて得る
+        const { cumulative, currentValue } = tree.prefixSum(index)
+        return cumulative - currentValue
+    }
+    const indexAt = (position: number): number => {
+        // 空軸・全 0 軸に「幅正の最近傍」は存在しない (fail-fast — §6.2.2-5)
+        if (count === 0 || tree.getTotal() === 0) {
+            throw new RangeError("[spreadsheet] indexAt requires a non-empty axis with positive total size")
+        }
+        // ❗ 入力はまず floor する。ヒットテスト入力は getBoundingClientRect の小数 + scrollBy の
+        // float 累積で小数になり、floor しないと各行下端 0.5px 帯が隣の行へ誤判定される
+        const p = Math.floor(position)
+        // 整数 px 契約により累積は常に整数。+0.5 は必ず区間内部に落ち、幅 0 行 (累積が増えない) を
+        // findIndexAtOrAfter が自然にスキップする。境界 p = offsetOf(k) は k 自身に、
+        // 区間終端 p = offsetOf(k) + sizeOf(k) は次の幅正行に解決される
+        const clamped = Math.min(Math.max(p, 0), tree.getTotal() - 1)
+        return tree.findIndexAtOrAfter(clamped + 0.5).index
+    }
+    const model: AxisModel = {
+        count,
+        sizeOf: (index) => tree.get(index),
+        offsetOf,
+        indexAt,
+        totalSize: () => tree.getTotal(),
+        resize: (index, size) => {
+            if (!(Number.isFinite(size) && size >= 0)) {
+                throw new RangeError(`[spreadsheet] resize requires a finite size >= 0, received ${size}`)
+            }
+            // hiddenCount は 0 ↔ 正の遷移で ±1 (丸め後の格納サイズ同士の比較 — §5.4(b))
+            const next = Math.round(size)
+            const prev = tree.get(index)
+            if ((prev === 0) !== (next === 0)) {
+                hidden += next === 0 ? 1 : -1
+            }
+            // 戻り値は設けない (総寸法は totalSize() を読む — update の返り値に依存した契約を作らない)
+            tree.update(index, next)
+        },
+        hiddenCount: () => hidden,
+    }
+    return { key: `${count}:${defaultSize}`, model }
+}
+
+/**
+ * Fenwick-jump visible-track scan (§5.1 — O(log n) even across a 100k hidden run). Forward:
+ * lands on offsetOf(from) + sizeOf(from) (a hidden `from` contributes 0, so the position IS
+ * the next visible track's start and indexAt's boundary rule resolves to it). Deliberately NO
+ * max(1, ·): it would overjump a 1px-wide visible track and falsely report "none visible"
+ * from the last 1px track (an empirically proven off-by-one). Returns null when no visible
+ * track exists in the direction — the caller chooses "stay" or "retry opposite".
+ * Fenwick ジャンプの可視トラック走査 (§5.1 — 10 万連続非表示でも O(log n))。前方は
+ * offsetOf(from) + sizeOf(from) へ着地 (非表示 from は寸法 0 で次可視の開始位置に一致し、
+ * indexAt の境界規則がそのまま次可視へ解決する)。max(1, ·) は幅 1px トラックの飛び越しと
+ * 最終可視 1px での「可視なし」誤報を生むため意図的に使わない。方向に可視が無ければ null。
+ */
+export const nextVisibleIndex = (axis: AxisModel, from: number, step: 1 | -1): number | null => {
+    if (step > 0) {
+        // 自身の区間終端 = 次可視トラックの開始オフセット (整数 px 契約により常に整数)
+        const offset = axis.offsetOf(from) + axis.sizeOf(from)
+        return offset >= axis.totalSize() ? null : axis.indexAt(offset)
+    }
+    // 後方: 自身の開始オフセットの 1px 手前は直前の幅正トラックの区間内部に落ちる
+    const offset = axis.offsetOf(from) - 1
+    return offset < 0 ? null : axis.indexAt(offset)
+}
+
+/**
+ * Enumerates the VISIBLE indices inside [from, to] via Fenwick jumps (§5.4 — the render-window
+ * enumeration primitive: a K-long hidden run inside the window costs O(log n), not O(K)).
+ * Computed once per slice by the callers and closed into the row renderers.
+ * [from, to] 内の可視 index を Fenwick ジャンプで列挙 (§5.4 — 描画ウィンドウ列挙の基本手。
+ * 窓内 K 連続非表示ランのコストは O(K) でなく O(log n))。呼び出し側がスライス 1 回につき
+ * 1 度算出し行レンダラーへ閉じ込める。
+ */
+export const visibleIndicesInRange = (axis: AxisModel, from: number, to: number): number[] => {
+    // 空ウィンドウ (from > to — 全列非表示 / 空軸で列窓が空) は空列挙 (仕様の空結果)
+    if (from > to || axis.count === 0 || axis.totalSize() === 0) {
+        return []
+    }
+    const result: number[] = []
+    // 起点自身が非表示なら次可視へジャンプしてから列挙を始める
+    let index: number | null = axis.sizeOf(from) > 0 ? from : nextVisibleIndex(axis, from, 1)
+    while (index !== null && index <= to) {
+        result.push(index)
+        index = nextVisibleIndex(axis, index, 1)
+    }
+    return result
+}
+
+/**
+ * Axis model hook. The tree lives in a ref-based lazy box keyed by count:defaultSize —
+ * NOT useMemo (React may discard memo caches, silently dropping user resize diffs).
+ * Rebuild on key change intentionally DROPS resize diffs (explicit v0.1 contract). The
+ * FLIP side is also contractual: the key is adapter-independent, so a sheet switch to an
+ * adapter with the SAME count/defaultSize reuses the box and CARRIES resize diffs across
+ * sheets (per-sheet sizes are a Phase 3+ decision — include adapter identity in the key then).
+ *
+ * 軸モデルフック。木は count:defaultSize キーの ref 遅延ボックスに保持 — useMemo は不可
+ * (React はキャッシュを破棄してよく、リサイズ差分が黙って消える)。キー変更時の再構築で
+ * リサイズ差分が消えるのは v0.1 の明示契約。裏面も契約: キーは adapter 非依存のため、同一
+ * count / defaultSize のシート切替ではボックスが再利用されリサイズ差分が持ち越される
+ * (シート別サイズは Phase 3 以降の判断 — その際は adapter identity をキーへ含める)。
+ * initialSizeOf は初回 identity を捕捉し、以後の関数差し替えは無視される
+ * (「initial」の流儀 — 可変ストアを読む安定クロージャは可)。
+ */
+export const useAxisModel = (count: number, defaultSize: number, initialSizeOf?: (index: number) => number): AxisModel => {
+    if (!(Number.isInteger(defaultSize) && defaultSize > 0)) {
+        throw new TypeError(`[spreadsheet] useAxisModel requires a positive integer defaultSize, received ${defaultSize}`)
+    }
+    const capturedInitial = useRef(initialSizeOf).current
+    const box = useRef<{ key: string; model: AxisModel } | null>(null)
+    const key = `${count}:${defaultSize}`
+    if (box.current === null || box.current.key !== key) {
+        // count / defaultSize 変更時のみ再構築 (差分は消える = 明示契約)
+        box.current = buildAxisBox(count, defaultSize, capturedInitial)
+    }
+    return box.current.model
+}

package/src/model/cellAnnotations.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Cell annotation vocabulary (v0.8, ADR-13): the comment-thread types on the read
+ * side (`CellComment` — what `getCellComments` returns) and the write side (`CellCommentInput` —
+ * what `CellPatch.comments` carries), the hyperlink scheme allowlist with its normaliser, and the
+ * whole-row / whole-column range predicates shared by clip serialisation. Comment ids are
+ * CONSUMER-scoped: an input carrying an `id` asks the consumer to keep that comment verbatim, an
+ * input without one is a new comment the consumer stamps (id / author / clock) — this package
+ * never mints an id, an author or a timestamp (the reply UI sends `[...existing, { text }]`, the
+ * paste path strips ids, `null` clears the thread). React-free and total (spec 08 §3).
+ *
+ * セル注釈の語彙 (v0.8、ADR-13): コメントスレッドの読み側型 (`CellComment` — getCellComments の
+ * 戻り) と書き側型 (`CellCommentInput` — CellPatch.comments が運ぶ)、リンクスキーム許可リストと
+ * その正規化、クリップ直列化が共有する全行 / 全列判定。コメント id は consumer スコープ: id つき
+ * 入力は「そのコメントを verbatim に保持」、id なし入力は「新規 (consumer が id / author / 時計を
+ * 刻印)」— パッケージは id も author も時刻も一切採番しない (返信 UI は `[...existing, { text }]`、
+ * paste 経路は id を剥がし、`null` はスレッド消去)。React 非依存・全域関数 (spec 08 §3)。
+ */
+
+import type { CellRange } from "./cellCoord.ts"
+
+/**
+ * One comment as the consumer stores it (read side of `getCellComments`): every field is
+ * present because the consumer stamped it when the comment was created.
+ * consumer が保持するコメント 1 件 (getCellComments の読み側): 作成時に consumer が刻印するため
+ * 全フィールドが揃う。
+ */
+export type CellComment = { id: string; author: string; text: string; createdAt: string }
+
+/**
+ * One comment as written through `CellPatch.comments` (the WHOLE thread travels): `id` present
+ * = keep that existing comment verbatim; `id` absent = a new comment whose id / author /
+ * createdAt the consumer mints (`author` / `createdAt` are carried only when a paste re-plays a
+ * foreign thread). A `CellComment` is assignable to this type as is, so a thread can be spread
+ * into a reply unchanged.
+ * CellPatch.comments で書かれるコメント 1 件 (スレッド全体を運ぶ): `id` あり = その既存コメントを
+ * verbatim に保持、`id` なし = 新規 (id / author / createdAt は consumer が採番 — author /
+ * createdAt は paste が外来スレッドを再生するときだけ載る)。`CellComment` はそのまま代入可能で、
+ * 既存スレッドを返信へ無変更で展開できる。
+ */
+export type CellCommentInput = { id?: string; text: string; author?: string; createdAt?: string }
+
+/** Allowed hyperlink schemes (ADR-10 / DX-9) — a closed set, nothing else is ever navigated. / 許可リンクスキーム (ADR-10 / DX-9) — 閉じた集合、他は決して航行しない。 */
+const HYPERLINK_SCHEMES: ReadonlySet<string> = new Set(["http:", "https:", "mailto:", "tel:"])
+
+/**
+ * Normalises a hyperlink candidate: trims, parses it with the WHATWG URL parser (no base URL —
+ * a relative path, a bare host or an empty string is not a link), keeps only the allow-listed
+ * schemes and returns the parser's serialisation (`href`: scheme and host lower-cased, an
+ * `http(s)` origin gets its `/` path). Anything else is null — dropped at parse time, never
+ * navigated, never substituted.
+ * リンク候補の正規化: トリム → WHATWG URL 解析 (基点 URL なし — 相対パス・裸のホスト・空文字は
+ * リンクでない) → 許可スキームのみ → パーサの直列化 (`href`: スキームとホストは小文字、http(s) の
+ * origin には `/` パスが付く)。他は null — 解析時に落とし、航行も代替もしない。
+ */
+export const normalizeHyperlink = (text: string): string | null => {
+    const trimmed = text.trim()
+    // WHATWG で解析できない文字列 (相対パス・空文字・裸のホスト名・ホスト欠落) はリンクにならない — 基点 URL で補わない
+    if (!URL.canParse(trimmed)) {
+        return null
+    }
+    const url = new URL(trimmed)
+    // 許可スキーム以外 (javascript: / data: / file: / ftp: …) は解析時に落とす — 決して航行しない
+    return HYPERLINK_SCHEMES.has(url.protocol) ? url.href : null
+}
+
+/**
+ * The adapter-read trust boundary for the hyperlink aspect (ADR-10): maps a raw
+ * `getCellHyperlink` result onto the scheme allowlist — `undefined` stays `undefined`, an
+ * unnormalisable URL is treated as link-less (`undefined`: never navigated, never exported into
+ * a clip flavour, never re-committed through `CellPatch.hyperlink`), and a valid one becomes its
+ * canonical href. Every v0.8 read of the aspect goes through here (open seams, the link marker,
+ * the link popover, `readClipCell` and `readFillSource`).
+ * リンク側面のアダプタ読みの信頼境界 (ADR-10): 生の `getCellHyperlink` 結果を許可スキーム集合へ
+ * 写す — `undefined` はそのまま、正規化不能 URL はリンク無し扱い (`undefined`: 航行・クリップ
+ * フレーバーへの書出・`CellPatch.hyperlink` への再確定をしない)、有効 URL は正準 href。v0.8 の
+ * 同側面の読み (開通シーム・リンク指標・link ポップオーバー・`readClipCell`・`readFillSource`)
+ * は全てここを通る。
+ */
+export const normalizeAdapterHyperlink = (raw: string | undefined): string | undefined => {
+    // 側面なし (undefined) はそのまま — 正規化不能だけをリンク無しへ畳む (代替 URL は作らない)
+    if (raw === undefined) {
+        return undefined
+    }
+    const normalized = normalizeHyperlink(raw)
+    return normalized === null ? undefined : normalized
+}
+
+/** Whether the range spans every column (whole rows — e.g. a row-header selection); shared by clip serialisation. / レンジが全列に及ぶか (全行 — 行ヘッダー選択など)。クリップ直列化が共有。 */
+export const isWholeRows = (range: CellRange, colCount: number): boolean => range.startCol === 0 && range.endCol === colCount - 1
+
+/** Whether the range spans every row (whole columns — e.g. a column-header selection); shared by clip serialisation. / レンジが全行に及ぶか (全列 — 列ヘッダー選択など)。クリップ直列化が共有。 */
+export const isWholeCols = (range: CellRange, rowCount: number): boolean => range.startRow === 0 && range.endRow === rowCount - 1

package/src/model/cellCoord.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Coordinate / range / operation vocabulary shared across the whole grid:
+ * cell-coordinate and range pure functions plus the public named unions (SpreadsheetDirection,
+ * SpreadsheetOperation). Every range in the system is a normalized rectangle built via
+ * makeRange.
+ *
+ * 座標・レンジ・操作の語彙: セル座標とレンジの純関数群 + 公開の名前つき union
+ * (SpreadsheetDirection / SpreadsheetOperation)。システム内の全レンジは makeRange で構築
+ * された正規化矩形。
+ */
+
+/** A single cell position (0-based). / 単一セル位置 (0 始まり)。 */
+export type CellCoord = { row: number; col: number }
+
+/**
+ * Grid navigation direction (public vocabulary). Package-prefixed: a bare `Direction` would
+ * clash with consumer-side types of the same name.
+ * グリッド航行方向 (公開語彙)。素の `Direction` は consumer 側の同名型と衝突しやすいため
+ * パッケージ接頭辞つき。
+ */
+export type SpreadsheetDirection = "up" | "down" | "left" | "right"
+
+/**
+ * Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
+ * gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
+ * "paste" / "fill" and, since v0.8, the format commands "format", the self-calculation
+ * commands "calc" and the note / comment / hyperlink / validation writes "annotate"). The write
+ * subset is exactly the non-edit `EditRejection.source` vocabulary (sealed by the type-parity
+ * guard in dataAdapter.spec.ts). Each widening (v0.2 "fill" / "resize", v0.8 the three
+ * command kinds) is a 0.x breaking change for consumers who annotated the callback parameter
+ * with the old inline union — contravariant position.
+ * ADR-12 拒否チャネルの一括操作種別 (公開語彙)。直列化のみのジェスチャ ("copy" / "cut")・
+ * グリッド幾何 ("resize")・**書込**ジェスチャ ("delete" / "paste" / "fill" と、v0.8 からの書式
+ * コマンド "format"・自己計算コマンド "calc"・ノート / コメント / リンク / 検証の書込
+ * "annotate")。書込部分集合は非 edit の `EditRejection.source` 語彙と過不足なく一致
+ * (dataAdapter.spec.ts の型パリティガードが封印)。各拡張 (v0.2 の "fill" / "resize"、v0.8 の
+ * コマンド 3 種) は旧インライン union を明示注釈していた consumer に対する 0.x の破壊枠
+ * (コールバック引数 = 反変位置)。
+ */
+export type SpreadsheetOperation = "copy" | "cut" | "delete" | "paste" | "fill" | "resize" | "format" | "calc" | "annotate"
+
+/**
+ * A normalized rectangular range (startRow <= endRow, startCol <= endCol). Construct ONLY via
+ * {@link makeRange}. / 正規化済み矩形レンジ。必ず {@link makeRange} で構築。
+ */
+export type CellRange = { startRow: number; startCol: number; endRow: number; endCol: number }
+
+/** A rectangle in logical px. / 論理 px の矩形。 */
+export type LogicalRect = { top: number; left: number; width: number; height: number }
+
+/** Builds a normalized range from two corners. / 2 隅から正規化レンジを構築。 */
+export const makeRange = (a: CellCoord, b: CellCoord): CellRange => ({
+    startRow: Math.min(a.row, b.row),
+    endRow: Math.max(a.row, b.row),
+    startCol: Math.min(a.col, b.col),
+    endCol: Math.max(a.col, b.col),
+})
+
+/** Whether the range contains the cell. / レンジがセルを含むか。 */
+export const rangeContains = (range: CellRange, cell: CellCoord): boolean => cell.row >= range.startRow && cell.row <= range.endRow && cell.col >= range.startCol && cell.col <= range.endCol
+
+/** Row/column extents of a range. / レンジの行数・列数。 */
+export const rangeSize = (range: CellRange): { rows: number; cols: number } => ({
+    rows: range.endRow - range.startRow + 1,
+    cols: range.endCol - range.startCol + 1,
+})
+
+/** Total cell count across ranges WITHOUT materializing. / 実体化せずレンジ群の総セル数を見積もる (重複は重複のまま数え、上限判定を保守側に倒す)。 */
+export const countRangeCells = (ranges: readonly CellRange[]): number => ranges.reduce((sum, r) => sum + rangeSize(r).rows * rangeSize(r).cols, 0)
+
+/**
+ * Enumerates the union of ranges exactly once per cell (row-major).
+ * レンジ群の和集合をセル単位で**重複なく**行優先順に列挙する単一シーム。Delete のような
+ * 「レンジ列挙由来」の編集で同一セルの無意味な二重編集を作らないためのもの (cut → paste が
+ * **意図的に**積む重複 (後勝ち) とは別問題 — そちらは applyEdits の順序契約が扱う)。
+ */
+export const enumerateRangeCells = (ranges: readonly CellRange[], visit: (cell: CellCoord) => void): void => {
+    if (ranges.length === 1) {
+        // 最頻ケース (単一レンジ) は Set を作らない高速路
+        const r = ranges[0]
+        for (let row = r.startRow; row <= r.endRow; row += 1) {
+            for (let col = r.startCol; col <= r.endCol; col += 1) {
+                visit({ row, col })
+            }
+        }
+        return
+    }
+    const seen = new Set<string>()
+    for (const r of ranges) {
+        for (let row = r.startRow; row <= r.endRow; row += 1) {
+            for (let col = r.startCol; col <= r.endCol; col += 1) {
+                const key = `${row}:${col}`
+                if (!seen.has(key)) {
+                    seen.add(key)
+                    visit({ row, col })
+                }
+            }
+        }
+    }
+}
+
+/** Clamps a coordinate into grid bounds (fail-fast on empty grid). / 空グリッドは throw のクランプ。 */
+export const clampCoord = (cell: CellCoord, rowCount: number, colCount: number): CellCoord => {
+    if (rowCount <= 0 || colCount <= 0) {
+        throw new RangeError(`[spreadsheet] clampCoord requires a non-empty grid, received ${rowCount} x ${colCount}`)
+    }
+    return {
+        row: Math.min(Math.max(Math.trunc(cell.row), 0), rowCount - 1),
+        col: Math.min(Math.max(Math.trunc(cell.col), 0), colCount - 1),
+    }
+}
+
+/** Structural equality of two coordinates. / 2 座標の構造等価。 */
+export const coordEquals = (a: CellCoord, b: CellCoord): boolean => a.row === b.row && a.col === b.col