@stll/template-conditions 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -47,8 +47,8 @@ declare const evaluateNumericExpression: (expression: string, data: Record<strin
 //#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.
+ * template fill applies: 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
@@ -83,18 +83,6 @@ type FieldDateFormat = {
  * 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
@@ -104,8 +92,6 @@ declare const renderComposite: (parts: readonly PartConfig[], format: string, pa
 type DeterministicFieldConfig = {
   path: string;
   inputType?: string | undefined;
-  parts?: readonly PartConfig[] | undefined;
-  format?: string | undefined;
   formula?: string | undefined;
   dateFormat?: FieldDateFormat | undefined;
 };
@@ -115,16 +101,13 @@ type DeterministicFieldConfig = {
  * 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
+ * Dispatch order mirrors the API fill pipeline (formula → date):
+ *   - 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.
+ * Formula and date return null when the expression or 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
@@ -249,10 +232,16 @@ declare const normalizeMarkerInner: (inner: string) => string;
  * not a nested marker. An apostrophe stays an ordinary character, so
  * `label("Owner's")` reads as it always did.
  *
+ * A quoted run honours `\`-escapes, the way the argument scanner reads them,
+ * so `label("she said \"yes\"")` is one span rather than three: the span and
+ * the scanner have to agree on where a literal ends or a marker the scanner
+ * would parse is one the recognizer never sees.
+ *
  * The alternatives cannot overlap (the plain one excludes every character the
- * quoted one may start with) and a quoted run's end is forced by its body, so
- * the scan stays linear on adversarial input: a `{{` with no closing `}}`
- * costs one failed pass, not a polynomial retry.
+ * quoted one may start with, and inside a quoted run the escape branch is the
+ * only one that starts with a backslash), so the scan stays linear on
+ * adversarial input: a `{{` with no closing `}}` costs one failed pass, not a
+ * polynomial retry.
  */
 declare const MARKER_OUTPUT_BODY: string;
 /** What a tag holds between `{%` and `%}`: anything but a brace, and a `%`
@@ -389,6 +378,172 @@ declare const classifyMarkerDefect: (innerRaw: string, form?: MarkerForm) => Mar
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
 declare const assertNever: (value: never) => never;
 //#endregion
+//#region src/loop-scope.d.ts
+/**
+ * The path a marker names, once the loops around it are taken into account.
+ *
+ * `{% for attorney in attorneys %}{{ attorney.name }}{% endfor %}` writes one
+ * field, and the manifest calls it `attorneys.name`: the loop's alias is the
+ * body's name for the item, the array path is the manifest's. Discovery reads
+ * that mapping, and every writer that puts a configuration back into a marker
+ * has to reverse it, so the rule lives beside the grammar rather than in each
+ * of them; two readings of one loop are two different documents.
+ */
+/** One enclosing `{% for %}`, as the body sees it and as the manifest does. */
+type RowScope = {
+  /** The loop variable the body addresses items through. */
+  alias: string;
+  /** The array path the opener was written with, before its own enclosing
+   *  loops were applied. */
+  declaredPath: string;
+  /** The array path the manifest speaks, enclosing loops included. */
+  scopedPath: string;
+};
+declare const rowScopePaths: (rowScopes: readonly RowScope[]) => string[];
+/** A path already under the innermost repeat is left alone; anything else is
+ *  read as a name relative to it. */
+declare const qualifyRowScopedPath: (path: string, rowPaths?: readonly string[]) => string;
+/** The manifest path for a marker written inside these loops. */
+declare const qualifyRowScopedPlaceholder: (path: string, rowScopes: readonly RowScope[]) => string;
+/** The manifest path for an array a `{% for %}` opens inside these loops. */
+declare const qualifyLoopPath: (declaredPath: string, rowScopes: readonly RowScope[]) => string;
+//#endregion
+//#region src/field-config.d.ts
+/** Where a field's value comes from, when a record supplies it. Only the shape
+ *  the filters read: each caller's own union satisfies it. */
+type MarkerFieldSource = {
+  kind: "matter";
+  field: string;
+} | {
+  kind: "contact";
+  field: string;
+} | {
+  kind: "firm";
+  field: string;
+} | {
+  kind: "party";
+  role: string;
+  field: string;
+} | {
+  kind: "attorney";
+  ref: string;
+  field: string;
+};
+/** The constraints a chain can express. */
+type MarkerFieldValidation = {
+  required?: boolean | undefined;
+  pattern?: string | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  minLength?: number | undefined;
+  maxLength?: number | undefined;
+  minItems?: number | undefined;
+  maxItems?: number | undefined;
+};
+/** A registry lookup and the renderings of its one resolved hit. */
+type MarkerFieldLookup = {
+  registry: string;
+  formats: readonly {
+    key: string;
+    template: string;
+  }[];
+};
+/** The input controls a marker can name. */
+type MarkerFieldInputType = "text" | "number" | "boolean" | "date" | "select";
+/**
+ * Everything about a field that a marker's filter chain can carry. A caller's
+ * own field type may hold more (a derived condition AST, a discovery count);
+ * those keys are simply not read here.
+ */
+type MarkerFieldConfig = {
+  path: string;
+  label?: string | undefined;
+  hint?: string | undefined;
+  inputType?: MarkerFieldInputType | undefined;
+  options?: readonly string[] | undefined;
+  optionsFrom?: string | undefined;
+  validation?: MarkerFieldValidation | undefined;
+  required?: boolean | undefined;
+  aiPrompt?: string | undefined;
+  aiAdapt?: boolean | undefined;
+  aiSeesDocument?: boolean | undefined;
+  lookup?: MarkerFieldLookup | undefined;
+  source?: MarkerFieldSource | undefined;
+  formula?: string | undefined;
+  condition?: string | undefined;
+  dateFormat?: FieldDateFormat | undefined;
+};
+/**
+ * The filters that describe a REPEAT rather than a value: how many rows it
+ * takes and what to call it. These are the ones a `{% for %}` tag may carry,
+ * since the loop path names the array, not one of its values.
+ */
+declare const ARRAY_FILTER_NAMES: readonly ["label", "hint", "required", "min_items", "max_items"];
+declare const isArrayFilterName: (name: FilterName) => boolean;
+/**
+ * The filter chain that declares this field in a document, in the catalogue's
+ * own order so a chain the writer produces and one an author wrote read the
+ * same.
+ */
+declare const filtersFromFieldConfig: (field: MarkerFieldConfig) => FilterCall[];
+/**
+ * The chain a `{% for %}` opener carries for this array: the repeat's own
+ * filters and nothing else, derived from {@link ARRAY_FILTER_NAMES}, so a
+ * value filter can never be written where the reader refuses it.
+ */
+declare const arrayFiltersFromFieldConfig: (field: MarkerFieldConfig) => FilterCall[];
+//#endregion
+//#region src/render.d.ts
+/** Why a value has no spelling the scanner reads back as itself. */
+type UnwritableReason = "tag-delimiter" | "number-spelling";
+/** The reason this literal cannot be written in a marker of this form, or
+ *  `null` when it can. A boolean always can; a string can in a `{{ }}` marker,
+ *  because the writer quotes and escapes it. */
+declare const unwritableMarkerLiteral: (value: MarkerLiteral, form?: MarkerForm) => UnwritableReason | null;
+/** Every value in a chain the grammar has no spelling for, with the filter it
+ *  was written on and why, so a caller can refuse a configuration before it
+ *  rewrites a document into something the scanner would read differently. A
+ *  repeat's chain goes in a tag, so pass `"statement"` for one. */
+declare const unwritableFilterValues: (filters: readonly FilterCall[], form?: MarkerForm) => {
+  filter: string;
+  value: MarkerLiteral;
+  reason: UnwritableReason;
+}[];
+/**
+ * One filter chain as marker text, without the leading pipe: `label("A") |
+ * required`. An empty chain renders the empty string, which is what a marker
+ * that configures nothing carries.
+ */
+declare const renderFilterChain: (filters: readonly FilterCall[]) => string;
+/** One value marker: `{{ path }}` or `{{ path | filters }}`. */
+declare const renderValueMarker: (path: string, filters: readonly FilterCall[]) => string;
+type ConditionTagOptions = {
+  /** Which branch opener this is; `elif` keeps its place in the chain. */
+  kind: "if" | "elif";
+  /** The `{% if %}` expression, already serialized. */
+  expression: string;
+  /** The placement the tag already carried. */
+  prefix: MarkerPrefix;
+};
+/**
+ * One `{% if %}` / `{% elif %}` opener carrying its expression.
+ *
+ * A rule that decides whether a block shows belongs in the tag that shows it:
+ * the tag is the only place a document has for it, so a builder's rule is
+ * serialized here rather than stored beside the document under a name.
+ */
+declare const renderConditionTag: ({ expression, kind, prefix }: ConditionTagOptions) => string;
+type ForOpenerOptions = {
+  alias: string;
+  path: string;
+  filters: readonly FilterCall[];
+  /** The placement the opener already carried, so rewriting its filters does
+   *  not move a row-form loop off its table row. */
+  prefix: MarkerPrefix;
+};
+/** One `{% for %}` opener, keeping its placement prefix. */
+declare const renderForOpener: ({ alias, filters, path, prefix }: ForOpenerOptions) => string;
+//#endregion
 //#region src/row-blocks.d.ts
 /** One end of a row block, addressed within the row that was scanned. */
 type RowBlockMarker = {
@@ -451,4 +606,4 @@ declare const MAX_CONDITION_DEPTH = 50;
  */
 declare const evaluateCondition: (expression: string, data: Record<string, unknown>, namedConditions?: readonly NamedCondition[], _resolved?: ReadonlySet<string>, _depth?: number) => boolean;
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, FILTER_NAMES, type FieldDateFormat, type FilterArgument, type FilterCall, type FilterName, type GroupNode, type InvalidMarker, LOOP_PROPERTIES, type LoopProperty, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, type MarkerDefect, type MarkerDefectKind, type MarkerForm, type MarkerLiteral, type MarkerMeta, type MarkerPrefix, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PartConfig, type PredicateNode, type PredicateOp, type RowBlockMarker, type RowBlockPair, type ScannedMarker, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, refPattern, referencedConditionPaths, renderComposite, renderDeterministicFieldValue, replaceOutputMarkers, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression };
+export { ARRAY_FILTER_NAMES, BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, type ConditionTagOptions, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, FILTER_NAMES, type FieldDateFormat, type FilterArgument, type FilterCall, type FilterName, type ForOpenerOptions, type GroupNode, type InvalidMarker, LOOP_PROPERTIES, type LoopProperty, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, type MarkerDefect, type MarkerDefectKind, type MarkerFieldConfig, type MarkerFieldInputType, type MarkerFieldLookup, type MarkerFieldSource, type MarkerFieldValidation, type MarkerForm, type MarkerLiteral, type MarkerMeta, type MarkerPrefix, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PredicateNode, type PredicateOp, type RowBlockMarker, type RowBlockPair, type RowScope, type ScannedMarker, type UnwritableReason, arrayFiltersFromFieldConfig, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, filtersFromFieldConfig, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isArrayFilterName, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, qualifyLoopPath, qualifyRowScopedPath, qualifyRowScopedPlaceholder, refPattern, referencedConditionPaths, renderConditionTag, renderDeterministicFieldValue, renderFilterChain, renderForOpener, renderValueMarker, replaceOutputMarkers, resolvePath, rowScopePaths, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression, unwritableFilterValues, unwritableMarkerLiteral };

package/dist/index.js

@@ -454,6 +454,164 @@ const referencedConditionPaths = (expression) => {
 	return node === null ? null : nodePaths(node);
 };
 //#endregion
+//#region src/field-values.ts
+/**
+* Single source of truth for the DETERMINISTIC field-value transforms a
+* template fill applies: 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 DATE_FORMAT_STYLES = [
+	"long",
+	"medium",
+	"short",
+	"iso"
+];
+/** Stable exemplar for date-format configuration previews. */
+const DATE_FORMAT_EXAMPLE_ISO = "2028-06-13";
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const STYLE_OPTIONS = {
+	long: { dateStyle: "long" },
+	medium: { dateStyle: "medium" },
+	short: { dateStyle: "short" }
+};
+const dateFormatters = /* @__PURE__ */ new Map();
+/** `Intl.DateTimeFormat` for a locale + style pair, cached per pair so it
+*  isn't rebuilt on every {@link formatDate} call. */
+const getDateFormatter = (locale, style) => {
+	const key = `${locale}:${style}`;
+	const cached = dateFormatters.get(key);
+	if (cached) return cached;
+	const formatter = new Intl.DateTimeFormat(locale, {
+		...STYLE_OPTIONS[style],
+		timeZone: "UTC"
+	});
+	dateFormatters.set(key, formatter);
+	return formatter;
+};
+/**
+* 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 getDateFormatter(dateFormat.locale, dateFormat.style).format(date);
+};
+/**
+* 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 (formula → date):
+*   - formula present → {@link evaluateNumericExpression}, stringified
+*   - else date (inputType "date" + dateFormat) → {@link formatDate}
+*   - else null
+*
+* Formula and date return null when the expression or value does not yield a
+* value, so the caller leaves the field as-is.
+*/
+const renderDeterministicFieldValue = (field, values) => {
+	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") {
+		const value = Array.isArray(node.value) ? node.value.join(",") : node.value ?? "";
+		return `${serializeLiteral(value)} in ${operand}`;
+	}
+	if (node.op === "is_not_empty") return `${operand} is defined`;
+	if (node.op === "is_empty") return `${operand} is not defined`;
+	return operand;
+};
+const serializeGroup = (group, top) => {
+	const parts = [];
+	for (const child of group.children) {
+		const part = serializeNode(child, false);
+		if (part.length > 0) parts.push(part);
+	}
+	if (parts.length === 0) return "";
+	const body = parts.length === 1 ? parts[0] ?? "" : parts.join(group.combinator === "and" ? " and " : " or ");
+	if (group.negated) return `not (${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/markers.ts
 /**
 * Canonical grammar for the docxtpl dialect of Jinja — the single source of
@@ -560,12 +718,18 @@ const normalizeMarkerInner = (inner) => inner.replace(SMART_DOUBLE_QUOTES, "\"")
 * not a nested marker. An apostrophe stays an ordinary character, so
 * `label("Owner's")` reads as it always did.
 *
+* A quoted run honours `\`-escapes, the way the argument scanner reads them,
+* so `label("she said \"yes\"")` is one span rather than three: the span and
+* the scanner have to agree on where a literal ends or a marker the scanner
+* would parse is one the recognizer never sees.
+*
 * The alternatives cannot overlap (the plain one excludes every character the
-* quoted one may start with) and a quoted run's end is forced by its body, so
-* the scan stays linear on adversarial input: a `{{` with no closing `}}`
-* costs one failed pass, not a polynomial retry.
+* quoted one may start with, and inside a quoted run the escape branch is the
+* only one that starts with a backslash), so the scan stays linear on
+* adversarial input: a `{{` with no closing `}}` costs one failed pass, not a
+* polynomial retry.
 */
-const MARKER_OUTPUT_BODY = String.raw`(?:[^{}"“”„«»]|["“„«][^"”»]*["”»])*`;
+const MARKER_OUTPUT_BODY = String.raw`(?:[^{}"“”„«»]|["“„«](?:\\[\s\S]|[^"”»\\])*["”»])*`;
 /** What a tag holds between `{%` and `%}`: anything but a brace, and a `%`
 *  only where it does not close the tag. */
 const MARKER_STATEMENT_BODY = String.raw`(?:[^{}%]|%(?!\}))*`;
@@ -1093,195 +1257,212 @@ const classifyMarkerDefect = (innerRaw, form = "output") => {
 /** 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
+//#region src/loop-scope.ts
+const rowScopePaths = (rowScopes) => rowScopes.map(({ scopedPath }) => scopedPath);
+/** A path already under the innermost repeat is left alone; anything else is
+*  read as a name relative to it. */
+const qualifyRowScopedPath = (path, rowPaths = []) => {
+	if (rowPaths.some((rowPath) => path === rowPath || path.startsWith(`${rowPath}.`))) return path;
+	const innermostRowPath = rowPaths.at(-1);
+	return innermostRowPath === void 0 ? path : `${innermostRowPath}.${path}`;
+};
+/** The manifest path for a marker written inside these loops. */
+const qualifyRowScopedPlaceholder = (path, rowScopes) => {
+	if (rowScopes.some(({ scopedPath }) => path === scopedPath || path.startsWith(`${scopedPath}.`))) return path;
+	for (const { alias, declaredPath, scopedPath } of rowScopes.toReversed()) for (const head of [alias, declaredPath]) {
+		if (path === head) return scopedPath;
+		if (path.startsWith(`${head}.`)) return `${scopedPath}.${path.slice(head.length + 1)}`;
+	}
+	return path;
+};
+/** The manifest path for an array a `{% for %}` opens inside these loops. */
+const qualifyLoopPath = (declaredPath, rowScopes) => qualifyRowScopedPath(qualifyRowScopedPlaceholder(declaredPath, rowScopes), rowScopePaths(rowScopes));
+//#endregion
+//#region src/field-config.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.
+* The filters that describe a REPEAT rather than a value: how many rows it
+* takes and what to call it. These are the ones a `{% for %}` tag may carry,
+* since the loop path names the array, not one of its values.
 */
-const DATE_FORMAT_STYLES = [
-	"long",
-	"medium",
-	"short",
-	"iso"
+const ARRAY_FILTER_NAMES = [
+	"label",
+	"hint",
+	"required",
+	"min_items",
+	"max_items"
 ];
-/** Stable exemplar for date-format configuration previews. */
-const DATE_FORMAT_EXAMPLE_ISO = "2028-06-13";
-const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
-const STYLE_OPTIONS = {
-	long: { dateStyle: "long" },
-	medium: { dateStyle: "medium" },
-	short: { dateStyle: "short" }
+const isArrayFilterName = (name) => ARRAY_FILTER_NAMES.some((candidate) => candidate === name);
+const NO_FILTERS = [];
+const filterCall = (name, ...args) => ({
+	name,
+	args
+});
+const positionalArg = (value) => ({
+	kind: "positional",
+	value
+});
+const keywordArg = (name, value) => ({
+	kind: "keyword",
+	name,
+	value
+});
+/** The `date()` spec that reads back as this pair: a locale, then the style it
+*  renders with. An ISO date reads the same in every language, so `iso` is
+*  written as the bare style the reader canonicalizes. */
+const dateSpec = ({ locale, style }) => style === "iso" ? style : `${locale}-${style}`;
+/** The numeric bounds, in the order the reader lists them, so a chain a
+*  document already carries and one this writes are the same text. */
+const VALIDATION_BOUNDS = [
+	["min", "min"],
+	["max", "max"],
+	["minLength", "min_length"],
+	["maxLength", "max_length"],
+	["minItems", "min_items"],
+	["maxItems", "max_items"]
+];
+const writeInputType = (field) => {
+	if (field.dateFormat !== void 0) return [filterCall("date", positionalArg(dateSpec(field.dateFormat)))];
+	const { inputType } = field;
+	if (inputType === void 0) return NO_FILTERS;
+	switch (inputType) {
+		case "boolean": return [filterCall("checkbox")];
+		case "date": return [filterCall("date", positionalArg("iso"))];
+		case "select": return [filterCall("select", ...(field.options ?? []).map((option) => positionalArg(option)))];
+		case "number":
+		case "text": return [filterCall(inputType)];
+		default: return assertNever(inputType);
+	}
 };
-const dateFormatters = /* @__PURE__ */ new Map();
-/** `Intl.DateTimeFormat` for a locale + style pair, cached per pair so it
-*  isn't rebuilt on every {@link formatDate} call. */
-const getDateFormatter = (locale, style) => {
-	const key = `${locale}:${style}`;
-	const cached = dateFormatters.get(key);
-	if (cached) return cached;
-	const formatter = new Intl.DateTimeFormat(locale, {
-		...STYLE_OPTIONS[style],
-		timeZone: "UTC"
-	});
-	dateFormatters.set(key, formatter);
-	return formatter;
+const writeSource = (field) => {
+	const { source } = field;
+	if (source === void 0) return NO_FILTERS;
+	switch (source.kind) {
+		case "party": return [filterCall("party", positionalArg(source.role), positionalArg(source.field))];
+		case "attorney": return [filterCall("attorney", positionalArg(source.ref), positionalArg(source.field))];
+		case "contact":
+		case "firm":
+		case "matter": return [filterCall(source.kind, positionalArg(source.field))];
+		default: return assertNever(source);
+	}
 };
-/**
-* 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;
+const writeAi = (field) => {
+	const { aiAdapt, aiPrompt, aiSeesDocument } = field;
+	if (aiPrompt === void 0 && aiAdapt !== true) return NO_FILTERS;
+	return [filterCall("ai", ...aiPrompt === void 0 ? [] : [positionalArg(aiPrompt)], ...aiAdapt === void 0 ? [] : [keywordArg("adapt", aiAdapt)], ...aiSeesDocument === void 0 ? [] : [keywordArg("sees_document", aiSeesDocument)])];
+};
+const writeValidation = (field) => {
+	const validation = field.validation;
+	if (validation === void 0) return NO_FILTERS;
+	const calls = [];
+	if (validation.pattern !== void 0) calls.push(filterCall("pattern", positionalArg(validation.pattern)));
+	for (const [key, name] of VALIDATION_BOUNDS) {
+		const bound = validation[key];
+		if (bound !== void 0) calls.push(filterCall(name, positionalArg(bound)));
+	}
+	return calls;
 };
 /**
-* 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.
+* Every key of {@link MarkerFieldConfig} and the filters that write it. Total
+* over the shape, so a property cannot join it without a decision about how an
+* author writes it in the document.
+*
+* A filter several properties feed (`ai`, `select`, `date`) is written by one
+* of them and skipped by the rest; the round-trip property in the api's
+* `field-filters.property.test.ts` is what proves nothing is dropped.
 */
-const formatDate = (value, dateFormat) => {
-	const date = parseIsoDate(value);
-	if (date === null) return null;
-	if (dateFormat.style === "iso") return value;
-	return getDateFormatter(dateFormat.locale, dateFormat.style).format(date);
+const MARKER_FIELD_FILTERS = {
+	path: () => NO_FILTERS,
+	inputType: writeInputType,
+	options: () => NO_FILTERS,
+	dateFormat: () => NO_FILTERS,
+	optionsFrom: ({ optionsFrom }) => optionsFrom === void 0 ? NO_FILTERS : [filterCall("options_from", positionalArg(optionsFrom))],
+	label: ({ label }) => label === void 0 ? NO_FILTERS : [filterCall("label", positionalArg(label))],
+	hint: ({ hint }) => hint === void 0 ? NO_FILTERS : [filterCall("hint", positionalArg(hint))],
+	required: (field) => field.required === true || field.validation?.required === true ? [filterCall("required")] : NO_FILTERS,
+	validation: writeValidation,
+	aiPrompt: writeAi,
+	aiAdapt: () => NO_FILTERS,
+	aiSeesDocument: () => NO_FILTERS,
+	lookup: ({ lookup }) => lookup === void 0 ? NO_FILTERS : [filterCall("lookup", positionalArg(lookup.registry), ...lookup.formats.map(({ key, template }) => keywordArg(key, template)))],
+	source: writeSource,
+	formula: ({ formula }) => formula === void 0 ? NO_FILTERS : [filterCall("formula", positionalArg(formula))],
+	condition: ({ condition }) => condition === void 0 ? NO_FILTERS : [filterCall("condition", positionalArg(condition))]
 };
 /**
-* 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.
+* The filter chain that declares this field in a document, in the catalogue's
+* own order so a chain the writer produces and one an author wrote read the
+* same.
 */
-const renderComposite = (parts, format, partValues) => replaceOutputMarkers(format, (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;
-};
+const filtersFromFieldConfig = (field) => Object.values(MARKER_FIELD_FILTERS).flatMap((write) => write(field));
 /**
-* 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.
+* The chain a `{% for %}` opener carries for this array: the repeat's own
+* filters and nothing else, derived from {@link ARRAY_FILTER_NAMES}, so a
+* value filter can never be written where the reader refuses it.
 */
-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;
-};
+const arrayFiltersFromFieldConfig = (field) => filtersFromFieldConfig(field).filter(({ name }) => isArrayFilterName(name));
 //#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") {
-		const value = Array.isArray(node.value) ? node.value.join(",") : node.value ?? "";
-		return `${serializeLiteral(value)} in ${operand}`;
-	}
-	if (node.op === "is_not_empty") return `${operand} is defined`;
-	if (node.op === "is_empty") return `${operand} is not defined`;
-	return operand;
+//#region src/render.ts
+/** The number literals the scanner reads: no exponent, no `Infinity`. */
+const WRITABLE_NUMBER = /^-?\d+(?:\.\d+)?$/u;
+/** What a tag's body cannot carry: it has no quoted-run escape hatch, so a
+*  brace or a tag closer inside one would end the tag early. */
+const RESERVED_IN_TAG = /[{}]|%\}/u;
+/** The reason this literal cannot be written in a marker of this form, or
+*  `null` when it can. A boolean always can; a string can in a `{{ }}` marker,
+*  because the writer quotes and escapes it. */
+const unwritableMarkerLiteral = (value, form = "output") => {
+	if (typeof value === "number") return WRITABLE_NUMBER.test(String(value)) ? null : "number-spelling";
+	if (typeof value === "string" && form === "statement") return RESERVED_IN_TAG.test(value) ? "tag-delimiter" : null;
+	return null;
 };
-const serializeGroup = (group, top) => {
-	const parts = [];
-	for (const child of group.children) {
-		const part = serializeNode(child, false);
-		if (part.length > 0) parts.push(part);
-	}
-	if (parts.length === 0) return "";
-	const body = parts.length === 1 ? parts[0] ?? "" : parts.join(group.combinator === "and" ? " and " : " or ");
-	if (group.negated) return `not (${body})`;
-	if (parts.length === 1) return body;
-	return top ? body : `(${body})`;
+/** One string literal, double-quoted, with backslashes and quotes escaped the
+*  way `scanQuoted` reads them back. */
+const renderString = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+const renderLiteral = (value) => typeof value === "string" ? renderString(value) : String(value);
+const renderArgument = (arg) => arg.kind === "positional" ? renderLiteral(arg.value) : `${arg.name}=${renderLiteral(arg.value)}`;
+/** Every value in a chain the grammar has no spelling for, with the filter it
+*  was written on and why, so a caller can refuse a configuration before it
+*  rewrites a document into something the scanner would read differently. A
+*  repeat's chain goes in a tag, so pass `"statement"` for one. */
+const unwritableFilterValues = (filters, form = "output") => filters.flatMap(({ args, name }) => args.flatMap((arg) => {
+	const reason = unwritableMarkerLiteral(arg.value, form);
+	return reason === null ? [] : [{
+		filter: name,
+		value: arg.value,
+		reason
+	}];
+}));
+/**
+* One filter chain as marker text, without the leading pipe: `label("A") |
+* required`. An empty chain renders the empty string, which is what a marker
+* that configures nothing carries.
+*/
+const renderFilterChain = (filters) => filters.map(({ args, name }) => args.length === 0 ? name : `${name}(${args.map(renderArgument).join(", ")})`).join(" | ");
+/** One value marker: `{{ path }}` or `{{ path | filters }}`. */
+const renderValueMarker = (path, filters) => {
+	const chain = renderFilterChain(filters);
+	return chain === "" ? `{{ ${path} }}` : `{{ ${path} | ${chain} }}`;
 };
-const serializeNode = (node, top) => {
-	if (node.type === "compare") return serializeCompare(node);
-	if (node.type === "predicate") return serializePredicate(node);
-	return serializeGroup(node, top);
+/** The docxtpl placement token a prefix is written with; `none` writes none. */
+const PREFIX_TOKEN = {
+	none: "",
+	paragraph: "p",
+	row: "tr"
 };
 /**
-* 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).
+* One `{% if %}` / `{% elif %}` opener carrying its expression.
+*
+* A rule that decides whether a block shows belongs in the tag that shows it:
+* the tag is the only place a document has for it, so a builder's rule is
+* serialized here rather than stored beside the document under a name.
 */
-const serializeCondition = (node) => serializeNode(node, true);
+const renderConditionTag = ({ expression, kind, prefix }) => `{%${PREFIX_TOKEN[prefix]} ${kind} ${expression} %}`;
+/** One `{% for %}` opener, keeping its placement prefix. */
+const renderForOpener = ({ alias, filters, path, prefix }) => {
+	const chain = renderFilterChain(filters);
+	const head = `{%${PREFIX_TOKEN[prefix]} for ${alias} in ${path}`;
+	return chain === "" ? `${head} %}` : `${head} | ${chain} %}`;
+};
 //#endregion
 //#region src/row-blocks.ts
 /**
@@ -1467,4 +1648,4 @@ const evaluateCondition = (expression, data, namedConditions, _resolved = /* @__
 	return evaluateCondition$1(node, makeResolver(data, namedConditions, _resolved, _depth));
 };
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, FILTER_NAMES, LOOP_PROPERTIES, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, refPattern, referencedConditionPaths, renderComposite, renderDeterministicFieldValue, replaceOutputMarkers, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression };
+export { ARRAY_FILTER_NAMES, BLOCK_DIRECTIVE_KINDS, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, FILTER_NAMES, LOOP_PROPERTIES, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, NUMERIC_FUNCTION_NAMES, arrayFiltersFromFieldConfig, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, filtersFromFieldConfig, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isArrayFilterName, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, qualifyLoopPath, qualifyRowScopedPath, qualifyRowScopedPlaceholder, refPattern, referencedConditionPaths, renderConditionTag, renderDeterministicFieldValue, renderFilterChain, renderForOpener, renderValueMarker, replaceOutputMarkers, resolvePath, rowScopePaths, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression, unwritableFilterValues, unwritableMarkerLiteral };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/template-conditions",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A document-template marker and condition engine: {{...}} marker grammar, parse, compute, serialize, field values.",
   "keywords": [
     "condition",