@pixerate/editor 0.23.0 → 0.24.0

package/dist/grammar/index.d.cts

@@ -1,5 +1,7 @@
-import { T as Token, P as PromptDiagnostic, d as PromptValues, f as Template, g as TemplateVersion, a as ConditionalKind, c as PromptValue } from '../tokens-CyLZmIei.cjs';
-export { C as ColorGradient, I as INSTRUCTION_REGEX, b as PromptDiagnosticCode, e as TEMPLATE_REGEX, h as TokenType, V as VARIABLE_REGEX, i as instructionRegex, t as templateRegex, v as variableRegex } from '../tokens-CyLZmIei.cjs';
+import { b as Token, a as PromptDiagnostic, P as PromptValues, T as Template, i as TemplateVersion, d as ConditionComparison, e as ConditionalKind, c as ComparisonOperator, g as PromptValue } from '../tokens-D7yXvUU6.cjs';
+export { C as ColorGradient, I as INSTRUCTION_REGEX, f as PromptDiagnosticCode, h as TEMPLATE_REGEX, j as TokenType, V as VARIABLE_REGEX, k as instructionRegex, t as templateRegex, v as variableRegex } from '../tokens-D7yXvUU6.cjs';
+import { S as SourceMapSegment } from '../sourcemap-C8AH3MBQ.cjs';
+export { R as ResolveTemplatesOptions, e as extractInstructionNames, a as extractTemplateNames, b as extractVariableNames, m as mapRawOffsetToResolved, c as mapResolvedOffsetToRaw, r as resolveTemplates, d as resolveTemplatesWithMapping, f as resolveVariables } from '../sourcemap-C8AH3MBQ.cjs';
 
 interface TokenizeResult {
     tokens: Token[];
@@ -24,93 +26,6 @@ declare function getPromptDiagnostics(text: string): PromptDiagnostic[];
  */
 declare function tokenizePromptWithDiagnostics(text: string): TokenizeResult;
 
-interface ResolveTemplatesOptions {
-    bindings?: Record<string, string>;
-    maxDepth?: number;
-    /**
-     * Values for `{variable}` slots and `{?variable}` sections. When omitted,
-     * variables, defaults and section tags are left exactly as written.
-     */
-    values?: PromptValues;
-}
-/**
- * Recursively resolves template tags `{{template_name}}` in a given text.
- * A tag that would recurse into itself is replaced with `TEMPLATE_LOOP_ERROR`,
- * and a tag nested deeper than `maxDepth` with `TEMPLATE_DEPTH_ERROR`; the rest
- * of the text still resolves normally.
- *
- * Pass `options.values` to also fill variables (falling back to their
- * `{name|default}`) and evaluate `{?name}…{/name}` / `{!name}…{/name}`
- * sections, including those inside template bodies. See `resolvePrompt` for
- * the source map and diagnostics.
- */
-declare function resolveTemplates(text: string, templates?: Template[], options?: ResolveTemplatesOptions): string;
-/**
- * Replaces `{variableName}` with values from a dictionary, falling back to a
- * `{variableName|default}` when no value is supplied, and evaluates
- * `{?name}…{/name}` / `{!name}…{/name}` sections. Variables with neither a
- * value nor a default are left as written. Templates are not expanded.
- */
-declare function resolveVariables(text: string, values: PromptValues): string;
-/**
- * Extracts unique template names referenced in text.
- */
-declare function extractTemplateNames(text: string): string[];
-/**
- * Extracts unique variable names referenced in text, including names used by
- * conditional section tags. Defaults and descriptions are stripped.
- */
-declare function extractVariableNames(text: string): string[];
-/**
- * Extracts unique instruction names referenced in text.
- */
-declare function extractInstructionNames(text: string): string[];
-
-/**
- * One contiguous piece of resolved output and the raw range it came from.
- *
- * - `raw`: copied verbatim; offsets map character by character.
- * - `template`: the expansion of a `{{template}}` tag.
- * - `variable`: a substituted value or `|default` for a `{variable}` tag.
- * - `conditional`: a section tag, or a whole removed section. These segments
- *   are empty in the resolved text (`resolvedStart === resolvedEnd`).
- *
- * Offsets inside non-raw segments map to the start of their raw range.
- */
-interface SourceMapSegment {
-    resolvedStart: number;
-    resolvedEnd: number;
-    source: "raw" | "template" | "variable" | "conditional";
-    rawStart: number;
-    rawEnd: number;
-    templateName?: string;
-    /** Variable substituted (`variable`) or tested (`conditional`). */
-    variableName?: string;
-    /** For `variable` segments: whether a supplied value or the default was used. */
-    valueSource?: "value" | "default";
-}
-/**
- * Resolves templates in text while tracking character offset mapping
- * between the raw input and the fully resolved output.
- *
- * Pass `options.values` to also substitute variables and evaluate conditional
- * sections (see `resolvePrompt`); without it the output is unchanged from the
- * template-only behavior.
- */
-declare function resolveTemplatesWithMapping(text: string, templates?: Template[], templateBindings?: Record<string, string>, options?: Pick<ResolveTemplatesOptions, "maxDepth" | "values">): {
-    text: string;
-    map: SourceMapSegment[];
-    diagnostics: PromptDiagnostic[];
-};
-/**
- * Maps an offset in resolved text back to the corresponding offset in raw text.
- */
-declare function mapResolvedOffsetToRaw(resolvedOffset: number, map: SourceMapSegment[]): number;
-/**
- * Maps an offset in raw text to the corresponding offset in resolved text.
- */
-declare function mapRawOffsetToResolved(rawOffset: number, map: SourceMapSegment[]): number;
-
 /**
  * Finds the latest version of a template based on `latestVersion` or last version entry.
  */
@@ -211,8 +126,76 @@ declare function isPromptValueSet(value: PromptValue): boolean;
  * value (it renders as nothing); `null`/`undefined` are not.
  */
 declare function getSuppliedValue(values: PromptValues, name: string): string | undefined;
-/** Whether a section opened by `{?name}` / `{!name}` keeps its body. */
-declare function evaluateCondition(conditional: Exclude<ConditionalKind, "end">, name: string, values: PromptValues): boolean;
+/**
+ * Whether a section opened by `{?name}` / `{!name}` keeps its body. With a
+ * `comparison` (from `{?name>3}`), the supplied value is compared instead of
+ * tested for presence; a missing value compares as `""`.
+ */
+declare function evaluateCondition(conditional: Exclude<ConditionalKind, "end">, name: string, values: PromptValues, comparison?: ConditionComparison): boolean;
+/**
+ * Compares two texts like a mail-merge `IF` field: as numbers when both parse
+ * as plain decimal numbers (so `"7"` equals `"7.0"`), otherwise as
+ * case-insensitive text.
+ */
+declare function compareConditionValues(left: string, operator: ComparisonOperator, right: string): boolean;
+/**
+ * The variable a conditional tag name compares when it is written as a
+ * comparison (`amount>100` → `amount`), or `undefined`. A tag only acts as a
+ * comparison when it is closed by `{/subject}`.
+ */
+declare function conditionSubject(name: string): string | undefined;
+type ParsedComparison = {
+    subject: string;
+    comparison: ConditionComparison;
+    error?: undefined;
+} | {
+    subject: string;
+    comparison?: undefined;
+    error: string;
+};
+/**
+ * Parses a comparison condition such as `amount >= 100`, `status=paid`,
+ * `status <> "on hold"` or `note=""`. Returns `undefined` when `text` has no
+ * subject and operator, or an `error` when the comparison is malformed
+ * (missing value, doubled operator, unterminated quote). `!=` is accepted as
+ * a synonym for `<>`.
+ */
+declare function parseComparison(text: string): ParsedComparison | undefined;
+/** Writes a comparison operand back as condition text, quoting it when needed. */
+declare function formatComparisonOperand(operand: string): string;
+/**
+ * The display form of a conditional tag: `{?name}`, `{!name}`, `{/name}`, or
+ * `{?amount>100}` for a comparison.
+ */
+declare function formatConditionalTag(tag: {
+    conditional?: ConditionalKind;
+    value: string;
+    comparison?: ConditionComparison;
+}): string;
+/** A tooltip for a conditional tag, e.g. `Shown when "amount" > 100`. */
+declare function describeConditionalTag(tag: {
+    conditional?: ConditionalKind;
+    value: string;
+    comparison?: ConditionComparison;
+}): string;
+/** A parsed standalone condition (see `parseConditionExpression`). */
+interface ConditionExpression {
+    /** `true` for `!name` / `!name=value`: the condition is inverted. */
+    negated: boolean;
+    name: string;
+    comparison?: ConditionComparison;
+}
+/**
+ * Parses a condition written like the inside of a section tag, without the
+ * braces: `vip` (has a value), `!vip` (has none), `amount>100`,
+ * `!status=paid`. A leading `?` is allowed. Used by options such as
+ * `mergeRecords({ skipIf })`. Returns `{ error }` for malformed text.
+ */
+declare function parseConditionExpression(text: string): ConditionExpression | {
+    error: string;
+};
+/** Evaluates a parsed condition expression against values. */
+declare function evaluateConditionExpression(expression: ConditionExpression, values: PromptValues): boolean;
 interface ConditionalTagLike {
     conditional: ConditionalKind;
     name: string;
@@ -220,15 +203,24 @@ interface ConditionalTagLike {
 interface ConditionalTagMatch {
     /** Index of the partner tag, or -1 when the tag is unbalanced. */
     partner: number;
-    /** Set when unbalanced. */
-    error?: "unclosed-section" | "unexpected-close";
+    /** Set when unbalanced, or on both tags of a malformed comparison pair. */
+    error?: "unclosed-section" | "unexpected-close" | "invalid-condition";
+    /**
+     * Set on both tags of a pair whose open tag is a comparison closed by its
+     * subject (`{?amount>100}…{/amount}`).
+     */
+    comparison?: ParsedComparison;
 }
 /**
  * Pairs conditional tags given in document order. A close tag pairs with the
- * nearest open tag of the same name; open tags skipped over are reported as
- * unclosed, and a close tag with no open partner as unexpected. Unbalanced tags
- * never throw: callers treat them as literal text. The surviving pairs are
- * always properly nested.
+ * nearest open tag of the same name, or with the nearest open comparison tag
+ * whose subject it names (`{?amount>100}` is closed by `{/amount}`; closing
+ * it with `{/amount>100}` keeps the old meaning, a presence check on a
+ * variable named `amount>100`). Open tags skipped over are reported as
+ * unclosed, a close tag with no open partner as unexpected, and a malformed
+ * comparison pair as an invalid condition. Unbalanced tags never throw:
+ * callers treat them as literal text. The surviving pairs are always properly
+ * nested.
  */
 declare function matchConditionalTags(tags: ConditionalTagLike[]): ConditionalTagMatch[];
 
@@ -241,8 +233,13 @@ interface VariableDescriptor {
     description?: string;
     /** Appears as a `{name}` slot. */
     usedAsValue: boolean;
-    /** Appears in a `{?name}` / `{!name}` condition. */
+    /** Appears in a `{?name}` / `{!name}` condition (including comparisons). */
     usedInCondition: boolean;
+    /**
+     * Present (and `true`) when the variable is compared in a condition such as
+     * `{?amount>100}`, so a form should ask for its text, not a checkbox.
+     */
+    usedInComparison?: true;
     /** Number of `{name…}` slots and condition tags (closing tags excluded). */
     occurrences: number;
     /** Templates whose bodies mention the variable, in discovery order. */
@@ -276,7 +273,10 @@ interface VariableFormField {
      * leaves the `{name}` placeholder in the resolved prompt.
      */
     required: boolean;
-    /** Only used by `{?name}` / `{!name}` conditions, never substituted. */
+    /**
+     * Only used by `{?name}` / `{!name}` presence conditions, never substituted
+     * or compared (a form can show a checkbox).
+     */
     conditionOnly: boolean;
 }
 /**
@@ -292,4 +292,226 @@ declare function getVariableFormFields(text: string, options?: ExtractVariablesO
  */
 declare function compactVariableValues(input: Record<string, string | null | undefined>): PromptValues;
 
-export { ConditionalKind, type ConditionalTagLike, type ConditionalTagMatch, type EvaluatedToken, type ExtractVariablesOptions, type ParsedVariableBody, PromptDiagnostic, PromptValue, PromptValues, type ResolvePromptOptions, type ResolvePromptResult, type ResolveTemplatesOptions, type SourceMapSegment, TEMPLATE_DEPTH_ERROR, TEMPLATE_LOOP_ERROR, Template, TemplateVersion, Token, type TokenizeResult, type VariableDescriptor, type VariableFormField, compactVariableValues, escapeVariableText, evaluateCondition, evaluatePromptTokens, extractInstructionNames, extractTemplateNames, extractVariableNames, extractVariables, getLatestVersion, getPromptDiagnostics, getSuppliedValue, getTemplateBody, getVariableFormFields, isPromptValueSet, mapRawOffsetToResolved, mapResolvedOffsetToRaw, matchConditionalTags, parseVariableBody, resolvePrompt, resolveTemplates, resolveTemplatesWithMapping, resolveVariables, tokenizePrompt, tokenizePromptWithDiagnostics, unescapeVariableText };
+/** Most records a data source keeps by default. */
+declare const MAX_DATA_SOURCE_RECORDS = 100000;
+/** Most fields a data source keeps by default. */
+declare const MAX_DATA_SOURCE_FIELDS = 1000;
+/** One record: field name → cell text. */
+type MergeRecord = Record<string, string>;
+/** Anything `parseDataSource` accepts. */
+type DataSourceInput = string | ReadonlyArray<ReadonlyArray<unknown>> | ReadonlyArray<Readonly<Record<string, unknown>>>;
+interface ParseDataSourceOptions {
+    /**
+     * Field separator for delimited text. `"auto"` (the default) picks whichever
+     * of `,` `;` and tab occurs most often in the first line (outside quotes),
+     * preferring `,` on a tie.
+     */
+    delimiter?: "auto" | string;
+    /**
+     * Whether the first row names the fields (default `true`). Without a header
+     * the fields are `Column 1`…`Column N`. Ignored for arrays of objects.
+     */
+    hasHeader?: boolean;
+    /**
+     * How to read a string: `"auto"` (default) parses text starting with `[` as
+     * JSON and falls back to delimited text when that fails.
+     */
+    format?: "auto" | "csv" | "json";
+    /** Record cap (default `MAX_DATA_SOURCE_RECORDS`). */
+    maxRecords?: number;
+    /** Field cap (default `MAX_DATA_SOURCE_FIELDS`). */
+    maxFields?: number;
+}
+type DataSourceWarningCode = "empty" | "invalid-json" | "unsupported-json" | "blank-header" | "duplicate-header" | "ragged-rows" | "records-truncated" | "fields-truncated";
+interface DataSourceWarning {
+    code: DataSourceWarningCode;
+    message: string;
+    /** For `ragged-rows`: how many records were padded or cut. */
+    count?: number;
+}
+interface MergeDataSource {
+    /** Field names: trimmed, unique (case-insensitively), never blank. */
+    fields: string[];
+    /** One entry per record, with every field present. */
+    records: MergeRecord[];
+    warnings: DataSourceWarning[];
+    /** How the input was read. */
+    format: "csv" | "json" | "rows" | "objects";
+    /** The delimiter used for delimited text. */
+    delimiter?: string;
+}
+/** Counts the auto-detect candidates in the first line, ignoring quoted text. */
+declare function detectDelimiter(text: string): string;
+/**
+ * Field names from a header row: names are trimmed, a blank name becomes
+ * `Column N` (its 1-based position), and repeats (compared case-insensitively)
+ * are numbered `Name 2`, `Name 3`, ….
+ */
+declare function normalizeFieldNames(row: ReadonlyArray<unknown>): string[];
+/**
+ * Reads a mail-merge data source.
+ *
+ * - **Text**: CSV / TSV (RFC 4180 quoting, doubled quotes, CRLF / LF / CR,
+ *   a leading BOM ignored) with the delimiter auto-detected, or JSON (an
+ *   array of objects or of arrays).
+ * - **Rows** (`unknown[][]`): the first row is the header unless
+ *   `hasHeader: false`.
+ * - **Objects**: the fields are the union of keys in first-seen order.
+ *
+ * Blank rows are skipped, header names are normalised (`normalizeFieldNames`),
+ * records are padded or cut to the header width, and records and fields are
+ * capped. Cells become strings (`null` → `""`, nested values → JSON). Problems
+ * are reported in `warnings`; this never throws.
+ */
+declare function parseDataSource(input: DataSourceInput, options?: ParseDataSourceOptions): MergeDataSource;
+/** Lower-cases and drops spaces, `_`, `-` and `.` so `First Name` matches `first_name`. */
+declare function normalizeFieldKey(name: string): string;
+/**
+ * Built-in alias groups for `matchFields`: any name in a group matches any
+ * other (after `normalizeFieldKey`). Extended from Word's address-block
+ * field detection.
+ */
+declare const FIELD_ALIASES: ReadonlyArray<ReadonlyArray<string>>;
+type FieldMatchKind = "exact" | "normalized" | "alias";
+interface FieldMatch {
+    variable: string;
+    /** The matched field, or `null`. */
+    field: string | null;
+    kind: FieldMatchKind | null;
+}
+interface FieldMapping {
+    /** Variable → field (or `null` when unmatched), in variable order. */
+    mapping: Record<string, string | null>;
+    matches: FieldMatch[];
+    unmatchedVariables: string[];
+    /** Fields no variable maps to. */
+    unusedFields: string[];
+}
+interface MatchFieldsOptions {
+    /** Extra alias groups, checked after the built-in ones. */
+    aliases?: ReadonlyArray<ReadonlyArray<string>>;
+}
+/**
+ * Maps prompt variables to data source fields: an exact name first, then a
+ * case-, space- and punctuation-insensitive match (`first_name` ↔
+ * `First Name`), then an alias (`FirstName` ↔ `First` / `GivenName`, see
+ * `FIELD_ALIASES`). Several variables may map to the same field.
+ */
+declare function matchFields(variables: ReadonlyArray<string | {
+    name: string;
+}>, fields: ReadonlyArray<string>, options?: MatchFieldsOptions): FieldMapping;
+interface RecordToValuesOptions {
+    /**
+     * Treat blank cells as missing so `{name|default}` falls back to its
+     * default (default `true`). With `false`, a blank cell renders as empty.
+     */
+    blankAsMissing?: boolean;
+}
+/**
+ * The prompt values for one record: every field under its own name, then
+ * each mapped variable set from its field (a `null` mapping leaves the
+ * variable unset even if a field shares its name).
+ */
+declare function recordToValues(record: MergeRecord, mapping?: Readonly<Record<string, string | null | undefined>>, options?: RecordToValuesOptions): PromptValues;
+
+/**
+ * Multi-record merge: resolves one prompt per data source record with
+ * `resolvePrompt`, like Word's Finish & Merge.
+ */
+
+/** Default cap on merged outputs. */
+declare const MAX_MERGE_OUTPUTS = 10000;
+/** Default cap on the total length of merged text (characters). */
+declare const MAX_MERGE_LENGTH = 20000000;
+interface MergeRecordsOptions {
+    /** Templates for `{{name}}` tags. */
+    templates?: Template[];
+    /** Template version bindings. */
+    bindings?: Record<string, string>;
+    /** Maximum template nesting depth (default 10). */
+    maxDepth?: number;
+    /**
+     * Variable → field. Variables left out are matched automatically with
+     * `matchFields`; a `null` entry leaves the variable unset.
+     */
+    mapping?: Record<string, string | null>;
+    /**
+     * Text placed between outputs in the joined `text`: default `"\n\n"`.
+     * `"none"` joins them with nothing in between.
+     */
+    separator?: string;
+    /**
+     * Drops a record's output when this holds. Either a function of the record
+     * (and its prompt values), or a condition written like the inside of a
+     * section tag: `void`, `!email`, `status=cancelled`, `amount<10`. The
+     * condition is evaluated against the record's prompt values (mapped
+     * variables and raw field names); a name that is neither is matched to a
+     * field like a variable (`status` → `Status`).
+     */
+    skipIf?: string | ((record: MergeRecord, values: PromptValues, index: number) => boolean);
+    /** Stop after this many outputs (default `MAX_MERGE_OUTPUTS`). */
+    maxOutputs?: number;
+    /** Stop once the outputs reach this many characters (default `MAX_MERGE_LENGTH`). */
+    maxLength?: number;
+    /** First record to merge, 1-based (default 1). */
+    from?: number;
+    /** Last record to merge, 1-based and inclusive (default: the last). */
+    to?: number;
+    /** See `recordToValues` (default `true`: blank cells use defaults). */
+    blankAsMissing?: boolean;
+    /** Options for parsing `source` when it is not already parsed. */
+    parse?: ParseDataSourceOptions;
+}
+interface MergeOutput {
+    /** 0-based index of the record in the data source. */
+    index: number;
+    record: MergeRecord;
+    /** The values the prompt was resolved with. */
+    values: PromptValues;
+    text: string;
+    map: SourceMapSegment[];
+}
+interface MergeSkip {
+    index: number;
+    record: MergeRecord;
+    reason: "skip-if";
+}
+type MergeDiagnosticCode = PromptDiagnostic["code"] | "unmapped-variable" | "invalid-skip-condition" | "max-outputs" | "max-length" | "data-source";
+/** A grammar diagnostic from the template, or a merge-level problem. */
+interface MergeDiagnostic {
+    code: MergeDiagnosticCode;
+    message: string;
+    /** Variable, for grammar and `unmapped-variable` diagnostics. */
+    name?: string;
+    start?: number;
+    end?: number;
+    templateName?: string;
+}
+interface MergeRecordsResult {
+    outputs: MergeOutput[];
+    skipped: MergeSkip[];
+    diagnostics: MergeDiagnostic[];
+    /** Every output's text joined with the separator. */
+    text: string;
+    /** The variable → field mapping used. */
+    mapping: Record<string, string | null>;
+    /** The merge stopped early at `maxOutputs` or `maxLength`. */
+    truncated: boolean;
+}
+/**
+ * Merges a prompt with every record of a data source: one resolved output per
+ * record, in order. Fields are matched to the prompt's variables
+ * automatically (override with `mapping`), blank cells fall back to the
+ * variable's default, `{?field}` / `{?field>3}` sections are evaluated per
+ * record, and `skipIf` drops records. Grammar diagnostics in the prompt are
+ * reported once. Never throws.
+ */
+declare function mergeRecords(template: string, source: MergeDataSource | DataSourceInput, options?: MergeRecordsOptions): MergeRecordsResult;
+/**
+ * Serializes merge outputs for copying or download: `"text"` joins them with
+ * `separator` (default `"\n\n"`), `"json"` writes an array of
+ * `{ record, text }` objects (`record` is 1-based).
+ */
+declare function serializeMergeOutputs(outputs: ReadonlyArray<Pick<MergeOutput, "index" | "text" | "values">>, format?: "text" | "json", separator?: string): string;
+
+export { ComparisonOperator, ConditionComparison, type ConditionExpression, ConditionalKind, type ConditionalTagLike, type ConditionalTagMatch, type DataSourceInput, type DataSourceWarning, type DataSourceWarningCode, type EvaluatedToken, type ExtractVariablesOptions, FIELD_ALIASES, type FieldMapping, type FieldMatch, type FieldMatchKind, MAX_DATA_SOURCE_FIELDS, MAX_DATA_SOURCE_RECORDS, MAX_MERGE_LENGTH, MAX_MERGE_OUTPUTS, type MatchFieldsOptions, type MergeDataSource, type MergeDiagnostic, type MergeDiagnosticCode, type MergeOutput, type MergeRecord, type MergeRecordsOptions, type MergeRecordsResult, type MergeSkip, type ParseDataSourceOptions, type ParsedComparison, type ParsedVariableBody, PromptDiagnostic, PromptValue, PromptValues, type RecordToValuesOptions, type ResolvePromptOptions, type ResolvePromptResult, SourceMapSegment, TEMPLATE_DEPTH_ERROR, TEMPLATE_LOOP_ERROR, Template, TemplateVersion, Token, type TokenizeResult, type VariableDescriptor, type VariableFormField, compactVariableValues, compareConditionValues, conditionSubject, describeConditionalTag, detectDelimiter, escapeVariableText, evaluateCondition, evaluateConditionExpression, evaluatePromptTokens, extractVariables, formatComparisonOperand, formatConditionalTag, getLatestVersion, getPromptDiagnostics, getSuppliedValue, getTemplateBody, getVariableFormFields, isPromptValueSet, matchConditionalTags, matchFields, mergeRecords, normalizeFieldKey, normalizeFieldNames, parseComparison, parseConditionExpression, parseDataSource, parseVariableBody, recordToValues, resolvePrompt, serializeMergeOutputs, tokenizePrompt, tokenizePromptWithDiagnostics, unescapeVariableText };