@stll/template-conditions 0.0.1-placeholder.0 → 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @stll/template-conditions
+
+A document-template marker and condition engine: the `{{...}}` marker grammar,
+an expression parser, numeric/arithmetic compute, a condition-builder
+serializer, and deterministic field-value rendering. Small, side-effect-free
+functions usable on both backend (Bun) and frontend (browser).
+
+Boolean conditions are evaluated through the canonical
+[`@stll/conditions`](https://github.com/stella/stella/tree/main/packages/conditions)
+AST and its single evaluator, so template `{{#if ...}}` conditionals share one
+set of operators and semantics with the rest of the system. This package owns
+the template surface: the marker grammar, the string parser, the named-condition
+resolver, the numeric expression evaluator, and the no-code builder serializer.
+
+```ts
+import { evaluateCondition, scanMarkers } from "@stll/template-conditions";
+
+const branch = evaluateCondition("isCompany and signed", fillData);
+
+for (const marker of scanMarkers(templateText)) {
+  // marker.kind, marker.path, ...
+}
+```
+
+## Install
+
+```sh
+bun add @stll/template-conditions
+```
+
+## Exports (`.`)
+
+- Condition evaluation: `evaluateCondition`, `parseCondition`,
+  `evaluateNumericExpression`, `serializeCondition`, `resolvePath`.
+- Field values: `renderDeterministicFieldValue`, `renderComposite`,
+  `formatDate`.
+- Marker grammar: `scanMarkers`, `classifyMarker`, `markerPattern`,
+  `placeholderPattern`, and the directive-kind constants.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { CompareNode, CompareOp, Condition, ConditionNode, ConditionNode as ConditionNode$1, GroupNode, Operand, PredicateNode, PredicateOp, conditionHasFormula, conditionNodeSchema, conditionSchema, emptyCondition } from "@stll/conditions";
+
+//#region src/path.d.ts
+/** Resolve a dotted path like `company.name` against data. */
+declare const resolvePath: (path: string, data: Record<string, unknown>) => unknown;
+//#endregion
+//#region src/parse.d.ts
+declare const parseCondition: (expression: string) => ConditionNode$1 | null;
+//#endregion
+//#region src/compute.d.ts
+/**
+ * Arithmetic evaluator for computed template fields.
+ *
+ * The condition engine ([[evaluateCondition]]) is boolean-only by design.
+ * Computed fields need a value, so this is a separate, pure recursive-descent
+ * evaluator: `+ - * / %`, unary `-`, parentheses, numeric literals (with `_`
+ * separators and decimals), dotted-path variables resolved from the fill data,
+ * and the functions `min`, `max`, `round` (optional 2nd arg = decimal places),
+ * `abs`, `floor`, `ceil`.
+ *
+ * Example — rent indexed by CPI but capped at +5%/yr:
+ *   `min(rent * (1 + index / 100), rent * 1.05)`
+ *
+ * Returns `undefined` on any parse or resolution failure (bad syntax, a
+ * non-numeric variable, division producing a non-finite result) so callers
+ * can fall back to leaving the field unfilled rather than emitting `NaN`.
+ */
+declare const evaluateNumericExpression: (expression: string, data: Record<string, unknown>) => number | undefined;
+//#endregion
+//#region src/field-values.d.ts
+/**
+ * Single source of truth for the DETERMINISTIC field-value transforms a
+ * template fill applies — composite (parts joined by a `{{key}}` format),
+ * formula (arithmetic over the other values), and locale-aware date rendering.
+ *
+ * Both the API fill engine (apps/api/src/handlers/docx) and the web live
+ * preview (template-studio.tsx) MUST route their rendering through
+ * {@link renderDeterministicFieldValue} so the preview and the generated
+ * document produce byte-identical strings. The api/field-value-parity.test.ts
+ * asserts this; reintroducing a bespoke transform on either side fails CI.
+ *
+ * Out of scope (non-deterministic / server-only, handled by callers):
+ *   - registry lookup (needs a network hit; the preview overlays it async)
+ *   - AI drafting / adaptation
+ *
+ * Pure: no IO, no model/provider dependency. The config types here are minimal
+ * STRUCTURAL shapes so the package stays free of api/web imports; callers pass
+ * their own field objects, which structurally satisfy these.
+ */
+/** Locale-aware date rendering config. "iso" leaves the submitted value as-is;
+ *  the other styles map to `Intl.DateTimeFormat` `dateStyle`. */
+type FieldDateFormat = {
+  /** BCP-47 language tag of the document, e.g. "cs", "de", "pl". */locale: string;
+  style: "long" | "medium" | "short" | "iso";
+};
+/**
+ * Format an ISO date (YYYY-MM-DD) per the field's locale + style via
+ * `Intl.DateTimeFormat` — ICU produces the correct localized (and, in date
+ * contexts, correctly inflected) month names, e.g. cs long → "13. června
+ * 2028". The "iso" style returns the value unchanged; an invalid calendar date
+ * returns null.
+ */
+declare const formatDate: (value: string, dateFormat: FieldDateFormat) => string | null;
+/** Minimal structural shape of one composite field part: only the `key`
+ *  referenced by the join format is needed to render. Callers' richer part
+ *  types (api FieldPart, web EditablePart) structurally satisfy this. */
+type PartConfig = {
+  key: string;
+};
+/**
+ * Render a `{{key}}` format over part values. Markers whose key has no part
+ * value are left as-is (a visible authoring artifact, not a render error), so
+ * a partially filled composite previews exactly as the fill engine renders it.
+ */
+declare const renderComposite: (parts: readonly PartConfig[], format: string, partValues: Readonly<Record<string, string>>) => string;
+/**
+ * Minimal STRUCTURAL config of a field, carrying only what the deterministic
+ * transforms read. Callers (api FieldMeta, web StudioField) structurally
+ * satisfy this; lookup/AI/scalar concerns are intentionally absent because the
+ * dispatcher does not handle them.
+ */
+type DeterministicFieldConfig = {
+  path: string;
+  inputType?: string | undefined;
+  parts?: readonly PartConfig[] | undefined;
+  format?: string | undefined;
+  formula?: string | undefined;
+  dateFormat?: FieldDateFormat | undefined;
+};
+/**
+ * THE deterministic field-value dispatcher: returns the string the fill engine
+ * writes for `field` given the submitted `values`, or null when the field has
+ * no deterministic transform (a scalar, lookup, or AI field the CALLER renders
+ * itself).
+ *
+ * Dispatch order mirrors the API fill pipeline (composite → formula → date):
+ *   - composite (parts + format present) → {@link renderComposite}
+ *   - else formula present → {@link evaluateNumericExpression}, stringified
+ *   - else date (inputType "date" + dateFormat) → {@link formatDate}
+ *   - else null
+ *
+ * Composite returns null when its value is not an object of part values (a
+ * plain string passes through unchanged on the api side, so the caller's
+ * scalar path handles it). Formula and date return null when the expression /
+ * value does not yield a value, so the caller leaves the field as-is.
+ */
+declare const renderDeterministicFieldValue: (field: DeterministicFieldConfig, values: Record<string, unknown>) => string | null;
+//#endregion
+//#region src/condition-builder.d.ts
+/**
+ * Serialize a condition tree into an expression for `evaluateCondition`.
+ * Returns an empty string for an empty tree (caller treats that as "no
+ * condition" / always-visible).
+ */
+declare const serializeCondition: (node: ConditionNode$1) => string;
+//#endregion
+//#region src/markers.d.ts
+/**
+ * Canonical grammar for `{{...}}` template markers — the single source of truth
+ * shared by the fill pipeline (api), the editor highlighter (folio), and the
+ * read-only preview (web).
+ *
+ * Add a new directive in ONE place: append its `kind` to {@link DIRECTIVE_KINDS},
+ * add a `MarkerMeta` member, and teach {@link classifyMarker} to recognize it.
+ * Every scanner that uses {@link scanMarkers} / {@link classifyMarker} then sees
+ * it automatically, and every exhaustive `switch` over a marker's kind (closed
+ * with {@link assertNever}) fails to compile at any consumer that has not yet
+ * handled it. That is what makes "added a directive server-side but a recognizer
+ * elsewhere silently ignored it" a build error rather than a latent bug.
+ *
+ * No consumer should define its own `{{...}}` regex. The low-level pattern
+ * factories below exist so handlers that mutate raw XML/text reuse the exact
+ * same literals; recognizers should prefer the high-level scanner.
+ */
+declare const DIRECTIVE_KINDS: readonly ["placeholder", "clause", "num", "ref", "index", "count", "if", "elseif", "else", "endif", "each", "endeach"];
+type DirectiveKind = (typeof DIRECTIVE_KINDS)[number];
+/** Directives that occupy their own paragraph (block-level), opener→closer. */
+declare const BLOCK_DIRECTIVE_KINDS: readonly ["if", "elseif", "else", "endif", "each", "endeach"];
+declare const isBlockDirectiveKind: (kind: DirectiveKind) => boolean;
+type MarkerMeta = {
+  kind: "placeholder";
+  expr: string;
+} | {
+  kind: "clause";
+  name: string;
+  version: string | undefined;
+} | {
+  kind: "num";
+  key: string;
+} | {
+  kind: "ref";
+  key: string;
+} | {
+  kind: "index";
+} | {
+  kind: "count";
+} | {
+  kind: "if";
+  expr: string;
+} | {
+  kind: "elseif";
+  expr: string;
+} | {
+  kind: "else";
+} | {
+  kind: "endif";
+} | {
+  kind: "each";
+  expr: string;
+} | {
+  kind: "endeach";
+};
+/** Any `{{...}}` marker; group 1 is the inner text (untrimmed — callers trim). */
+declare const markerPattern: () => RegExp;
+/** Inline field / clause / numbering marker (inner allows the directive sigils). */
+declare const placeholderPattern: () => RegExp;
+/** `{{@clause:Name}}` / `{{@clause:Name:v3}}` — `name` and `modifier` groups. */
+declare const clauseSlotPattern: () => RegExp;
+/** `{{@num:Key}}` — the `key` group. */
+declare const numPattern: () => RegExp;
+/** `{{@ref:Key}}` — the `key` group. */
+declare const refPattern: () => RegExp;
+/** `{{@index}}` — the 1-based position within the innermost enclosing loop. */
+declare const indexPattern: () => RegExp;
+/** `{{@count}}` — the item count of the innermost enclosing loop. */
+declare const countPattern: () => RegExp;
+/** Cheap presence test for any numbering marker (no capture). */
+declare const hasNumberingPattern: () => RegExp;
+/** Cheap presence test for any block directive (no capture). */
+declare const hasBlockDirectivePattern: () => RegExp;
+/** A whole line that is a single block directive — `tag` and `expr` groups. */
+declare const blockDirectiveLinePattern: () => RegExp;
+/** Whether `value` is a valid field path per the marker grammar (dotted
+ *  segments of letters/digits/underscore/dash — no brackets or spaces). */
+declare const isFieldPath: (value: string) => boolean;
+/**
+ * Classify the inner text of a `{{...}}` marker. Returns `null` when the text is
+ * not a recognized directive (so a recognizer can leave stray braces alone).
+ */
+declare const classifyMarker: (innerRaw: string) => MarkerMeta | null;
+type ScannedMarker = {
+  /** Offset of `{{` in the source text. */start: number; /** Offset just past `}}`. */
+  end: number; /** The full matched marker, e.g. `{{@num:scope}}`. */
+  raw: string; /** The (untrimmed) inner text. */
+  inner: string;
+  meta: MarkerMeta;
+};
+/**
+ * Find every recognized `{{...}}` marker in `text`, in document order, with
+ * offsets and classified metadata. Unrecognized `{{...}}` spans are skipped.
+ */
+declare const scanMarkers: (text: string) => ScannedMarker[];
+/** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
+declare const assertNever: (value: never) => never;
+//#endregion
+//#region src/index.d.ts
+type NamedCondition = {
+  name: string; /** The `{{#if}}` expression string. Authoritative unless `node` is set. */
+  expression: string;
+  /**
+   * The canonical AST, set when the condition cannot round-trip through the
+   * expression string — i.e. it uses a `formula` operand the `{{#if}}` grammar
+   * has no syntax for. When present it is evaluated directly and `expression`
+   * is ignored.
+   */
+  node?: ConditionNode$1;
+  label?: string;
+};
+/**
+ * Maximum recursion depth for named condition resolution.
+ * Prevents stack overflow when a long chain of named
+ * conditions (A→B→C→...→Z) is evaluated without cycles.
+ */
+declare const MAX_CONDITION_DEPTH = 50;
+/**
+ * Evaluate a template `{{#if ...}}` condition. The expression is parsed into
+ * the canonical `@stll/conditions` AST and evaluated by the shared evaluator.
+ *
+ * Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), `contains`,
+ * truthiness, negation (`!`), logical operators (`and`, `or`), parentheses,
+ * dotted paths, numeric underscores, and named-condition references.
+ *
+ * An empty or unparseable expression is `false` ("no condition" never gates a
+ * branch true).
+ */
+declare const evaluateCondition: (expression: string, data: Record<string, unknown>, namedConditions?: readonly NamedCondition[], _resolved?: ReadonlySet<string>, _depth?: number) => boolean;
+//#endregion
+export { BLOCK_DIRECTIVE_KINDS, type CompareNode, type CompareOp, type Condition, type ConditionNode, DIRECTIVE_KINDS, type DeterministicFieldConfig, type DirectiveKind, type FieldDateFormat, type GroupNode, MAX_CONDITION_DEPTH, type MarkerMeta, NamedCondition, type Operand, type PartConfig, type PredicateNode, type PredicateOp, type ScannedMarker, assertNever, blockDirectiveLinePattern, classifyMarker, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanMarkers, serializeCondition };

