@businessdash/sdk 0.9.60

package/src/forms-core/formula.ts

@@ -0,0 +1,1339 @@
+/**
+ * Safe, isomorphic formula engine for Business Functions + the Math form element.
+ *
+ * SECURITY: there is NO `eval`, `new Function`, or any dynamic code execution.
+ * A formula is tokenized → parsed into an AST → walked by an evaluator that only
+ * does arithmetic/logic and calls a fixed, whitelisted function table. Unknown
+ * identifiers (that aren't a provided variable) and unknown functions are hard
+ * errors. The same module runs on the client (non-sensitive functions, live) and
+ * the server (all functions) so results never disagree. The SDK keeps a mirror at
+ * `biab-dev/src/forms-core/formula.ts`.
+ *
+ * Values are scalars: number | string | boolean. (Tables / arrays are a
+ * fast-follow.) Function reference: see FORMULA_FUNCTIONS.
+ */
+
+/** A record value — e.g. a measurement field `{ size, unit, base }`, a CRM record,
+ *  or a multi-output function result. Fields are read with member access
+ *  (`source.field`). */
+export interface FormulaObject {
+	[key: string]: FormulaValue;
+}
+export type FormulaValue = number | string | boolean | FormulaObject;
+export type FormulaVars = Record<string, FormulaValue | null | undefined>;
+
+function isFormulaObject(v: FormulaValue): v is FormulaObject {
+	return typeof v === "object" && v !== null;
+}
+
+/** Public guard: is this value a record (object) rather than a scalar? */
+export function isFormulaObjectValue(v: unknown): v is FormulaObject {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export type FormulaResult =
+	| { ok: true; value: FormulaValue }
+	| { ok: false; error: string };
+
+// ── AST ──────────────────────────────────────────────────────────────────────
+
+type Node =
+	| { t: "num"; v: number }
+	| { t: "str"; v: string }
+	| { t: "bool"; v: boolean }
+	| { t: "var"; name: string }
+	| { t: "member"; obj: Node; key: string }
+	| { t: "unary"; op: string; arg: Node }
+	| { t: "binary"; op: string; left: Node; right: Node }
+	| { t: "call"; name: string; args: Node[] };
+
+/** A formula AST plus the names it references (for validation/UI). */
+export interface ParsedFormula {
+	ast: Node;
+	/** Distinct variable identifiers referenced (excludes function names). */
+	variables: string[];
+	/** Distinct function names called (built-in or user/business functions). */
+	functions: string[];
+}
+
+/**
+ * A user/business function callable from another formula by name. `params` are
+ * the ordered variable names the call's arguments bind to. Pass a map of these
+ * to {@link evaluateFormula} so formulas can reference other functions.
+ */
+export interface UserFunctionDef {
+	params: string[];
+	formula: ParsedFormula;
+}
+
+export interface EvalOptions {
+	/** name → user function, enabling formula-references-formula composition. */
+	functions?: Record<string, UserFunctionDef>;
+}
+
+interface EvalCtx {
+	vars: FormulaVars;
+	fns: Record<string, UserFunctionDef>;
+	/** Names currently on the call stack — for circular-reference detection. */
+	stack: Set<string>;
+}
+
+class FormulaError extends Error {}
+
+// ── Tokenizer ────────────────────────────────────────────────────────────────
+
+type Tok =
+	| { k: "num"; v: number }
+	| { k: "str"; v: string }
+	| { k: "ident"; v: string }
+	| { k: "op"; v: string }
+	| { k: "lparen" }
+	| { k: "rparen" }
+	| { k: "comma" }
+	| { k: "dot" };
+
+const MULTI_OPS = ["<=", ">=", "<>", "==", "!=", "&&", "||"];
+const SINGLE_OPS = new Set([
+	"+",
+	"-",
+	"*",
+	"/",
+	"%",
+	"^",
+	"&",
+	"<",
+	">",
+	"=",
+	"!",
+]);
+
+function tokenize(src: string): Tok[] {
+	const toks: Tok[] = [];
+	let i = 0;
+	const n = src.length;
+	while (i < n) {
+		const c = src[i] as string;
+		if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		// String literal: "..." with \" escape.
+		if (c === '"') {
+			let s = "";
+			i++;
+			while (i < n && src[i] !== '"') {
+				if (src[i] === "\\" && i + 1 < n) {
+					s += src[i + 1];
+					i += 2;
+				} else {
+					s += src[i];
+					i++;
+				}
+			}
+			if (i >= n) throw new FormulaError("Unterminated string literal.");
+			i++; // closing quote
+			toks.push({ k: "str", v: s });
+			continue;
+		}
+		// Number: 12, 12.5, .5, 1e3
+		if (
+			(c >= "0" && c <= "9") ||
+			(c === "." && /[0-9]/.test(src[i + 1] ?? ""))
+		) {
+			let j = i;
+			while (j < n && /[0-9.]/.test(src[j] as string)) j++;
+			if ((src[j] === "e" || src[j] === "E") && j + 1 < n) {
+				j++;
+				if (src[j] === "+" || src[j] === "-") j++;
+				while (j < n && /[0-9]/.test(src[j] as string)) j++;
+			}
+			const raw = src.slice(i, j);
+			const num = Number(raw);
+			if (Number.isNaN(num)) throw new FormulaError(`Invalid number "${raw}".`);
+			toks.push({ k: "num", v: num });
+			i = j;
+			continue;
+		}
+		// Identifier (function / variable / TRUE / FALSE): letters, digits, _
+		if (/[A-Za-z_]/.test(c)) {
+			let j = i;
+			while (j < n && /[A-Za-z0-9_]/.test(src[j] as string)) j++;
+			toks.push({ k: "ident", v: src.slice(i, j) });
+			i = j;
+			continue;
+		}
+		if (c === "(") {
+			toks.push({ k: "lparen" });
+			i++;
+			continue;
+		}
+		if (c === ")") {
+			toks.push({ k: "rparen" });
+			i++;
+			continue;
+		}
+		if (c === ",") {
+			toks.push({ k: "comma" });
+			i++;
+			continue;
+		}
+		// Member access dot (a leading-digit "." was already consumed as a number).
+		if (c === ".") {
+			toks.push({ k: "dot" });
+			i++;
+			continue;
+		}
+		// Operators (multi-char first).
+		const two = src.slice(i, i + 2);
+		if (MULTI_OPS.includes(two)) {
+			toks.push({ k: "op", v: two });
+			i += 2;
+			continue;
+		}
+		if (SINGLE_OPS.has(c)) {
+			toks.push({ k: "op", v: c });
+			i++;
+			continue;
+		}
+		throw new FormulaError(`Unexpected character "${c}".`);
+	}
+	return toks;
+}
+
+// ── Parser (recursive descent, lowest precedence first) ──────────────────────
+
+class Parser {
+	private pos = 0;
+	constructor(private readonly toks: Tok[]) {}
+
+	private peek(): Tok | undefined {
+		return this.toks[this.pos];
+	}
+	private next(): Tok | undefined {
+		return this.toks[this.pos++];
+	}
+	private eat(k: Tok["k"]): Tok {
+		const t = this.next();
+		if (!t || t.k !== k) throw new FormulaError(`Expected ${k}.`);
+		return t;
+	}
+	private isOp(v: string): boolean {
+		const t = this.peek();
+		return !!t && t.k === "op" && t.v === v;
+	}
+	private isIdent(v: string): boolean {
+		const t = this.peek();
+		return !!t && t.k === "ident" && t.v.toUpperCase() === v;
+	}
+
+	parse(): Node {
+		const node = this.parseOr();
+		if (this.pos < this.toks.length)
+			throw new FormulaError("Unexpected trailing input.");
+		return node;
+	}
+
+	private parseOr(): Node {
+		let left = this.parseAnd();
+		while (this.isOp("||") || this.isIdent("OR")) {
+			this.next();
+			const right = this.parseAnd();
+			left = { t: "binary", op: "OR", left, right };
+		}
+		return left;
+	}
+	private parseAnd(): Node {
+		let left = this.parseNot();
+		while (this.isOp("&&") || this.isIdent("AND")) {
+			this.next();
+			const right = this.parseNot();
+			left = { t: "binary", op: "AND", left, right };
+		}
+		return left;
+	}
+	private parseNot(): Node {
+		if (this.isOp("!") || this.isIdent("NOT")) {
+			this.next();
+			return { t: "unary", op: "NOT", arg: this.parseNot() };
+		}
+		return this.parseComparison();
+	}
+	private parseComparison(): Node {
+		let left = this.parseConcat();
+		const cmp = ["=", "==", "<>", "!=", "<", ">", "<=", ">="];
+		while (
+			this.peek()?.k === "op" &&
+			cmp.includes((this.peek() as { v: string }).v)
+		) {
+			const op = (this.next() as { v: string }).v;
+			const right = this.parseConcat();
+			left = { t: "binary", op, left, right };
+		}
+		return left;
+	}
+	private parseConcat(): Node {
+		let left = this.parseAdd();
+		while (this.isOp("&")) {
+			this.next();
+			left = { t: "binary", op: "&", left, right: this.parseAdd() };
+		}
+		return left;
+	}
+	private parseAdd(): Node {
+		let left = this.parseMul();
+		while (this.isOp("+") || this.isOp("-")) {
+			const op = (this.next() as { v: string }).v;
+			left = { t: "binary", op, left, right: this.parseMul() };
+		}
+		return left;
+	}
+	private parseMul(): Node {
+		let left = this.parseUnary();
+		while (this.isOp("*") || this.isOp("/") || this.isOp("%")) {
+			const op = (this.next() as { v: string }).v;
+			left = { t: "binary", op, left, right: this.parseUnary() };
+		}
+		return left;
+	}
+	private parseUnary(): Node {
+		if (this.isOp("-") || this.isOp("+")) {
+			const op = (this.next() as { v: string }).v;
+			return { t: "unary", op, arg: this.parseUnary() };
+		}
+		return this.parsePower();
+	}
+	private parsePower(): Node {
+		const base = this.parsePrimary();
+		if (this.isOp("^")) {
+			this.next();
+			// Right-associative.
+			return { t: "binary", op: "^", left: base, right: this.parseUnary() };
+		}
+		return base;
+	}
+	private parsePrimary(): Node {
+		// Atom followed by zero or more `.field` member accesses.
+		let node = this.parseAtom();
+		while (this.peek()?.k === "dot") {
+			this.next();
+			const id = this.eat("ident");
+			node = { t: "member", obj: node, key: (id as { v: string }).v };
+		}
+		return node;
+	}
+	private parseAtom(): Node {
+		const t = this.peek();
+		if (!t) throw new FormulaError("Unexpected end of formula.");
+		if (t.k === "num") {
+			this.next();
+			return { t: "num", v: t.v };
+		}
+		if (t.k === "str") {
+			this.next();
+			return { t: "str", v: t.v };
+		}
+		if (t.k === "lparen") {
+			this.next();
+			const inner = this.parseOr();
+			this.eat("rparen");
+			return inner;
+		}
+		if (t.k === "ident") {
+			this.next();
+			const upper = t.v.toUpperCase();
+			if (upper === "TRUE") return { t: "bool", v: true };
+			if (upper === "FALSE") return { t: "bool", v: false };
+			// Function call?
+			if (this.peek()?.k === "lparen") {
+				this.next();
+				const args: Node[] = [];
+				if (this.peek()?.k !== "rparen") {
+					args.push(this.parseOr());
+					while (this.peek()?.k === "comma") {
+						this.next();
+						args.push(this.parseOr());
+					}
+				}
+				this.eat("rparen");
+				return { t: "call", name: upper, args };
+			}
+			return { t: "var", name: t.v };
+		}
+		throw new FormulaError(`Unexpected token.`);
+	}
+}
+
+// ── Coercion helpers ─────────────────────────────────────────────────────────
+
+function toNum(v: FormulaValue): number {
+	if (typeof v === "number") return v;
+	if (typeof v === "boolean") return v ? 1 : 0;
+	if (isFormulaObject(v))
+		throw new FormulaError("Cannot use an object as a number.");
+	const n = Number(v);
+	if (Number.isNaN(n)) throw new FormulaError(`"${v}" is not a number.`);
+	return n;
+}
+function toBool(v: FormulaValue): boolean {
+	if (typeof v === "boolean") return v;
+	if (typeof v === "number") return v !== 0;
+	if (isFormulaObject(v))
+		throw new FormulaError("Cannot use an object as a boolean.");
+	return v !== "" && v.toLowerCase() !== "false";
+}
+function toStr(v: FormulaValue): string {
+	if (typeof v === "string") return v;
+	if (isFormulaObject(v))
+		throw new FormulaError("Cannot use an object as text.");
+	return String(v);
+}
+
+// ── Function library ─────────────────────────────────────────────────────────
+
+export type FormulaCategory =
+	| "math"
+	| "statistical"
+	| "logical"
+	| "text"
+	| "date"
+	| "reference"
+	| "geo";
+
+interface FnDef {
+	category: FormulaCategory;
+	/** Min args (inclusive). */
+	min: number;
+	/** Max args, or null for variadic. */
+	max: number | null;
+	help: string;
+	fn: (args: FormulaValue[]) => FormulaValue;
+}
+
+const R = (n: number, places = 0) => {
+	const f = 10 ** places;
+	return Math.round(n * f) / f;
+};
+
+function parseDate(v: FormulaValue): Date {
+	const d = new Date(typeof v === "number" ? v : String(v));
+	if (Number.isNaN(d.getTime())) throw new FormulaError("Invalid date.");
+	return d;
+}
+
+/** Haversine distance between two lat/lng points. Default km; "mi" for miles. */
+function haversine(
+	lat1: number,
+	lng1: number,
+	lat2: number,
+	lng2: number,
+	unit: "km" | "mi" = "km",
+): number {
+	const toRad = (d: number) => (d * Math.PI) / 180;
+	const Rk = 6371; // km
+	const dLat = toRad(lat2 - lat1);
+	const dLng = toRad(lng2 - lng1);
+	const a =
+		Math.sin(dLat / 2) ** 2 +
+		Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
+	const km = 2 * Rk * Math.asin(Math.min(1, Math.sqrt(a)));
+	return unit === "mi" ? km * 0.621371 : km;
+}
+
+/** Extension → file category for FILETYPE(url). */
+const FILE_TYPE_BY_EXT: Record<string, string> = {};
+for (const [type, exts] of [
+	["image", ["png", "jpg", "jpeg", "gif", "webp", "svg", "avif", "heic"]],
+	["video", ["mp4", "mov", "webm", "mkv", "avi"]],
+	["audio", ["mp3", "wav", "m4a", "flac", "ogg", "aac"]],
+	["pdf", ["pdf"]],
+	["doc", ["doc", "docx", "txt", "rtf", "md", "pages"]],
+	["spreadsheet", ["xls", "xlsx", "csv", "numbers"]],
+	["archive", ["zip", "rar", "7z", "tar", "gz"]],
+] as const) {
+	for (const ext of exts) FILE_TYPE_BY_EXT[ext] = type;
+}
+
+/** File category of a URL/filename by its extension (lowercased, query/hash
+ *  stripped). Empty / extension-less / unknown-extension input → "other". */
+function fileTypeOf(url: string): string {
+	const path = (url.split(/[?#]/, 1)[0] ?? "").trim();
+	const dot = path.lastIndexOf(".");
+	if (dot === -1) return "other";
+	const ext = path.slice(dot + 1).toLowerCase();
+	return FILE_TYPE_BY_EXT[ext] ?? "other";
+}
+
+/**
+ * Replace every occurrence of any `find` with its paired `replace`, in ONE pass.
+ *
+ * Single-pass is the whole point. A naive implementation loops the pairs and
+ * calls `replaceAll` for each, which CHAINS: `SUBSTITUTE(t,"a","b","b","c")`
+ * would turn an "a" into "b" and then that "b" into "c". Scanning once and
+ * taking the first pair that matches at each position means a replacement's
+ * OUTPUT is never re-examined, so pairs stay independent of their order.
+ *
+ * Longest-match-first at each position, so overlapping patterns behave the way
+ * people expect ("ab" wins over "a" when both are listed).
+ */
+function substituteAll(
+	text: string,
+	pairs: ReadonlyArray<readonly [string, string]>,
+): string {
+	// Empty search strings would match at every position and never advance.
+	const active = pairs.filter(([find]) => find.length > 0);
+	if (active.length === 0) return text;
+	const ordered = [...active].sort((a, b) => b[0].length - a[0].length);
+
+	let out = "";
+	let i = 0;
+	outer: while (i < text.length) {
+		for (const [find, replace] of ordered) {
+			if (text.startsWith(find, i)) {
+				out += replace;
+				i += find.length;
+				continue outer;
+			}
+		}
+		out += text[i];
+		i += 1;
+	}
+	return out;
+}
+
+/**
+ * The platform's canonical slug.
+ *
+ * There were five hand-rolled `slugify` functions in this codebase when this
+ * was written (docs TOC, site-builder, page-builder, company locations, blog
+ * editor) and they did NOT agree — some stripped accents, some didn't; some
+ * collapsed repeated separators, some left them. This is the one a form can
+ * reach, and it is deliberately the strict version:
+ *
+ *   lowercase → strip accents → anything not [a-z0-9] becomes a hyphen →
+ *   collapse runs → trim leading/trailing hyphens.
+ *
+ * "Solar Panel Install (2026)" → "solar-panel-install-2026"
+ */
+function slugifyText(text: string): string {
+	return (
+		text
+			.normalize("NFKD")
+			// Combining marks left behind by NFKD — é → e, not e+◌́.
+			.replace(/[\u0300-\u036f]/g, "")
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "")
+	);
+}
+
+export const FORMULA_FUNCTIONS: Record<string, FnDef> = {
+	// Math
+	SUM: {
+		category: "math",
+		min: 1,
+		max: null,
+		help: "Sum of the arguments.",
+		fn: (a) => a.reduce((s: number, x) => s + toNum(x), 0),
+	},
+	PRODUCT: {
+		category: "math",
+		min: 1,
+		max: null,
+		help: "Product of the arguments.",
+		fn: (a) => a.reduce((s: number, x) => s * toNum(x), 1),
+	},
+	ABS: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Absolute value.",
+		fn: (a) => Math.abs(toNum(a[0] as FormulaValue)),
+	},
+	ROUND: {
+		category: "math",
+		min: 1,
+		max: 2,
+		help: "Round to N decimal places.",
+		fn: (a) =>
+			R(toNum(a[0] as FormulaValue), a[1] !== undefined ? toNum(a[1]) : 0),
+	},
+	ROUNDUP: {
+		category: "math",
+		min: 1,
+		max: 2,
+		help: "Round up.",
+		fn: (a) => {
+			const p = a[1] !== undefined ? toNum(a[1]) : 0;
+			const f = 10 ** p;
+			return Math.ceil(toNum(a[0] as FormulaValue) * f) / f;
+		},
+	},
+	ROUNDDOWN: {
+		category: "math",
+		min: 1,
+		max: 2,
+		help: "Round down (toward zero).",
+		fn: (a) => {
+			const p = a[1] !== undefined ? toNum(a[1]) : 0;
+			const f = 10 ** p;
+			return Math.trunc(toNum(a[0] as FormulaValue) * f) / f;
+		},
+	},
+	CEILING: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Round up to the nearest integer.",
+		fn: (a) => Math.ceil(toNum(a[0] as FormulaValue)),
+	},
+	FLOOR: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Round down to the nearest integer.",
+		fn: (a) => Math.floor(toNum(a[0] as FormulaValue)),
+	},
+	INT: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Integer part (toward zero).",
+		fn: (a) => Math.trunc(toNum(a[0] as FormulaValue)),
+	},
+	MOD: {
+		category: "math",
+		min: 2,
+		max: 2,
+		help: "Remainder of division.",
+		fn: (a) => toNum(a[0] as FormulaValue) % toNum(a[1] as FormulaValue),
+	},
+	POWER: {
+		category: "math",
+		min: 2,
+		max: 2,
+		help: "Base raised to an exponent.",
+		fn: (a) => toNum(a[0] as FormulaValue) ** toNum(a[1] as FormulaValue),
+	},
+	SQRT: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Square root.",
+		fn: (a) => Math.sqrt(toNum(a[0] as FormulaValue)),
+	},
+	SIGN: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "-1, 0, or 1.",
+		fn: (a) => Math.sign(toNum(a[0] as FormulaValue)),
+	},
+	EXP: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "e raised to a power.",
+		fn: (a) => Math.exp(toNum(a[0] as FormulaValue)),
+	},
+	LN: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Natural log.",
+		fn: (a) => Math.log(toNum(a[0] as FormulaValue)),
+	},
+	LOG10: {
+		category: "math",
+		min: 1,
+		max: 1,
+		help: "Base-10 log.",
+		fn: (a) => Math.log10(toNum(a[0] as FormulaValue)),
+	},
+
+	// Statistical
+	AVERAGE: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Mean of the arguments.",
+		fn: (a) => a.reduce((s: number, x) => s + toNum(x), 0) / a.length,
+	},
+	MIN: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Smallest argument.",
+		fn: (a) => Math.min(...a.map(toNum)),
+	},
+	MAX: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Largest argument.",
+		fn: (a) => Math.max(...a.map(toNum)),
+	},
+	MEDIAN: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Middle value.",
+		fn: (a) => {
+			const s = a.map(toNum).sort((x, y) => x - y);
+			const m = Math.floor(s.length / 2);
+			return s.length % 2
+				? (s[m] as number)
+				: ((s[m - 1] as number) + (s[m] as number)) / 2;
+		},
+	},
+	COUNT: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Count of numeric arguments.",
+		fn: (a) =>
+			a.filter(
+				(x) =>
+					typeof x === "number" ||
+					(typeof x === "string" &&
+						x.trim() !== "" &&
+						!Number.isNaN(Number(x))),
+			).length,
+	},
+	COUNTA: {
+		category: "statistical",
+		min: 1,
+		max: null,
+		help: "Count of non-empty arguments.",
+		fn: (a) =>
+			a.filter((x) => x !== "" && x !== null && x !== undefined).length,
+	},
+
+	// Logical
+	IF: {
+		category: "logical",
+		min: 2,
+		max: 3,
+		help: "IF(test, then, else).",
+		fn: (a) =>
+			toBool(a[0] as FormulaValue)
+				? (a[1] as FormulaValue)
+				: a[2] !== undefined
+					? a[2]
+					: false,
+	},
+	AND: {
+		category: "logical",
+		min: 1,
+		max: null,
+		help: "True when all are true.",
+		fn: (a) => a.every(toBool),
+	},
+	OR: {
+		category: "logical",
+		min: 1,
+		max: null,
+		help: "True when any is true.",
+		fn: (a) => a.some(toBool),
+	},
+	NOT: {
+		category: "logical",
+		min: 1,
+		max: 1,
+		help: "Logical negation.",
+		fn: (a) => !toBool(a[0] as FormulaValue),
+	},
+	XOR: {
+		category: "logical",
+		min: 1,
+		max: null,
+		help: "True when an odd number are true.",
+		fn: (a) => a.filter(toBool).length % 2 === 1,
+	},
+	TRUE: {
+		category: "logical",
+		min: 0,
+		max: 0,
+		help: "The boolean true.",
+		fn: () => true,
+	},
+	FALSE: {
+		category: "logical",
+		min: 0,
+		max: 0,
+		help: "The boolean false.",
+		fn: () => false,
+	},
+	IFS: {
+		category: "logical",
+		min: 2,
+		max: null,
+		help: "IFS(test1, val1, test2, val2, …).",
+		fn: (a) => {
+			for (let i = 0; i + 1 < a.length; i += 2) {
+				if (toBool(a[i] as FormulaValue)) return a[i + 1] as FormulaValue;
+			}
+			throw new FormulaError("No IFS condition matched.");
+		},
+	},
+
+	// Reference
+	CHOOSE: {
+		category: "reference",
+		min: 2,
+		max: null,
+		help: "CHOOSE(index, a, b, …) — 1-based.",
+		fn: (a) => {
+			const idx = Math.trunc(toNum(a[0] as FormulaValue));
+			const v = a[idx];
+			if (v === undefined) throw new FormulaError("CHOOSE index out of range.");
+			return v;
+		},
+	},
+	SWITCH: {
+		category: "reference",
+		min: 3,
+		max: null,
+		help: "SWITCH(expr, case1, val1, …, [default]).",
+		fn: (a) => {
+			const expr = a[0] as FormulaValue;
+			let i = 1;
+			for (; i + 1 < a.length; i += 2) {
+				if ((a[i] as FormulaValue) === expr) return a[i + 1] as FormulaValue;
+			}
+			return i < a.length ? (a[i] as FormulaValue) : false;
+		},
+	},
+
+	// Text
+	CONCATENATE: {
+		category: "text",
+		min: 1,
+		max: null,
+		help: "Join text together.",
+		fn: (a) => a.map(toStr).join(""),
+	},
+	LEN: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: "Length of text.",
+		fn: (a) => toStr(a[0] as FormulaValue).length,
+	},
+	LOWER: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: "Lowercase.",
+		fn: (a) => toStr(a[0] as FormulaValue).toLowerCase(),
+	},
+	UPPER: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: "Uppercase.",
+		fn: (a) => toStr(a[0] as FormulaValue).toUpperCase(),
+	},
+	SUBSTITUTE: {
+		category: "text",
+		min: 3,
+		max: null,
+		help: 'Replace text. SUBSTITUTE(text, find, replace, [find2, replace2, ...]). Pairs are applied in a single pass, so a replacement\'s output is never itself replaced. Repeat the same replacement to map several things onto one: SUBSTITUTE(name, " ", "-", "_", "-").',
+		fn: (a) => {
+			const text = toStr(a[0] as FormulaValue);
+			const rest = a.slice(1);
+			if (rest.length % 2 !== 0) {
+				throw new FormulaError(
+					"SUBSTITUTE needs find/replace in pairs — it got an odd number of arguments after the text.",
+				);
+			}
+			const pairs: Array<[string, string]> = [];
+			for (let i = 0; i < rest.length; i += 2) {
+				pairs.push([
+					toStr(rest[i] as FormulaValue),
+					toStr(rest[i + 1] as FormulaValue),
+				]);
+			}
+			return substituteAll(text, pairs);
+		},
+	},
+	SLUGIFY: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: 'URL-safe slug: lowercase, accents stripped, non-alphanumerics collapsed to single hyphens. SLUGIFY("Solar Panel Install (2026)") is "solar-panel-install-2026".',
+		fn: (a) => slugifyText(toStr(a[0] as FormulaValue)),
+	},
+	TRIM: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: "Trim surrounding whitespace.",
+		fn: (a) => toStr(a[0] as FormulaValue).trim(),
+	},
+	LEFT: {
+		category: "text",
+		min: 1,
+		max: 2,
+		help: "Leftmost N characters.",
+		fn: (a) =>
+			toStr(a[0] as FormulaValue).slice(
+				0,
+				a[1] !== undefined ? toNum(a[1]) : 1,
+			),
+	},
+	RIGHT: {
+		category: "text",
+		min: 1,
+		max: 2,
+		help: "Rightmost N characters.",
+		fn: (a) => {
+			const n = a[1] !== undefined ? toNum(a[1]) : 1;
+			return toStr(a[0] as FormulaValue).slice(-n);
+		},
+	},
+	MID: {
+		category: "text",
+		min: 3,
+		max: 3,
+		help: "MID(text, start, length) — 1-based start.",
+		fn: (a) => {
+			const start = toNum(a[1] as FormulaValue) - 1;
+			return toStr(a[0] as FormulaValue).slice(
+				start,
+				start + toNum(a[2] as FormulaValue),
+			);
+		},
+	},
+	FILETYPE: {
+		category: "text",
+		min: 1,
+		max: 1,
+		help: 'File category of a URL by extension: "image", "video", "audio", "pdf", "doc", "spreadsheet", "archive", or "other".',
+		fn: (a) => fileTypeOf(toStr(a[0] as FormulaValue)),
+	},
+
+	// Date (parse ISO strings; return numbers)
+	TODAY: {
+		category: "date",
+		min: 0,
+		max: 0,
+		help: "Today's date (ISO string).",
+		fn: () => new Date().toISOString().slice(0, 10),
+	},
+	YEAR: {
+		category: "date",
+		min: 1,
+		max: 1,
+		help: "Year of a date.",
+		fn: (a) => parseDate(a[0] as FormulaValue).getUTCFullYear(),
+	},
+	MONTH: {
+		category: "date",
+		min: 1,
+		max: 1,
+		help: "Month of a date (1-12).",
+		fn: (a) => parseDate(a[0] as FormulaValue).getUTCMonth() + 1,
+	},
+	DAY: {
+		category: "date",
+		min: 1,
+		max: 1,
+		help: "Day of the month.",
+		fn: (a) => parseDate(a[0] as FormulaValue).getUTCDate(),
+	},
+	DAYS: {
+		category: "date",
+		min: 2,
+		max: 2,
+		help: "Whole days between two dates (end - start).",
+		fn: (a) =>
+			Math.round(
+				(parseDate(a[0] as FormulaValue).getTime() -
+					parseDate(a[1] as FormulaValue).getTime()) /
+					86_400_000,
+			),
+	},
+	NOW: {
+		category: "date",
+		min: 0,
+		max: 0,
+		help: "Current date-time (ISO string).",
+		fn: () => new Date().toISOString(),
+	},
+	MINUTES: {
+		category: "date",
+		min: 2,
+		max: 2,
+		help: "Minutes between two date-times (end - start).",
+		fn: (a) =>
+			Math.round(
+				(parseDate(a[1] as FormulaValue).getTime() -
+					parseDate(a[0] as FormulaValue).getTime()) /
+					60_000,
+			),
+	},
+	HOURS: {
+		category: "date",
+		min: 2,
+		max: 3,
+		help: "Hours between two date-times (end - start); HOURS(start, end, decimals=2).",
+		fn: (a) => {
+			const p = a[2] !== undefined ? toNum(a[2]) : 2;
+			const f = 10 ** p;
+			return (
+				Math.round(
+					((parseDate(a[1] as FormulaValue).getTime() -
+						parseDate(a[0] as FormulaValue).getTime()) /
+						3_600_000) *
+						f,
+				) / f
+			);
+		},
+	},
+	WEEKS: {
+		category: "date",
+		min: 2,
+		max: 2,
+		help: "Whole weeks between two dates (end - start).",
+		fn: (a) =>
+			Math.trunc(
+				(parseDate(a[1] as FormulaValue).getTime() -
+					parseDate(a[0] as FormulaValue).getTime()) /
+					604_800_000,
+			),
+	},
+	MONTHS: {
+		category: "date",
+		min: 2,
+		max: 2,
+		help: "Whole calendar months completed between two dates (end - start).",
+		fn: (a) => {
+			const s = parseDate(a[0] as FormulaValue);
+			const e = parseDate(a[1] as FormulaValue);
+			let m =
+				(e.getUTCFullYear() - s.getUTCFullYear()) * 12 +
+				(e.getUTCMonth() - s.getUTCMonth());
+			if (e.getUTCDate() < s.getUTCDate()) m -= 1;
+			return m;
+		},
+	},
+	YEARS: {
+		category: "date",
+		min: 2,
+		max: 2,
+		help: "Whole years completed between two dates (end - start).",
+		fn: (a) => {
+			const s = parseDate(a[0] as FormulaValue);
+			const e = parseDate(a[1] as FormulaValue);
+			let y = e.getUTCFullYear() - s.getUTCFullYear();
+			const anniv = Date.UTC(
+				e.getUTCFullYear(),
+				s.getUTCMonth(),
+				s.getUTCDate(),
+			);
+			if (e.getTime() < anniv) y -= 1;
+			return y;
+		},
+	},
+	DATEDIFF: {
+		category: "date",
+		min: 3,
+		max: 3,
+		help: 'DATEDIFF("minutes"|"hours"|"days"|"weeks"|"months"|"years", start, end).',
+		fn: (a) => {
+			const unit = toStr(a[0] as FormulaValue).toLowerCase();
+			const s = parseDate(a[1] as FormulaValue);
+			const e = parseDate(a[2] as FormulaValue);
+			const ms = e.getTime() - s.getTime();
+			switch (unit) {
+				case "minutes":
+					return Math.round(ms / 60_000);
+				case "hours":
+					return Math.round((ms / 3_600_000) * 100) / 100;
+				case "days":
+					return Math.round(ms / 86_400_000);
+				case "weeks":
+					return Math.trunc(ms / 604_800_000);
+				case "months": {
+					let m =
+						(e.getUTCFullYear() - s.getUTCFullYear()) * 12 +
+						(e.getUTCMonth() - s.getUTCMonth());
+					if (e.getUTCDate() < s.getUTCDate()) m -= 1;
+					return m;
+				}
+				case "years": {
+					let y = e.getUTCFullYear() - s.getUTCFullYear();
+					const anniv = Date.UTC(
+						e.getUTCFullYear(),
+						s.getUTCMonth(),
+						s.getUTCDate(),
+					);
+					if (e.getTime() < anniv) y -= 1;
+					return y;
+				}
+				default:
+					throw new FormulaError(`Unknown DATEDIFF unit "${unit}".`);
+			}
+		},
+	},
+
+	// Geo
+	DISTANCE: {
+		category: "geo",
+		min: 4,
+		max: 5,
+		help: 'DISTANCE(lat1, lng1, lat2, lng2, ["km"|"mi"]) — straight-line (haversine).',
+		fn: (a) => {
+			const unit =
+				a[4] !== undefined && toStr(a[4]).toLowerCase() === "mi" ? "mi" : "km";
+			return haversine(
+				toNum(a[0] as FormulaValue),
+				toNum(a[1] as FormulaValue),
+				toNum(a[2] as FormulaValue),
+				toNum(a[3] as FormulaValue),
+				unit,
+			);
+		},
+	},
+};
+
+// ── Evaluator ────────────────────────────────────────────────────────────────
+
+function evalNode(node: Node, ctx: EvalCtx): FormulaValue {
+	switch (node.t) {
+		case "num":
+			return node.v;
+		case "str":
+			return node.v;
+		case "bool":
+			return node.v;
+		case "var": {
+			const v = ctx.vars[node.name];
+			if (v === undefined || v === null)
+				throw new FormulaError(`Variable "${node.name}" has no value.`);
+			return v;
+		}
+		case "member": {
+			const obj = evalNode(node.obj, ctx);
+			if (!isFormulaObject(obj))
+				throw new FormulaError(
+					`Cannot read field "${node.key}" of a non-object value.`,
+				);
+			const v = obj[node.key];
+			if (v === undefined || v === null)
+				throw new FormulaError(`Field "${node.key}" has no value.`);
+			return v;
+		}
+		case "unary": {
+			if (node.op === "NOT") return !toBool(evalNode(node.arg, ctx));
+			const x = toNum(evalNode(node.arg, ctx));
+			return node.op === "-" ? -x : x;
+		}
+		case "binary":
+			return evalBinary(node, ctx);
+		case "call": {
+			const def = FORMULA_FUNCTIONS[node.name];
+			if (def) {
+				const args = node.args.map((a) => evalNode(a, ctx));
+				if (
+					args.length < def.min ||
+					(def.max !== null && args.length > def.max)
+				)
+					throw new FormulaError(
+						`${node.name} got the wrong number of arguments.`,
+					);
+				return def.fn(args);
+			}
+			// User / business function (formula references another formula).
+			const user = ctx.fns[node.name];
+			if (!user) throw new FormulaError(`Unknown function "${node.name}".`);
+			if (ctx.stack.has(node.name))
+				throw new FormulaError(`Circular function reference: "${node.name}".`);
+			if (node.args.length !== user.params.length)
+				throw new FormulaError(
+					`${node.name} expects ${user.params.length} argument(s).`,
+				);
+			const args = node.args.map((a) => evalNode(a, ctx));
+			const scope: FormulaVars = {};
+			user.params.forEach((p, i) => {
+				scope[p] = args[i];
+			});
+			return evalNode(user.formula.ast, {
+				vars: scope,
+				fns: ctx.fns,
+				stack: new Set([...ctx.stack, node.name]),
+			});
+		}
+	}
+}
+
+function evalBinary(
+	node: Extract<Node, { t: "binary" }>,
+	ctx: EvalCtx,
+): FormulaValue {
+	const { op } = node;
+	// Short-circuit logical operators.
+	if (op === "AND")
+		return (
+			toBool(evalNode(node.left, ctx)) && toBool(evalNode(node.right, ctx))
+		);
+	if (op === "OR")
+		return (
+			toBool(evalNode(node.left, ctx)) || toBool(evalNode(node.right, ctx))
+		);
+	const l = evalNode(node.left, ctx);
+	const r = evalNode(node.right, ctx);
+	switch (op) {
+		case "+":
+			return toNum(l) + toNum(r);
+		case "-":
+			return toNum(l) - toNum(r);
+		case "*":
+			return toNum(l) * toNum(r);
+		case "/": {
+			const d = toNum(r);
+			if (d === 0) throw new FormulaError("Division by zero.");
+			return toNum(l) / d;
+		}
+		case "%": {
+			const d = toNum(r);
+			if (d === 0) throw new FormulaError("Division by zero.");
+			return toNum(l) % d;
+		}
+		case "^":
+			return toNum(l) ** toNum(r);
+		case "&":
+			return toStr(l) + toStr(r);
+		case "=":
+		case "==":
+			return looseEq(l, r);
+		case "<>":
+		case "!=":
+			return !looseEq(l, r);
+		case "<":
+			return cmp(l, r) < 0;
+		case ">":
+			return cmp(l, r) > 0;
+		case "<=":
+			return cmp(l, r) <= 0;
+		case ">=":
+			return cmp(l, r) >= 0;
+		default:
+			throw new FormulaError(`Unknown operator "${op}".`);
+	}
+}
+
+function looseEq(l: FormulaValue, r: FormulaValue): boolean {
+	if (typeof l === "number" || typeof r === "number") {
+		const ln = Number(l);
+		const rn = Number(r);
+		if (!Number.isNaN(ln) && !Number.isNaN(rn)) return ln === rn;
+	}
+	return toStr(l) === toStr(r);
+}
+function cmp(l: FormulaValue, r: FormulaValue): number {
+	if (typeof l === "number" || typeof r === "number") {
+		return toNum(l) - toNum(r);
+	}
+	return toStr(l) < toStr(r) ? -1 : toStr(l) > toStr(r) ? 1 : 0;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/** Parse a formula into an AST + its referenced variables. Throws on syntax error. */
+export function parseFormula(src: string): ParsedFormula {
+	const ast = new Parser(tokenize(src)).parse();
+	const variables = new Set<string>();
+	const functions = new Set<string>();
+	const collect = (n: Node) => {
+		if (n.t === "var") variables.add(n.name);
+		else if (n.t === "member") collect(n.obj);
+		else if (n.t === "unary") collect(n.arg);
+		else if (n.t === "binary") {
+			collect(n.left);
+			collect(n.right);
+		} else if (n.t === "call") {
+			functions.add(n.name);
+			n.args.forEach(collect);
+		}
+	};
+	collect(ast);
+	return { ast, variables: [...variables], functions: [...functions] };
+}
+
+/** Evaluate a parsed formula against a variables context. Never throws — returns
+ *  a controlled result. */
+export function evaluateFormula(
+	parsed: ParsedFormula,
+	vars: FormulaVars,
+	options?: EvalOptions,
+): FormulaResult {
+	try {
+		const ctx: EvalCtx = {
+			vars,
+			fns: options?.functions ?? {},
+			stack: new Set(),
+		};
+		return { ok: true, value: evalNode(parsed.ast, ctx) };
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof FormulaError ? err.message : "Formula error.",
+		};
+	}
+}
+
+/** Parse + evaluate in one call. Never throws. */
+export function runFormula(
+	src: string,
+	vars: FormulaVars,
+	options?: EvalOptions,
+): FormulaResult {
+	let parsed: ParsedFormula;
+	try {
+		parsed = parseFormula(src);
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof FormulaError ? err.message : "Invalid formula.",
+		};
+	}
+	return evaluateFormula(parsed, vars, options);
+}
+
+/**
+ * Static check for the builder: valid syntax, and every referenced identifier is
+ * either a known variable or a known function. Returns the unknown names so the
+ * UI can flag them.
+ */
+export function validateFormula(
+	src: string,
+	knownVars: readonly string[],
+	knownFunctions: readonly string[] = [],
+): { ok: true; variables: string[] } | { ok: false; error: string } {
+	let parsed: ParsedFormula;
+	try {
+		parsed = parseFormula(src);
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof FormulaError ? err.message : "Invalid formula.",
+		};
+	}
+	const known = new Set(knownVars);
+	const unknown = parsed.variables.filter((v) => !known.has(v));
+	if (unknown.length > 0)
+		return { ok: false, error: `Unknown variable(s): ${unknown.join(", ")}.` };
+	// A called name must be a built-in or a known user/business function.
+	const fnPool = new Set([
+		...Object.keys(FORMULA_FUNCTIONS),
+		...knownFunctions,
+	]);
+	const unknownFns = parsed.functions.filter((f) => !fnPool.has(f));
+	if (unknownFns.length > 0)
+		return {
+			ok: false,
+			error: `Unknown function(s): ${unknownFns.join(", ")}.`,
+		};
+	return { ok: true, variables: parsed.variables };
+}