@wildwinter/expr-editor 0.14.1 → 0.15.1

package/dist/index.d.cts

@@ -56,6 +56,12 @@ 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 set/clear-a-flag value: `set_flags(@scope.name, +flag)` - adjust one
+ *  flag, keep the rest, which is what outcomes on a flags property
+ *  overwhelmingly do (and the form a whole-value change cannot express).
+ *  Lives here with the other pure ref helpers so the value wizard can build
+ *  it without importing the effects mount (which imports the wizard). */
+declare const flagChangeSrc: (targetRef: string, sign: "+" | "-", flag: 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).
@@ -183,11 +189,21 @@ interface Filter {
     acceptTypes?: PropertyType[];
     acceptScopes?: string[];
 }
-/** The reference string for an entry: `@name` for the default scope, else `@scope.name`. */
+/** The reference string for an entry: `@name` for the default scope, else `@scope.name`.
+ *  CONDITION-side sugar only: a change TARGET must use {@link targetRefOf} - the storylets
+ *  compiler requires `@scope.name` there, and emitting this shorthand for a default-scope
+ *  target made every picker-authored change invalid (the Storyletter antagonist audit's
+ *  find, 2026-08-29). Patter's grammar takes both forms, so the split costs it nothing. */
 declare const refOf: (e: {
     scope: string;
     name: string;
 }, defaultScope: string) => string;
