@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/containers/data-grid/filter-builder.ts

@@ -0,0 +1,308 @@
+// Advanced filter: AND / OR groups of conditions, evaluated against rows.
+import {
+  cellToNumber,
+  cellToTime,
+  filterKindOf,
+  formatCellValue,
+  getCellValue,
+  isoDayBounds,
+  normalizeText,
+} from "./model.js";
+import type { CellValue, DataGridColumn } from "./types.js";
+
+export type FilterOperator =
+  | "contains"
+  | "notContains"
+  | "equals"
+  | "notEquals"
+  | "startsWith"
+  | "endsWith"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "between"
+  | "before"
+  | "after"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export type FilterLogic = "and" | "or";
+
+export interface FilterCondition {
+  type: "condition";
+  id: string;
+  columnId: string;
+  operator: FilterOperator;
+  /** Text, number or `yyyy-mm-dd` date, as typed. */
+  value: string;
+  /** Upper end of `between`. */
+  value2?: string;
+}
+
+export interface FilterGroup {
+  type: "group";
+  id: string;
+  logic: FilterLogic;
+  children: FilterNode[];
+}
+
+export type FilterNode = FilterCondition | FilterGroup;
+
+const TEXT_OPERATORS: FilterOperator[] = [
+  "contains",
+  "notContains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+  "isEmpty",
+  "isNotEmpty",
+];
+const NUMBER_OPERATORS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "isEmpty",
+  "isNotEmpty",
+];
+const DATE_OPERATORS: FilterOperator[] = [
+  "equals",
+  "before",
+  "after",
+  "between",
+  "isEmpty",
+  "isNotEmpty",
+];
+const SELECT_OPERATORS: FilterOperator[] = ["equals", "notEquals", "isEmpty", "isNotEmpty"];
+
+export type ValueKind = "text" | "number" | "date";
+
+export function valueKindOf<T>(column: DataGridColumn<T>): ValueKind {
+  const kind = filterKindOf(column);
+  if (kind === "range") return "number";
+  if (kind === "dateRange") return "date";
+  return "text";
+}
+
+export function operatorsFor<T>(column: DataGridColumn<T>): FilterOperator[] {
+  const kind = filterKindOf(column);
+  if (kind === "range") return NUMBER_OPERATORS;
+  if (kind === "dateRange") return DATE_OPERATORS;
+  if (kind === "select" || kind === "set") return SELECT_OPERATORS;
+  return TEXT_OPERATORS;
+}
+
+export function operatorNeedsValue(operator: FilterOperator): boolean {
+  return operator !== "isEmpty" && operator !== "isNotEmpty";
+}
+
+let counter = 0;
+export function newFilterId(prefix = "f"): string {
+  counter += 1;
+  return `${prefix}${counter}`;
+}
+
+export function emptyGroup(logic: FilterLogic = "and", id = newFilterId("g")): FilterGroup {
+  return { type: "group", id, logic, children: [] };
+}
+
+export function newCondition<T>(column: DataGridColumn<T>): FilterCondition {
+  return {
+    type: "condition",
+    id: newFilterId("c"),
+    columnId: column.id,
+    operator: operatorsFor(column)[0] ?? "contains",
+    value: "",
+  };
+}
+
+function isEmptyValue(value: CellValue): boolean {
+  return value === null || value === undefined || value === "";
+}
+
+function compare(a: number, b: number): number {
+  return a - b;
+}
+
+/** A condition counts once it has what its operator needs. */
+export function isConditionActive(condition: FilterCondition): boolean {
+  if (!operatorNeedsValue(condition.operator)) return true;
+  if (condition.value.trim() === "") return false;
+  if (condition.operator === "between") return (condition.value2 ?? "").trim() !== "";
+  return true;
+}
+
+export function evaluateCondition<T>(
+  row: T,
+  condition: FilterCondition,
+  columns: readonly DataGridColumn<T>[],
+): boolean {
+  const column = columns.find((c) => c.id === condition.columnId);
+  if (!column) return true;
+  const cell = getCellValue(row, column);
+  const { operator } = condition;
+  if (operator === "isEmpty") return isEmptyValue(cell);
+  if (operator === "isNotEmpty") return !isEmptyValue(cell);
+
+  const kind = valueKindOf(column);
+  if (kind === "number") {
+    const left = cellToNumber(cell);
+    const right = Number.parseFloat(condition.value.replace(",", "."));
+    if (left === null || !Number.isFinite(right)) return false;
+    const upper = Number.parseFloat((condition.value2 ?? "").replace(",", "."));
+    switch (operator) {
+      case "equals":
+        return compare(left, right) === 0;
+      case "notEquals":
+        return compare(left, right) !== 0;
+      case "gt":
+        return left > right;
+      case "gte":
+        return left >= right;
+      case "lt":
+        return left < right;
+      case "lte":
+        return left <= right;
+      case "between":
+        return (
+          Number.isFinite(upper) && left >= Math.min(right, upper) && left <= Math.max(right, upper)
+        );
+      default:
+        return false;
+    }
+  }
+  if (kind === "date") {
+    const time = cellToTime(cell);
+    const start = isoDayBounds(condition.value, false);
+    const end = isoDayBounds(condition.value, true);
+    if (time === null || start === null || end === null) return false;
+    switch (operator) {
+      case "equals":
+        return time >= start && time <= end;
+      case "before":
+        return time < start;
+      case "after":
+        return time > end;
+      case "between": {
+        const upper = isoDayBounds(condition.value2 ?? "", true);
+        return upper !== null && time >= start && time <= upper;
+      }
+      default:
+        return false;
+    }
+  }
+
+  const text = normalizeText(formatCellValue(cell, column) || String(cell ?? ""));
+  const needle = normalizeText(condition.value.trim());
+  switch (operator) {
+    case "contains":
+      return text.includes(needle);
+    case "notContains":
+      return !text.includes(needle);
+    case "equals":
+      return text === needle;
+    case "notEquals":
+      return text !== needle;
+    case "startsWith":
+      return text.startsWith(needle);
+    case "endsWith":
+      return text.endsWith(needle);
+    default:
+      return false;
+  }
+}
+
+/** Empty groups and incomplete conditions are ignored; a group with no active child matches all. */
+export function isNodeActive(node: FilterNode): boolean {
+  if (node.type === "condition") return isConditionActive(node);
+  return node.children.some(isNodeActive);
+}
+
+export function evaluateNode<T>(
+  row: T,
+  node: FilterNode,
+  columns: readonly DataGridColumn<T>[],
+): boolean {
+  if (node.type === "condition") {
+    return isConditionActive(node) ? evaluateCondition(row, node, columns) : true;
+  }
+  const active = node.children.filter(isNodeActive);
+  if (active.length === 0) return true;
+  return node.logic === "and"
+    ? active.every((child) => evaluateNode(row, child, columns))
+    : active.some((child) => evaluateNode(row, child, columns));
+}
+
+export function applyAdvancedFilter<T>(
+  rows: readonly T[],
+  columns: readonly DataGridColumn<T>[],
+  node: FilterGroup | undefined,
+): T[] {
+  if (!node || !isNodeActive(node)) return [...rows];
+  return rows.filter((row) => evaluateNode(row, node, columns));
+}
+
+export function countConditions(node: FilterNode): number {
+  if (node.type === "condition") return isConditionActive(node) ? 1 : 0;
+  return node.children.reduce((sum, child) => sum + countConditions(child), 0);
+}
+
+function mapNode(node: FilterNode, id: string, fn: (node: FilterNode) => FilterNode): FilterNode {
+  if (node.id === id) return fn(node);
+  if (node.type === "condition") return node;
+  return { ...node, children: node.children.map((child) => mapNode(child, id, fn)) };
+}
+
+/** Replaces the node with `id` (immutably). */
+export function updateNode(
+  root: FilterGroup,
+  id: string,
+  fn: (node: FilterNode) => FilterNode,
+): FilterGroup {
+  return mapNode(root, id, fn) as FilterGroup;
+}
+
+/** Adds `child` at the end of the group `groupId`. */
+export function addChild(root: FilterGroup, groupId: string, child: FilterNode): FilterGroup {
+  return updateNode(root, groupId, (node) =>
+    node.type === "group" ? { ...node, children: [...node.children, child] } : node,
+  );
+}
+
+/** Removes the node with `id`; the root itself stays. */
+export function removeNode(root: FilterGroup, id: string): FilterGroup {
+  const strip = (group: FilterGroup): FilterGroup => ({
+    ...group,
+    children: group.children
+      .filter((child) => child.id !== id)
+      .map((child) => (child.type === "group" ? strip(child) : child)),
+  });
+  return strip(root);
+}
+
+/** Readable summary, for example `(Barbero es Luis Y Total > 30)`. */
+export function describeFilter<T>(
+  node: FilterNode,
+  columns: readonly DataGridColumn<T>[],
+  words: { and: string; or: string; operators: Record<FilterOperator, string> },
+): string {
+  if (node.type === "condition") {
+    if (!isConditionActive(node)) return "";
+    const header = columns.find((c) => c.id === node.columnId)?.header ?? node.columnId;
+    const value = operatorNeedsValue(node.operator)
+      ? node.operator === "between"
+        ? ` ${node.value} – ${node.value2 ?? ""}`
+        : ` ${node.value}`
+      : "";
+    return `${header} ${words.operators[node.operator]}${value}`;
+  }
+  const parts = node.children.map((child) => describeFilter(child, columns, words)).filter(Boolean);
+  if (parts.length === 0) return "";
+  const text = parts.join(` ${node.logic === "and" ? words.and : words.or} `);
+  return parts.length > 1 ? `(${text})` : text;
+}

