@k2b/editor 0.0.0-stage → 0.1.0

package/src/markdown/sub-sup.ts

@@ -0,0 +1,115 @@
+/**
+ * Subscript and Superscript extension for CodeMirror.
+ *
+ *     H~2~O           ← `~2~` rendered with `vertical-align: sub`
+ *     E=mc^2^         ← `^2^` rendered with `vertical-align: super`
+ *
+ * The lezer markdown parser doesn't model these, so we scan the doc with
+ * regex and decorate inner spans. Markers stay visible (KISS — same as
+ * `==mark==`); the visual sub/super-shift is enough signal.
+ *
+ * Carefully scoped regexes:
+ *  - subscript: a single `~`, the inner content has no whitespace or `~`,
+ *    closing `~` not adjacent to another `~`. Avoids stomping on
+ *    GFM strikethrough (`~~text~~`).
+ *  - superscript: a single `^`, no whitespace, closing `^`.
+ */
+
+import type { EditorState, Extension, Range, Transaction } from "@codemirror/state";
+import { RangeSet, StateField } from "@codemirror/state";
+import type { DecorationSet } from "@codemirror/view";
+import { Decoration, EditorView } from "@codemirror/view";
+import { SUB_REGEX, SUP_REGEX } from "./_lib/inline-syntax";
+
+const subDecoration = Decoration.mark({ class: "cm-subscript" });
+const supDecoration = Decoration.mark({ class: "cm-superscript" });
+
+type SubSupState = {
+  decorations: DecorationSet;
+  ranges: Array<{ from: number; to: number }>;
+};
+
+const findSubSup = (state: EditorState): SubSupState => {
+  const decorations: Range<Decoration>[] = [];
+  const ranges: Array<{ from: number; to: number }> = [];
+  const text = state.doc.toString();
+  for (const match of text.matchAll(SUB_REGEX)) {
+    if (match.index === undefined) continue;
+    const from = match.index;
+    const to = match.index + match[0].length;
+    decorations.push(subDecoration.range(from, to));
+    ranges.push({ from, to });
+  }
+  for (const match of text.matchAll(SUP_REGEX)) {
+    if (match.index === undefined) continue;
+    const from = match.index;
+    const to = match.index + match[0].length;
+    decorations.push(supDecoration.range(from, to));
+    ranges.push({ from, to });
+  }
+  // Decorations must be in document order for RangeSet.of(..., true).
+  decorations.sort((a, b) => a.from - b.from);
+  ranges.sort((a, b) => a.from - b.from);
+  return { decorations: RangeSet.of(decorations, true), ranges };
+};
+
+const intersectsRanges = (ranges: Array<{ from: number; to: number }>, from: number, to: number): boolean =>
+  ranges.some((range) => from <= range.to && to >= range.from);
+
+const changesMightAffectSubSup = (tr: Transaction, ranges: Array<{ from: number; to: number }>): boolean => {
+  let might = false;
+  tr.changes.iterChanges((fromA, toA, fromB, toB, inserted) => {
+    if (might) return;
+    if (intersectsRanges(ranges, fromA, toA)) {
+      might = true;
+      return;
+    }
+    if (/[~^]/.test(inserted.toString())) {
+      might = true;
+      return;
+    }
+    const from = Math.max(0, fromB - 2);
+    const to = Math.min(tr.state.doc.length, toB + 2);
+    might = /[~^]/.test(tr.state.doc.sliceString(from, to));
+  });
+  return might;
+};
+
+const mapRanges = (tr: Transaction, ranges: Array<{ from: number; to: number }>): Array<{ from: number; to: number }> =>
+  ranges
+    .map((range) => ({
+      from: tr.changes.mapPos(range.from, 1),
+      to: tr.changes.mapPos(range.to, -1),
+    }))
+    .filter((range) => range.from < range.to);
+
+export const subSupExtension = (): Extension => {
+  const stateField = StateField.define<SubSupState>({
+    create(state) {
+      return findSubSup(state);
+    },
+    update(value, tr) {
+      if (tr.docChanged) {
+        if (changesMightAffectSubSup(tr, value.ranges)) return findSubSup(tr.state);
+        return { decorations: value.decorations.map(tr.changes), ranges: mapRanges(tr, value.ranges) };
+      }
+      return value;
+    },
+    provide(field) {
+      return EditorView.decorations.from(field, (value) => value.decorations);
+    },
+  });
+
+  const theme = EditorView.theme({
+    ".cm-subscript": {
+      verticalAlign: "sub",
+      fontSize: "0.75em",
+    },
+    ".cm-superscript": {
+      verticalAlign: "super",
+      fontSize: "0.75em",
+    },
+  });
+
+  return [stateField, theme];
+};

