sfora-cli 0.10.0 → 0.12.0

package/dist/format/sheetCellSpans.js

@@ -0,0 +1,223 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * Where every sheet cell lives in the authored bytes.
+ *
+ * `parseSheet` hands the reader a grid of DECODED strings — trimmed, escapes
+ * resolved, short rows padded. That is the right shape to draw and the wrong
+ * shape to write back through: re-serializing the whole grid from it would
+ * rewrite the author's column padding, their outer pipes, their delimiter row,
+ * every byte they lined up by hand.
+ *
+ * So an edit is a splice, not a re-serialization. This module answers "which
+ * byte range is that cell?" and writes a single cell in place. Everything the
+ * author wrote outside the edited cell survives untouched, which is what makes
+ * the no-op case byte-identical by construction rather than by luck:
+ * `writeSheetCell(source, r, c, currentText)` returns the same string back.
+ *
+ * The escape rules here are a second reading of the same grammar `sheetCells`
+ * in `blocks/parsers.ts` reads, and a second reading is only trustworthy if
+ * something checks it against the first. `sheetCellSpans.test.ts` does: every
+ * span's slice is fed back through `parseSheet` and must equal the cell the
+ * parser reports. A divergence is a test failure, never a silent misalignment.
+ *
+ * The CODE-SPAN half is no longer a second reading at all. While this module
+ * lived in `src/components/editor/` it could not reach the engine's private
+ * helpers, so it carried a hand-rolled `codeSpanMask` that closed a backtick
+ * run with `indexOf` — which lets a longer run close a shorter one, where
+ * CommonMark (and `lineGeometry.codeSpanMask`, which `sheetCells` uses) wants
+ * the closing run to be exactly as long as the opening one. Moving the file
+ * into the engine (board card #278) retires the copy: both readings of "where
+ * are the code spans" are now the one function, so the two cannot drift.
+ */
+import { isSheetRow, parseSheet } from "./blocks/parsers.js";
+import { codeSpanMask } from "./lineGeometry.js";
+const ASCII_PUNCTUATION = /[!-/:-@[-`{-~]/;
+const SHEET_SEPARATOR_CELL = /^:?-+:?$/;
+function isEscapedAt(text, index) {
+    let backslashes = 0;
+    for (let i = index - 1; i >= 0 && text[i] === "\\"; i--)
+        backslashes++;
+    return backslashes % 2 === 1;
+}
+/**
+ * Split one already-trimmed row into the byte ranges between its delimiters.
+ * Offsets are relative to `line`; the caller shifts them into the source.
+ */
+function rowCells(line) {
+    let from = 0;
+    let to = line.length;
+    if (line.startsWith("|"))
+        from = 1;
+    const trailingPipe = line.endsWith("|") && !isEscapedAt(line, line.length - 1);
+    if (trailingPipe)
+        to = line.length - 1;
+    const content = line.slice(from, to);
+    const inCode = codeSpanMask(content);
+    const cells = [];
+    let cellStart = 0;
+    for (let i = 0; i < content.length; i++) {
+        const character = content[i];
+        if (character === "\\") {
+            const next = content[i + 1];
+            // Same rule as the engine: `\|` is a literal pipe even inside a code
+            // span; every other escape belongs to inline parsing and stops there.
+            if (next === "|" || (next !== undefined && !inCode[i] && ASCII_PUNCTUATION.test(next))) {
+                i++;
+            }
+            continue;
+        }
+        if (character === "|" && !inCode[i]) {
+            cells.push({ start: cellStart, end: i });
+            cellStart = i + 1;
+            continue;
+        }
+    }
+    cells.push({ start: cellStart, end: content.length });
+    return {
+        cells: cells.map((cell) => ({ start: cell.start + from, end: cell.end + from })),
+        trailingPipe,
+    };
+}
+function sourceLines(source) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i <= source.length; i++) {
+        if (i === source.length || source[i] === "\n") {
+            let end = i;
+            if (end > start && source[end - 1] === "\r")
+                end -= 1;
+            out.push({ start, end, text: source.slice(start, end) });
+            start = i + 1;
+        }
+    }
+    return out;
+}
+/** Trim a raw range in place, so the author's padding stays outside the span. */
+function trimRange(source, start, end) {
+    let from = start;
+    let to = end;
+    while (from < to && /\s/.test(source[from]))
+        from++;
+    while (to > from && /\s/.test(source[to - 1]))
+        to--;
+    return { start: from, end: to };
+}
+function rowSpan(source, line, texts) {
+    const trimmed = line.text.trim();
+    const lead = line.text.length - line.text.trimStart().length;
+    const base = line.start + lead;
+    const { cells, trailingPipe } = rowCells(trimmed);
+    return {
+        cells: cells.map((cell, index) => {
+            const range = trimRange(source, base + cell.start, base + cell.end);
+            return { start: range.start, end: range.end, text: texts[index] ?? source.slice(range.start, range.end) };
+        }),
+        appendAt: base + trimmed.length,
+        trailingPipe,
+    };
+}
+/**
+ * Build the source-anchored grid, or null when the source is not a sheet the
+ * reader would draw — the same null the renderer already falls back on.
+ *
+ * The cell TEXTS come from `parseSheet`, never from this file's own decoding:
+ * one reader of the grammar owns what a cell says, and this module only owns
+ * where it sits. When the two disagree about how many cells the header has,
+ * the grid degrades to null instead of handing back a misaligned map.
+ */
+export function sheetCellGrid(source) {
+    const data = parseSheet(source);
+    if (!data)
+        return null;
+    const lines = sourceLines(source).filter((line) => {
+        const text = line.text.trim();
+        return text.length > 0 && isSheetRow(text);
+    });
+    if (lines.length < 2)
+        return null;
+    const headerSpan = rowSpan(source, lines[0], data.columns.map((column) => column.label));
+    if (headerSpan.cells.length !== data.columns.length)
+        return null;
+    const separatorCells = rowCells(lines[1].text.trim()).cells;
+    const hasSeparator = separatorCells.length === data.columns.length &&
+        separatorCells.every((cell) => {
+            const trimmed = lines[1].text.trim().slice(cell.start, cell.end).trim();
+            return SHEET_SEPARATOR_CELL.test(trimmed);
+        });
+    const bodyLines = lines.slice(hasSeparator ? 2 : 1);
+    if (bodyLines.length !== data.rows.length)
+        return null;
+    return {
+        columns: data.columns.length,
+        header: headerSpan,
+        rows: bodyLines.map((line, index) => rowSpan(source, line, data.rows[index])),
+    };
+}
+/**
+ * Encode a value for a table cell.
+ *
+ * The inverse of the engine's decoding over the alphabet that decoding
+ * touches: `\` and `|`. Everything else is left as the author typed it —
+ * the sheet renders cell text literally, so nothing else needs a spelling.
+ * A row cannot hold a line break, so whitespace runs collapse to one space.
+ */
+export function encodeSheetCell(value) {
+    return value.replace(/\s+/g, " ").trim().replace(/[\\|]/g, (match) => `\\${match}`);
+}
+/**
+ * Write one cell and return the whole block source back.
+ *
+ * Total by construction: every refusal names itself, nothing returns
+ * `undefined`, and the unchanged source always comes back on the result so a
+ * caller cannot accidentally drop the document by not checking `ok`.
+ */
+export function writeSheetCell(source, rowIndex, columnIndex, value) {
+    const grid = sheetCellGrid(source);
+    if (!grid)
+        return { ok: false, reason: "no-grid", source };
+    if (rowIndex < 0 || rowIndex >= grid.rows.length) {
+        return { ok: false, reason: "row-out-of-range", source };
+    }
+    if (columnIndex < 0 || columnIndex >= grid.columns) {
+        return { ok: false, reason: "column-out-of-range", source };
+    }
+    const encoded = encodeSheetCell(value);
+    const shown = decodeForDisplay(encoded);
+    const normalized = shown !== value;
+    const row = grid.rows[rowIndex];
+    const current = row.cells[columnIndex];
+    // The no-op door. Nothing is spliced, so the bytes cannot drift — this is
+    // why the round trip is identity and not merely "usually identity". An
+    // absent cell in a short row counts: the reader already draws it as empty,
+    // so writing empty into it is asking for what is already true.
+    const shown0 = current ? current.text : "";
+    if (shown0 === value) {
+        return { ok: true, source, value, changed: false, normalized: false };
+    }
+    if (current) {
+        const next = source.slice(0, current.start) + encoded + source.slice(current.end);
+        return { ok: true, source: next, value: shown, changed: next !== source, normalized };
+    }
+    // A short row: grow it to reach the column, rather than refusing an edit the
+    // reader already drew as an empty cell.
+    const additions = [];
+    for (let index = row.cells.length; index <= columnIndex; index++) {
+        additions.push(index === columnIndex ? encoded : "");
+    }
+    const inserted = additions
+        .map((cell) => row.trailingPipe
+        ? cell
+            ? ` ${cell} |`
+            : " |"
+        : cell
+            ? ` | ${cell}`
+            : " |")
+        .join("");
+    const next = source.slice(0, row.appendAt) + inserted + source.slice(row.appendAt);
+    return { ok: true, source: next, value: shown, changed: true, normalized };
+}
+/** What the reader will show for bytes this module just wrote. */
+function decodeForDisplay(encoded) {
+    return encoded.replace(/\\([\\|])/g, "$1");
+}

package/dist/format/sheetSelection.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Keyboard-first selection for the sheet block.
+ *
+ * The shape is BlockSuite's data-view model, kept because it earns its keep: a
+ * selection is a plain serializable VALUE — a focus coordinate plus a rung —
+ * not a DOM range, not a set of element references. That is what lets the same
+ * selection survive a re-render, a re-parse of the block source, a round trip
+ * through JSON, and (later) a collaborative cursor. Reference:
+ * context/AFFiNE/blocksuite/affine/data-view/src/view-presets/table/selection.ts
+ * and .../table/pc/controller/hotkeys.ts.
+ *
+ * Three of their behaviours are deliberately NOT copied.
+ *
+ * 1. The inescapable Escape loop. In their hotkeys, Escape on a cell promotes
+ *    to row selection and Escape on a row selection converts the rows straight
+ *    back into an area selection — the two rungs trade places forever and the
+ *    table never lets go. Here Escape walks a strictly decreasing ladder
+ *    (editing → cell → row → none) and then reports `ignored` so the key
+ *    belongs to whatever encloses the block. `selectionRung` is the proof
+ *    obligation: every Escape lowers it, so the walk terminates.
+ *
+ * 2. Tab dead-ending. Theirs wraps to the next row and stops moving at the last
+ *    cell while still swallowing the key, so a keyboard user is trapped in the
+ *    grid with no way forward. Here Tab past the last cell RELEASES — the
+ *    caller lets the browser move focus on — and the selection value is left
+ *    intact so tabbing back in lands where you left.
+ *
+ * 3. Silent undefined. Their cell lookups go through a DOM query that returns
+ *    `undefined` and the handler simply does nothing, so a coordinate that has
+ *    drifted out of range is indistinguishable from a key that did nothing.
+ *    This reducer is total: coordinates are clamped against the shape on every
+ *    transition, and every call returns a named outcome.
+ */
+/** How many body rows and columns the block is currently drawing. */
+export type SheetShape = {
+    rows: number;
+    columns: number;
+};
+export type SheetSelection = {
+    kind: "none";
+} | {
+    kind: "row";
+    rowIndex: number;
+} | {
+    kind: "cell";
+    rowIndex: number;
+    columnIndex: number;
+    isEditing: boolean;
+};
+export declare const SHEET_SELECTION_NONE: SheetSelection;
+/**
+ * The ladder rung. Escape lowers it by exactly one, which is the whole reason
+ * the Escape walk terminates rather than ping-ponging.
+ */
+export declare function selectionRung(selection: SheetSelection): 0 | 1 | 2 | 3;
+export type SheetAction = {
+    type: "focusCell";
+    rowIndex: number;
+    columnIndex: number;
+    edit?: boolean;
+} | {
+    type: "move";
+    direction: "up" | "down" | "left" | "right";
+} | {
+    type: "step";
+    direction: "forward" | "back";
+} | {
+    type: "enter";
+} | {
+    type: "escape";
+} | {
+    type: "typeChar";
+    char: string;
+} | {
+    type: "clear";
+} | {
+    type: "commit";
+    value: string;
+    then: "stay" | "down" | "forward" | "back";
+} | {
+    type: "release";
+};
+export type SheetOutcome = 
+/** The block consumed the key. */
+"handled"
+/** The block is done: focus should move to the next thing after it. */
+ | "released-forward"
+/** The block is done: focus should move to the thing before it. */
+ | "released-back"
+/** Not ours — let the key bubble to whatever encloses the block. */
+ | "ignored";
+/** A write the caller must apply to the block source. */
+export type SheetWrite = {
+    rowIndex: number;
+    columnIndex: number;
+    value: string;
+};
+export type SheetTransition = {
+    selection: SheetSelection;
+    outcome: SheetOutcome;
+    /** Null unless the transition changed a cell's value. */
+    write: SheetWrite | null;
+    /** The text an opening editor starts with, or null when none opens. */
+    draft: string | null;
+};
+export type SheetContext = {
+    shape: SheetShape;
+    /** The current text of a cell. Total: out-of-range reads answer "". */
+    read: (rowIndex: number, columnIndex: number) => string;
+};
+/**
+ * Re-seat a selection against a new shape. The block source can change under
+ * the selection — an agent writes a row, a paste shortens one — and the value
+ * has to stay meaningful without being thrown away.
+ */
+export declare function reseatSelection(selection: SheetSelection, shape: SheetShape): SheetSelection;
+export declare function sheetSelectionReducer(selection: SheetSelection, action: SheetAction, context: SheetContext): SheetTransition;
+/**
+ * A keyboard event, read as an action. Split from the reducer so the key map
+ * is a table a test can walk without a DOM.
+ *
+ * Returns null for keys the block has no opinion about, which is the same
+ * statement as `ignored` — nothing here silently swallows a key.
+ */
+export declare function sheetKeyAction(event: {
+    key: string;
+    shiftKey?: boolean;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+}): SheetAction | null;
+/**
+ * Where Enter should land after committing an edit — down a row, matching
+ * every spreadsheet. Kept as a named function so the hook and its test agree.
+ */
+export declare const ENTER_COMMIT_LANDING: "down";

package/dist/format/sheetSelection.js

@@ -0,0 +1,282 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * Keyboard-first selection for the sheet block.
+ *
+ * The shape is BlockSuite's data-view model, kept because it earns its keep: a
+ * selection is a plain serializable VALUE — a focus coordinate plus a rung —
+ * not a DOM range, not a set of element references. That is what lets the same
+ * selection survive a re-render, a re-parse of the block source, a round trip
+ * through JSON, and (later) a collaborative cursor. Reference:
+ * context/AFFiNE/blocksuite/affine/data-view/src/view-presets/table/selection.ts
+ * and .../table/pc/controller/hotkeys.ts.
+ *
+ * Three of their behaviours are deliberately NOT copied.
+ *
+ * 1. The inescapable Escape loop. In their hotkeys, Escape on a cell promotes
+ *    to row selection and Escape on a row selection converts the rows straight
+ *    back into an area selection — the two rungs trade places forever and the
+ *    table never lets go. Here Escape walks a strictly decreasing ladder
+ *    (editing → cell → row → none) and then reports `ignored` so the key
+ *    belongs to whatever encloses the block. `selectionRung` is the proof
+ *    obligation: every Escape lowers it, so the walk terminates.
+ *
+ * 2. Tab dead-ending. Theirs wraps to the next row and stops moving at the last
+ *    cell while still swallowing the key, so a keyboard user is trapped in the
+ *    grid with no way forward. Here Tab past the last cell RELEASES — the
+ *    caller lets the browser move focus on — and the selection value is left
+ *    intact so tabbing back in lands where you left.
+ *
+ * 3. Silent undefined. Their cell lookups go through a DOM query that returns
+ *    `undefined` and the handler simply does nothing, so a coordinate that has
+ *    drifted out of range is indistinguishable from a key that did nothing.
+ *    This reducer is total: coordinates are clamped against the shape on every
+ *    transition, and every call returns a named outcome.
+ */
+export const SHEET_SELECTION_NONE = { kind: "none" };
+/**
+ * The ladder rung. Escape lowers it by exactly one, which is the whole reason
+ * the Escape walk terminates rather than ping-ponging.
+ */
+export function selectionRung(selection) {
+    if (selection.kind === "none")
+        return 0;
+    if (selection.kind === "row")
+        return 1;
+    return selection.isEditing ? 3 : 2;
+}
+function clamp(value, max) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > max)
+        return max;
+    return value;
+}
+function inShape(shape) {
+    return shape.rows > 0 && shape.columns > 0;
+}
+/** Every coordinate that leaves this module has been pulled back in range. */
+function normalize(selection, shape) {
+    if (!inShape(shape))
+        return SHEET_SELECTION_NONE;
+    if (selection.kind === "row") {
+        return { kind: "row", rowIndex: clamp(selection.rowIndex, shape.rows - 1) };
+    }
+    if (selection.kind === "cell") {
+        return {
+            kind: "cell",
+            rowIndex: clamp(selection.rowIndex, shape.rows - 1),
+            columnIndex: clamp(selection.columnIndex, shape.columns - 1),
+            isEditing: selection.isEditing,
+        };
+    }
+    return selection;
+}
+/**
+ * Re-seat a selection against a new shape. The block source can change under
+ * the selection — an agent writes a row, a paste shortens one — and the value
+ * has to stay meaningful without being thrown away.
+ */
+export function reseatSelection(selection, shape) {
+    return normalize(selection, shape);
+}
+function stay(selection, outcome = "handled") {
+    return { selection, outcome, write: null, draft: null };
+}
+/** Linear cell index, so Tab is one arithmetic step and its edges are obvious. */
+function linearIndex(rowIndex, columnIndex, shape) {
+    return rowIndex * shape.columns + columnIndex;
+}
+export function sheetSelectionReducer(selection, action, context) {
+    const shape = context.shape;
+    if (!inShape(shape))
+        return stay(SHEET_SELECTION_NONE, "ignored");
+    const current = normalize(selection, shape);
+    switch (action.type) {
+        case "focusCell": {
+            const next = normalize({
+                kind: "cell",
+                rowIndex: action.rowIndex,
+                columnIndex: action.columnIndex,
+                isEditing: action.edit === true,
+            }, shape);
+            const draft = next.kind === "cell" && next.isEditing ? context.read(next.rowIndex, next.columnIndex) : null;
+            return { selection: next, outcome: "handled", write: null, draft };
+        }
+        case "release":
+            return stay(SHEET_SELECTION_NONE);
+        case "move": {
+            if (current.kind === "none") {
+                return {
+                    selection: { kind: "cell", rowIndex: 0, columnIndex: 0, isEditing: false },
+                    outcome: "handled",
+                    write: null,
+                    draft: null,
+                };
+            }
+            if (current.kind === "row") {
+                // A row is a whole-row rung: up and down walk rows, right steps back
+                // into the row's first cell. Left has nothing lower to go to.
+                if (action.direction === "up" || action.direction === "down") {
+                    const delta = action.direction === "up" ? -1 : 1;
+                    return stay(normalize({ kind: "row", rowIndex: current.rowIndex + delta }, shape));
+                }
+                if (action.direction === "right") {
+                    return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+                }
+                return stay(current);
+            }
+            // Arrows inside an open editor belong to the caret, not to the grid.
+            if (current.isEditing)
+                return stay(current, "ignored");
+            const rowDelta = action.direction === "up" ? -1 : action.direction === "down" ? 1 : 0;
+            const columnDelta = action.direction === "left" ? -1 : action.direction === "right" ? 1 : 0;
+            // Arrows clamp at the edges rather than wrapping: an arrow key names a
+            // direction on the grid, and wrapping would make it name a different one.
+            return stay(normalize({
+                kind: "cell",
+                rowIndex: current.rowIndex + rowDelta,
+                columnIndex: current.columnIndex + columnDelta,
+                isEditing: false,
+            }, shape));
+        }
+        case "step": {
+            if (current.kind === "none") {
+                const first = action.direction === "forward"
+                    ? { rowIndex: 0, columnIndex: 0 }
+                    : { rowIndex: shape.rows - 1, columnIndex: shape.columns - 1 };
+                return stay({ kind: "cell", ...first, isEditing: false });
+            }
+            if (current.kind === "row") {
+                return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+            }
+            const total = shape.rows * shape.columns;
+            const index = linearIndex(current.rowIndex, current.columnIndex, shape);
+            const nextIndex = action.direction === "forward" ? index + 1 : index - 1;
+            if (nextIndex < 0 || nextIndex >= total) {
+                // The grid is finished with the key. The coordinate is KEPT — tabbing
+                // back in returns to the cell you left, which is the whole reason not
+                // to dead-end here.
+                return stay({ kind: "cell", rowIndex: current.rowIndex, columnIndex: current.columnIndex, isEditing: false }, action.direction === "forward" ? "released-forward" : "released-back");
+            }
+            return stay({
+                kind: "cell",
+                rowIndex: Math.floor(nextIndex / shape.columns),
+                columnIndex: nextIndex % shape.columns,
+                isEditing: false,
+            });
+        }
+        case "enter": {
+            if (current.kind === "none") {
+                return stay({ kind: "cell", rowIndex: 0, columnIndex: 0, isEditing: false });
+            }
+            if (current.kind === "row") {
+                return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+            }
+            if (current.isEditing) {
+                // Committing is the caller's job — it holds the draft. Enter only says
+                // where to land afterwards.
+                return stay(current, "handled");
+            }
+            return {
+                selection: { ...current, isEditing: true },
+                outcome: "handled",
+                write: null,
+                draft: context.read(current.rowIndex, current.columnIndex),
+            };
+        }
+        case "escape": {
+            if (current.kind === "none")
+                return stay(current, "ignored");
+            if (current.kind === "row")
+                return stay(SHEET_SELECTION_NONE);
+            if (current.isEditing) {
+                // Escape discards. No write leaves this branch, which is what makes
+                // "Escape returns to cell selection" safe to press on a typo.
+                return stay({ ...current, isEditing: false });
+            }
+            return stay({ kind: "row", rowIndex: current.rowIndex });
+        }
+        case "typeChar": {
+            if (current.kind !== "cell" || current.isEditing)
+                return stay(current, "ignored");
+            if (action.char.length !== 1)
+                return stay(current, "ignored");
+            // Typing REPLACES: the draft starts as the character, not as the cell.
+            return {
+                selection: { ...current, isEditing: true },
+                outcome: "handled",
+                write: null,
+                draft: action.char,
+            };
+        }
+        case "clear": {
+            if (current.kind !== "cell" || current.isEditing)
+                return stay(current, "ignored");
+            return {
+                selection: current,
+                outcome: "handled",
+                write: { rowIndex: current.rowIndex, columnIndex: current.columnIndex, value: "" },
+                draft: null,
+            };
+        }
+        case "commit": {
+            if (current.kind !== "cell")
+                return stay(current, "ignored");
+            const write = {
+                rowIndex: current.rowIndex,
+                columnIndex: current.columnIndex,
+                value: action.value,
+            };
+            if (action.then === "stay") {
+                return { selection: { ...current, isEditing: false }, outcome: "handled", write, draft: null };
+            }
+            if (action.then === "down") {
+                const next = normalize({ kind: "cell", rowIndex: current.rowIndex + 1, columnIndex: current.columnIndex, isEditing: false }, shape);
+                return { selection: next, outcome: "handled", write, draft: null };
+            }
+            const stepped = sheetSelectionReducer({ ...current, isEditing: false }, { type: "step", direction: action.then === "forward" ? "forward" : "back" }, context);
+            return { selection: stepped.selection, outcome: stepped.outcome, write, draft: null };
+        }
+    }
+}
+/**
+ * A keyboard event, read as an action. Split from the reducer so the key map
+ * is a table a test can walk without a DOM.
+ *
+ * Returns null for keys the block has no opinion about, which is the same
+ * statement as `ignored` — nothing here silently swallows a key.
+ */
+export function sheetKeyAction(event) {
+    const modified = event.metaKey === true || event.ctrlKey === true || event.altKey === true;
+    switch (event.key) {
+        case "ArrowUp":
+            return modified ? null : { type: "move", direction: "up" };
+        case "ArrowDown":
+            return modified ? null : { type: "move", direction: "down" };
+        case "ArrowLeft":
+            return modified ? null : { type: "move", direction: "left" };
+        case "ArrowRight":
+            return modified ? null : { type: "move", direction: "right" };
+        case "Tab":
+            return modified ? null : { type: "step", direction: event.shiftKey ? "back" : "forward" };
+        case "Enter":
+            return modified ? null : { type: "enter" };
+        case "Escape":
+            return { type: "escape" };
+        case "Backspace":
+        case "Delete":
+            return modified ? null : { type: "clear" };
+        default:
+            if (!modified && event.key.length === 1)
+                return { type: "typeChar", char: event.key };
+            return null;
+    }
+}
+/**
+ * Where Enter should land after committing an edit — down a row, matching
+ * every spreadsheet. Kept as a named function so the hook and its test agree.
+ */
+export const ENTER_COMMIT_LANDING = "down";

package/dist/format/textStats.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Document statistics for editor footers.
+ *
+ * Word counting splits with `Intl.Segmenter` where it exists: whitespace
+ * splitting reports one word for an entire Chinese or Japanese sentence, which
+ * is the bug open-knowledge's `selection-stats.ts` fixes the same way. The
+ * fallback keeps that property by counting CJK ideographs individually.
+ *
+ * Token count is a chars/4 heuristic, not a tokenizer — always render it with a
+ * leading `~` so it never reads as exact.
+ */
+/**
+ * Words in a chunk of Markdown. Punctuation-only segments (`#`, `*`, `|`) are
+ * not word-like, so Markdown syntax drops out without a stripping pass.
+ */
+export declare function countWords(text: string): number;
+/** Rough token count: ~4 characters per token, the usual English-prose ratio. */
+export declare function estimateTokens(text: string): number;
+export type DocumentStats = {
+    words: number;
+    tokens: number;
+};
+export declare function documentStats(text: string): DocumentStats;