@wildwinter/expr-editor 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,351 @@
+import { BinaryOp, ExprNode, AstPath, UnaryOp, PropertyType, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
+export { ExpressionValidationIssue, ExpressionValidationResult, PropertyType } from '@wildwinter/expr';
+
+declare const boolLit: (value: boolean) => ExprNode;
+declare const numLit: (value: number) => ExprNode;
+declare const strLit: (value: string) => ExprNode;
+declare const scopedVar: (scope: string, name: string) => ExprNode;
+declare const binary: (op: BinaryOp, left: ExprNode, right: ExprNode) => ExprNode;
+declare const notNode: (operand: ExprNode) => ExprNode;
+declare const callNode: (name: string, args: ExprNode[]) => ExprNode;
+declare const flagDelta: (sign: "+" | "-", name: string) => ExprNode;
+/** A no-op sentinel: `true and X === X`, `false or X === X`, so a half-filled slot is inert. */
+declare const placeholderForOp: (op: "and" | "or") => ExprNode;
+declare const isPlaceholderForOp: (node: ExprNode, op: "and" | "or") => boolean;
+declare const isComparisonOp: (op: BinaryOp) => boolean;
+/** The node at `path`, or null if any segment fails to resolve. */
+declare function getNodeAt(ast: ExprNode, path: AstPath): ExprNode | null;
+/** Replace the node at `path` with `next`. `path.length === 0` returns `next`. */
+declare function setNodeAt(ast: ExprNode, path: AstPath, next: ExprNode): ExprNode;
+/**
+ * Delete the node at `path`, collapsing its parent:
+ *   - binary parent -> the surviving sibling replaces the parent (`A and B`, del B -> `A`)
+ *   - unary parent  -> the operand replaces the unary (strips the wrapper)
+ *   - call parent   -> the arg is spliced out
+ * Deleting the root (`path === []`) returns null (the caller clears the expression).
+ */
+declare function deleteAt(ast: ExprNode, path: AstPath): ExprNode | null;
+/** Wrap the node at `path` in a new `binary(op, …)`, the clause on `side`. */
+declare function insertSiblingClauseAt(ast: ExprNode, path: AstPath, op: "and" | "or", side: "left" | "right", clause: ExprNode): ExprNode;
+/** True iff the node at `path` is the operand of a `not`. */
+declare function isWrappedInNot(ast: ExprNode, path: AstPath): boolean;
+/** Wrap the node at `path` in `not(…)`. */
+declare function wrapInNotAt(ast: ExprNode, path: AstPath): ExprNode;
+/** Add a `not` if absent, strip it if present. */
+declare function toggleNotAt(ast: ExprNode, path: AstPath): ExprNode;
+/**
+ * If the node at `path` is one operand of an equality comparison (`==` / `!=`)
+ * whose OTHER operand is a property reference, return that property — so a string
+ * literal can offer the property's enum values. Null otherwise.
+ */
+declare function findEnumPeer(ast: ExprNode, path: AstPath): {
+    scope: string;
+    name: string;
+} | null;
+/**
+ * DFS for the first unfilled slot in a template-inserted clause: an empty string
+ * literal (a tag / value the author still has to set) or an unnamed flag delta.
+ * Returns its path relative to `node`, or null when the clause is complete —
+ * wizard-built clauses have no empty slots, so they never auto-open anything.
+ */
+declare function firstEmptyLeafPath(node: ExprNode, base?: AstPath): AstPath | null;
+
+type TreeRow = {
+    kind: "container";
+    op: "and" | "or";
+    negated: boolean;
+    children: TreeRow[];
+    path: AstPath;
+    chainPath: AstPath;
+} | {
+    kind: "comparison";
+    left: ExprNode;
+    op: BinaryOp;
+    right: ExprNode;
+    negated: boolean;
+    path: AstPath;
+    contentPath: AstPath;
+} | {
+    kind: "wrapped";
+    node: ExprNode;
+    negated: boolean;
+    path: AstPath;
+    contentPath: AstPath;
+};
+/** Derive the renderable row for `node` (at `path` in the whole AST). */
+declare function astToTree(node: ExprNode, path?: AstPath): TreeRow;
+/** Append `clause` to the chain at `chainPath` (left-folded; inherits the chain op, default "and"). */
+declare function addChildToContainer(ast: ExprNode, chainPath: AstPath, clause: ExprNode): ExprNode;
+/** Flip every binary in the chain at `chainPath` from its current op to `newOp` (placeholders re-polarise). */
+declare function flipContainerOp(ast: ExprNode, chainPath: AstPath, newOp: "and" | "or"): ExprNode;
+/** Wrap the node at `path` in `not(…)`, or strip the `not` if it already is one. */
+declare function toggleContainerNot(ast: ExprNode, path: AstPath): ExprNode;
+/** A new sub-group: its op is the OPPOSITE of the parent's (same-op would just flatten away). */
+declare function buildSubGroupClause(parentOp: "and" | "or", firstClause: ExprNode): ExprNode;
+/**
+ * Walk one step up from `path` to its parent binary AND/OR; if the sibling at
+ * that level is a placeholder for the parent's op, return the PARENT's path so a
+ * downstream `deleteAt` collapses the whole half-filled sub-group rather than
+ * leaving the placeholder (`true`/`false`) floating up as a bare clause. Returns
+ * `path` unchanged otherwise. Ported from the storylets tree editor; fixes the
+ * "delete the last real clause of a temp OR/AND group leaves `false`" case.
+ */
+declare function redirectDeleteForPlaceholderSibling(ast: ExprNode, path: AstPath): AstPath;
+/** Move a child within its container chain (reorder). Out-of-range is a no-op. */
+declare function moveChildInContainer(ast: ExprNode, chainPath: AstPath, from: number, to: number): ExprNode;
+
+/** Human label for a binary operator (words for logical, glyphs for relational). */
+declare const BINARY_LABEL: Record<BinaryOp, string>;
+declare const UNARY_LABEL: Record<UnaryOp, string>;
+declare const COMPARISON_OPS: BinaryOp[];
+declare const ARITHMETIC_OPS: BinaryOp[];
+/** The set of operators a given operator can be swapped to inline, or null if structural (and/or/not). */
+declare function opSwapGroup(op: BinaryOp): BinaryOp[] | null;
+/** Whether a child binary needs parentheses inside a parent binary on the given side. */
+declare function needsParens(childOp: BinaryOp, parentOp: BinaryOp, side: "left" | "right"): boolean;
+/** Render a number without IEEE-754 noise (integers plain; floats trimmed). */
+declare function formatNumber(n: number): string;
+
+interface CatalogueEntry {
+    scope: string;
+    /** Property name (stored lowercased to match parsed scopedvar names). */
+    name: string;
+    type: PropertyType;
+    enumValues?: string[];
+    /** Free-text description; the picker search matches it alongside the name. */
+    purpose?: string;
+}
+interface Filter {
+    acceptTypes?: PropertyType[];
+    acceptScopes?: string[];
+}
+/** The reference string for an entry: `@name` for the default scope, else `@scope.name`. */
+declare const refOf: (e: {
+    scope: string;
+    name: string;
+}, defaultScope: string) => string;
+/** The label shown in the picker / on a property pill. */
+declare const displayName: (e: {
+    scope: string;
+    name: string;
+}, defaultScope: string) => string;
+declare function filterCatalogue(entries: readonly CatalogueEntry[], filter?: Filter): CatalogueEntry[];
+/** Filter by a case-insensitive query against the display name AND the purpose text. */
+declare function searchCatalogue(entries: readonly CatalogueEntry[], query: string, defaultScope: string): CatalogueEntry[];
+/** Group entries by scope, scopes in `scopeOrder` first (then alphabetical), names sorted within. */
+declare function groupByScope(entries: readonly CatalogueEntry[], scopeOrder?: string[]): Array<{
+    scope: string;
+    entries: CatalogueEntry[];
+}>;
+/** Find an entry by scope + name (name compared case-insensitively). */
+declare function lookup(entries: readonly CatalogueEntry[], scope: string, name: string): CatalogueEntry | null;
+
+/** Stable string key for an AST path (for the issue index). */
+declare const pathKey: (p: AstPath) => string;
+interface Validation extends ExpressionValidationResult {
+    ast: ExprNode | null;
+    /** Issues keyed by `pathKey(issue.path)`. */
+    byPath: Map<string, ExpressionValidationIssue[]>;
+    /** True when the source could not even be parsed (the editor should fall back to raw text). */
+    unparseable: boolean;
+}
+declare function validateSource(src: string, schema: ExpressionSchema, dialect: Dialect): Validation;
+/** Issues attached to a specific node path. */
+declare const issuesAt: (byPath: Map<string, ExpressionValidationIssue[]>, path: AstPath) => ExpressionValidationIssue[];
+
+/** One step of a declarative clause wizard: a text entry, a number entry, or an
+ *  operator pick. The generic runner walks the steps in order (with back/cancel
+ *  chrome) and hands the collected values to the spec's `build()`. */
+type WizardStepSpec = {
+    kind: "string";
+    title: string;
+    caption?: string;
+    placeholder?: string;
+} | {
+    kind: "number";
+    title: string;
+    caption?: string;
+    placeholder?: string;
+    initial?: number;
+}
+/** Operator pick; `ops` defaults to the comparison set. */
+ | {
+    kind: "op";
+    title: string;
+    ops?: BinaryOp[];
+};
+type WizardValue = string | number | BinaryOp;
+/** A declarative multi-step wizard for a dialect function template. Lets a host
+ *  add guided flows (e.g. tag -> operator -> threshold) without upstream code. */
+interface WizardSpec {
+    steps: WizardStepSpec[];
+    /** Build the finished clause from the step values (index-aligned with `steps`). */
+    build(values: WizardValue[]): ExprNode;
+}
+/** A "+ Add condition" template — a named node the wizard inserts; args are then
+ *  refined by clicking the resulting pills. Dialect-specific functions (e.g.
+ *  patter's `seen` / `check_flags`) are supplied by the host as these. */
+interface FunctionTemplateSpec {
+    name: string;
+    label: string;
+    hint?: string;
+    /** Shown greyed and non-pickable (e.g. `check_flags` with no flags property
+     *  declared) so the option's existence is still discoverable. */
+    disabled?: boolean;
+    /** When set, picking this template runs a guided multi-step wizard instead of
+     *  inserting `build()` directly: one of the named built-ins (matching the
+     *  storylets condition editor) or a declarative `WizardSpec`. */
+    wizard?: "check_flags" | "random" | WizardSpec;
+    /** Build the node to insert (used when there is no `wizard`, e.g. seen / visits insert-then-pick). */
+    build(): ExprNode;
+}
+/** The editing context every renderer receives. */
+interface EditCtx {
+    schema: ExpressionSchema;
+    dialect: Dialect;
+    defaultScope: string;
+    catalogue: CatalogueEntry[];
+    scopeOrder: string[];
+    functions: FunctionTemplateSpec[];
+    byPath: Map<string, ExpressionValidationIssue[]>;
+    /** The current root AST (never null here; the empty/always state is handled by mount). */
+    getAst(): ExprNode;
+    /** Commit a new root AST (null clears the whole expression to "always"). */
+    apply(next: ExprNode | null): void;
+    /** Open a popover anchored to `anchor`; `render(close)` builds the content. */
+    openPopover(anchor: HTMLElement, render: (close: () => void) => Node): void;
+    /** Host-provided picker for a flow-node reference arg (e.g. `seen(...)` / `visits(...)`). When set,
+     *  the node-ref arg renders as a pill that opens this instead of a free-text field; `onPick` receives
+     *  the chosen node id. Absent in dialects / hosts that have no node catalogue. */
+    pickNode?(anchor: HTMLElement, current: string, onPick: (id: string) => void): void;
+    /** Resolve a node id to its readable label for the node-ref pill (falls back to the raw id). */
+    nodeLabel?(id: string): string;
+    /** Ask the mount to auto-open the micro-editor of the pill at `path` after the
+     *  next render — used by insert-then-refine templates so the author lands
+     *  straight in the first unfilled slot instead of chasing the error ring. */
+    requestFocus?(path: AstPath): void;
+}
+
+interface ExpressionEditorOptions {
+    /** Current expression in name-form (`@gold > 0 and @met`); "" = always / empty. */
+    value: string;
+    schema: ExpressionSchema;
+    dialect: Dialect;
+    /** Properties the picker offers. */
+    catalogue: CatalogueEntry[];
+    /** Scope display order for the picker groups. */
+    scopeOrder?: string[];
+    /** Dialect-specific clause templates (beyond the generic property comparisons). */
+    functions?: FunctionTemplateSpec[];
+    /** "tree" (default) for conditions, "flat" for a single inline expression. */
+    mode?: "tree" | "flat";
+    /** Flat mode only: show an optional "+ term" affordance that extends the value with one more term -
+     *  type-led: "arithmetic" extends a number (`5` → `5 + @bonus`); "boolean" extends a true/false value
+     *  with a logical term (`true` → `true and @met`). Omit for text / enum (no meaningful extension). */
+    addTerm?: "arithmetic" | "boolean";
+    /** Label for the empty/always pill (default "always"). */
+    nullLabel?: string;
+    /** Host picker for flow-node reference args (seen/visits); renders those args as a node pill. */
+    pickNode?: EditCtx["pickNode"];
+    /** Resolve a node id to a readable label for node-ref pills. */
+    nodeLabel?: EditCtx["nodeLabel"];
+    /** Start in raw-text mode (the host's global "show as text" toggle drives this; no inline `</>`). */
+    text?: boolean;
+    /** Render the editor's own validation message list under the pills (default true).
+     *  Hosts that display their own validation messages pass false to avoid doubling up. */
+    messages?: boolean;
+    /** Emitted on every edit (name-form; "" when cleared). */
+    onChange: (src: string) => void;
+    /** Notified when the author starts (true) / stops (false) editing inside a popover
+     *  micro-editor — lets the host suppress its own validation display mid-edit. */
+    onEditingChange?: (editing: boolean) => void;
+}
+interface ExpressionEditorHandle {
+    setValue(v: string): void;
+    /** Flip between the pill view and the raw-text view (driven by the host's global toggle). */
+    setText(on: boolean): void;
+    destroy(): void;
+}
+declare function mountExpressionEditor(host: HTMLElement, opts: ExpressionEditorOptions): ExpressionEditorHandle;
+
+/** One effect in name-form: a property assignment or a host event. Mirrors the
+ *  host's own Effect model (patter's `set` / `emit`) so it round-trips verbatim. */
+type EditorEffect = {
+    kind: "set";
+    target: string;
+    value: string;
+} | {
+    kind: "emit";
+    event: string;
+    args: string[];
+};
+interface EffectsEditorOptions {
+    /** The current effect list (edited in place via onChange). */
+    effects: EditorEffect[];
+    schema: ExpressionSchema;
+    dialect: Dialect;
+    /** Properties the target picker + value editors offer. */
+    catalogue: CatalogueEntry[];
+    scopeOrder?: string[];
+    /** Dialect clause templates passed through to each value editor. */
+    functions?: FunctionTemplateSpec[];
+    /** Known host event names to suggest when adding an `emit` (optional). */
+    events?: string[];
+    /** Offer the "+ emit event" affordance (default true). A host whose effects are SET-ONLY (e.g.
+     *  patter, where host events ride on gameData, not effects) passes false to hide it entirely. */
+    allowEmit?: boolean;
+    /** Start each inline value editor in raw-text mode (host's global "show as text" toggle drives this). */
+    text?: boolean;
+    /** Emitted on every structural / value edit with the whole new list. */
+    onChange: (effects: EditorEffect[]) => void;
+}
+interface EffectsEditorHandle {
+    setValue(effects: EditorEffect[]): void;
+    /** Flip every inline value editor between pills and raw text (host's global toggle). */
+    setText(on: boolean): void;
+    destroy(): void;
+}
+declare const addSet: (list: EditorEffect[], target: string, value: string) => EditorEffect[];
+declare const addEmit: (list: EditorEffect[], event: string) => EditorEffect[];
+declare const removeAt: (list: EditorEffect[], i: number) => EditorEffect[];
+declare function moveAt(list: EditorEffect[], i: number, dir: -1 | 1): EditorEffect[];
+declare function updateAt(list: EditorEffect[], i: number, patch: Partial<EditorEffect>): EditorEffect[];
+declare function setArgAt(list: EditorEffect[], i: number, argIdx: number, value: string): EditorEffect[];
+declare function addArg(list: EditorEffect[], i: number, value?: string): EditorEffect[];
+declare function removeArgAt(list: EditorEffect[], i: number, argIdx: number): EditorEffect[];
+/** A sensible starting value-expression for a freshly targeted property. Literals
+ *  are seeded so the value editor opens on an editable pill, never the empty state. */
+declare function seedValueSrc(type: PropertyType, enumValues?: string[]): string;
+declare function mountEffectsEditor(host: HTMLElement, opts: EffectsEditorOptions): EffectsEditorHandle;
+
+interface PreviewOptions {
+    schema: ExpressionSchema;
+    dialect: Dialect;
+    catalogue: CatalogueEntry[];
+    scopeOrder?: string[];
+    /** Resolve a node id to a readable label for seen()/visits() node pills. */
+    nodeLabel?: (id: string) => string;
+}
+/** Read-only pill strip for a condition (name-form). Empty/unparseable is the caller's concern; a
+ *  non-empty unparseable string falls back to its raw text. */
+declare function renderConditionPreview(src: string, o: PreviewOptions): HTMLElement;
+/** Read-only pill strip for an effects list: each `set` as `target = value`, each `emit` as
+ *  `emit event(args…)`, one per line. */
+declare function renderEffectsPreview(effects: EditorEffect[], o: PreviewOptions): HTMLElement;
+
+interface ValueWizardOptions {
+    catalogue: CatalogueEntry[];
+    scopeOrder: string[];
+    defaultScope: string;
+    /** When known (a `set` target's declared type), the picker leads straight to that input. */
+    expectedType?: PropertyType;
+    expectedEnumValues?: string[];
+    /** Receives the chosen value as name-form source. */
+    onCommit: (src: string) => void;
+    /** Optional cancel (the ✕ on the step). */
+    onCancel?: () => void;
+}
+/** Build the wizard UI into a fresh element (drive it via the host's popover). */
+declare function valueWizard(opts: ValueWizardOptions): HTMLElement;
+
+export { ARITHMETIC_OPS, BINARY_LABEL, COMPARISON_OPS, type CatalogueEntry, type EditCtx, type EditorEffect, type EffectsEditorHandle, type EffectsEditorOptions, type ExpressionEditorHandle, type ExpressionEditorOptions, type Filter, type FunctionTemplateSpec, type PreviewOptions, type TreeRow, UNARY_LABEL, type Validation, type ValueWizardOptions, type WizardSpec, type WizardStepSpec, type WizardValue, addArg, addChildToContainer, addEmit, addSet, astToTree, binary, boolLit, buildSubGroupClause, callNode, deleteAt, displayName, filterCatalogue, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };