@stll/template-conditions 0.2.2 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ 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
+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.

package/dist/index.d.ts

@@ -6,6 +6,22 @@ declare const resolvePath: (path: string, data: Record<string, unknown>) => unkn
 //#region src/parse.d.ts
 declare const parseCondition: (expression: string) => ConditionNode$1 | null;
 //#endregion
+//#region src/referenced-paths.d.ts
+/**
+ * What a `{% if %}` expression reads. Structural, not evaluative: the paths a
+ * condition depends on, for callers that decide something about the condition
+ * itself rather than about a document being filled.
+ */
+/**
+ * Every field path an expression reads, in source order.
+ *
+ * `null` says the expression does not answer the question: it did not parse,
+ * or it reads an operand whose own references cannot be enumerated. A caller
+ * deciding what a condition depends on must not read that as "depends on
+ * nothing".
+ */
+declare const referencedConditionPaths: (expression: string) => string[] | null;
+//#endregion
 //#region src/compute.d.ts
 /**
  * Arithmetic evaluator for computed template fields.
@@ -122,22 +138,47 @@ 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).
+ * Canonical grammar for the docxtpl dialect of Jinja — the single source of
+ * truth shared by the fill pipeline (api), the editor highlighter (folio), and
+ * the read-only preview (web).
+ *
+ * Two spans carry meaning: an output marker `{{ ... }}` prints a value, and a
+ * tag `{% ... %}` opens or closes a block. A tag may carry a docxtpl placement
+ * prefix — `{%p ... %}` owns its paragraph, `{%tr ... %}` owns its table row —
+ * and a bare tag is placed by the leniency rules the consumer applies.
  *
  * Add a new directive to `MarkerMeta` and teach {@link classifyMarker} to
  * recognize it. Compile-time totality checks then require its ordered runtime
  * value and its block/inline disposition, while exhaustive consumer switches
  * fail until they handle it.
  *
- * No consumer should define its own `{{...}}` regex. The low-level pattern
+ * No consumer should define its own marker 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.
  */
