@wildwinter/expr-editor 0.10.3 → 0.11.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BinaryOp, ExprNode, AstPath, UnaryOp, PropertyType, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
+import { BinaryOp, ExprNode, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
 export { ExpressionValidationIssue, ExpressionValidationResult, PropertyType } from '@wildwinter/expr';
 
 declare const boolLit: (value: boolean) => ExprNode;
@@ -99,6 +99,20 @@ declare const BINARY_LABEL: Record<BinaryOp, string>;
 declare const UNARY_LABEL: Record<UnaryOp, string>;
 declare const COMPARISON_OPS: BinaryOp[];
 declare const ARITHMETIC_OPS: BinaryOp[];
+/** Property types a comparison clause can be built on - what the clause wizard offers as a left-hand
+ *  side. `flags` is absent because its clause is the flag-check wizard, not a comparison. */
+declare const COMPARABLE_TYPES: PropertyType[];
+/** The operators offered for a comparison on a property of this type.
+ *
+ *  Ordered types get the full set; the rest get equality only. A QUALITY is ordered: its stages are a
+ *  ladder, and "at or past a stage" is the gate the type exists for, so offering it `==` alone (as the
+ *  editor did before 0.11.0) hides the feature behind hand-written source. */
+declare const comparisonOpsFor: (t: PropertyType) => BinaryOp[];
+declare const EQUALITY_OPS: BinaryOp[];
+/** The property types a comparison's RIGHT-hand side may be picked from, given the left's type.
+ *  A quality accepts only another quality: a plain string would name a stage nothing validates, and
+ *  comparing across two ladders is an error the engine raises by design. */
+declare const rhsTypesFor: (t: PropertyType) => PropertyType[];
 /** 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. */
@@ -112,9 +126,22 @@ interface CatalogueEntry {
     name: string;
     type: PropertyType;
     enumValues?: string[];
+    /** A quality's ORDERED stage ladder. Separate from `enumValues` because the order carries meaning
+     *  here (comparisons are positional, `advance()` walks it) - a host that smuggled stages through
+     *  `enumValues` got a value picker but no ordering affordances. */
+    stages?: string[];
     /** Free-text description; the picker search matches it alongside the name. */
     purpose?: string;
 }
+/** The CLOSED set of values a property can hold, when it has one: a quality's stages (in ladder
+ *  order) or an enum's values. Everything that offers "pick a value" for a property goes through
+ *  this, so a quality is never mistaken for free text. `stages` falls back to `enumValues` for a
+ *  host still passing a quality's ladder the old way. */
+declare const choicesOf: (e: {
+    type: PropertyType;
+    enumValues?: string[];
+    stages?: string[];
+} | null | undefined) => string[] | undefined;
 interface Filter {
     acceptTypes?: PropertyType[];
     acceptScopes?: string[];
@@ -381,8 +408,13 @@ declare function setArgAt(list: EditorEffect[], i: number, argIdx: number, value
 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;
+ *  are seeded so the value editor opens on an editable pill, never the empty state.
+ *
+ *  A QUALITY seeds to `advance(<ref>)` when the target's ref is known: moving to the next stage is
+ *  what outcomes on a ladder overwhelmingly do, and it is the form that keeps a story insertion-safe
+ *  (it names no destination, so a stage added later routes through it). Pass no ref and it falls back
+ *  to the first stage as a literal, which the author can still swap to `advance(...)`. */
+declare function seedValueSrc(type: PropertyType, values?: string[], ref?: string): string;
 declare function mountEffectsEditor(host: HTMLElement, opts: EffectsEditorOptions): EffectsEditorHandle;
 
 interface PreviewOptions {
@@ -427,4 +459,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, 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 };
+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, 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, 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, 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, UnaryOp, PropertyType, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
+import { BinaryOp, ExprNode, AstPath, PropertyType, UnaryOp, ExpressionValidationResult, ExpressionValidationIssue, ExpressionSchema, Dialect } from '@wildwinter/expr';
 export { ExpressionValidationIssue, ExpressionValidationResult, PropertyType } from '@wildwinter/expr';
 
 declare const boolLit: (value: boolean) => ExprNode;
@@ -99,6 +99,20 @@ declare const BINARY_LABEL: Record<BinaryOp, string>;
 declare const UNARY_LABEL: Record<UnaryOp, string>;
 declare const COMPARISON_OPS: BinaryOp[];
 declare const ARITHMETIC_OPS: BinaryOp[];
+/** Property types a comparison clause can be built on - what the clause wizard offers as a left-hand
+ *  side. `flags` is absent because its clause is the flag-check wizard, not a comparison. */
+declare const COMPARABLE_TYPES: PropertyType[];
+/** The operators offered for a comparison on a property of this type.
+ *
+ *  Ordered types get the full set; the rest get equality only. A QUALITY is ordered: its stages are a
+ *  ladder, and "at or past a stage" is the gate the type exists for, so offering it `==` alone (as the
+ *  editor did before 0.11.0) hides the feature behind hand-written source. */
+declare const comparisonOpsFor: (t: PropertyType) => BinaryOp[];
+declare const EQUALITY_OPS: BinaryOp[];
+/** The property types a comparison's RIGHT-hand side may be picked from, given the left's type.
+ *  A quality accepts only another quality: a plain string would name a stage nothing validates, and
+ *  comparing across two ladders is an error the engine raises by design. */
+declare const rhsTypesFor: (t: PropertyType) => PropertyType[];
 /** 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. */
@@ -112,9 +126,22 @@ interface CatalogueEntry {
     name: string;
     type: PropertyType;
     enumValues?: string[];
+    /** A quality's ORDERED stage ladder. Separate from `enumValues` because the order carries meaning
+     *  here (comparisons are positional, `advance()` walks it) - a host that smuggled stages through
+     *  `enumValues` got a value picker but no ordering affordances. */
+    stages?: string[];
     /** Free-text description; the picker search matches it alongside the name. */
     purpose?: string;
 }
+/** The CLOSED set of values a property can hold, when it has one: a quality's stages (in ladder
+ *  order) or an enum's values. Everything that offers "pick a value" for a property goes through
+ *  this, so a quality is never mistaken for free text. `stages` falls back to `enumValues` for a
+ *  host still passing a quality's ladder the old way. */
+declare const choicesOf: (e: {
+    type: PropertyType;
+    enumValues?: string[];
+    stages?: string[];
+} | null | undefined) => string[] | undefined;
 interface Filter {
     acceptTypes?: PropertyType[];
     acceptScopes?: string[];
@@ -381,8 +408,13 @@ declare function setArgAt(list: EditorEffect[], i: number, argIdx: number, value
 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;
+ *  are seeded so the value editor opens on an editable pill, never the empty state.
+ *
+ *  A QUALITY seeds to `advance(<ref>)` when the target's ref is known: moving to the next stage is
+ *  what outcomes on a ladder overwhelmingly do, and it is the form that keeps a story insertion-safe
+ *  (it names no destination, so a stage added later routes through it). Pass no ref and it falls back
+ *  to the first stage as a literal, which the author can still swap to `advance(...)`. */
+declare function seedValueSrc(type: PropertyType, values?: string[], ref?: string): string;
 declare function mountEffectsEditor(host: HTMLElement, opts: EffectsEditorOptions): EffectsEditorHandle;
 
 interface PreviewOptions {
@@ -427,4 +459,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, 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 };
+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, 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, 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, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };

package/dist/index.js

@@ -220,6 +220,10 @@ var BINARY_LABEL = {
 var UNARY_LABEL = { not: "NOT", neg: "\u2212" };
 var COMPARISON_OPS = ["==", "!=", ">", ">=", "<", "<="];
 var ARITHMETIC_OPS = ["+", "-", "*", "/"];
+var COMPARABLE_TYPES = ["boolean", "number", "string", "enum", "quality"];
+var comparisonOpsFor = (t) => t === "number" || t === "quality" ? COMPARISON_OPS : EQUALITY_OPS;
+var EQUALITY_OPS = ["==", "!="];
+var rhsTypesFor = (t) => t === "number" ? ["number"] : t === "boolean" ? ["boolean"] : t === "quality" ? ["quality"] : t === "enum" ? ["enum", "string"] : ["string", "enum"];
 function opSwapGroup(op) {
   if (COMPARISON_OPS.includes(op)) return COMPARISON_OPS;
   if (ARITHMETIC_OPS.includes(op)) return ARITHMETIC_OPS;
@@ -249,6 +253,12 @@ function formatNumber(n) {
 }
 
 // src/schema.ts
+var choicesOf = (e) => {
+  if (!e) return void 0;
+  if (e.type === "quality") return e.stages?.length ? e.stages : e.enumValues;
+  if (e.type === "enum") return e.enumValues;
+  return void 0;
+};
 var refOf = (e, defaultScope) => e.scope === defaultScope ? `@${e.name}` : `@${e.scope}.${e.name}`;
 var displayName = (e, defaultScope) => e.scope === defaultScope ? e.name : `${e.scope}.${e.name}`;
 function filterCatalogue(entries, filter = {}) {
@@ -552,8 +562,9 @@ function stringEditor(ctx, path, node, anchor) {
   const peer = findEnumPeer(ctx.getAst(), path);
   const enumEntry = peer ? lookup(ctx.catalogue, peer.scope, peer.name) : null;
   const rootValueEnums = path.length === 0 && ctx.valueEnumValues?.length ? ctx.valueEnumValues : null;
-  const enumValues = enumEntry?.enumValues?.length ? enumEntry.enumValues : rootValueEnums;
-  const enumHeadLabel = enumEntry ? `${displayName(enumEntry, ctx.defaultScope)} value` : "Value";
+  const peerChoices = choicesOf(enumEntry);
+  const enumValues = peerChoices?.length ? peerChoices : rootValueEnums;
+  const enumHeadLabel = enumEntry ? `${displayName(enumEntry, ctx.defaultScope)} ${enumEntry.type === "quality" ? "stage" : "value"}` : "Value";
   ctx.openPopover(anchor, (close) => {
     if (enumValues?.length) {
       const wrap = el("div", "exed-menu");
@@ -703,7 +714,6 @@ function propertyPicker(ctx, opts) {
 }
 
 // src/clausewizard.ts
-var EQUALITY = ["==", "!="];
 var OP_WORD = {
   "==": "equals",
   "!=": "not equal to",
@@ -717,8 +727,6 @@ var opButton = (o, onClick) => {
   b.append(el("span", "exed-opt-name", [BINARY_LABEL[o]]), el("span", "exed-opt-purpose", [OP_WORD[o] ?? ""]));
   return b;
 };
-var opsForType = (t) => t === "number" ? COMPARISON_OPS : EQUALITY;
-var rhsTypesFor = (t) => t === "number" ? ["number"] : t === "boolean" ? ["boolean"] : t === "enum" ? ["enum", "string"] : ["string", "enum"];
 function header(host, title, back, cancel) {
   const h = el("div", "exed-vwiz-head");
   if (back) h.append(button("exed-vwiz-back", "\u2190", back, "Back"));
@@ -749,8 +757,8 @@ function valueStep(host, w, lhs, op, back, cancel, commit) {
       const row = el("div", "exed-field-row");
       row.append(button("exed-opt", "true", () => done(boolLit(true))), button("exed-opt", "false", () => done(boolLit(false))));
       body.append(row);
-    } else if (lhs.type === "enum" && lhs.enumValues?.length) {
-      for (const v of lhs.enumValues) body.append(button("exed-opt", v, () => done(strLit(v))));
+    } else if (choicesOf(lhs)?.length) {
+      for (const v of choicesOf(lhs)) body.append(button("exed-opt", v, () => done(strLit(v))));
     } else if (lhs.type === "number") {
       body.append(textField({ caption: "Number", placeholder: "e.g. 3", validate: (v) => v.trim() !== "" && Number.isFinite(Number(v)), onCommit: (v) => done(numLit(Number(v))) }));
     } else {
@@ -772,8 +780,13 @@ function comparisonWizard(host, w, commit, cancel) {
     const body = el("div", "exed-vwiz-body");
     host.append(body);
     body.append(propertyPicker(pickCtxOf(w), {
-      accept: ["boolean", "number", "string", "enum"],
-      onPick: (e) => pickOp({ ref: refDisplay(w, e), type: e.type, ...e.enumValues ? { enumValues: e.enumValues } : {} })
+      accept: COMPARABLE_TYPES,
+      onPick: (e) => pickOp({
+        ref: refDisplay(w, e),
+        type: e.type,
+        ...e.enumValues ? { enumValues: e.enumValues } : {},
+        ...e.stages ? { stages: e.stages } : {}
+      })
     }));
   };
   const pickOp = (lhs) => {
@@ -781,7 +794,7 @@ function comparisonWizard(host, w, commit, cancel) {
     header(host, el("span", void 0, ["Operator for ", mono(lhs.ref)]), pickLhs, cancel);
     const body = el("div", "exed-vwiz-body");
     host.append(body);
-    for (const o of opsForType(lhs.type)) {
+    for (const o of comparisonOpsFor(lhs.type)) {
       body.append(opButton(o, () => valueStep(host, w, lhs, o, () => pickOp(lhs), cancel, commit)));
     }
   };
@@ -1433,14 +1446,16 @@ function removeArgAt(list, i, argIdx) {
   cur.args.splice(argIdx, 1);
   return next;
 }
-function seedValueSrc(type, enumValues) {
+function seedValueSrc(type, values, ref) {
   switch (type) {
     case "boolean":
       return "true";
     case "number":
       return "0";
     case "enum":
-      return JSON.stringify(enumValues?.[0] ?? "");
+      return JSON.stringify(values?.[0] ?? "");
+    case "quality":
+      return ref ? `advance(${ref})` : JSON.stringify(values?.[0] ?? "");
     case "string":
       return '""';
     default:
@@ -1538,7 +1553,8 @@ function mountEffectsEditor(host, opts) {
     const row = el("div", "exed-effect exed-effect-set");
     const targetBtn = button("exed-pill exed-pill-prop", eff.target || "(pick property)", (e) => {
       pickTarget(e.currentTarget, void 0, (entry) => {
-        commit(updateAt(effects, i, { target: refOf(entry, defaultScope), value: seedValueSrc(entry.type, entry.enumValues) }));
+        const ref = refOf(entry, defaultScope);
+        commit(updateAt(effects, i, { target: ref, value: seedValueSrc(entry.type, choicesOf(entry), ref) }));
       });
     }, "change the target property");
     row.append(targetBtn, el("span", "exed-effect-eq", ["="]));
@@ -1712,6 +1728,6 @@ function renderEffectsPreview(effects, o) {
   return wrap;
 }
 
-export { ARITHMETIC_OPS, BINARY_LABEL, COMPARISON_OPS, UNARY_LABEL, 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 };
+export { ARITHMETIC_OPS, BINARY_LABEL, COMPARABLE_TYPES, COMPARISON_OPS, EQUALITY_OPS, UNARY_LABEL, addArg, addChildToContainer, addEmit, addSet, astToTree, binary, boolLit, buildSubGroupClause, callNode, choicesOf, comparisonOpsFor, 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, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map