@wildwinter/expr-editor 0.12.3 → 0.13.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BinaryOp, ExprNode, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
+import { ExprNode, BinaryOp, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
 export { ExpressionValidationIssue, ExpressionValidationResult, PropertyType } from '@wildwinter/expr';
 
 declare const boolLit: (value: boolean) => ExprNode;
@@ -53,6 +53,16 @@ declare function findChoicePeer(ast: ExprNode, path: AstPath): {
 } | null;
 /** @deprecated Renamed to {@link findChoicePeer} - it serves qualities as well as enums now. */
 declare const findEnumPeer: typeof findChoicePeer;
+/** A name-form ref in ONE form, so two spellings of the same property compare equal: the default
+ *  scope may be written or left off (`@patter.debt` and `@debt`), and refs are case-insensitive. */
+declare const normaliseRef: (ref: string, defaultScope: string) => string;
+/** The name-form ref a call ADVANCES, when the call is the plain `advance(@x)` shape: one scopedvar
+ *  argument and nothing else. Null for any other call, and for an argument that is not a property
+ *  (`advance(f(@x))` keeps its explicit form, since collapsing it would hide the middle).
+ *
+ *  `advance` is the language's own built-in rather than a dialect function, so it is matched by name
+ *  here the way the evaluator and validator match it. */
+declare function advancedRef(node: ExprNode, defaultScope: string): 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.
@@ -280,6 +290,11 @@ interface EditCtx {
      *  (an enum-typed outcome target). Lets the string editor show an enum picker
      *  even without a comparison peer. No effect on non-root literals. */
     valueEnumValues?: string[];
+    /** The name-form ref of the SET this value belongs to, when there is one. Its only use is the
+     *  self-advance idiom: `@debt = advance(@debt)` names the property three times to say one thing,
+     *  so when the value is exactly `advance(<this ref>)` the call collapses to a single "advances"
+     *  word and the row reads `debt advances`. Any other target, or any other shape, renders in full. */
+    selfAdvanceRef?: string;
     /** Host actions for a property pill (e.g. "Go to definition"). When set,
      *  right-clicking a property pill opens a menu of these actions. The host
      *  resolves what each does (navigation etc.); empty array = no menu. */
@@ -335,6 +350,10 @@ interface ExpressionEditorOptions {
     /** Enum values for the single root literal of a value field (an enum-typed
      *  target): the literal editor then offers them as a picker. Flat mode only. */
     valueEnumValues?: string[];
+    /** The ref of the SET this value belongs to (flat value fields only). Lets `advance(<that ref>)`
+     *  render as a single "advances" word: the outcome row already names the property in its target
+     *  column, so the call would say it twice more. */
+    selfAdvanceRef?: string;
     /** Flat single-value field: an empty value renders one editable "set a value…"
      *  placeholder pill (a root string literal) rather than the condition
      *  clause-menu empty state. Pairs with mode:"flat". */
@@ -498,4 +517,4 @@ interface ValueWizardOptions {
 /** 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, COMPARABLE_TYPES, COMPARISON_OPS, type CatalogueEntry, EQUALITY_OPS, type EditCtx, type EditorEffect, type EffectsEditorHandle, type EffectsEditorOptions, type ExpressionEditorHandle, type ExpressionEditorOptions, type Filter, type FunctionTemplateSpec, OP_WORD, 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, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
+export { ARITHMETIC_OPS, BINARY_LABEL, COMPARABLE_TYPES, COMPARISON_OPS, type CatalogueEntry, EQUALITY_OPS, type EditCtx, type EditorEffect, type EffectsEditorHandle, type EffectsEditorOptions, type ExpressionEditorHandle, type ExpressionEditorOptions, type Filter, type FunctionTemplateSpec, OP_WORD, type PreviewOptions, type TreeRow, UNARY_LABEL, type Validation, type ValueWizardOptions, type WizardSpec, type WizardStepSpec, type WizardValue, addArg, addChildToContainer, addEmit, addSet, advancedRef, astToTree, binary, boolLit, buildSubGroupClause, callNode, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BinaryOp, ExprNode, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
+import { ExprNode, BinaryOp, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
 export { ExpressionValidationIssue, ExpressionValidationResult, PropertyType } from '@wildwinter/expr';
 
 declare const boolLit: (value: boolean) => ExprNode;
@@ -53,6 +53,16 @@ declare function findChoicePeer(ast: ExprNode, path: AstPath): {
 } | null;
 /** @deprecated Renamed to {@link findChoicePeer} - it serves qualities as well as enums now. */
 declare const findEnumPeer: typeof findChoicePeer;
+/** A name-form ref in ONE form, so two spellings of the same property compare equal: the default
+ *  scope may be written or left off (`@patter.debt` and `@debt`), and refs are case-insensitive. */
+declare const normaliseRef: (ref: string, defaultScope: string) => string;
+/** The name-form ref a call ADVANCES, when the call is the plain `advance(@x)` shape: one scopedvar
+ *  argument and nothing else. Null for any other call, and for an argument that is not a property
+ *  (`advance(f(@x))` keeps its explicit form, since collapsing it would hide the middle).
+ *
+ *  `advance` is the language's own built-in rather than a dialect function, so it is matched by name
+ *  here the way the evaluator and validator match it. */
+declare function advancedRef(node: ExprNode, defaultScope: string): 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.
@@ -280,6 +290,11 @@ interface EditCtx {
      *  (an enum-typed outcome target). Lets the string editor show an enum picker
      *  even without a comparison peer. No effect on non-root literals. */
     valueEnumValues?: string[];
+    /** The name-form ref of the SET this value belongs to, when there is one. Its only use is the
+     *  self-advance idiom: `@debt = advance(@debt)` names the property three times to say one thing,
+     *  so when the value is exactly `advance(<this ref>)` the call collapses to a single "advances"
+     *  word and the row reads `debt advances`. Any other target, or any other shape, renders in full. */
+    selfAdvanceRef?: string;
     /** Host actions for a property pill (e.g. "Go to definition"). When set,
      *  right-clicking a property pill opens a menu of these actions. The host
      *  resolves what each does (navigation etc.); empty array = no menu. */
@@ -335,6 +350,10 @@ interface ExpressionEditorOptions {
     /** Enum values for the single root literal of a value field (an enum-typed
      *  target): the literal editor then offers them as a picker. Flat mode only. */
     valueEnumValues?: string[];
+    /** The ref of the SET this value belongs to (flat value fields only). Lets `advance(<that ref>)`
+     *  render as a single "advances" word: the outcome row already names the property in its target
+     *  column, so the call would say it twice more. */
+    selfAdvanceRef?: string;
     /** Flat single-value field: an empty value renders one editable "set a value…"
      *  placeholder pill (a root string literal) rather than the condition
      *  clause-menu empty state. Pairs with mode:"flat". */
@@ -498,4 +517,4 @@ interface ValueWizardOptions {
 /** 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, COMPARABLE_TYPES, COMPARISON_OPS, type CatalogueEntry, EQUALITY_OPS, type EditCtx, type EditorEffect, type EffectsEditorHandle, type EffectsEditorOptions, type ExpressionEditorHandle, type ExpressionEditorOptions, type Filter, type FunctionTemplateSpec, OP_WORD, 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, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
+export { ARITHMETIC_OPS, BINARY_LABEL, COMPARABLE_TYPES, COMPARISON_OPS, type CatalogueEntry, EQUALITY_OPS, type EditCtx, type EditorEffect, type EffectsEditorHandle, type EffectsEditorOptions, type ExpressionEditorHandle, type ExpressionEditorOptions, type Filter, type FunctionTemplateSpec, OP_WORD, type PreviewOptions, type TreeRow, UNARY_LABEL, type Validation, type ValueWizardOptions, type WizardSpec, type WizardStepSpec, type WizardValue, addArg, addChildToContainer, addEmit, addSet, advancedRef, astToTree, binary, boolLit, buildSubGroupClause, callNode, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { parseAndValidate, unparse } from '@wildwinter/expr';
+import { parseAndValidate, parse, unparse } from '@wildwinter/expr';
 
 // src/ast.ts
 var boolLit = (value) => ({ kind: "bool", value });
@@ -91,6 +91,16 @@ function findChoicePeer(ast, path) {
   return other.kind === "scopedvar" ? { scope: other.scope, name: other.name } : null;
 }
 var findEnumPeer = findChoicePeer;
+var normaliseRef = (ref, defaultScope) => {
+  const low = ref.toLowerCase();
+  const prefix = `@${defaultScope.toLowerCase()}.`;
+  return low.startsWith(prefix) ? `@${low.slice(prefix.length)}` : low;
+};
+function advancedRef(node, defaultScope) {
+  if (node.kind !== "call" || node.name !== "advance" || node.args.length !== 1) return null;
+  const arg = node.args[0];
+  return arg.kind === "scopedvar" ? normaliseRef(`@${arg.scope}.${arg.name}`, defaultScope) : null;
+}
 function firstEmptyLeafPath(node, base = []) {
   switch (node.kind) {
     case "string":
@@ -461,6 +471,16 @@ function renderNode(node, path, ctx, parentOp, side) {
         for (let i = 1; i < node.args.length; i++) row2.append(renderNode(node.args[i], [...path, "args", i], ctx));
         return row2;
       }
+      if (ctx.selfAdvanceRef && advancedRef(node, ctx.defaultScope) === normaliseRef(ctx.selfAdvanceRef, ctx.defaultScope)) {
+        const row2 = el("span", "exed-call exed-call-advance");
+        row2.append(pill(
+          "advance",
+          "advances",
+          (b) => callEditor(ctx, path, node, b),
+          { issue, title: "advance one stage", aria: "advances one stage" }
+        ));
+        return row2;
+      }
       const row = el("span", "exed-call");
       row.append(pill("func", node.name, (b) => callEditor(ctx, path, node, b), { issue }));
       row.append(el("span", "exed-paren", ["("]));
@@ -1144,6 +1164,7 @@ function mountExpressionEditor(host, opts) {
       },
       ...opts.requireNonEmpty ? { requireNonEmpty: true } : {},
       ...opts.valueEnumValues ? { valueEnumValues: opts.valueEnumValues } : {},
+      ...opts.selfAdvanceRef ? { selfAdvanceRef: opts.selfAdvanceRef } : {},
       ...opts.propertyActions ? { propertyActions: opts.propertyActions } : {},
       ...opts.pickNode ? { pickNode: opts.pickNode } : {},
       ...opts.nodeLabel ? { nodeLabel: opts.nodeLabel } : {}
@@ -1407,6 +1428,14 @@ function valueWizard(opts) {
 }
 
 // src/effects.ts
+function isSelfAdvance(eff, defaultScope, dialect) {
+  if (eff.kind !== "set" || !eff.target) return false;
+  try {
+    return advancedRef(parse(eff.value, dialect), defaultScope) === normaliseRef(eff.target, defaultScope);
+  } catch {
+    return false;
+  }
+}
 var clone = (list) => list.map((e) => e.kind === "set" ? { ...e } : { ...e, args: [...e.args] });
 var addSet = (list, target, value) => [...clone(list), { kind: "set", target, value }];
 var addEmit = (list, event) => [...clone(list), { kind: "emit", event, args: [] }];
@@ -1503,7 +1532,7 @@ function mountEffectsEditor(host, opts) {
     }), { container: opts.popoverContainer });
   };
   const targetType = (target) => opts.catalogue.find((e) => refOf(e, defaultScope) === target)?.type;
-  const valueDisplay = (value, onChange, type) => {
+  const valueDisplay = (value, onChange, type, selfAdvanceRef) => {
     const sub = el("div", "exed-effect-value");
     const addTerm = type === "number" ? "arithmetic" : type === "boolean" ? "boolean" : void 0;
     inner.push(mountExpressionEditor(sub, {
@@ -1514,7 +1543,13 @@ function mountEffectsEditor(host, opts) {
       scopeOrder: opts.scopeOrder,
       functions: opts.functions,
       mode: "flat",
+      // Every editor here holds a VALUE (a set's value, an emit's argument), never a condition. Say
+      // so, or emptying one falls back to the condition empty state and an outcome row reads
+      // "always / + Add your first condition" - condition vocabulary, offering clauses where a value
+      // belongs, and no way back to a value. `valueField` renders an editable empty literal instead.
+      valueField: true,
       ...addTerm ? { addTerm } : {},
+      ...selfAdvanceRef ? { selfAdvanceRef } : {},
       ...opts.popoverContainer ? { popoverContainer: opts.popoverContainer } : {},
       text: textMode,
       onChange
@@ -1565,11 +1600,18 @@ function mountEffectsEditor(host, opts) {
         commit(updateAt(effects, i, { target: refOf(entry, defaultScope), value: initialValueFor(entry, defaultScope).src }));
       });
     }, "change the target property");
-    row.append(targetBtn, el("span", "exed-effect-eq", ["="]));
+    const advances = isSelfAdvance(eff, defaultScope, opts.dialect);
+    row.append(targetBtn);
+    if (!advances) row.append(el("span", "exed-effect-eq", ["="]));
     row.append(valueDisplay(eff.value, (src) => {
-      effects = updateAt(effects, i, { value: src });
+      const next = updateAt(effects, i, { value: src });
+      if (isSelfAdvance(next[i], defaultScope, opts.dialect) !== advances) {
+        commit(next);
+        return;
+      }
+      effects = next;
       opts.onChange(effects);
-    }, targetType(eff.target)));
+    }, targetType(eff.target), advances ? eff.target : void 0));
     row.append(rowActions2(i));
     return row;
   }
@@ -1683,7 +1725,7 @@ function mountEffectsEditor(host, opts) {
 }
 
 // src/preview.ts
-function frozenCtx(src, o) {
+function frozenCtx(src, o, selfAdvanceRef) {
   const v = validateSource(src, o.schema, o.dialect);
   const ctx = {
     schema: o.schema,
@@ -1702,6 +1744,7 @@ function frozenCtx(src, o) {
     pickNode: () => {
     },
     // enables labelled node pills; never fires (preview is read-only)
+    ...selfAdvanceRef ? { selfAdvanceRef } : {},
     ...o.nodeLabel ? { nodeLabel: o.nodeLabel } : {},
     ...o.propertyActions ? {
       propertyActions: o.propertyActions,
@@ -1712,8 +1755,8 @@ function frozenCtx(src, o) {
   };
   return { ctx, ast: v.ast };
 }
-function exprPills(src, o) {
-  const { ctx, ast } = frozenCtx(src, o);
+function exprPills(src, o, selfAdvanceRef) {
+  const { ctx, ast } = frozenCtx(src, o, selfAdvanceRef);
   return ast ? renderNode(ast, [], ctx) : el("span", "exed-preview-raw", [src]);
 }
 function renderConditionPreview(src, o) {
@@ -1725,9 +1768,10 @@ function renderEffectsPreview(effects, o) {
   for (const eff of effects) {
     const row = el("div", "exed-preview-eff");
     if (eff.kind === "set") {
+      const advances = isSelfAdvance(eff, o.dialect.defaultScope, o.dialect);
       row.append(el("span", "exed-pill exed-pill-prop", [eff.target || "(property)"]));
-      row.append(el("span", "exed-effect-eq", ["="]));
-      row.append(exprPills(eff.value, o));
+      if (!advances) row.append(el("span", "exed-effect-eq", ["="]));
+      row.append(exprPills(eff.value, o, advances ? eff.target : void 0));
     } else {
       row.append(el("span", "exed-effect-kw", ["emit"]));
       row.append(el("span", "exed-pill exed-pill-event", [eff.event ? `"${eff.event}"` : "(name)"]));
@@ -1743,6 +1787,6 @@ function renderEffectsPreview(effects, o) {
   return wrap;
 }
 
-export { ARITHMETIC_OPS, BINARY_LABEL, COMPARABLE_TYPES, COMPARISON_OPS, EQUALITY_OPS, OP_WORD, UNARY_LABEL, addArg, addChildToContainer, addEmit, addSet, astToTree, binary, boolLit, buildSubGroupClause, callNode, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
+export { ARITHMETIC_OPS, BINARY_LABEL, COMPARABLE_TYPES, COMPARISON_OPS, EQUALITY_OPS, OP_WORD, UNARY_LABEL, addArg, addChildToContainer, addEmit, addSet, advancedRef, astToTree, binary, boolLit, buildSubGroupClause, callNode, choicesOf, comparisonOpsFor, deleteAt, displayName, filterCatalogue, findChoicePeer, findEnumPeer, firstEmptyLeafPath, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map