+/** A literal an author can write inside a filter or function call. */
+type MarkerLiteral = string | number | boolean;
+/** One argument of a filter call: positional, or `name=value`. */
+type FilterArgument = {
+  kind: "positional";
+  value: MarkerLiteral;
+} | {
+  kind: "keyword";
+  name: string;
+  value: MarkerLiteral;
+};
+/** One `| name` / `| name(args)` step of an output marker's filter chain. */
+type FilterCall = {
+  name: FilterName;
+  args: readonly FilterArgument[];
+};
+/** The loop properties addressable inside a `{% for %}` body. */
+declare const LOOP_PROPERTIES: readonly ["index", "index0", "first", "last", "length"];
+type LoopProperty = (typeof LOOP_PROPERTIES)[number];
 type MarkerMeta = {
   kind: "placeholder";
   expr: string;
+  filters: readonly FilterCall[];
 } | {
   kind: "clause";
   name: string;
@@ -149,126 +190,241 @@ type MarkerMeta = {
   kind: "ref";
   key: string;
 } | {
-  kind: "index";
-} | {
-  kind: "count";
+  kind: "loop";
+  property: LoopProperty;
 } | {
   kind: "if";
   expr: string;
 } | {
-  kind: "elseif";
+  kind: "elif";
   expr: string;
 } | {
   kind: "else";
 } | {
   kind: "endif";
 } | {
-  kind: "each";
-  expr: string;
+  kind: "for";
+  alias: string;
+  path: string;
+  /** Filters on the loop path configure the ARRAY: how many rows it takes
+   *  and what to call it. */
+  filters: readonly FilterCall[];
 } | {
-  kind: "endeach";
+  kind: "endfor";
 };
 type DirectiveKind = MarkerMeta["kind"];
-declare const DIRECTIVE_KINDS: readonly ["placeholder", "clause", "num", "ref", "index", "count", "if", "elseif", "else", "endif", "each", "endeach"];
+declare const DIRECTIVE_KINDS: readonly ["placeholder", "clause", "num", "ref", "loop", "if", "elif", "else", "endif", "for", "endfor"];
 declare const DIRECTIVE_PLACEMENT: {
   readonly placeholder: "inline";
   readonly clause: "inline";
   readonly num: "inline";
   readonly ref: "inline";
-  readonly index: "inline";
-  readonly count: "inline";
+  readonly loop: "inline";
   readonly if: "block";
-  readonly elseif: "block";
+  readonly elif: "block";
   readonly else: "block";
   readonly endif: "block";
-  readonly each: "block";
-  readonly endeach: "block";
+  readonly for: "block";
+  readonly endfor: "block";
 };
 type BlockDirectiveKind = { [TKind in DirectiveKind]: (typeof DIRECTIVE_PLACEMENT)[TKind] extends "block" ? TKind : never; }[DirectiveKind];
 /** Directives that occupy their own paragraph, in canonical grammar order. */
-declare const BLOCK_DIRECTIVE_KINDS: readonly ["if", "elseif", "else", "endif", "each", "endeach"];
+declare const BLOCK_DIRECTIVE_KINDS: readonly ["if", "elif", "else", "endif", "for", "endfor"];
 declare const isBlockDirectiveKind: (kind: unknown) => kind is BlockDirectiveKind;
-/** Any `{{...}}` marker; group 1 is the inner text (untrimmed — callers trim). */
+/**
+ * Every filter the dialect accepts on a fillable value. The names are the
+ * grammar's; which manifest property each one writes is decided by the field
+ * catalogue in the api, which is total over BOTH this list and the manifest
+ * keys, so neither side can gain an entry the other has not decided.
+ */
+declare const FILTER_NAMES: readonly ["text", "number", "date", "checkbox", "select", "options_from", "label", "hint", "required", "pattern", "min", "max", "min_length", "max_length", "min_items", "max_items", "ai", "lookup", "matter", "contact", "party", "attorney", "firm", "formula", "condition"];
+type FilterName = (typeof FILTER_NAMES)[number];
+/** Normalise one marker's inner text: typographic quotes become straight
+ *  quotes, fixed-width spaces become ordinary ones. */
+declare const normalizeMarkerInner: (inner: string) => string;
+/**
+ * What an output marker holds between its braces: anything but a brace or a
+ * double quote, plus whole double-quoted arguments, whose braces are content
+ * rather than the marker's own delimiters — `pattern("^[0-9]{5}$")` is a regex,
+ * not a nested marker. An apostrophe stays an ordinary character, so
+ * `label("Owner's")` reads as it always did.
+ *
+ * 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.
+ */
+declare const MARKER_OUTPUT_BODY: string;
+/** What a tag holds between `{%` and `%}`: anything but a brace, and a `%`
+ *  only where it does not close the tag. */
+declare const MARKER_STATEMENT_BODY: string;
+/**
+ * Any marker span: an output `{{...}}` (group `output`) or a tag `{%...%}`
+ * (group `statement`, with the docxtpl placement in group `prefix`).
+ */
 declare const markerPattern: () => RegExp;
-/** Inline field / clause / numbering marker (inner allows the directive sigils). */
+/** Inline value marker, including its filter chain; group `name` is the path
+ *  the value comes from and group `filters` the untouched chain. */
 declare const placeholderPattern: () => RegExp;
-/** `{{@clause:Name}}` / `{{@clause:Name:v3}}` — `name` and `modifier` groups. */
+/** `{{ clause("Name") }}` / `{{ clause("Name", "v3") }}`. */
 declare const clauseSlotPattern: () => RegExp;
-/** `{{@num:Key}}` — the `key` group. */
+/** `{{ num("key") }}` — the `key` group. */
 declare const numPattern: () => RegExp;
-/** `{{@ref:Key}}` — the `key` group. */
+/** `{{ 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;
+/** `{{ loop.index }}` and its siblings — the `property` group. */
+declare const loopPattern: () => RegExp;
 /** Cheap presence test for any numbering marker (no capture). */
 declare const hasNumberingPattern: () => RegExp;
-/** Cheap presence test for any block directive (no capture). */
+/** Cheap presence test for any tag (no capture). */
 declare const hasBlockDirectivePattern: () => RegExp;
-/** A whole line that is a single block directive — `tag` and `expr` groups. */
+/** A whole line that is a single block tag — `prefix`, `tag` and `expr`. */
 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;
 /** Whether `value` is safe to use as a dotted object path. */
 declare const isSafeFieldPath: (value: string) => boolean;
-/** Whether `value` is a valid name for authoring a `{{@clause:NAME}}` slot:
- *  the intersection of the clause-slot parse grammar and the fill pipeline's
- *  placeholder charset, so every accepted name round-trips through fill. */
+/** Whether `value` is a valid name for authoring a `clause("NAME")` slot. */
 declare const isClauseSlotName: (value: string) => boolean;
+/** Which brace pair carried the marker text. */
+type MarkerForm = "output" | "statement";
+/** Where a tag's docxtpl prefix says the tag belongs. `"none"` is a bare tag,
+ *  placed by the consumer's leniency rules, and every output marker. */
+type MarkerPrefix = "none" | "paragraph" | "row";
 /**
- * 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).
+ * Classify the inner text of one 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;
+declare const classifyMarker: (innerRaw: string, form?: MarkerForm) => MarkerMeta | null;
 type ScannedMarker = {
-  /** Offset of `{{` in the source text. */
+  /** Offset of the opening brace pair in the source text. */
   start: number;
-  /** Offset just past `}}`. */
+  /** Offset just past the closing brace pair. */
   end: number;
-  /** The full matched marker, e.g. `{{@num:scope}}`. */
+  /** The full matched marker, e.g. `{% endfor %}`. */
   raw: string;
-  /** The (untrimmed) inner text. */
+  /** The normalized, trimmed inner text. */
   inner: string;
+  form: MarkerForm;
+  /** The docxtpl placement prefix the author wrote. */
+  prefix: MarkerPrefix;
   meta: MarkerMeta;
 };
 /**
- * Find every recognized `{{...}}` marker in `text`, in document order, with
- * offsets and classified metadata. Unrecognized `{{...}}` spans are skipped.
+ * Find every recognized marker in `text`, in document order, with offsets and
+ * classified metadata. Unrecognized spans are skipped.
  */
 declare const scanMarkers: (text: string) => ScannedMarker[];
