sfora-cli 0.9.0 → 0.11.0

package/dist/format/sheetCellSpans.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+/** One cell's trimmed content, addressed in the block source. */
+export type SheetCellSpan = {
+    /** Offset of the first byte of trimmed content. */
+    start: number;
+    /** Offset just past the last byte. `start === end` for an empty cell. */
+    end: number;
+    /** The text the reader shows — the same string `parseSheet` reports. */
+    text: string;
+};
+/** One source line's cells, plus where a missing trailing cell would go. */
+export type SheetRowSpan = {
+    /** Cells present in the source. May be shorter than the column count. */
+    cells: SheetCellSpan[];
+    /** End-of-line offset, where a short row grows. */
+    appendAt: number;
+    /** Whether the line closes with a pipe, which decides the append shape. */
+    trailingPipe: boolean;
+};
+export type SheetCellGrid = {
+    columns: number;
+    header: SheetRowSpan;
+    rows: SheetRowSpan[];
+};
+/**
+ * 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 declare function sheetCellGrid(source: string): SheetCellGrid | null;
+/**
+ * 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 declare function encodeSheetCell(value: string): string;
+export type SheetWriteResult = {
+    ok: true;
+    source: string;
+    /** The value as the reader will now show it, after normalization. */
+    value: string;
+    /** False when the write was a no-op — `source` is then the input string. */
+    changed: boolean;
+    /** True when a line break or padding was collapsed to fit a row. */
+    normalized: boolean;
+} | {
+    ok: false;
+    reason: "no-grid" | "row-out-of-range" | "column-out-of-range";
+    /** Always the untouched input, so a caller can assign unconditionally. */
+    source: string;
+};
+/**
+ * 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 declare function writeSheetCell(source: string, rowIndex: number, columnIndex: number, value: string): SheetWriteResult;

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";