package/dist/index.js

@@ -0,0 +1,715 @@
+import { conditionHasFormula, conditionNodeSchema, conditionSchema, emptyCondition, evaluateCondition as evaluateCondition$1 } from "@stll/conditions";
+import { panic } from "better-result";
+//#region src/path.ts
+/**
+* Dotted-path resolution against a data record. Extracted from index.ts so both
+* the condition engine (index.ts) and the arithmetic evaluator (compute.ts) can
+* import it without a dependency cycle.
+*/
+/** Narrow `unknown` to a string-keyed record. */
+const isRecord = (v) => typeof v === "object" && v !== null;
+/** Resolve a dotted path like `company.name` against data. */
+const resolvePath = (path, data) => {
+	if (Object.hasOwn(data, path)) return data[path];
+	const parts = path.split(".");
+	let current = data;
+	for (const part of parts) {
+		if (!isRecord(current)) return;
+		current = current[part];
+	}
+	return current;
+};
+//#endregion
+//#region src/compute.ts
+/**
+* Arithmetic evaluator for computed template fields.
+*
+* The condition engine ([[evaluateCondition]]) is boolean-only by design.
+* Computed fields need a value, so this is a separate, pure recursive-descent
+* evaluator: `+ - * / %`, unary `-`, parentheses, numeric literals (with `_`
+* separators and decimals), dotted-path variables resolved from the fill data,
+* and the functions `min`, `max`, `round` (optional 2nd arg = decimal places),
+* `abs`, `floor`, `ceil`.
+*
+* Example — rent indexed by CPI but capped at +5%/yr:
+*   `min(rent * (1 + index / 100), rent * 1.05)`
+*
+* Returns `undefined` on any parse or resolution failure (bad syntax, a
+* non-numeric variable, division producing a non-finite result) so callers
+* can fall back to leaving the field unfilled rather than emitting `NaN`.
+*/
+const TOKEN_RE$1 = /(?<numeric>[0-9][0-9_]*(?:\.[0-9]+)?)|(?<ident>[\p{L}_][\p{L}\p{N}_.]*(?:-[\p{L}\p{N}_.]+)*)|(?<punct>[+\-*/%(),])|(?<invalid>\S)/gu;
+const PRECEDENCE = {
+	"+": 1,
+	"-": 1,
+	"*": 2,
+	"/": 2,
+	"%": 2
+};
+const tokenize$1 = (expression) => {
+	const tokens = [];
+	for (const match of expression.matchAll(TOKEN_RE$1)) {
+		const { numeric, ident, punct, invalid } = match.groups ?? {};
+		if (invalid !== void 0) throw new Error(`Unexpected token: ${invalid}`);
+		if (numeric !== void 0) tokens.push({
+			t: "num",
+			v: Number(numeric.replace(/_/gu, ""))
+		});
+		else if (ident !== void 0) tokens.push({
+			t: "id",
+			v: ident
+		});
+		else if (punct === "(") tokens.push({ t: "lp" });
+		else if (punct === ")") tokens.push({ t: "rp" });
+		else if (punct === ",") tokens.push({ t: "comma" });
+		else if (punct !== void 0) tokens.push({
+			t: "op",
+			v: punct
+		});
+	}
+	return tokens;
+};
+const applyOp = (op, a, b) => {
+	switch (op) {
+		case "+": return a + b;
+		case "-": return a - b;
+		case "*": return a * b;
+		case "/": return a / b;
+		default: return a % b;
+	}
+};
+const callFunction = (name, args) => {
+	switch (name) {
+		case "min": return Math.min(...args);
+		case "max": return Math.max(...args);
+		case "abs": return Math.abs(args[0] ?? NaN);
+		case "floor": return Math.floor(args[0] ?? NaN);
+		case "ceil": return Math.ceil(args[0] ?? NaN);
+		case "round": {
+			const value = args[0] ?? NaN;
+			const digits = args[1] ?? 0;
+			const factor = 10 ** Math.trunc(digits);
+			return Math.round(value * factor) / factor;
+		}
+		default: throw new Error(`Unknown function: ${name}`);
+	}
+};
+const evaluateNumericExpression = (expression, data) => {
+	try {
+		const tokens = tokenize$1(expression);
+		if (tokens.length === 0) return;
+		let pos = 0;
+		const resolveIdentifier = (path) => {
+			const raw = resolvePath(path, data);
+			const num = typeof raw === "number" ? raw : Number(raw);
+			if (!Number.isFinite(num)) throw new TypeError(`Non-numeric variable: ${path}`);
+			return num;
+		};
+		const parseAtom = () => {
+			const tok = tokens[pos];
+			if (!tok) throw new Error("Unexpected end of expression");
+			if (tok.t === "op" && (tok.v === "-" || tok.v === "+")) {
+				pos += 1;
+				const operand = parseAtom();
+				return tok.v === "-" ? -operand : operand;
+			}
+			if (tok.t === "num") {
+				pos += 1;
+				return tok.v;
+			}
+			if (tok.t === "lp") {
+				pos += 1;
+				const value = parseBinary(0);
+				if (tokens[pos]?.t !== "rp") throw new Error("Expected )");
+				pos += 1;
+				return value;
+			}
+			if (tok.t === "id") {
+				pos += 1;
+				if (tokens[pos]?.t === "lp") {
+					pos += 1;
+					const args = [];
+					if (tokens[pos]?.t !== "rp") {
+						args.push(parseBinary(0));
+						while (tokens[pos]?.t === "comma") {
+							pos += 1;
+							args.push(parseBinary(0));
+						}
+					}
+					if (tokens[pos]?.t !== "rp") throw new Error("Expected )");
+					pos += 1;
+					return callFunction(tok.v, args);
+				}
+				return resolveIdentifier(tok.v);
+			}
+			throw new Error("Unexpected token in expression");
+		};
+		const parseBinary = (minPrecedence) => {
+			let left = parseAtom();
+			let next = tokens[pos];
+			while (next?.t === "op" && (PRECEDENCE[next.v] ?? 0) >= minPrecedence) {
+				const op = next.v;
+				pos += 1;
+				const right = parseBinary((PRECEDENCE[op] ?? 0) + 1);
+				left = applyOp(op, left, right);
+				next = tokens[pos];
+			}
+			return left;
+		};
+		const result = parseBinary(0);
+		if (pos !== tokens.length) return;
+		return Number.isFinite(result) ? result : void 0;
+	} catch {
+		return;
+	}
+};
+//#endregion
+//#region src/parse.ts
+const TOKEN_RE = /(?<token>"[^"\\]*(?:\\.[^"\\]*)*"|==|!=|>=|<=|>|<|!(?!=)|and\b|or\b|contains\b|[()]|-?\d[\p{N}_.]*|[\p{L}\p{N}_.]+(?:-[\p{L}\p{N}_.]+)*)/gu;
+const STARTS_WITH_DIGIT_RE = /^-?\d/u;
+const COMPARE_SYMBOL_TO_OP = {
+	"==": "eq",
+	"!=": "neq",
+	">": "gt",
+	"<": "lt",
+	">=": "gte",
+	"<=": "lte"
+};
+const tokenize = (expr) => {
+	const tokens = [];
+	for (const m of expr.matchAll(TOKEN_RE)) {
+		const raw = m.groups?.["token"] ?? m[0];
+		if (raw === "and") tokens.push({ type: "and" });
+		else if (raw === "or") tokens.push({ type: "or" });
+		else if (raw === "!") tokens.push({ type: "not" });
+		else if (raw === "==" || raw === "!=" || raw === ">" || raw === "<" || raw === ">=" || raw === "<=" || raw === "contains") tokens.push({
+			type: "op",
+			raw
+		});
+		else if (raw === "(") tokens.push({ type: "lparen" });
+		else if (raw === ")") tokens.push({ type: "rparen" });
+		else if (raw.startsWith("\"")) tokens.push({
+			type: "string",
+			raw: raw.slice(1, -1).replace(/\\"/gu, "\"")
+		});
+		else tokens.push({
+			type: "value",
+			raw
+		});
+	}
+	return tokens;
+};
+/** Parse a numeric literal, supporting `_` separators. */
+const parseNumeric = (raw) => {
+	if (!STARTS_WITH_DIGIT_RE.test(raw)) return;
+	const n = Number(raw.replace(/_/gu, ""));
+	return Number.isFinite(n) ? n : void 0;
+};
+/** A `value`/`string` token becomes a literal (string / number / boolean) or a
+*  dotted `path` operand. */
+const operandFromToken = (token) => {
+	if (token.type === "string") return {
+		type: "literal",
+		value: token.raw
+	};
+	const num = parseNumeric(token.raw);
+	if (num !== void 0) return {
+		type: "literal",
+		value: num
+	};
+	if (token.raw === "true") return {
+		type: "literal",
+		value: true
+	};
+	if (token.raw === "false") return {
+		type: "literal",
+		value: false
+	};
+	return {
+		type: "path",
+		path: token.raw
+	};
+};
+/** `contains` carries a literal payload (`string`), not an operand: render the
+*  right-hand token as a string. */
+const containsValue = (token) => {
+	const operand = operandFromToken(token);
+	return operand.type === "literal" ? String(operand.value) : token.raw;
+};
+const parseCondition = (expression) => {
+	const tokens = tokenize(expression);
+	if (tokens.length === 0) return null;
+	let pos = 0;
+	const peek = () => tokens[pos];
+	const parseOr = () => {
+		const first = parseAnd();
+		if (peek()?.type !== "or") return first;
+		const children = [first];
+		while (peek()?.type === "or") {
+			pos += 1;
+			children.push(parseAnd());
+		}
+		return {
+			type: "group",
+			combinator: "or",
+			children
+		};
+	};
+	const parseAnd = () => {
+		const first = parseNot();
+		if (peek()?.type !== "and") return first;
+		const children = [first];
+		while (peek()?.type === "and") {
+			pos += 1;
+			children.push(parseNot());
+		}
+		return {
+			type: "group",
+			combinator: "and",
+			children
+		};
+	};
+	const parseNot = () => {
+		if (peek()?.type === "not") {
+			pos += 1;
+			return {
+				type: "group",
+				combinator: "and",
+				negated: true,
+				children: [parseNot()]
+			};
+		}
+		return parseComparison();
+	};
+	const parseComparison = () => {
+		if (peek()?.type === "lparen") {
+			pos += 1;
+			const inner = parseOr();
+			if (peek()?.type === "rparen") pos += 1;
+			return inner;
+		}
+		const leftTok = peek();
+		if (!leftTok || leftTok.type !== "value" && leftTok.type !== "string") {
+			pos += 1;
+			return {
+				type: "group",
+				combinator: "and",
+				children: []
+			};
+		}
+		pos += 1;
+		const left = operandFromToken(leftTok);
+		const opTok = peek();
+		if (opTok?.type !== "op") return {
+			type: "predicate",
+			operand: left,
+			op: "is_truthy"
+		};
+		pos += 1;
+		const rightTok = peek();
+		if (!rightTok || rightTok.type !== "value" && rightTok.type !== "string") return {
+			type: "predicate",
+			operand: left,
+			op: "is_truthy"
+		};
+		pos += 1;
+		if (opTok.raw === "contains") return {
+			type: "predicate",
+			operand: left,
+			op: "contains",
+			value: containsValue(rightTok)
+		};
+		return {
+			type: "compare",
+			left,
+			op: COMPARE_SYMBOL_TO_OP[opTok.raw] ?? "eq",
+			right: operandFromToken(rightTok)
+		};
+	};
+	return parseOr();
+};
+//#endregion
+//#region src/markers.ts
+/**
+* Canonical grammar for `{{...}}` template markers — the single source of truth
+* shared by the fill pipeline (api), the editor highlighter (folio), and the
+* read-only preview (web).
+*
+* Add a new directive in ONE place: append its `kind` to {@link DIRECTIVE_KINDS},
+* add a `MarkerMeta` member, and teach {@link classifyMarker} to recognize it.
+* Every scanner that uses {@link scanMarkers} / {@link classifyMarker} then sees
+* it automatically, and every exhaustive `switch` over a marker's kind (closed
+* with {@link assertNever}) fails to compile at any consumer that has not yet
+* handled it. That is what makes "added a directive server-side but a recognizer
+* elsewhere silently ignored it" a build error rather than a latent bug.
+*
+* No consumer should define its own `{{...}}` regex. The low-level pattern
+* factories below exist so handlers that mutate raw XML/text reuse the exact
+* same literals; recognizers should prefer the high-level scanner.
+*/
+const DIRECTIVE_KINDS = [
+	"placeholder",
+	"clause",
+	"num",
+	"ref",
+	"index",
+	"count",
+	"if",
+	"elseif",
+	"else",
+	"endif",
+	"each",
+	"endeach"
+];
+/** Directives that occupy their own paragraph (block-level), opener→closer. */
+const BLOCK_DIRECTIVE_KINDS = [
+	"if",
+	"elseif",
+	"else",
+	"endif",
+	"each",
+	"endeach"
+];
+const BLOCK_KIND_SET = new Set(BLOCK_DIRECTIVE_KINDS);
+const isBlockDirectiveKind = (kind) => BLOCK_KIND_SET.has(kind);
+/** Any `{{...}}` marker; group 1 is the inner text (untrimmed — callers trim). */
+const markerPattern = () => /\{\{(?<inner>[^{}]*)\}\}/gu;
+/** Inline field / clause / numbering marker (inner allows the directive sigils). */
+const placeholderPattern = () => /\{\{\s*(?<name>[\p{L}\p{N}_.@:-]+)\s*\}\}/gu;
+/** `{{@clause:Name}}` / `{{@clause:Name:v3}}` — `name` and `modifier` groups. */
+const clauseSlotPattern = () => /\{\{\s*@clause:(?<name>[^:}\s]+)(?::(?<modifier>[^}\s]+))?\s*\}\}/gu;
+/** `{{@num:Key}}` — the `key` group. */
+const numPattern = () => /\{\{\s*@num:(?<key>[\p{L}\p{N}_.-]+)\s*\}\}/gu;
+/** `{{@ref:Key}}` — the `key` group. */
+const refPattern = () => /\{\{\s*@ref:(?<key>[\p{L}\p{N}_.-]+)\s*\}\}/gu;
+/** `{{@index}}` — the 1-based position within the innermost enclosing loop. */
+const indexPattern = () => /\{\{\s*@index\s*\}\}/gu;
+/** `{{@count}}` — the item count of the innermost enclosing loop. */
+const countPattern = () => /\{\{\s*@count\s*\}\}/gu;
+/** Cheap presence test for any numbering marker (no capture). */
+const hasNumberingPattern = () => /\{\{\s*@(?:num|ref):/u;
+/** Cheap presence test for any block directive (no capture). */
+const hasBlockDirectivePattern = () => /\{\{\s*[#/]/u;
+/** A whole line that is a single block directive — `tag` and `expr` groups. */
+const blockDirectiveLinePattern = () => /^\s*\{\{\s*(?<tag>#if|#elseif|#else|#each|\/if|\/each)\b(?<expr>[^{}]*)\}\}\s*$/u;
+const FIELD_PATH_RE = /^[\p{L}\p{N}_.-]+$/u;
+/** Whether `value` is a valid field path per the marker grammar (dotted
+*  segments of letters/digits/underscore/dash — no brackets or spaces). */
+const isFieldPath = (value) => FIELD_PATH_RE.test(value);
+const CLAUSE_INNER_RE = /^@clause:(?<name>[^:}\s]+)(?::(?<version>[^}\s]+))?$/u;
+const NUM_INNER_RE = /^@num:(?<key>[\p{L}\p{N}_.-]+)$/u;
+const REF_INNER_RE = /^@ref:(?<key>[\p{L}\p{N}_.-]+)$/u;
+const INDEX_INNER_RE = /^@index$/u;
+const COUNT_INNER_RE = /^@count$/u;
+const BLOCK_INNER_RE = /^(?<token>#if|#elseif|#else|#each|\/if|\/each)\b(?<expr>.*)$/u;
+/**
+* Classify the inner text of a `{{...}}` marker. Returns `null` when the text is
+* not a recognized directive (so a recognizer can leave stray braces alone).
+*/
+const classifyMarker = (innerRaw) => {
+	const inner = innerRaw.trim();
+	const block = BLOCK_INNER_RE.exec(inner);
+	if (block) {
+		const token = block.groups?.["token"] ?? "";
+		const expr = (block.groups?.["expr"] ?? "").trim();
+		if (token === "#if") return {
+			kind: "if",
+			expr
+		};
+		if (token === "#elseif") return {
+			kind: "elseif",
+			expr
+		};
+		if (token === "#each") return {
+			kind: "each",
+			expr
+		};
+		if (token === "#else") return { kind: "else" };
+		if (token === "/if") return { kind: "endif" };
+		if (token === "/each") return { kind: "endeach" };
+	}
+	const clause = CLAUSE_INNER_RE.exec(inner);
+	if (clause) return {
+		kind: "clause",
+		name: clause.groups?.["name"] ?? "",
+		version: clause.groups?.["version"]
+	};
+	const num = NUM_INNER_RE.exec(inner);
+	if (num) return {
+		kind: "num",
+		key: num.groups?.["key"] ?? ""
+	};
+	const ref = REF_INNER_RE.exec(inner);
+	if (ref) return {
+		kind: "ref",
+		key: ref.groups?.["key"] ?? ""
+	};
+	if (INDEX_INNER_RE.test(inner)) return { kind: "index" };
+	if (COUNT_INNER_RE.test(inner)) return { kind: "count" };
+	if (FIELD_PATH_RE.test(inner)) return {
+		kind: "placeholder",
+		expr: inner
+	};
+	return null;
+};
+/**
+* Find every recognized `{{...}}` marker in `text`, in document order, with
+* offsets and classified metadata. Unrecognized `{{...}}` spans are skipped.
+*/
+const scanMarkers = (text) => {
+	const re = markerPattern();
+	const out = [];
+	let match = re.exec(text);
+	while (match !== null) {
+		const inner = (match[1] ?? "").trim();
+		const meta = classifyMarker(inner);
+		if (meta) out.push({
+			start: match.index,
+			end: match.index + match[0].length,
+			raw: match[0],
+			inner,
+			meta
+		});
+		match = re.exec(text);
+	}
+	return out;
+};
+/** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
+const assertNever = (value) => panic(`Unhandled template directive: ${JSON.stringify(value)}`);
+//#endregion
+//#region src/field-values.ts
+/**
+* Single source of truth for the DETERMINISTIC field-value transforms a
+* template fill applies — composite (parts joined by a `{{key}}` format),
+* formula (arithmetic over the other values), and locale-aware date rendering.
+*
+* Both the API fill engine (apps/api/src/handlers/docx) and the web live
+* preview (template-studio.tsx) MUST route their rendering through
+* {@link renderDeterministicFieldValue} so the preview and the generated
+* document produce byte-identical strings. The api/field-value-parity.test.ts
+* asserts this; reintroducing a bespoke transform on either side fails CI.
+*
+* Out of scope (non-deterministic / server-only, handled by callers):
+*   - registry lookup (needs a network hit; the preview overlays it async)
+*   - AI drafting / adaptation
+*
+* Pure: no IO, no model/provider dependency. The config types here are minimal
+* STRUCTURAL shapes so the package stays free of api/web imports; callers pass
+* their own field objects, which structurally satisfy these.
+*/
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const STYLE_OPTIONS = {
+	long: { dateStyle: "long" },
+	medium: { dateStyle: "medium" },
+	short: { dateStyle: "short" }
+};
+/**
+* Parse a strict YYYY-MM-DD calendar date; null when malformed or not a real
+* date. UTC-anchored so the rendered day never shifts with the timezone.
+* `Date` rolls out-of-range components over (2028-02-30 → March 1), so the
+* round-trip comparison catches non-existent dates.
+*/
+const parseIsoDate = (value) => {
+	if (!ISO_DATE_PATTERN.test(value)) return null;
+	const date = /* @__PURE__ */ new Date(`${value}T00:00:00Z`);
+	if (Number.isNaN(date.getTime()) || !date.toISOString().startsWith(value)) return null;
+	return date;
+};
+/**
+* Format an ISO date (YYYY-MM-DD) per the field's locale + style via
+* `Intl.DateTimeFormat` — ICU produces the correct localized (and, in date
+* contexts, correctly inflected) month names, e.g. cs long → "13. června
+* 2028". The "iso" style returns the value unchanged; an invalid calendar date
+* returns null.
+*/
+const formatDate = (value, dateFormat) => {
+	const date = parseIsoDate(value);
+	if (date === null) return null;
+	if (dateFormat.style === "iso") return value;
+	return new Intl.DateTimeFormat(dateFormat.locale, {
+		...STYLE_OPTIONS[dateFormat.style],
+		timeZone: "UTC"
+	}).format(date);
+};
+/**
+* Render a `{{key}}` format over part values. Markers whose key has no part
+* value are left as-is (a visible authoring artifact, not a render error), so
+* a partially filled composite previews exactly as the fill engine renders it.
+*/
+const renderComposite = (parts, format, partValues) => format.replace(markerPattern(), (raw, inner) => {
+	const key = inner.trim();
+	if (!parts.some((part) => part.key === key)) return raw;
+	return partValues[key] ?? raw;
+});
+/** A plain object of part values: a non-null, non-array object. The api
+*  composite step accepts exactly this shape (an array or primitive is not a
+*  part-values object), so the dispatcher mirrors it. */
+const isPartValuesObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Build the `{{key}} → value` map for a composite field from its raw object
+*  value, keeping only string part values for declared part keys. */
+const compositePartValues = (parts, raw) => {
+	const partValues = {};
+	for (const part of parts) {
+		const value = raw[part.key];
+		if (typeof value === "string") partValues[part.key] = value;
+	}
+	return partValues;
+};
+/**
+* THE deterministic field-value dispatcher: returns the string the fill engine
+* writes for `field` given the submitted `values`, or null when the field has
+* no deterministic transform (a scalar, lookup, or AI field the CALLER renders
+* itself).
+*
+* Dispatch order mirrors the API fill pipeline (composite → formula → date):
+*   - composite (parts + format present) → {@link renderComposite}
+*   - else formula present → {@link evaluateNumericExpression}, stringified
+*   - else date (inputType "date" + dateFormat) → {@link formatDate}
+*   - else null
+*
+* Composite returns null when its value is not an object of part values (a
+* plain string passes through unchanged on the api side, so the caller's
+* scalar path handles it). Formula and date return null when the expression /
+* value does not yield a value, so the caller leaves the field as-is.
+*/
+const renderDeterministicFieldValue = (field, values) => {
+	if (field.parts !== void 0 && field.format !== void 0) {
+		const raw = resolvePath(field.path, values);
+		if (!isPartValuesObject(raw)) return null;
+		return renderComposite(field.parts, field.format, compositePartValues(field.parts, raw));
+	}
+	if (field.formula !== void 0) {
+		const result = evaluateNumericExpression(field.formula, values);
+		return result === void 0 ? null : String(result);
+	}
+	if (field.inputType === "date" && field.dateFormat !== void 0) {
+		const raw = resolvePath(field.path, values);
+		if (typeof raw !== "string" || raw.trim() === "") return null;
+		return formatDate(raw, field.dateFormat);
+	}
+	return null;
+};
+//#endregion
+//#region src/condition-builder.ts
+const COMPARE_OP_TO_SYMBOL = {
+	eq: "==",
+	neq: "!=",
+	gt: ">",
+	lt: "<",
+	gte: ">=",
+	lte: "<="
+};
+/** Render a literal: strings are quoted/escaped, booleans and numbers are
+*  emitted bare (matching the parser's literal handling); an array literal
+*  joins on `,` (rare; the template builder edits scalar rules). */
+const serializeLiteral = (value) => {
+	if (typeof value === "string") return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"")}"`;
+	if (Array.isArray(value)) return `"${value.join(",")}"`;
+	return String(value);
+};
+const serializeOperand = (operand) => {
+	if (operand.type === "literal") return serializeLiteral(operand.value);
+	if (operand.type === "path") return operand.path;
+	if (operand.type === "formula") panic("serializeCondition: formula operand requires AST storage");
+	return "";
+};
+const serializeCompare = (node) => `${serializeOperand(node.left)} ${COMPARE_OP_TO_SYMBOL[node.op]} ${serializeOperand(node.right)}`;
+const serializePredicate = (node) => {
+	const operand = serializeOperand(node.operand);
+	if (node.op === "contains") return `${operand} contains ${serializeLiteral(Array.isArray(node.value) ? node.value.join(",") : node.value ?? "")}`;
+	return operand;
+};
+const serializeGroup = (group, top) => {
+	const parts = group.children.map((child) => serializeNode(child, false)).filter((part) => part.length > 0);
+	if (parts.length === 0) return "";
+	const body = parts.length === 1 ? parts[0] ?? "" : parts.join(group.combinator === "and" ? " and " : " or ");
+	if (group.negated) return `!(${body})`;
+	if (parts.length === 1) return body;
+	return top ? body : `(${body})`;
+};
+const serializeNode = (node, top) => {
+	if (node.type === "compare") return serializeCompare(node);
+	if (node.type === "predicate") return serializePredicate(node);
+	return serializeGroup(node, top);
+};
+/**
+* Serialize a condition tree into an expression for `evaluateCondition`.
+* Returns an empty string for an empty tree (caller treats that as "no
+* condition" / always-visible).
+*/
+const serializeCondition = (node) => serializeNode(node, true);
+//#endregion
+//#region src/index.ts
+/**
+* Shared condition evaluation + marker grammar for DOCX templates. Small,
+* side-effect-free functions usable on both backend (Bun) and frontend
+* (browser).
+*
+* Boolean conditions are evaluated through the canonical `@stll/conditions`
+* AST and its single evaluator, so view filters, AI-extraction gating, and
+* template `{{#if ...}}` conditionals share one set of operators and semantics
+* and never drift apart. This module owns the template surface: the string
+* parser (`./parse`), the named-condition resolver, and the no-code builder
+* serializer (`./condition-builder`).
+*/
+/**
+* Maximum recursion depth for named condition resolution.
+* Prevents stack overflow when a long chain of named
+* conditions (A→B→C→...→Z) is evaluated without cycles.
+*/
+const MAX_CONDITION_DEPTH = 50;
+/**
+* Normalize a fill-bag value into a `ConditionValue` the shared evaluator
+* accepts: arrays become string arrays (multi-select fields hold their options
+* as strings, so membership tests like `parties contains "guarantor"` work
+* even when an element is numeric), primitives pass through, anything else is
+* stringified.
+*/
+const toConditionValue = (raw) => {
+	if (raw === null || raw === void 0) return raw;
+	if (Array.isArray(raw)) return raw.map(String);
+	if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") return raw;
+};
+/**
+* Build the operand resolver for one evaluation. Only `path` operands need
+* resolving (the evaluator handles literals). A path is first matched against
+* the named conditions: a hit evaluates that condition's expression — so
+* `{{#if isCompany}}` and `{{#if isCompany and signed}}` both work — guarded
+* against cycles (`resolved`) and runaway chains (`MAX_CONDITION_DEPTH`).
+* Otherwise the path resolves against the fill data.
+*/
+const makeResolver = (data, namedConditions, resolved, depth) => {
+	const resolve = (operand) => {
+		if (operand.type === "formula") return evaluateNumericExpression(operand.expr, data);
+		if (operand.type !== "path") return;
+		const { path } = operand;
+		const named = namedConditions?.find((c) => c.name === path);
+		if (named) {
+			if (depth >= 50 || resolved.has(path)) return false;
+			const next = new Set(resolved);
+			next.add(path);
+			if (named.node) return evaluateCondition$1(named.node, makeResolver(data, namedConditions, next, depth + 1));
+			return evaluateCondition(named.expression, data, namedConditions, next, depth + 1);
+		}
+		return toConditionValue(resolvePath(path, data));
+	};
+	return resolve;
+};
+/**
+* Evaluate a template `{{#if ...}}` condition. The expression is parsed into
+* the canonical `@stll/conditions` AST and evaluated by the shared evaluator.
+*
+* Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), `contains`,
+* truthiness, negation (`!`), logical operators (`and`, `or`), parentheses,
+* dotted paths, numeric underscores, and named-condition references.
+*
+* An empty or unparseable expression is `false` ("no condition" never gates a
+* branch true).
+*/
+const evaluateCondition = (expression, data, namedConditions, _resolved = /* @__PURE__ */ new Set(), _depth = 0) => {
+	const node = parseCondition(expression);
+	if (node === null) return false;
+	return evaluateCondition$1(node, makeResolver(data, namedConditions, _resolved, _depth));
+};
+//#endregion
+export { BLOCK_DIRECTIVE_KINDS, DIRECTIVE_KINDS, MAX_CONDITION_DEPTH, assertNever, blockDirectiveLinePattern, classifyMarker, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanMarkers, serializeCondition };

package/package.json

@@ -1,5 +1,64 @@
 {
   "name": "@stll/template-conditions",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. The real package ships via the next @stll release."
-}
+  "version": "0.1.0",
+  "description": "A document-template marker and condition engine: {{...}} marker grammar, parse, compute, serialize, field values.",
+  "keywords": [
+    "condition",
+    "field-values",
+    "marker",
+    "parse",
+    "placeholder",
+    "serialize",
+    "template"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/template-conditions",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/template-conditions"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test",
+    "test:property": "bun test $(grep -rlF 'fc.assert' src --include='*.test.ts')",
+    "typecheck": "tsgo --noEmit",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/template-conditions",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/template-conditions",
+    "format": "oxfmt .",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@stll/conditions": "^0.1.0",
+    "better-result": "2.9.2"
+  },
+  "devDependencies": {
+    "@stll/property-testing": "0.0.0",
+    "@stll/typescript-config": "0.0.0",
+    "@types/bun": "1.3.14",
+    "fast-check": "^4.8.0",
+    "tsdown": "0.22.3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}