-/** A `{{...}}` span that looks like a marker but classifies to nothing. */
+/**
+ * Rewrite every `{{ ... }}` output marker in `text` through `replace`, which
+ * receives the whole marker and its raw inner text and returns the replacement.
+ * Tags are left untouched. The single scan is the same one the classifier uses,
+ * so a caller that rewrites marker text never needs its own regex.
+ */
+declare const replaceOutputMarkers: (text: string, replace: (raw: string, inner: string) => string) => string;
+/**
+ * The values-map key one marker substitutes from, or `null` when the marker is
+ * not a substitution target (a tag, or a `loop.*` token the loop expander
+ * resolves first). One function so the key discovery writes is the key the
+ * patcher reads.
+ */
+declare const substitutionKey: (meta: MarkerMeta) => string | null;
+/** The values-map key for one clause slot. */
+declare const clauseSlotKey: (name: string, version?: string) => string;
+/** A marker-shaped span that classifies to nothing. */
 type InvalidMarker = {
-  /** Offset of `{{` in the source text. */
+  /** Offset of the opening brace pair in the source text. */
   start: number;
-  /** Offset just past `}}`. */
+  /** Offset just past the closing brace pair. */
   end: number;
   /** The full matched span, e.g. `{{my field}}`. */
   raw: string;
-  /** The (trimmed) inner text. */
+  /** The normalized, trimmed inner text. */
   inner: string;
+  form: MarkerForm;
 };
 /**
- * Find every `{{...}}` span whose inner text is NOT a recognized directive —
- * near-misses an author clearly meant as markers but that every recognizer
- * skips, so they print literally at fill time (e.g. `{{my field}}` with a
- * space, `{{@clause:}}` with no name). Offsets and raw text are shaped like
- * {@link scanMarkers} results, minus the classified `meta`. This is the exact
+ * Find every marker-shaped span whose inner text is NOT a recognized
+ * directive — near-misses an author clearly meant as markers but that every
+ * recognizer skips, so they print literally at fill time. This is the exact
  * complement of {@link scanMarkers}: a span is in one list or the other.
  */
 declare const scanInvalidMarkers: (text: string) => InvalidMarker[];
+/** The loop alias the codemod (and the legacy-marker message) generates for a
+ *  `{{#each path}}`: the singular of the last plain-word segment, else `item`. */
+declare const legacyLoopAlias: (path: string) => string;
+/** Translate an old-dialect condition expression to the Jinja surface:
+ *  `!a` becomes `not a`, `a contains "x"` becomes `"x" in a`. */
+declare const translateLegacyExpression: (expr: string) => string;
+/**
+ * The Jinja marker that replaces one old-dialect marker's inner text, or
+ * `null` when the text is not old-dialect. Shared by the rejection message and
+ * the codemod, so the fix an author is told to make is the fix the script
+ * would have made.
+ */
+declare const legacyMarkerReplacement: (innerRaw: string) => string | null;
+/**
+ * Why a marker-shaped span misses the grammar in a way that names the
+ * authoring mistake rather than merely failing to classify. Consumers derive
+ * their own warning codes from {@link MARKER_DEFECT_KINDS} so the two never
+ * drift.
+ */
+type MarkerDefectKind = "legacy_marker" | "unsupported_tag" | "unknown_filter" | "python_expression" | "bracket_index";
+declare const MARKER_DEFECT_KINDS: readonly ["legacy_marker", "unsupported_tag", "unknown_filter", "python_expression", "bracket_index"];
+/** One diagnosis of a rejected span: the kind plus the construct to quote. */
+type MarkerDefect = {
+  kind: MarkerDefectKind;
+  /** The construct the author wrote that the grammar refuses. */
+  construct: string;
+  /** The Jinja that replaces it, when the mistake has one exact fix. */
+  replacement?: string;
+};
+/**
+ * Name the authoring mistake behind one marker's inner text, or `null` when
+ * the text is a recognized directive ({@link classifyMarker} accepts it) or an
+ * unrecognizable span with no specific diagnosis (`{{my field}}`).
+ */
+declare const classifyMarkerDefect: (innerRaw: string, form?: MarkerForm) => MarkerDefect | null;
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
 declare const assertNever: (value: never) => never;
 //#endregion
+//#region src/row-blocks.d.ts
+/** One end of a row block, addressed within the row that was scanned. */
+type RowBlockMarker = {
+  /** Index into the row's cells. */
+  cellIndex: number;
+  /** Index into that cell's paragraphs. */
+  paragraphIndex: number;
+  marker: ScannedMarker;
+};
+type RowBlockPair = {
+  open: RowBlockMarker;
+  close: RowBlockMarker;
+};
+/**
+ * The one row block a table row declares in the lenient form, or `null`.
+ *
+ * `cells` is the row's cells in document order, each as its paragraph texts in
+ * document order.
+ *
+ * A row qualifies when exactly two block markers reach outside their own
+ * paragraph, they are a matching opener/closer pair, the closer sits in a LATER
+ * cell than the opener, the opener prefixes its cell and the closer suffixes
+ * its cell. Everything else — one half of a pair, two nested pairs, a stray
+ * `{% else %}`, a pair wrapping the paragraphs of a single cell — is left to the
+ * engine's existing structure errors rather than guessed at.
+ */
+declare const detectRowBlockPair: (cells: readonly (readonly string[])[]) => RowBlockPair | null;
+//#endregion
 //#region src/index.d.ts
 type NamedCondition = {
   name: string;
-  /** The `{{#if}}` expression string. Authoritative unless `node` is set. */
+  /** 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
+   * 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.
    */
@@ -282,16 +438,17 @@ type NamedCondition = {
  */
 declare const MAX_CONDITION_DEPTH = 50;
 /**
- * Evaluate a template `{{#if ...}}` condition. The expression is parsed into
+ * 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.
+ * Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), membership
+ * (`"x" in path`), presence (`is defined` / `is not defined`), truthiness,
+ * negation (`not`), 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 BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, type FieldDateFormat, type GroupNode, type InvalidMarker, MAX_CONDITION_DEPTH, type MarkerMeta, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, 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, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };
+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 };