package/src/markdown/surface-press.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a press on the note's surface missed the editor, so the surface puts the caret at the end of the note.
+ *
+ * A press the editor already handled did not miss it, even when handling it replaced the pressed element: ticking a
+ * checklist box redraws the box, so by the time the press reaches the surface its target is no longer inside the
+ * editor. Treating that press as a miss would move the caret to the end and scroll the note there. A press on the
+ * comments beside the text belongs to them, not to the text.
+ * Shared-editor chrome, including preserved-input fields outside `.cm-editor`, keeps its native interaction too.
+ */
+export const pressMissedEditor = (event: MouseEvent): boolean =>
+  !event.defaultPrevented &&
+  !(
+    event.target instanceof Element &&
+    event.target.closest(
+      '.cm-editor, .notebook-comments, .notebook-comments-gutter, .notebook-comments-open, button, input, textarea, select, label, a[href], [contenteditable="true"], [role="button"]',
+    )
+  );

package/src/markdown/tab-indent.ts

@@ -0,0 +1,104 @@
+/**
+ * Tab and Shift+Tab in the note editor.
+ *
+ * - With a suggestion list open, Tab accepts the highlighted suggestion.
+ * - In a table, Tab selects the next cell and Shift+Tab the previous one.
+ * - On a list item, Tab nests the selected items one level and Shift+Tab
+ *   lifts them one level; the items and text nested under them move along.
+ *   A level is the content column of the item above, so ordered and bullet
+ *   lists nest the way Markdown renders them. The first item stays put;
+ *   items joining a list adopt its marker, and new ordered sublists start at 1.
+ * - Everywhere else, including code blocks, Tab inserts two spaces at the
+ *   cursor or indents the selected lines, and Shift+Tab removes up to two
+ *   spaces of indentation.
+ *
+ * The note keeps plain spaces. Keyboard users leave the editor with
+ * CodeMirror's escape: Esc, then Tab. People who prefer Tab for focus
+ * movement leave this extension out through their Notebooks preference.
+ */
+import { acceptCompletion } from "@codemirror/autocomplete";
+import { indentLess, indentMore } from "@codemirror/commands";
+import { syntaxTree } from "@codemirror/language";
+import { EditorSelection, type EditorState, type Extension, type Line } from "@codemirror/state";
+import { type Command, EditorView, keymap } from "@codemirror/view";
+import type { SyntaxNode } from "@lezer/common";
+import { leadingWhitespace } from "./_lib/list-item-line";
+import { splitTableLineCells } from "./_lib/table-cell";
+import { indentListItems, outdentListItems } from "./list-commands";
+
+const INDENT = "  ";
+type Direction = 1 | -1;
+
+const tableAround = (state: EditorState, line: Line): SyntaxNode | null => {
+  if (!line.text.trim()) return null;
+  for (
+    let node: SyntaxNode | null = syntaxTree(state).resolveInner(line.from + leadingWhitespace(line.text), 1);
+    node;
+    node = node.parent
+  ) {
+    if (node.name === "Table") return node;
+  }
+  return null;
+};
+
+/** Every cell in document order; the delimiter row below the header holds none. Empty cells count. */
+const tableCells = (state: EditorState, table: SyntaxNode) => {
+  const first = state.doc.lineAt(table.from).number;
+  const last = state.doc.lineAt(table.to).number;
+  const cells: { from: number; to: number }[] = [];
+  for (let number = first; number <= last; number++) {
+    if (number === first + 1) continue;
+    const line = state.doc.line(number);
+    for (const cell of splitTableLineCells(line.text)) cells.push({ from: line.from + cell.fromInLine, to: line.from + cell.toInLine });
+  }
+  return cells;
+};
+
+const moveTableCell = (view: EditorView, direction: Direction): boolean => {
+  const { state } = view;
+  const head = state.selection.main.head;
+  const table = tableAround(state, state.doc.lineAt(head));
+  if (!table) return false;
+  const cells = tableCells(state, table);
+  const current = cells.findIndex((cell) => cell.from <= head && head <= cell.to);
+  const target =
+    current >= 0
+      ? cells[current + direction]
+      : direction > 0
+        ? cells.find((cell) => cell.from > head)
+        : cells.findLast((cell) => cell.to < head);
+  // The first and last cell keep the cursor; Esc, then Tab still leaves the editor.
+  if (!target) return true;
+  const text = state.sliceDoc(target.from, target.to);
+  const from = target.from + leadingWhitespace(text);
+  const to = target.to - (text.length - text.trimEnd().length);
+  const selection = from < to ? EditorSelection.range(from, to) : EditorSelection.cursor(Math.min(target.from + 1, target.to));
+  view.dispatch({ selection, scrollIntoView: true, userEvent: "select" });
+  return true;
+};
+
+const insertIndent: Command = (view) => {
+  if (view.state.selection.ranges.some((range) => !range.empty)) return indentMore(view);
+  view.dispatch(view.state.replaceSelection(INDENT), { scrollIntoView: true, userEvent: "input" });
+  return true;
+};
+
+/** Tab: accepted suggestion, next table cell, nested list item, or two spaces of indentation. */
+const indentOnTab: Command = (view) =>
+  !view.state.readOnly && (acceptCompletion(view) || moveTableCell(view, 1) || indentListItems(view) || insertIndent(view));
+
+/** Shift+Tab: previous table cell, lifted list item, or up to two spaces less indentation. */
+const outdentOnShiftTab: Command = (view) =>
+  !view.state.readOnly && (moveTableCell(view, -1) || outdentListItems(view) || indentLess(view));
+
+/**
+ * CodeMirror arms its Esc-then-Tab escape only when no key binding handles Esc, but Esc also collapses
+ * a selection and closes suggestions. Arming it on every Esc keeps "Esc, then Tab" leaving the editor.
+ */
+const armTabEscape = EditorView.domEventObservers({
+  keydown: (event, view) => {
+    if (event.key === "Escape") view.setTabFocusMode(2000);
+  },
+});
+
+export const tabIndentExtension = (): Extension => [keymap.of([{ key: "Tab", run: indentOnTab, shift: outdentOnShiftTab }]), armTabEscape];

