@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/containers/data-grid/formula-bar.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { cn } from "../../utils/cn.js";
+function FormulaBar({
+  address,
+  value,
+  editable,
+  error,
+  labels,
+  onCommit,
+  onDiscard
+}) {
+  const [draft, setDraft] = useState(value);
+  useEffect(() => {
+    setDraft(value);
+  }, [address, value]);
+  return /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 items-center gap-2 border-b-divider px-2 py-1.5", children: [
+    /* @__PURE__ */ jsxs(
+      "span",
+      {
+        title: labels.cell,
+        className: "grid h-control-sm min-w-12 shrink-0 place-items-center rounded-xs bg-surface-2 px-2 font-[650] text-[12px] text-ink-2 tabular-nums",
+        children: [
+          /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+            labels.cell,
+            ": "
+          ] }),
+          address || "\u2014"
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "shrink-0 font-[650] text-[13px] text-accent-ink italic", children: "fx" }),
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        type: "text",
+        "aria-label": labels.bar,
+        "aria-invalid": error ? true : void 0,
+        spellCheck: false,
+        autoComplete: "off",
+        disabled: address === "",
+        readOnly: !editable,
+        value: draft,
+        placeholder: address === "" ? labels.empty : void 0,
+        onChange: (event) => setDraft(event.target.value),
+        onKeyDown: (event) => {
+          if (event.key === "Enter" && editable) {
+            event.preventDefault();
+            onCommit(draft);
+          } else if (event.key === "Escape") {
+            event.preventDefault();
+            setDraft(value);
+            onDiscard();
+          }
+        },
+        className: cn(
+          "h-control-sm min-w-0 flex-1 rounded-input border-control bg-surface-control px-2 font-mono text-[13px] text-ink placeholder:text-ink-3 focus-visible:border-accent focus-visible:outline-none disabled:opacity-60",
+          error && "border-danger"
+        )
+      }
+    ),
+    error ? /* @__PURE__ */ jsx("span", { role: "alert", className: "shrink-0 text-[12px] text-danger", children: error }) : null
+  ] });
+}
+export {
+  FormulaBar
+};

package/dist/containers/data-grid/formula-sheet.d.ts

@@ -0,0 +1,48 @@
+import { type ErrorCode, type FormulaNode, type FormulaValue } from "./formula.js";
+import type { CellValue } from "./types.js";
+export interface SheetFormula {
+    text: string;
+    /** Null when the text does not parse; `error` says what to show then. */
+    ast: FormulaNode | null;
+    error: ErrorCode | null;
+    /** Keys (`row * cols + col`) of the cells the formula reads, ranges expanded. */
+    deps: readonly number[];
+}
+export type ParseCache = Map<string, Pick<SheetFormula, "ast" | "error">>;
+export interface FormulaSheet {
+    readonly rows: number;
+    readonly cols: number;
+    /** Raw content of a cell: what the data holds, formulas as `=...` text. */
+    readonly read: (r: number, c: number) => CellValue;
+    readonly formulas: ReadonlyMap<number, SheetFormula>;
+    /** For each cell, the formula cells that read it. */
+    readonly dependents: ReadonlyMap<number, ReadonlySet<number>>;
+    /** Results of the formula cells. */
+    readonly values: ReadonlyMap<number, FormulaValue>;
+}
+export interface SheetInput {
+    rows: number;
+    cols: number;
+    read: (r: number, c: number) => CellValue;
+    /** Reuses parsed formulas across rebuilds. */
+    cache?: ParseCache;
+}
+/** A raw cell as a formula operand: dates are ISO text, anything unreadable is empty. */
+export declare function rawToFormulaValue(value: CellValue): FormulaValue;
+/** Finds every formula cell, links the dependency graph and evaluates the sheet. */
+export declare function buildSheet(input: SheetInput): FormulaSheet;
+/** Cells that must be recalculated after `key` changes: itself and everything that reads it. */
+export declare function dirtyCells(sheet: Pick<FormulaSheet, "dependents">, key: number): Set<number>;
+/**
+ * Sets one cell and recalculates only what depends on it. Returns a new sheet; the previous one
+ * is left untouched.
+ */
+export declare function updateCell(sheet: FormulaSheet, r: number, c: number, raw: CellValue, cache?: ParseCache): FormulaSheet;
+/** Result of a cell, formulas evaluated. */
+export declare function sheetValue(sheet: FormulaSheet, r: number, c: number): FormulaValue;
+/** The value a grid cell shows: formula results as plain values, errors as their code. */
+export declare function displayValue(sheet: FormulaSheet, r: number, c: number): CellValue | undefined;
+/** Cells the formula at (r, c) reads, as `[row, col]` pairs. */
+export declare function precedentsOf(sheet: FormulaSheet, r: number, c: number): Array<[number, number]>;
+/** Whether a displayed value is the text of a formula error. */
+export declare function isErrorText(value: CellValue): value is ErrorCode;

package/dist/containers/data-grid/formula-sheet.js

@@ -0,0 +1,175 @@
+import {
+  evaluateFormula,
+  formulaError,
+  isFormulaError,
+  isFormulaText,
+  parseFormula,
+  referencesOf
+} from "./formula.js";
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
+function rawToFormulaValue(value) {
+  if (value === null || value === void 0) return null;
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  return value;
+}
+function parseCell(text, rows, cols, cache) {
+  let parsed = cache?.get(text);
+  if (!parsed) {
+    const result = parseFormula(text);
+    parsed = result.ok ? { ast: result.ast, error: null } : { ast: null, error: result.error };
+    cache?.set(text, parsed);
+  }
+  return { ...parsed, deps: parsed.ast ? referencesOf(parsed.ast, rows, cols) : [] };
+}
+function linkDependents(formulas) {
+  const dependents = /* @__PURE__ */ new Map();
+  for (const [key, formula] of formulas) {
+    for (const dep of formula.deps) {
+      let set = dependents.get(dep);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        dependents.set(dep, set);
+      }
+      set.add(key);
+    }
+  }
+  return dependents;
+}
+function evaluateTargets(sheet, targets, values) {
+  const { rows, cols, read, formulas } = sheet;
+  const ctx = {
+    rows,
+    cols,
+    cell: (r, c) => {
+      const key = r * cols + c;
+      if (!formulas.has(key)) return rawToFormulaValue(read(r, c));
+      return values.get(key) ?? formulaError("#CYCLE!");
+    }
+  };
+  const settle = (key) => {
+    const formula = formulas.get(key);
+    return formula.ast ? evaluateFormula(formula.ast, ctx) : formulaError(formula.error ?? "#ERROR!");
+  };
+  for (const start of targets) {
+    if (values.has(start) || !formulas.has(start)) continue;
+    const stack = [{ key: start, next: 0 }];
+    const onStack = /* @__PURE__ */ new Map([[start, 0]]);
+    const cyclic = /* @__PURE__ */ new Set();
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      const deps = formulas.get(top.key).deps;
+      if (top.next < deps.length) {
+        const dep = deps[top.next];
+        top.next += 1;
+        if (!formulas.has(dep) || values.has(dep)) continue;
+        const at = onStack.get(dep);
+        if (at !== void 0) {
+          for (let i = at; i < stack.length; i += 1) cyclic.add(stack[i].key);
+          continue;
+        }
+        onStack.set(dep, stack.length);
+        stack.push({ key: dep, next: 0 });
+        continue;
+      }
+      stack.pop();
+      onStack.delete(top.key);
+      values.set(top.key, cyclic.has(top.key) ? formulaError("#CYCLE!") : settle(top.key));
+    }
+  }
+}
+function buildSheet(input) {
+  const { rows, cols, read, cache } = input;
+  const formulas = /* @__PURE__ */ new Map();
+  for (let r = 0; r < rows; r += 1) {
+    for (let c = 0; c < cols; c += 1) {
+      const raw = read(r, c);
+      if (isFormulaText(raw))
+        formulas.set(r * cols + c, { text: raw, ...parseCell(raw, rows, cols, cache) });
+    }
+  }
+  const values = /* @__PURE__ */ new Map();
+  evaluateTargets({ rows, cols, read, formulas }, formulas.keys(), values);
+  return { rows, cols, read, formulas, dependents: linkDependents(formulas), values };
+}
+function dirtyCells(sheet, key) {
+  const dirty = /* @__PURE__ */ new Set([key]);
+  const queue = [key];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const dependent of sheet.dependents.get(current) ?? []) {
+      if (!dirty.has(dependent)) {
+        dirty.add(dependent);
+        queue.push(dependent);
+      }
+    }
+  }
+  return dirty;
+}
+function updateCell(sheet, r, c, raw, cache) {
+  const { rows, cols } = sheet;
+  const key = r * cols + c;
+  const read = (rr, cc) => rr === r && cc === c ? raw : sheet.read(rr, cc);
+  const formulas = new Map(sheet.formulas);
+  const dependents = new Map(sheet.dependents);
+  const touch = (dep) => {
+    const copy = new Set(dependents.get(dep) ?? []);
+    dependents.set(dep, copy);
+    return copy;
+  };
+  for (const dep of sheet.formulas.get(key)?.deps ?? []) touch(dep).delete(key);
+  if (isFormulaText(raw)) {
+    const formula = { text: raw, ...parseCell(raw, rows, cols, cache) };
+    formulas.set(key, formula);
+    for (const dep of formula.deps) touch(dep).add(key);
+  } else {
+    formulas.delete(key);
+  }
+  const dirty = dirtyCells({ dependents }, key);
+  const values = new Map(sheet.values);
+  for (const cell of dirty) values.delete(cell);
+  evaluateTargets({ rows, cols, read, formulas }, dirty, values);
+  return { rows, cols, read, formulas, dependents, values };
+}
+function sheetValue(sheet, r, c) {
+  const key = r * sheet.cols + c;
+  if (!sheet.formulas.has(key)) return rawToFormulaValue(sheet.read(r, c));
+  return sheet.values.get(key) ?? formulaError("#CYCLE!");
+}
+function displayValue(sheet, r, c) {
+  const key = r * sheet.cols + c;
+  if (!sheet.formulas.has(key)) return void 0;
+  const value = sheet.values.get(key) ?? formulaError("#CYCLE!");
+  return isFormulaError(value) ? value.code : value;
+}
+function precedentsOf(sheet, r, c) {
+  return (sheet.formulas.get(r * sheet.cols + c)?.deps ?? []).map((key) => [
+    Math.floor(key / sheet.cols),
+    key % sheet.cols
+  ]);
+}
+const ERROR_TEXTS = /* @__PURE__ */ new Set([
+  "#REF!",
+  "#DIV/0!",
+  "#NAME?",
+  "#VALUE!",
+  "#CYCLE!",
+  "#ERROR!"
+]);
+function isErrorText(value) {
+  return typeof value === "string" && ERROR_TEXTS.has(value);
+}
+export {
+  buildSheet,
+  dirtyCells,
+  displayValue,
+  isErrorText,
+  precedentsOf,
+  rawToFormulaValue,
+  sheetValue,
+  updateCell
+};