+/** The reference a change TARGET is written as: always fully qualified. A target is a
+ *  reference, not an expression, and the shorthand is condition-side sugar (see refOf). */
+declare const targetRefOf: (e: {
+    scope: string;
+    name: string;
+}) => string;
 /** The label shown in the picker / on a property pill. */
 declare const displayName: (e: {
     scope: string;
@@ -529,6 +545,13 @@ interface ValueWizardOptions {
     expectedChoices?: string[];
     /** @deprecated Use `expectedChoices`. Kept so a 0.11.x caller keeps working. */
     expectedEnumValues?: string[];
+    /** A FLAGS target's qualified ref and declared flags: together they unlock the
+     *  set/clear-a-flag step, which is what outcomes on a flags property
+     *  overwhelmingly want and which a whole-value change cannot express (the
+     *  Storyletter antagonist audit's find, 2026-08-29). Absent, the generic
+     *  kinds stand alone as before. */
+    expectedRef?: string;
+    expectedFlags?: string[];
     /** Receives the chosen value as name-form source. */
     onCommit: (src: string) => void;
     /** Optional cancel (the ✕ on the step). */
@@ -537,4 +560,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, 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, propertyTip, 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, flagChangeSrc, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, propertyTip, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, targetRefOf, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };

package/dist/index.d.ts

@@ -56,6 +56,12 @@ 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 set/clear-a-flag value: `set_flags(@scope.name, +flag)` - adjust one
+ *  flag, keep the rest, which is what outcomes on a flags property
+ *  overwhelmingly do (and the form a whole-value change cannot express).
+ *  Lives here with the other pure ref helpers so the value wizard can build
+ *  it without importing the effects mount (which imports the wizard). */
+declare const flagChangeSrc: (targetRef: string, sign: "+" | "-", flag: 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).
@@ -183,11 +189,21 @@ interface Filter {
     acceptTypes?: PropertyType[];
     acceptScopes?: string[];
 }
-/** The reference string for an entry: `@name` for the default scope, else `@scope.name`. */
+/** The reference string for an entry: `@name` for the default scope, else `@scope.name`.
+ *  CONDITION-side sugar only: a change TARGET must use {@link targetRefOf} - the storylets
+ *  compiler requires `@scope.name` there, and emitting this shorthand for a default-scope
+ *  target made every picker-authored change invalid (the Storyletter antagonist audit's
+ *  find, 2026-08-29). Patter's grammar takes both forms, so the split costs it nothing. */
 declare const refOf: (e: {
     scope: string;
     name: string;
 }, defaultScope: string) => string;
+/** The reference a change TARGET is written as: always fully qualified. A target is a
+ *  reference, not an expression, and the shorthand is condition-side sugar (see refOf). */
+declare const targetRefOf: (e: {
+    scope: string;
+    name: string;
+}) => string;
 /** The label shown in the picker / on a property pill. */
 declare const displayName: (e: {
     scope: string;
@@ -529,6 +545,13 @@ interface ValueWizardOptions {
     expectedChoices?: string[];
     /** @deprecated Use `expectedChoices`. Kept so a 0.11.x caller keeps working. */
     expectedEnumValues?: string[];
+    /** A FLAGS target's qualified ref and declared flags: together they unlock the
+     *  set/clear-a-flag step, which is what outcomes on a flags property
+     *  overwhelmingly want and which a whole-value change cannot express (the
+     *  Storyletter antagonist audit's find, 2026-08-29). Absent, the generic
+     *  kinds stand alone as before. */
+    expectedRef?: string;
+    expectedFlags?: string[];
     /** Receives the chosen value as name-form source. */
     onCommit: (src: string) => void;
     /** Optional cancel (the ✕ on the step). */
@@ -537,4 +560,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, 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, propertyTip, 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, flagChangeSrc, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, propertyTip, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, targetRefOf, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };

package/dist/index.js

@@ -96,6 +96,7 @@ var normaliseRef = (ref, defaultScope) => {
   const prefix = `@${defaultScope.toLowerCase()}.`;
   return low.startsWith(prefix) ? `@${low.slice(prefix.length)}` : low;
 };
+var flagChangeSrc = (targetRef, sign, flag) => `set_flags(${targetRef}, ${sign}${flag})`;
 function advancedRef(node, defaultScope) {
   if (node.kind !== "call" || node.name !== "advance" || node.args.length !== 1) return null;
   const arg = node.args[0];
@@ -294,6 +295,7 @@ var propertyTip = (e) => {
   return lines.length ? lines.join("\n") : void 0;
 };
 var refOf = (e, defaultScope) => e.scope === defaultScope ? `@${e.name}` : `@${e.scope}.${e.name}`;
+var targetRefOf = (e) => `@${e.scope}.${e.name}`;
 var displayName = (e, defaultScope) => e.scope === defaultScope ? e.name : `${e.scope}.${e.name}`;
 function filterCatalogue(entries, filter = {}) {
   return entries.filter(
@@ -381,8 +383,14 @@ function openPopover(anchor, render, opts = {}) {
   container.append(pop);
   const a = anchor.getBoundingClientRect();
   const ph = pop.getBoundingClientRect();
-  let top = a.bottom + 4;
-  if (top + ph.height > window.innerHeight - 8 && a.top - ph.height - 4 > 8) top = a.top - ph.height - 4;
+  const GAP = 4;
+  const EDGE = 8;
+  const below = window.innerHeight - EDGE - (a.bottom + GAP);
+  const above = a.top - GAP - EDGE;
+  const flip = ph.height > below && above > below;
+  const room = flip ? above : below;
+  const top = flip ? a.top - Math.min(ph.height, above) - GAP : a.bottom + GAP;
+  if (ph.height > room) pop.style.maxHeight = `${Math.max(96, Math.round(room))}px`;
   let left = a.left;
   if (left + ph.width > window.innerWidth - 8) left = Math.max(8, window.innerWidth - 8 - ph.width);
   if (container === document.body) {
@@ -1082,7 +1090,7 @@ function seedClause(ctx) {
 function clauseMenu(ctx, anchor, onPick) {
   ctx.openPopover(anchor, (close) => {
     const wrap = el("div", "exed-menu");
-    wrap.append(el("div", "exed-menu-head", ["Add a clause"]));
+    wrap.append(el("div", "exed-menu-head", ["Add a condition"]));
     const add = (label, hint, make, disabled = false) => {
       const b = button(`exed-opt${disabled ? " disabled" : ""}`, "", () => {
         if (disabled) return;
@@ -1381,7 +1389,9 @@ function valueWizard(opts) {
   host.append(body);
   const choices = opts.expectedChoices?.length ? opts.expectedChoices : opts.expectedEnumValues;
   const isStage = opts.expectedType === "quality";
-  let kind = opts.expectedType === "number" ? "number" : opts.expectedType === "string" ? "text" : opts.expectedType === "boolean" ? "bool" : (opts.expectedType === "enum" || opts.expectedType === "quality") && choices?.length ? "enum" : "menu";
+  const flagsReady = opts.expectedType === "flags" && opts.expectedRef !== void 0;
+  let kind = opts.expectedType === "number" ? "number" : opts.expectedType === "string" ? "text" : opts.expectedType === "boolean" ? "bool" : (opts.expectedType === "enum" || opts.expectedType === "quality") && choices?.length ? "enum" : flagsReady ? "flags" : "menu";
+  let flagSign = "+";
   const draw = () => {
     body.replaceChildren();
     const other = () => button("exed-vwiz-other", "\u21A9 a different kind", () => {
@@ -1390,6 +1400,10 @@ function valueWizard(opts) {
     });
     switch (kind) {
       case "menu":
+        if (flagsReady) body.append(optBtn("Set or clear a flag\u2026", () => {
+          kind = "flags";
+          draw();
+        }));
         body.append(optBtn("A property\u2026", () => {
           kind = "property";
           draw();
@@ -1411,6 +1425,33 @@ function valueWizard(opts) {
           draw();
         }));
         break;
+      case "flags": {
+        const flags = opts.expectedFlags ?? [];
+        if (!flags.length) body.append(el("div", "exed-hint", ["This property declares no flag values yet."]));
+        else {
+          const signRow = el("div", "exed-field-row");
+          signRow.append(
+            button(`exed-opt${flagSign === "+" ? " sel" : ""}`, "\uFF0B set", () => {
+              flagSign = "+";
+              draw();
+            }),
+            button(`exed-opt${flagSign === "-" ? " sel" : ""}`, "\uFF0D clear", () => {
+              flagSign = "-";
+              draw();
+            })
+          );
+          body.append(signRow);
+          body.append(el("div", "exed-vwiz-note", [flagSign === "+" ? "Set a flag:" : "Clear a flag:"]));
+          const list = el("div", "exed-picker-list");
+          for (const f of flags) list.append(optBtn(`${flagSign} ${f}`, () => opts.onCommit(flagChangeSrc(opts.expectedRef, flagSign, f))));
+          body.append(list);
+        }
+        body.append(button("exed-vwiz-other", "\u21A9 a different kind (replaces every flag)", () => {
+          kind = "menu";
+          draw();
+        }));
+        break;
+      }
       case "property":
         body.append(propertyPicker(pickCtx, { onPick: (e) => opts.onCommit(refOf(e, opts.defaultScope)) }));
         body.append(other());
@@ -1449,6 +1490,10 @@ function isSelfAdvance(eff, defaultScope, dialect) {
     return false;
   }
 }
+function entryForTarget(catalogue, target, defaultScope) {
+  const want = normaliseRef(target, defaultScope);
+  return catalogue.find((e) => normaliseRef(`@${e.scope}.${e.name}`, defaultScope) === want);
+}
 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: [] }];
@@ -1537,6 +1582,11 @@ function mountEffectsEditor(host, opts) {
       // choicesOf, never a raw field: a quality's ladder lives in `stages`, and reading `enumValues`
       // here told the wizard the type and withheld the values.
       ...choicesOf(expected) ? { expectedChoices: choicesOf(expected) } : {},
+      // The flags step needs the target itself: its declared flags, and the
+      // qualified ref its set_flags(...) is written against. choicesOf stays
+      // out of it deliberately - flags are not a pick-one list, and a pinned
+      // test holds it to that.
+      ...expected?.type === "flags" ? { expectedRef: targetRefOf(expected), expectedFlags: expected.enumValues ?? [] } : {},
       onCommit: (src) => {
         onCommit(src);
         close();
@@ -1544,7 +1594,7 @@ function mountEffectsEditor(host, opts) {
       onCancel: close
     }), { container: opts.popoverContainer });
   };
-  const targetType = (target) => opts.catalogue.find((e) => refOf(e, defaultScope) === target)?.type;
+  const targetType = (target) => entryForTarget(opts.catalogue, target, defaultScope)?.type;
   const valueDisplay = (value, onChange, type, selfAdvanceRef) => {
     const sub = el("div", "exed-effect-value");
     const addTerm = type === "number" ? "arithmetic" : type === "boolean" ? "boolean" : void 0;
@@ -1611,10 +1661,10 @@ 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: initialValueFor(entry, defaultScope).src }));
+        commit(updateAt(effects, i, { target: targetRefOf(entry), value: initialValueFor(entry, defaultScope).src }));
       });
     }, "change the target property");
-    const targetEntry = opts.catalogue.find((e) => refOf(e, defaultScope) === eff.target);
+    const targetEntry = entryForTarget(opts.catalogue, eff.target, defaultScope);
     const tip = propertyTip(targetEntry);
     if (tip) targetBtn.title = tip;
     if (targetEntry && opts.propertyActions) {
@@ -1718,10 +1768,10 @@ function mountEffectsEditor(host, opts) {
       pickTarget(anchor, void 0, (entry) => {
         const { src, ask } = initialValueFor(entry, defaultScope);
         if (!ask) {
-          commit(addSet(effects, refOf(entry, defaultScope), src));
+          commit(addSet(effects, targetRefOf(entry), src));
           return;
         }
-        openValueWizard(anchor, entry, (chosen) => commit(addSet(effects, refOf(entry, defaultScope), chosen)));
+        openValueWizard(anchor, entry, (chosen) => commit(addSet(effects, targetRefOf(entry), chosen)));
       });
     }));
     if (opts.allowEmit !== false) {
@@ -1825,6 +1875,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, 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, propertyTip, 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, flagChangeSrc, flagDelta, flipContainerOp, formatNumber, getNodeAt, groupByScope, initialValueFor, insertSiblingClauseAt, isComparisonOp, isPlaceholderForOp, isWrappedInNot, issuesAt, lookup, mountEffectsEditor, mountExpressionEditor, moveAt, moveChildInContainer, needsParens, normaliseRef, notNode, numLit, opSwapGroup, pathKey, placeholderForOp, propertyTip, redirectDeleteForPlaceholderSibling, refOf, removeArgAt, removeAt, renderConditionPreview, renderEffectsPreview, rhsTypesFor, scopedVar, searchCatalogue, seedValueSrc, setArgAt, setNodeAt, strLit, targetRefOf, toggleContainerNot, toggleNotAt, updateAt, validateSource, valueWizard, wrapInNotAt };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map