package/src/markdown/table-columns.ts

@@ -0,0 +1,188 @@
+/**
+ * Autocomplete für Spaltennamen in Tabellen-Formel-Argumenten.
+ *
+ * Trigger: cursor sits inside the parentheses of a formula call in
+ * a table cell — i.e. after `=FUNC(` or after `=FUNC(arg, `. The
+ * partial word being typed (or empty after `(` / `,`) is matched
+ * against the column names in the current table's header row.
+ *
+ * Examples (`|` = cursor position):
+ *
+ *   | =SUM(|              → columns
+ *   | =SUM(Co|            → columns starting with "Co"
+ *   | =IF(ColA, |         → columns (for the second argument)
+ *   | =IF(ColA, ColB, Co| → columns starting with "Co"
+ *
+ * # Header detection
+ *
+ * Markdown tables are anchored by their separator row (`|---|---|`).
+ * The HEADER is the line immediately before the separator. We walk
+ * backwards from the cursor line — at most a handful of lines for
+ * any realistic table — and return the cells of the line above the
+ * first separator we hit. If we hit a non-table line before any
+ * separator (e.g. cursor IS on the header line), the table is
+ * malformed or we're typing into the header itself; return no
+ * suggestions either way.
+ *
+ * # Performance
+ *
+ * Hot-path cost when NOT inside a table: a single `lineAt` call +
+ * `isTableRow` check on the current line text. ~µs. Once we know
+ * we're in a table cell, the in-cell regex match is the next gate.
+ * Header lookup only runs after both pass.
+ *
+ * Header extraction is O(table height) — bounded by table size,
+ * not document size. A 50-row table costs ~50 line reads, sub-ms.
+ *
+ * # Scope
+ *
+ * No fenced-code check needed — the table-row gate already
+ * excludes code-block context (Markdown tables aren't recognised
+ * inside fenced blocks; lines that begin and end with `|` inside a
+ * code fence are just literal pipe characters, and the user is
+ * not editing a table there).
+ */
+import type { Completion, CompletionContext, CompletionResult } from "@codemirror/autocomplete";
+import type { EditorState } from "@codemirror/state";
+import { cellTextBeforeCursor, isTableRow, splitTableLineCells, TABLE_SEPARATOR_RE, tableCellText, withIcon } from "@k2b/editor/markdown";
+
+const isSeparatorRow = (lineText: string): boolean => TABLE_SEPARATOR_RE.test(lineText);
+
+/** Walk backwards from the cursor's line to find the table's
+ *  separator row, then return the cells of the line immediately
+ *  before it (the header). Empty array if no header is reachable
+ *  (cursor is on the header line, or the table has no separator). */
+const extractHeaderColumns = (state: EditorState, currentLineNumber: number): string[] => {
+  for (let n = currentLineNumber - 1; n >= 1; n--) {
+    const lineText = state.doc.line(n).text;
+    if (isSeparatorRow(lineText)) {
+      // Header is the line just above the separator. If we'd run
+      // off the doc start, there's no header.
+      if (n - 1 < 1) return [];
+      const headerText = state.doc.line(n - 1).text;
+      return splitHeaderCells(headerText);
+    }
+    if (!isTableRow(lineText)) {
+      // Hit a non-table line before finding the separator —
+      // current cursor is above or outside the header section.
+      return [];
+    }
+  }
+  return [];
+};
+
+/** Split a header row into cell labels. Strips the leading/trailing
+ *  pipes and trims whitespace from each cell. */
+const splitHeaderCells = (lineText: string): string[] => {
+  return splitTableLineCells(lineText)
+    .map((cell) => tableCellText(cell.text))
+    .filter(Boolean);
+};
+
+/** Match: cursor is positioned at the END of cell text that looks
+ *  like a partial formula call with an open-but-unclosed paren —
+ *  i.e. we're inside the argument list and the user is typing a
+ *  word fragment (or nothing yet, right after `(` or `,`).
+ *
+ *  Captures the partial word being typed at position 1 (may be the
+ *  empty string when cursor sits right after `(` or `, `).
+ *
+ *  Examples that match (`|` = cursor, capture group in []):
+ *    `=SUM(|`              → []
+ *    `=SUM(Co|`            → [Co]
+ *    `=IF(ColA, |`         → []
+ *    `=IF(ColA, ColB, Co|` → [Co]
+ *
+ *  Doesn't match once the paren closes — by then the user is past
+ *  argument entry. */
+const FORMULA_ARG_RE = /=\w+\([^)]*?(\w*)$/;
+
+/** Strict identifier pattern matching what the formula tokenizer
+ *  accepts as a bare IDENT (see `isIdentStart` / `isIdentChar` in
+ *  `cloud/shared/markdown/formula.ts`): `[a-zA-Z_]` to start, then
+ *  word chars. Anything else needs backtick quoting. */
+const BARE_IDENT_RE = /^[a-zA-Z_]\w*$/;
+
+/** Wrap a column name for safe insertion into formula source.
+ *  - Bare identifiers → returned as-is.
+ *  - Everything else (spaces, parens, `%`, leading digit, …) →
+ *    backtick-quoted with `\\` and `\\\`` escapes, mirroring the
+ *    backtick-ident tokenizer rules in `formula.ts`.
+ *
+ *  `userTypedBacktick = true` means the user already typed an
+ *  opening backtick before our `partialFrom`; we then emit ONLY
+ *  the escaped body + a closing backtick so the result reads as
+ *  `` `Tax (19%)` `` rather than `` ``Tax (19%)` `` (which would
+ *  fail to parse as an identifier). */
+const buildColumnApply = (col: string, userTypedBacktick: boolean): string => {
+  if (!userTypedBacktick && BARE_IDENT_RE.test(col)) return col;
+  const escaped = col.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\|/g, "\\|");
+  return userTypedBacktick ? `${escaped}\`` : `\`${escaped}\``;
+};
+
+/**
+ * Completion source. Wire after `tableFormulaCompletionSource` in
+ * the `autocompletion({override: …})` array.
+ */
+export const tableColumnCompletionSource = (context: CompletionContext): CompletionResult | null => {
+  // Stage 1 — cheap: must be on a line that LOOKS like a table row.
+  const line = context.state.doc.lineAt(context.pos);
+  if (!isTableRow(line.text)) return null;
+
+  // Stage 2 — must be in a cell that has formula-call-with-open-paren
+  // shape leading up to the cursor.
+  const cursorCol = context.pos - line.from;
+  const cell = cellTextBeforeCursor(line.text, cursorCol);
+  if (!cell) return null;
+  const match = FORMULA_ARG_RE.exec(cell.text);
+  if (!match) return null;
+
+  // Stage 3 — extract the table header (one walk-backwards, capped
+  // at the table's vertical size).
+  const columns = extractHeaderColumns(context.state, line.number);
+  if (columns.length === 0) return null;
+
+  // Build completions. `completionIcon` is set via structural cast (same
+  // pattern as the other completion sources) so the option-list shows a
+  // distinct glyph (`ti-columns-3`) for column entries — visually
+  // separates them from ordinary identifiers.
+  //
+  // The `apply` text is computed per-completion based on whether
+  // the column name needs backtick-quoting AND whether the user
+  // has already typed an opening backtick. Without this the
+  // autocomplete would insert raw `Tax (19%)` for a special-char
+  // column, which the formula parser rejects (`%` is not a valid
+  // identifier char). With the quoting it emits `` `Tax (19%)` ``,
+  // which is what the formula tokenizer accepts via its
+  // backtick-ident rule.
+  const partial = match[1] ?? "";
+  const partialFrom = context.pos - partial.length;
+  // Check whether the char immediately before our match start is a
+  // backtick — that signals the user is already typing inside a
+  // quoted-ident, so our apply should NOT add another opening
+  // backtick (would produce ``…` which doesn't parse).
+  const charBefore = partialFrom > 0 ? context.state.sliceDoc(partialFrom - 1, partialFrom) : "";
+  const userTypedBacktick = charBefore === "`";
+
+  const options: Completion[] = columns.map((col) => {
+    const c: Completion = {
+      // `label` is the raw column name — used both for the popup
+      // display AND for CM's prefix filter. So a user typing "Tax"
+      // narrows to "Tax (19%)" even though the actual inserted
+      // text is the backtick-quoted form.
+      label: col,
+      type: "property",
+      detail: "column",
+      apply: buildColumnApply(col, userTypedBacktick),
+    };
+    withIcon(c, "ti-columns-3");
+    return c;
+  });
+
+  return {
+    from: partialFrom,
+    to: context.pos,
+    options,
+    validFor: /^\w*$/,
+  };
+};