package/src/containers/data-grid/formula-bar.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cn } from "../../utils/cn.js";
+
+export interface FormulaBarProps {
+  /** Address of the focused cell (`C4`), empty when no data cell has focus. */
+  address: string;
+  /** Raw content of the cell: the formula text for formula cells. */
+  value: string;
+  editable: boolean;
+  /** Message of the last refused commit. */
+  error?: string;
+  labels: { bar: string; cell: string; empty: string };
+  onCommit: (text: string) => void;
+  onDiscard: () => void;
+}
+
+/** Shows (and edits) the raw content of the focused cell, so formulas stay readable. */
+export function FormulaBar({
+  address,
+  value,
+  editable,
+  error,
+  labels,
+  onCommit,
+  onDiscard,
+}: FormulaBarProps) {
+  const [draft, setDraft] = useState(value);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a new cell or a new content resets the draft.
+  useEffect(() => {
+    setDraft(value);
+  }, [address, value]);
+
+  return (
+    <div className="flex min-w-0 items-center gap-2 border-b-divider px-2 py-1.5">
+      <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"
+      >
+        <span className="sr-only">{labels.cell}: </span>
+        {address || "—"}
+      </span>
+      <span aria-hidden="true" className="shrink-0 font-[650] text-[13px] text-accent-ink italic">
+        fx
+      </span>
+      <input
+        type="text"
+        aria-label={labels.bar}
+        aria-invalid={error ? true : undefined}
+        spellCheck={false}
+        autoComplete="off"
+        disabled={address === ""}
+        readOnly={!editable}
+        value={draft}
+        placeholder={address === "" ? labels.empty : undefined}
+        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 ? (
+        <span role="alert" className="shrink-0 text-[12px] text-danger">
+          {error}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/src/containers/data-grid/formula-sheet.ts

@@ -0,0 +1,254 @@
+// A sheet of cells with formulas: dependency graph, recalculation and cycle detection. Pure.
+import {
+  type ErrorCode,
+  evaluateFormula,
+  type FormulaNode,
+  type FormulaValue,
+  formulaError,
+  isFormulaError,
+  isFormulaText,
+  parseFormula,
+  referencesOf,
+} 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;
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** A raw cell as a formula operand: dates are ISO text, anything unreadable is empty. */
+export function rawToFormulaValue(value: CellValue): FormulaValue {
+  if (value === null || value === undefined) 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: string,
+  rows: number,
+  cols: number,
+  cache?: ParseCache,
+): Omit<SheetFormula, "text"> {
+  let parsed = cache?.get(text);
+  if (!parsed) {
+    const result = parseFormula(text);
+    parsed = result.ok
+      ? { ast: result.ast, error: null }
+      : { ast: null, error: result.error as ErrorCode };
+    cache?.set(text, parsed);
+  }
+  return { ...parsed, deps: parsed.ast ? referencesOf(parsed.ast, rows, cols) : [] };
+}
+
+function linkDependents(formulas: ReadonlyMap<number, SheetFormula>): Map<number, Set<number>> {
+  const dependents = new Map<number, Set<number>>();
+  for (const [key, formula] of formulas) {
+    for (const dep of formula.deps) {
+      let set = dependents.get(dep);
+      if (!set) {
+        set = new Set();
+        dependents.set(dep, set);
+      }
+      set.add(key);
+    }
+  }
+  return dependents;
+}
+
+/**
+ * Evaluates `targets` (formula cells) in dependency order with an explicit stack, so long chains
+ * do not overflow the call stack. Cells on a cycle get `#CYCLE!`.
+ */
+function evaluateTargets(
+  sheet: Pick<FormulaSheet, "rows" | "cols" | "read" | "formulas">,
+  targets: Iterable<number>,
+  values: Map<number, FormulaValue>,
+): void {
+  const { rows, cols, read, formulas } = sheet;
+  const ctx = {
+    rows,
+    cols,
+    cell: (r: number, c: number): FormulaValue => {
+      const key = r * cols + c;
+      if (!formulas.has(key)) return rawToFormulaValue(read(r, c));
+      return values.get(key) ?? formulaError("#CYCLE!");
+    },
+  };
+  const settle = (key: number): FormulaValue => {
+    const formula = formulas.get(key) as SheetFormula;
+    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: number; next: number }[] = [{ key: start, next: 0 }];
+    const onStack = new Map<number, number>([[start, 0]]);
+    const cyclic = new Set<number>();
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1] as { key: number; next: number };
+      const deps = (formulas.get(top.key) as SheetFormula).deps;
+      if (top.next < deps.length) {
+        const dep = deps[top.next] as number;
+        top.next += 1;
+        if (!formulas.has(dep) || values.has(dep)) continue;
+        const at = onStack.get(dep);
+        if (at !== undefined) {
+          for (let i = at; i < stack.length; i += 1) cyclic.add((stack[i] as { key: number }).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));
+    }
+  }
+}
+
+/** Finds every formula cell, links the dependency graph and evaluates the sheet. */
+export function buildSheet(input: SheetInput): FormulaSheet {
+  const { rows, cols, read, cache } = input;
+  const formulas = new Map<number, SheetFormula>();
+  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 = new Map<number, FormulaValue>();
+  evaluateTargets({ rows, cols, read, formulas }, formulas.keys(), values);
+  return { rows, cols, read, formulas, dependents: linkDependents(formulas), values };
+}
+
+/** Cells that must be recalculated after `key` changes: itself and everything that reads it. */
+export function dirtyCells(sheet: Pick<FormulaSheet, "dependents">, key: number): Set<number> {
+  const dirty = new Set<number>([key]);
+  const queue = [key];
+  while (queue.length > 0) {
+    const current = queue.pop() as number;
+    for (const dependent of sheet.dependents.get(current) ?? []) {
+      if (!dirty.has(dependent)) {
+        dirty.add(dependent);
+        queue.push(dependent);
+      }
+    }
+  }
+  return dirty;
+}
+
+/**
+ * Sets one cell and recalculates only what depends on it. Returns a new sheet; the previous one
+ * is left untouched.
+ */
+export function updateCell(
+  sheet: FormulaSheet,
+  r: number,
+  c: number,
+  raw: CellValue,
+  cache?: ParseCache,
+): FormulaSheet {
+  const { rows, cols } = sheet;
+  const key = r * cols + c;
+  const read = (rr: number, cc: number): CellValue =>
+    rr === r && cc === c ? raw : sheet.read(rr, cc);
+
+  const formulas = new Map(sheet.formulas);
+  const dependents = new Map(sheet.dependents);
+  const touch = (dep: number): Set<number> => {
+    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: SheetFormula = { 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 };
+}
+
+/** Result of a cell, formulas evaluated. */
+export function sheetValue(sheet: FormulaSheet, r: number, c: number): FormulaValue {
+  const key = r * sheet.cols + c;
+  if (!sheet.formulas.has(key)) return rawToFormulaValue(sheet.read(r, c));
+  return sheet.values.get(key) ?? formulaError("#CYCLE!");
+}
+
+/** The value a grid cell shows: formula results as plain values, errors as their code. */
+export function displayValue(sheet: FormulaSheet, r: number, c: number): CellValue | undefined {
+  const key = r * sheet.cols + c;
+  if (!sheet.formulas.has(key)) return undefined;
+  const value = sheet.values.get(key) ?? formulaError("#CYCLE!");
+  return isFormulaError(value) ? value.code : value;
+}
+
+/** Cells the formula at (r, c) reads, as `[row, col]` pairs. */
+export function precedentsOf(sheet: FormulaSheet, r: number, c: number): Array<[number, number]> {
+  return (sheet.formulas.get(r * sheet.cols + c)?.deps ?? []).map((key) => [
+    Math.floor(key / sheet.cols),
+    key % sheet.cols,
+  ]);
+}
+
+const ERROR_TEXTS: ReadonlySet<string> = new Set([
+  "#REF!",
+  "#DIV/0!",
+  "#NAME?",
+  "#VALUE!",
+  "#CYCLE!",
+  "#ERROR!",
+]);
+
+/** Whether a displayed value is the text of a formula error. */
+export function isErrorText(value: CellValue): value is ErrorCode {
+  return typeof value === "string" && ERROR_TEXTS.has(value);
+}