package/dist/containers/data-grid/formula.d.ts

@@ -0,0 +1,86 @@
+export type ErrorCode = "#REF!" | "#DIV/0!" | "#NAME?" | "#VALUE!" | "#CYCLE!" | "#ERROR!";
+export declare class FormulaError {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode);
+}
+export declare function isFormulaError(value: unknown): value is FormulaError;
+/** What a formula or a cell evaluates to; `null` is an empty cell. */
+export type FormulaValue = number | string | boolean | null | FormulaError;
+export interface CellRef {
+    r: number;
+    c: number;
+    /** `$` before the row / column: it does not move when the formula is filled elsewhere. */
+    absR: boolean;
+    absC: boolean;
+}
+export type FormulaNode = {
+    t: "num";
+    v: number;
+} | {
+    t: "str";
+    v: string;
+} | {
+    t: "bool";
+    v: boolean;
+} | {
+    t: "name";
+    v: string;
+} | {
+    t: "ref";
+    ref: CellRef;
+} | {
+    t: "range";
+    a: CellRef;
+    b: CellRef;
+} | {
+    t: "un";
+    op: "-" | "+";
+    x: FormulaNode;
+} | {
+    t: "bin";
+    op: string;
+    l: FormulaNode;
+    r: FormulaNode;
+} | {
+    t: "call";
+    name: string;
+    args: FormulaNode[];
+};
+export type ParseResult = {
+    ok: true;
+    ast: FormulaNode;
+} | {
+    ok: false;
+    error: string;
+};
+/** 0 -> A, 25 -> Z, 26 -> AA. */
+export declare function columnLabel(index: number): string;
+/** A -> 0, AA -> 26; -1 when the text is not a column label. */
+export declare function columnIndex(label: string): number;
+/** `B3` for row 2, column 1 (0-based). */
+export declare function cellAddress(r: number, c: number): string;
+/** Reads `B3`, `$B$3` or `R3C2`; null for anything else. */
+export declare function parseAddress(text: string): CellRef | null;
+export declare function isFormulaText(value: unknown): value is string;
+/** Parses a formula; the leading `=` is optional. Syntax problems are reported, not thrown. */
+export declare function parseFormula(text: string): ParseResult;
+/**
+ * Moves the relative references of a formula by `dr` rows and `dc` columns, the way a spreadsheet
+ * does when a formula is filled down or right; `$` references stay. Text outside references is
+ * kept as typed. A reference pushed off the sheet becomes `#REF!`.
+ */
+export declare function shiftFormula(text: string, dr: number, dc: number): string;
+export declare function formulaError(code: ErrorCode): FormulaError;
+export interface EvalContext {
+    rows: number;
+    cols: number;
+    /** Value of a cell inside the sheet (formulas already evaluated). */
+    cell: (r: number, c: number) => FormulaValue;
+}
+export declare function formulaText(value: FormulaValue): string;
+/** Names of the functions a formula may call. */
+export declare const FORMULA_FUNCTIONS: readonly string[];
+/** Evaluates a parsed formula to a single value (a bare range is an error, like in a cell). */
+export declare function evaluateFormula(ast: FormulaNode, ctx: EvalContext): FormulaValue;
+/** Every cell a formula reads, ranges expanded; references and ranges outside the sheet are left out (they evaluate to #REF!). */
+export declare function referencesOf(ast: FormulaNode, rows: number, cols: number): number[];