package/src/markdown/table-formulas.ts

@@ -0,0 +1,178 @@
+/**
+ * Autocomplete für `=FORMULA(...)` in Markdown-Tabellenzellen.
+ *
+ * Trigger: cursor is inside a table cell whose typed content so far
+ * begins with `=` (optionally followed by an in-progress function
+ * name). Accepting a suggestion expands to a full call template
+ * with tab-stops for arguments — e.g. `=SUM(${1:Column})` lands
+ * the cursor inside the parens with the column-name placeholder
+ * already selected for replacement.
+ *
+ * Functions mirror the registry in
+ * `@k2b/editor/formula` (the same module
+ * that EVALUATES the formulas in both edit-mode preview and
+ * read-mode rendering). Keep them in sync when new functions are
+ * added there.
+ *
+ * # Scope detection
+ *
+ * We don't lean on the Lezer-markdown `Table` / `TableRow` /
+ * `TableCell` nodes because they require the table to be
+ * structurally complete to be emitted — while the user is actively
+ * typing a new row (no separator line yet, or a cell being filled
+ * mid-edit) the parser often hasn't promoted the lines to a Table
+ * node yet, and the completions wouldn't fire. The structural
+ * heuristic is more robust:
+ *
+ *   1. Current line begins AND ends with `|` after trimming
+ *   2. Current line is NOT the separator row (`|---|---|`)
+ *   3. The cell the cursor sits in (text between the nearest `|`
+ *      before the cursor and the cursor itself) trims to `=<partial>`
+ *
+ * All three checks are O(line length) — cheap.
+ */
+import { type Completion, type CompletionContext, type CompletionResult, snippetCompletion } from "@codemirror/autocomplete";
+import { cellTextBeforeCursor, isTableRow, withIcon } from "@k2b/editor/markdown";
+
+type Formula = {
+  /** Function name as it appears in the formula source. */
+  name: string;
+  /** Signature shown inline as the option detail. */
+  detail: string;
+  /** Snippet body inside the parens. `${1:foo}` are tab-stops the
+   *  user can step through after accepting. */
+  args: string;
+  /** Tabler icon — categorises functions visually. */
+  icon: string;
+};
+
+/** Registry — keep in sync with `FUNCTIONS` in
+ *  `packages/cloud/src/shared/markdown/formula.ts`. */
+const FORMULAS: Formula[] = [
+  // Math ─────────────────────────────────────────────────────────
+  { name: "ROUND", detail: "(number, digits)", args: "${1:value}, ${2:2}", icon: "ti-math-function" },
+  { name: "ABS", detail: "(number)", args: "${1:value}", icon: "ti-math-function" },
+  { name: "SQRT", detail: "(number) — square root", args: "${1:value}", icon: "ti-math-function" },
+  { name: "POW", detail: "(base, exp) — power", args: "${1:base}, ${2:exp}", icon: "ti-math-function" },
+  { name: "MOD", detail: "(a, b) — remainder", args: "${1:a}, ${2:b}", icon: "ti-math-function" },
+  // Column aggregates ────────────────────────────────────────────
+  { name: "SUM", detail: "(column) — sum of column", args: "${1:Column}", icon: "ti-sum" },
+  { name: "AVG", detail: "(column) — average of column", args: "${1:Column}", icon: "ti-math-avg" },
+  { name: "MEAN", detail: "(column) — alias for AVG", args: "${1:Column}", icon: "ti-math-avg" },
+  { name: "MIN", detail: "(column) — minimum of column", args: "${1:Column}", icon: "ti-math-min" },
+  { name: "MAX", detail: "(column) — maximum of column", args: "${1:Column}", icon: "ti-math-max" },
+  { name: "COUNT", detail: "(column) — non-empty count", args: "${1:Column}", icon: "ti-tallymark-4" },
+  { name: "MEDIAN", detail: "(column) — median of column", args: "${1:Column}", icon: "ti-math-avg" },
+  { name: "UNIQUE", detail: "(column) — distinct non-empty count", args: "${1:Column}", icon: "ti-fingerprint" },
+  { name: "STDEV", detail: "(column) — sample standard deviation", args: "${1:Column}", icon: "ti-chart-bar" },
+  { name: "COUNTIF", detail: "(column, value) — count matching cells", args: "${1:Column}, ${2:'value'}", icon: "ti-tallymark-4" },
+  { name: "SUMIF", detail: "(sumCol, condCol, value) — conditional sum", args: "${1:SumCol}, ${2:CondCol}, ${3:'value'}", icon: "ti-sum" },
+  // Sugar ────────────────────────────────────────────────────────
+  { name: "PERCENT", detail: "(part, total) — rounded percent", args: "${1:part}, ${2:total}", icon: "ti-percentage" },
+  { name: "PROGRESS", detail: "(ratio) or (done, total) — progress bar", args: "${1:done}, ${2:total}", icon: "ti-progress" },
+  // Row aggregates ───────────────────────────────────────────────
+  { name: "ROWSUM", detail: "() — sum of other cells in row", args: "", icon: "ti-sum" },
+  { name: "ROWAVG", detail: "() — average of other cells in row", args: "", icon: "ti-math-avg" },
+  { name: "ROWMEAN", detail: "() — alias for ROWAVG", args: "", icon: "ti-math-avg" },
+  // Conditional ──────────────────────────────────────────────────
+  { name: "IF", detail: "(cond, then, else)", args: "${1:condition}, ${2:then}, ${3:else}", icon: "ti-git-branch" },
+  { name: "IFEMPTY", detail: "(value, fallback)", args: "${1:value}, ${2:fallback}", icon: "ti-git-branch" },
+  { name: "IFERROR", detail: "(value, fallback)", args: "${1:value}, ${2:fallback}", icon: "ti-git-branch" },
+  // Logical ──────────────────────────────────────────────────────
+  { name: "AND", detail: "(a, b, ...) — all truthy", args: "${1:a}, ${2:b}", icon: "ti-logic-and" },
+  { name: "OR", detail: "(a, b, ...) — any truthy", args: "${1:a}, ${2:b}", icon: "ti-logic-or" },
+  { name: "NOT", detail: "(a) — invert truthiness", args: "${1:value}", icon: "ti-logic-not" },
+  { name: "CONTAINS", detail: "(haystack, needle) — substring match", args: "${1:haystack}, ${2:'needle'}", icon: "ti-search" },
+  // Text ─────────────────────────────────────────────────────────
+  { name: "CONCAT", detail: "(...parts) — join strings", args: "${1:a}, ${2:b}", icon: "ti-typography" },
+  { name: "UPPER", detail: "(text) — uppercase", args: "${1:text}", icon: "ti-letter-case-upper" },
+  { name: "LOWER", detail: "(text) — lowercase", args: "${1:text}", icon: "ti-letter-case-lower" },
+  { name: "TRIM", detail: "(text) — strip whitespace", args: "${1:text}", icon: "ti-typography" },
+  { name: "LEFT", detail: "(text, n) — first n chars", args: "${1:text}, ${2:n}", icon: "ti-cut" },
+  { name: "RIGHT", detail: "(text, n) — last n chars", args: "${1:text}, ${2:n}", icon: "ti-cut" },
+  { name: "LEN", detail: "(text) — character count", args: "${1:text}", icon: "ti-ruler-measure" },
+  { name: "SUBSTRING", detail: "(text, start, length)", args: "${1:text}, ${2:start}, ${3:length}", icon: "ti-cut" },
+  { name: "REPLACE", detail: "(text, search, replacement)", args: "${1:text}, ${2:'search'}, ${3:'replacement'}", icon: "ti-replace" },
+  // Date / time ──────────────────────────────────────────────────
+  { name: "NOW", detail: "() — current YYYY-MM-DD HH:MM:SS", args: "", icon: "ti-clock" },
+  { name: "TODAY", detail: "() — current YYYY-MM-DD", args: "", icon: "ti-calendar" },
+  {
+    name: "DATEDIFF",
+    detail: "(d1, d2, unit?) — date diff (d/h/m/s/ms)",
+    args: "${1:'2026-01-01'}, ${2:'2026-12-31'}, ${3:'d'}",
+    icon: "ti-calendar-stats",
+  },
+];
+
+/** Snippet template. Does NOT include the leading `=` because the
+ *  `from` position in the CompletionResult is anchored AFTER the
+ *  `=` the user already typed — CM's prefix-filter compares the
+ *  typed name fragment against `label` ("SUM", "AVG", …), and on
+ *  acceptance only the text between `from` and the cursor is
+ *  replaced. The user's typed `=` stays in place. The trailing
+ *  `${0}` parks the final cursor outside the parens. */
+const buildSnippet = (f: Formula): string => (f.args.length === 0 ? `${f.name}()` : `${f.name}(${f.args})\${0}`);
+
+const COMPLETIONS: Completion[] = FORMULAS.map((f) => {
+  const c = snippetCompletion(buildSnippet(f), {
+    label: f.name,
+    type: "function",
+    detail: f.detail,
+  });
+  withIcon(c, f.icon);
+  return c;
+});
+
+/**
+ * Completion source. Wire into `autocompletion({override: […]})`.
+ *
+ * # Two-stage filter for hot-path performance
+ *
+ * Per keystroke, MOST users are NOT inside a table cell. Doing
+ * `lineAt` + `isTableRow` + `cellTextBeforeCursor` on every
+ * keystroke would burn CPU for nothing. We bail early via the
+ * cheapest possible check first:
+ *
+ *   1. `matchBefore(/=\w*\$/)` — the cursor must be on text that
+ *      ends with `=<word>`. If not, return null immediately. This
+ *      is the same `Line.text.search()` call CM does internally;
+ *      sub-millisecond on any sane line length.
+ *
+ *   2. ONLY THEN do we verify the line is a table row AND the cell
+ *      content matches the formula pattern.
+ *
+ * Without this two-stage filter the source was the dominant
+ * per-keystroke cost in ordinary text (it always called
+ * `lineAt` + ran a regex over the full line, even when typing in
+ * a plain paragraph far from any table).
+ */
+export const tableFormulaCompletionSource = (context: CompletionContext): CompletionResult | null => {
+  // Stage 1 — cheap: must be typing something that ends in `=<word>`.
+  const word = context.matchBefore(/=\w*/);
+  if (!word) return null;
+
+  // Stage 2 — confirm we're in a table cell.
+  const line = context.state.doc.lineAt(context.pos);
+  if (!isTableRow(line.text)) return null;
+
+  const cursorCol = context.pos - line.from;
+  const cell = cellTextBeforeCursor(line.text, cursorCol);
+  if (!cell) return null;
+
+  // Cell content must START with `=` (after optional whitespace).
+  // Once the user types `(` or any non-word char, this source
+  // stops firing (correct — they're inside an argument list, not
+  // picking a function).
+  if (!/^\s*=\w*$/.test(cell.text)) return null;
+
+  // Anchor `from` AFTER the `=` so CM's prefix-filter sees just the
+  // function-name fragment (e.g. "SU" → "SUM"). Anchoring at the `=`
+  // would force the labels to start with `=`, which they don't, so
+  // CM would silently drop every option → empty popup.
+  return {
+    from: word.from + 1,
+    to: context.pos,
+    options: COMPLETIONS,
+    validFor: /^\w*$/,
+  };
+};