@ai-matrx/design-system 0.22.0 → 0.25.0

package/dist/formulas/index.d.ts

@@ -0,0 +1,389 @@
+/**
+ * @ai-matrx/design-system/formulas — THE formula language for computed columns.
+ *
+ * This module moved here from the app so every table in the product shares
+ * one formula language. It stays pure: no React, no DOM, no network.
+ *
+ * A **formula column** holds nothing. Its cell is always `null` in the
+ * database; the value the user sees is computed, on read, from the OTHER
+ * columns of the SAME row. Champion: Airtable's formula field.
+ *
+ * THE THREE RULES THIS FILE OBEYS
+ *
+ * 1. **No `eval`, no `new Function`, no dynamic code.** A formula is user
+ *    content; it is tokenized, parsed into an AST, and interpreted. Nothing a
+ *    user types ever becomes JavaScript.
+ * 2. **Nothing throws.** `parseFormula` and `evaluateFormula` both return a
+ *    discriminated result. A syntax error, a missing column, a division by
+ *    zero and a type mismatch are all `ok: false` with a plain-English
+ *    sentence a non-technical person can act on — never an exception, never a
+ *    silent blank cell (THE FALLBACK LAW, `lib/field-formats/FEATURE.md`).
+ * 3. **The engine is pure.** It reads cells through a caller-supplied
+ *    `resolve(name)`. It never touches Redux, Supabase, or the DOM, which is
+ *    what makes every rule below testable.
+ *
+ * THE COERCION RULES (the whole contract, in one place)
+ *
+ * - **BLANK** is `null`, `undefined`, or `""`. All three are the same value to
+ *   a formula, because a text cell that was cleared holds `""` and a number
+ *   cell that was cleared holds `null`, and a user does not distinguish them.
+ * - **A missing column is NOT blank.** `resolve()` returns `undefined` for a
+ *   column that does not exist (as opposed to `null` for one that is empty),
+ *   and that is an error: `{a} + {Typo}` must say the column is unknown rather
+ *   than quietly computing with zero.
+ * - **Arithmetic treats BLANK as 0.** `{a} + {b}` with `b` empty is `{a}`.
+ *   That is the tolerant reading every spreadsheet uses, and the alternative
+ *   (the whole cell erroring because one input is empty) makes a formula
+ *   column useless on real, partly-filled data.
+ * - **Numeric strings coerce.** `"1,234"`, `" 42 "`, `"$5"` and `"3.5"` are
+ *   numbers in arithmetic; `"n/a"` is a type error naming the value.
+ * - **Booleans are 1 and 0 in arithmetic**, so SUM over a checkbox column
+ *   counts the ticks.
+ * - **Aggregates SKIP blanks.** `SUM`/`MIN`/`MAX`/`AVERAGE` ignore empty
+ *   inputs entirely — `AVERAGE` divides by the count of the values that were
+ *   actually there, and returns BLANK when there were none.
+ * - **Text conversion**: BLANK becomes `""`, a number becomes its shortest
+ *   exact decimal, a boolean becomes `"true"` / `"false"`.
+ * - **Comparison** is numeric when both sides read as numbers, otherwise a
+ *   plain string comparison. BLANK takes the shape of what it is compared
+ *   against — `0` beside a number, `""` beside text — so `{a} = BLANK()`,
+ *   `{a} = 0` and `{a} = ''` all hold for an empty cell.
+ * - **Truthiness** (for `IF` / `AND` / `OR` / `NOT`): BLANK is false, a
+ *   boolean is itself, a number is true unless `0`, a string is true unless
+ *   empty.
+ * - **Dates are ISO strings, read and written in UTC.** A date function
+ *   accepts an ISO string (or a `Date`) and returns an ISO string — date-only
+ *   (`2026-09-14`) when the input was date-only, full (`2026-09-14T…Z`)
+ *   otherwise. UTC throughout on purpose: reading `2026-09-14` with local
+ *   getters turns it into the 13th for half the planet.
+ * - **Division (and `%`) by zero is an error**, never `Infinity` and never
+ *   `NaN`. A cell may not lie about arithmetic that did not happen.
+ */
+type FormulaValue = string | number | boolean | null;
+type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "&" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=";
+type FormulaAst = {
+    kind: "number";
+    value: number;
+    position: number;
+} | {
+    kind: "string";
+    value: string;
+    position: number;
+} | {
+    kind: "boolean";
+    value: boolean;
+    position: number;
+} | {
+    kind: "reference";
+    name: string;
+    position: number;
+} | {
+    kind: "unary";
+    operator: "-";
+    operand: FormulaAst;
+    position: number;
+} | {
+    kind: "binary";
+    operator: BinaryOperator;
+    left: FormulaAst;
+    right: FormulaAst;
+    position: number;
+} | {
+    kind: "call";
+    name: FormulaFunctionName;
+    args: FormulaAst[];
+    position: number;
+};
+type ParseResult = {
+    ok: true;
+    ast: FormulaAst;
+    references: string[];
+} | {
+    ok: false;
+    error: string;
+    position: number;
+};
+type FormulaResult = {
+    ok: true;
+    value: FormulaValue;
+} | {
+    ok: false;
+    error: string;
+};
+type FormulaResultType = "number" | "text" | "boolean" | "date" | "unknown";
+/** What a cell lookup may answer: a value, BLANK, or `undefined` = no such column. */
+type ResolveCell = (name: string) => unknown;
+/** Best-effort declared type of a column, for static result typing. */
+type ResolveColumnType = (name: string) => "number" | "text" | "boolean" | "date" | undefined;
+declare const FUNCTION_SPECS: {
+    readonly SUM: {
+        readonly signature: "SUM(number, …)";
+        readonly description: "Adds every value, ignoring empty ones.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "number";
+    };
+    readonly MIN: {
+        readonly signature: "MIN(number, …)";
+        readonly description: "The smallest value, ignoring empty ones.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "number";
+    };
+    readonly MAX: {
+        readonly signature: "MAX(number, …)";
+        readonly description: "The largest value, ignoring empty ones.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "number";
+    };
+    readonly AVERAGE: {
+        readonly signature: "AVERAGE(number, …)";
+        readonly description: "The average of the values that are filled in. Empty values are not counted.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "number";
+    };
+    readonly ROUND: {
+        readonly signature: "ROUND(number, places?)";
+        readonly description: "Rounds to the given number of decimal places (0 when omitted). Halves round away from zero.";
+        readonly min: 1;
+        readonly max: 2;
+        readonly result: "number";
+    };
+    readonly ABS: {
+        readonly signature: "ABS(number)";
+        readonly description: "The value without its minus sign.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "number";
+    };
+    readonly LEN: {
+        readonly signature: "LEN(text)";
+        readonly description: "How many characters the text has.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "number";
+    };
+    readonly UPPER: {
+        readonly signature: "UPPER(text)";
+        readonly description: "The text in capitals.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "text";
+    };
+    readonly LOWER: {
+        readonly signature: "LOWER(text)";
+        readonly description: "The text in lower case.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "text";
+    };
+    readonly TRIM: {
+        readonly signature: "TRIM(text)";
+        readonly description: "The text without leading or trailing spaces.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "text";
+    };
+    readonly CONCATENATE: {
+        readonly signature: "CONCATENATE(text, …)";
+        readonly description: "Joins every value into one piece of text.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "text";
+    };
+    readonly LEFT: {
+        readonly signature: "LEFT(text, count)";
+        readonly description: "The first few characters of the text.";
+        readonly min: 2;
+        readonly max: 2;
+        readonly result: "text";
+    };
+    readonly RIGHT: {
+        readonly signature: "RIGHT(text, count)";
+        readonly description: "The last few characters of the text.";
+        readonly min: 2;
+        readonly max: 2;
+        readonly result: "text";
+    };
+    readonly CONTAINS: {
+        readonly signature: "CONTAINS(text, part)";
+        readonly description: "Yes when the text contains that part. Upper and lower case are treated the same.";
+        readonly min: 2;
+        readonly max: 2;
+        readonly result: "boolean";
+    };
+    readonly IF: {
+        readonly signature: "IF(condition, then, otherwise?)";
+        readonly description: "The second value when the condition holds, otherwise the third (empty when omitted).";
+        readonly min: 2;
+        readonly max: 3;
+        readonly result: "unknown";
+    };
+    readonly AND: {
+        readonly signature: "AND(condition, …)";
+        readonly description: "Yes when every condition holds.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "boolean";
+    };
+    readonly OR: {
+        readonly signature: "OR(condition, …)";
+        readonly description: "Yes when at least one condition holds.";
+        readonly min: 1;
+        readonly max: number;
+        readonly result: "boolean";
+    };
+    readonly NOT: {
+        readonly signature: "NOT(condition)";
+        readonly description: "Turns yes into no and no into yes.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "boolean";
+    };
+    readonly BLANK: {
+        readonly signature: "BLANK()";
+        readonly description: "An empty value, for comparing against or returning.";
+        readonly min: 0;
+        readonly max: 0;
+        readonly result: "unknown";
+    };
+    readonly ISBLANK: {
+        readonly signature: "ISBLANK(value)";
+        readonly description: "Yes when the value is empty.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "boolean";
+    };
+    readonly TODAY: {
+        readonly signature: "TODAY()";
+        readonly description: "Today's date.";
+        readonly min: 0;
+        readonly max: 0;
+        readonly result: "date";
+    };
+    readonly NOW: {
+        readonly signature: "NOW()";
+        readonly description: "The current date and time.";
+        readonly min: 0;
+        readonly max: 0;
+        readonly result: "date";
+    };
+    readonly DATEDIFF: {
+        readonly signature: "DATEDIFF(from, to, 'days' | 'hours' | 'minutes')";
+        readonly description: "How far the second date is after the first. Negative when it is earlier.";
+        readonly min: 3;
+        readonly max: 3;
+        readonly result: "number";
+    };
+    readonly YEAR: {
+        readonly signature: "YEAR(date)";
+        readonly description: "The four-digit year of the date.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "number";
+    };
+    readonly MONTH: {
+        readonly signature: "MONTH(date)";
+        readonly description: "The month of the date, 1 to 12.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "number";
+    };
+    readonly DAY: {
+        readonly signature: "DAY(date)";
+        readonly description: "The day of the month, 1 to 31.";
+        readonly min: 1;
+        readonly max: 1;
+        readonly result: "number";
+    };
+    readonly DATEADD: {
+        readonly signature: "DATEADD(date, count, 'days' | 'months' | 'years')";
+        readonly description: "The date moved forward by that many units. Use a negative count to go back.";
+        readonly min: 3;
+        readonly max: 3;
+        readonly result: "date";
+    };
+};
+type FormulaFunctionName = keyof typeof FUNCTION_SPECS;
+/** The help list the formula editor shows. Order is the order it renders in. */
+declare const FORMULA_FUNCTIONS: readonly {
+    name: FormulaFunctionName;
+    signature: string;
+    description: string;
+}[];
+/**
+ * Turn formula text into an AST plus the list of columns it reads.
+ *
+ * `references` holds every `{…}` name exactly as typed, in first-use order —
+ * the caller resolves them (display name OR machine field name) through its own
+ * lookup, so this module never needs to know the table.
+ */
+declare function parseFormula(source: string): ParseResult;
+/**
+ * Compute one cell. NEVER throws.
+ *
+ * `resolve(name)` is given the name exactly as it was typed between the braces
+ * and must return the cell's value, or `undefined` when no such column exists —
+ * the difference between "empty" and "misspelt", which is the difference
+ * between a working formula and a wrong answer.
+ */
+declare function evaluateFormula(ast: FormulaAst, resolve: ResolveCell): FormulaResult;
+/**
+ * Best-effort: what kind of value will this formula produce? The UI uses it to
+ * pick a sensible display format for the computed column. `unknown` is always a
+ * legal answer — never guess a format on a shaky reading.
+ */
+declare function formulaResultType(ast: FormulaAst, columnType: ResolveColumnType): FormulaResultType;
+/** The slice of a field row this helper needs to find and evaluate formulas. */
+interface ComputedColumnField {
+    field_name: string;
+    display_name: string;
+    data_type: string;
+    metadata?: unknown;
+}
+interface ComputedColumn<F extends ComputedColumnField = ComputedColumnField> {
+    field: F;
+    parsed: ParseResult;
+}
+/** True when the column's declared format is `formula`. */
+declare function isFormulaColumn(field: ComputedColumnField): boolean;
+/** Every formula column among `fields`, each with its expression parsed once. */
+declare function formulaColumnsOf<F extends ComputedColumnField>(fields: readonly F[]): ComputedColumn<F>[];
+interface ComputedRowsResult<R> {
+    rows: R[];
+    /** `${rowId}::${fieldName}` → the plain-English reason that cell shows #ERROR. */
+    errors: Map<string, string>;
+    /** Machine names of the formula columns, for callers that must skip them. */
+    formulaFieldNames: Set<string>;
+}
+/**
+ * Return `rows` with every formula column's value computed from the row's
+ * other cells. Pure; the input rows are never mutated. When `fields` holds no
+ * formula column the SAME array is returned, so callers pay nothing.
+ *
+ * Formula columns are evaluated in `fields` order, and each one is written into
+ * the working copy of the row before the next runs — so a later formula may
+ * reference an earlier one. References resolve by machine name first, then by
+ * display name (case-insensitive), matching the grid.
+ */
+declare function withComputedColumns<R extends {
+    id: string;
+    data: Record<string, unknown>;
+}, F extends ComputedColumnField>(rows: readonly R[], fields: readonly F[]): ComputedRowsResult<R>;
+/**
+ * Rewrite every `{from}` reference in `expression` to `{to}` — what keeps a
+ * formula working when the column it names is renamed (Airtable and Sheets do
+ * this silently; a rename that turned a working column into #ERROR would be
+ * the platform punishing the user for tidying up).
+ *
+ * Walks the source with the tokenizer's own rules for the two things that
+ * matter: a `{…}` inside a quoted string is TEXT and is left alone, and `\`
+ * escapes the next character inside a string. The match is on the trimmed
+ * name, case-insensitive — the same comparison `withComputedColumns` makes.
+ * Returns the SAME string when nothing referenced `from`.
+ */
+declare function rewriteFormulaReferences(expression: string, from: string, to: string): string;
+
+export { type BinaryOperator, type ComputedColumn, type ComputedColumnField, type ComputedRowsResult, FORMULA_FUNCTIONS, type FormulaAst, type FormulaFunctionName, type FormulaResult, type FormulaResultType, type FormulaValue, type ParseResult, type ResolveCell, type ResolveColumnType, evaluateFormula, formulaColumnsOf, formulaResultType, isFormulaColumn, parseFormula, rewriteFormulaReferences, withComputedColumns };