@rohal12/spindle 0.51.3 → 0.52.0

package/src/components/macros/WidgetInvocation.tsx

@@ -9,12 +9,22 @@ import {
   LocalsValuesContext,
   LocalsUpdateContext,
   NobrContext,
+  InlineContext,
   WidgetChildrenContext,
+  RawTextContext,
   renderNodes,
 } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { evaluate } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
+import { splitArgs } from './arg-utils';
+import {
+  checkVariableName,
+  createNamespace,
+  withEntry,
+} from '../../utils/namespace';
+
+export { splitArgs };
 
 interface WidgetInvocationProps {
   body: ASTNode[];
@@ -23,159 +33,6 @@ interface WidgetInvocationProps {
   invocationChildren?: ASTNode[];
 }
 
-/**
- * Check whether a whitespace-delimited token looks like a standalone value
- * (not an operator or partial expression).
- */
-function isStandaloneValue(token: string): boolean {
-  const first = token[0]!;
-  // Quoted string
-  if (first === '"' || first === "'" || first === '`') return true;
-  // Variable ($var, _var, @var)
-  if (first === '$' || first === '_' || first === '@' || first === '%')
-    return true;
-  // Number literal
-  if (/\d/.test(first)) return true;
-  // Signed number (-1, +2)
-  if (
-    (first === '-' || first === '+') &&
-    token.length > 1 &&
-    /\d/.test(token[1]!)
-  )
-    return true;
-  // Grouped expression or collection literal
-  if (first === '(' || first === '[' || first === '{') return true;
-  // Boolean / null / undefined
-  if (/^(true|false|null|undefined)$/.test(token)) return true;
-  // Negation (!$flag, !true)
-  if (first === '!' && token.length > 1) return true;
-  return false;
-}
-
-/**
- * Try to split a raw string on whitespace at depth 0 (respecting quotes,
- * parentheses, brackets, and braces). Each resulting token must pass
- * `isStandaloneValue()` or the split is rejected and `null` is returned.
- */
-function trySplitOnWhitespace(raw: string): string[] | null {
-  const args: string[] = [];
-  let current = '';
-  let depth = 0;
-  let inString: string | null = null;
-
-  for (let i = 0; i < raw.length; i++) {
-    const ch = raw[i]!;
-
-    if (inString) {
-      current += ch;
-      if (ch === inString && raw[i - 1] !== '\\') inString = null;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'" || ch === '`') {
-      inString = ch;
-      current += ch;
-      continue;
-    }
-
-    if (ch === '(' || ch === '[' || ch === '{') {
-      depth++;
-      current += ch;
-      continue;
-    }
-
-    if (ch === ')' || ch === ']' || ch === '}') {
-      depth--;
-      current += ch;
-      continue;
-    }
-
-    if (/\s/.test(ch) && depth === 0) {
-      if (current) {
-        args.push(current);
-        current = '';
-      }
-      continue;
-    }
-
-    current += ch;
-  }
-
-  if (current) args.push(current);
-
-  // Need 2+ tokens
-  if (args.length < 2) return null;
-
-  // Every token must be a standalone value (not an operator)
-  for (const arg of args) {
-    if (!isStandaloneValue(arg)) return null;
-  }
-
-  return args;
-}
-
-/**
- * Split rawArgs by commas, respecting parentheses, brackets, braces, and
- * strings. When no top-level commas are present, also supports adjacent quoted
- * string literals separated by whitespace (e.g. `"Label" "target"`).
- */
-export function splitArgs(raw: string): string[] {
-  const args: string[] = [];
-  let current = '';
-  let depth = 0;
-  let inString: string | null = null;
-  let hasComma = false;
-
-  for (let i = 0; i < raw.length; i++) {
-    const ch = raw[i]!;
-
-    if (inString) {
-      current += ch;
-      if (ch === inString && raw[i - 1] !== '\\') inString = null;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'" || ch === '`') {
-      inString = ch;
-      current += ch;
-      continue;
-    }
-
-    if (ch === '(' || ch === '[' || ch === '{') {
-      depth++;
-      current += ch;
-      continue;
-    }
-
-    if (ch === ')' || ch === ']' || ch === '}') {
-      depth--;
-      current += ch;
-      continue;
-    }
-
-    if (ch === ',' && depth === 0) {
-      hasComma = true;
-      args.push(current.trim());
-      current = '';
-      continue;
-    }
-
-    current += ch;
-  }
-
-  const last = current.trim();
-  if (last) args.push(last);
-
-  // If no commas were found and we got a single expression, try splitting
-  // on whitespace at depth 0 (e.g. "Label" "target", $var "text", $x $y).
-  if (!hasComma && args.length === 1) {
-    const split = trySplitOnWhitespace(args[0]!);
-    if (split) return split;
-  }
-
-  return args;
-}
-
 function WidgetBody({
   body,
   parentValues,
@@ -186,12 +43,14 @@ function WidgetBody({
   ownKeys: Record<string, unknown>;
 }) {
   const nobr = useContext(NobrContext);
+  const inline = useContext(InlineContext);
+  const raw = useContext(RawTextContext);
   const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
     {},
   );
 
   const localState = useMemo(
-    () => ({ ...parentValues, ...ownKeys, ...localMutations }),
+    () => createNamespace(parentValues, ownKeys, localMutations),
     [parentValues, ownKeys, localMutations],
   );
 
@@ -203,7 +62,8 @@ function WidgetBody({
     // Apply synchronously so later macros in the same render pass (e.g. a
     // second {set}) read the new value via getValues(); the state update
     // then re-renders consumers of LocalsValuesContext.
-    valuesRef.current = { ...valuesRef.current, [key]: value };
+    checkVariableName(key, `@${key}`);
+    valuesRef.current = withEntry(valuesRef.current, key, value);
     setLocalMutations((prev) => ({ ...prev, [key]: value }));
   }, []);
   const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
@@ -211,7 +71,7 @@ function WidgetBody({
   return (
     <LocalsUpdateContext.Provider value={updater}>
       <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(body, { nobr, locals: localState })}
+        {renderNodes(body, { nobr, inline, raw, locals: localState })}
       </LocalsValuesContext.Provider>
     </LocalsUpdateContext.Provider>
   );
@@ -225,6 +85,8 @@ export function WidgetInvocation({
 }: WidgetInvocationProps) {
   const parentValues = useContext(LocalsValuesContext);
   const nobr = useContext(NobrContext);
+  const inline = useContext(InlineContext);
+  const raw = useContext(RawTextContext);
   const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
     useMergedLocals();
 
@@ -235,7 +97,7 @@ export function WidgetInvocation({
   if (params.length === 0) {
     return (
       <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, { nobr, locals: parentValues })}
+        {renderNodes(body, { nobr, inline, raw, locals: parentValues })}
       </WidgetChildrenContext.Provider>
     );
   }
@@ -263,7 +125,7 @@ export function WidgetInvocation({
   }
 
   const ownKeys = useMemo(() => {
-    const keys: Record<string, unknown> = {};
+    const keys = createNamespace();
     for (let i = 0; i < params.length; i++) {
       keys[params[i]!.startsWith('@') ? params[i]!.slice(1) : params[i]!] =
         values[i];

package/src/components/macros/arg-utils.ts

@@ -0,0 +1,226 @@
+/**
+ * Shared helpers for macros that split or read their raw argument text by
+ * hand. Their lexical model is the expression lexer's (`js-lexer.ts`):
+ * string, template and regex literals and comments are opaque (a backslash
+ * inside a literal escapes the character after it, and `${…}` parts of a
+ * template are code), `/` opens a regex only where an operand is expected,
+ * and `(`/`[`/`{` nest.
+ */
+import { lexJs, lexTemplate, scanStringLiteral } from '../../js-lexer';
+
+/** True for a whitespace character. */
+export function isWhitespace(ch: string): boolean {
+  return /\s/.test(ch);
+}
+
+function isOpener(ch: string): boolean {
+  return ch === '(' || ch === '[' || ch === '{';
+}
+
+function isCloser(ch: string): boolean {
+  return ch === ')' || ch === ']' || ch === '}';
+}
+
+/**
+ * Given the index of an opening quote (`"`, `'` or a backtick), return the
+ * index just past its closing quote, or `src.length` if it is unterminated.
+ * A backslash escapes the character after it, so a quote preceded by an even
+ * run of backslashes still closes the string and one preceded by an odd run
+ * does not. Inside a template literal, `${…}` interpolations are lexed as
+ * code, so quotes, backticks, braces and regexes inside them do not end it.
+ */
+export function skipString(src: string, start: number): number {
+  return src[start] === '`'
+    ? lexTemplate(src, start)
+    : scanStringLiteral(src, start).end;
+}
+
+/**
+ * Undo the escapes allowed in a literal quoted macro argument: `\"`, `\'`
+ * and `\\` become `"`, `'` and `\`. Other backslash sequences (`\n`, `\d`)
+ * are kept as written, so code and regex text inside the string survive.
+ */
+export function unescapeQuoted(body: string): string {
+  return body.replace(/\\(["'\\])/g, '$1');
+}
+
+/**
+ * Read the `"…"` or `'…'` string whose opening quote is at `start`.
+ * Returns its unescaped value and the index just past the closing quote, or
+ * `null` if there is no such quote at `start` or the string is unterminated.
+ */
+export function readQuoted(
+  src: string,
+  start: number,
+): { value: string; end: number } | null {
+  const quote = src[start];
+  if (quote !== '"' && quote !== "'") return null;
+  const { end, closed } = scanStringLiteral(src, start);
+  if (!closed) return null;
+  return { value: unescapeQuoted(src.slice(start + 1, end - 1)), end };
+}
+
+/**
+ * The unescaped value of `src` when it is exactly one `"…"` or `'…'` string
+ * (as with `readQuoted`), otherwise `null`.
+ */
+export function readWholeQuoted(src: string): string | null {
+  const quoted = readQuoted(src, 0);
+  return quoted && quoted.end === src.length ? quoted.value : null;
+}
+
+/**
+ * Strip an optional quote from each end of an unquoted-or-loosely-quoted
+ * argument (`"Red`, `Red'`), leaving at least one character. This is the
+ * lenient fallback for labels that are not one well-formed quoted string.
+ */
+export function stripLooseQuotes(src: string): string {
+  return /^["']?(.+?)["']?$/s.exec(src)?.[1] ?? src;
+}
+
+/** An operator character, or an operator keyword, at the end of code. */
+const TRAILING_OPERATOR_RE =
+  /(?:[-+*/%&|^!~=<>?:,.]|(?:^|[^\w$@.])(?:typeof|void|new|delete|in|instanceof|await|yield))$/;
+
+/**
+ * Whether `src` ends with an operator that still needs an operand (`$a +`,
+ * `$a+`, `$x ==`, `typeof`), so it cannot be a complete value on its own.
+ * Only code counts: the closing `/` of a regex literal is not division, a
+ * variable reference (`$a`, `%name`, ...) is an operand, trailing comments are skipped,
+ * and a postfix `++` or `--` completes its operand.
+ */
+export function endsWithOperator(src: string): boolean {
+  // Index just past the last code token, or -1 when a literal or transient
+  // reference ends the source.
+  let end = -1;
+  lexJs(src, {
+    code(ch, i, nesting) {
+      if (nesting === 0 && !isWhitespace(ch)) end = i + 1;
+    },
+    literal(text, _i, nesting) {
+      const comment = text.startsWith('//') || text.startsWith('/*');
+      if (nesting === 0 && !comment) end = -1;
+    },
+    variable(_sigil, _name, _i, nesting) {
+      if (nesting === 0) end = -1;
+    },
+  });
+  if (end < 0) return false;
+  const code = src.slice(0, end);
+  if (/(?:\+\+|--)$/.test(code)) return false;
+  return TRAILING_OPERATOR_RE.test(code);
+}
+
+/**
+ * Indices of the characters in `src` that satisfy `isSeparator` and sit at
+ * depth 0: in code outside string, template and regex literals and comments,
+ * and outside `()`, `[]` and `{}` pairs.
+ */
+export function topLevelIndices(
+  src: string,
+  isSeparator: (ch: string) => boolean,
+): number[] {
+  const indices: number[] = [];
+  let depth = 0;
+  lexJs(src, {
+    code(ch, i, nesting) {
+      if (nesting > 0) return; // inside a template interpolation
+      if (isOpener(ch)) depth++;
+      else if (isCloser(ch)) depth--;
+      else if (depth === 0 && isSeparator(ch)) indices.push(i);
+    },
+  });
+  return indices;
+}
+
+/**
+ * Split `src` at every depth-0 separator (see `topLevelIndices`). Segments
+ * are returned as written, untrimmed, and empty segments are kept, so
+ * `n` separators always give `n + 1` segments.
+ */
+export function splitTopLevel(
+  src: string,
+  isSeparator: (ch: string) => boolean,
+): string[] {
+  const segments: string[] = [];
+  let from = 0;
+  for (const i of topLevelIndices(src, isSeparator)) {
+    segments.push(src.slice(from, i));
+    from = i + 1;
+  }
+  segments.push(src.slice(from));
+  return segments;
+}
+
+/**
+ * Check whether a whitespace-delimited token looks like a standalone value
+ * (not an operator or partial expression): it starts like a value and does
+ * not end with an operator still waiting for its operand.
+ */
+function isStandaloneValue(token: string): boolean {
+  return startsLikeValue(token) && !endsWithOperator(token);
+}
+
+function startsLikeValue(token: string): boolean {
+  const first = token[0]!;
+  // Quoted string
+  if (first === '"' || first === "'" || first === '`') return true;
+  // Variable ($var, _var, @var, %var), but not the modulo operator in `$a % 2`
+  if (/^[$_@]\w|^%[A-Za-z_]/.test(token)) return true;
+  // Number literal
+  if (/\d/.test(first)) return true;
+  // Signed number (-1, +2)
+  if (
+    (first === '-' || first === '+') &&
+    token.length > 1 &&
+    /\d/.test(token[1]!)
+  )
+    return true;
+  // Grouped expression or collection literal
+  if (first === '(' || first === '[' || first === '{') return true;
+  // Boolean / null / undefined, alone or leading an expression (true||$x)
+  if (/^(?:true|false|null|undefined)(?![\w$])/.test(token)) return true;
+  // Negation (!$flag, !true), but not the operators != and !==
+  if (first === '!' && token.length > 1 && token[1] !== '=') return true;
+  return false;
+}
+
+/**
+ * Try to split a raw string on whitespace at depth 0 (respecting strings,
+ * template literals, parentheses, brackets, and braces). Each resulting token
+ * must pass `isStandaloneValue()` or the split is rejected and `null` is
+ * returned.
+ */
+function trySplitOnWhitespace(raw: string): string[] | null {
+  const args = splitTopLevel(raw, isWhitespace).filter(Boolean);
+
+  // Need 2+ tokens
+  if (args.length < 2) return null;
+
+  // Every token must be a standalone value (not an operator)
+  for (const arg of args) {
+    if (!isStandaloneValue(arg)) return null;
+  }
+
+  return args;
+}
+
+/**
+ * Split rawArgs by commas, respecting parentheses, brackets, braces, and
+ * strings. When no top-level commas are present, also supports adjacent quoted
+ * string literals separated by whitespace (e.g. `"Label" "target"`).
+ */
+export function splitArgs(raw: string): string[] {
+  const args = splitTopLevel(raw, (ch) => ch === ',').map((a) => a.trim());
+  const hasComma = args.length > 1;
+  if (args[args.length - 1] === '') args.pop();
+
+  // If no commas were found and we got a single expression, try splitting
+  // on whitespace at depth 0 (e.g. "Label" "target", $var "text", $x $y).
+  if (!hasComma && args.length === 1) {
+    const split = trySplitOnWhitespace(args[0]!);
+    if (split) return split;
+  }
+
+  return args;
+}

package/src/components/macros/detached-body.tsx

@@ -0,0 +1,68 @@
+import { render } from 'preact';
+import { useContext } from 'preact/hooks';
+import {
+  renderNodes,
+  LocalsUpdateContext,
+  LocalsValuesContext,
+  NobrContext,
+  InlineContext,
+  WidgetChildrenContext,
+} from '../../markup/render';
+import type { ASTNode } from '../../markup/ast';
+import { liveLocalsView } from '../../utils/live-locals';
+import { runWithCommittedMutations } from '../../execute-mutation';
+import { RepeatContext } from './Repeat';
+import { DialogCloseContext } from '../PassageDialog';
+
+/**
+ * Return a function that runs a macro body once, outside the passage tree:
+ * it renders `children` into a detached node, so the body's macros ({set},
+ * {if}, {goto}, ...) fire their side effects through the normal Preact
+ * pipeline, then unmounts it. Used by {button} and {link} on click.
+ *
+ * A detached render starts with no contexts, so the hook captures the ones
+ * the owning macro sees and provides them again: the locals scope (read
+ * through a live view, so a local assigned earlier in the body is visible),
+ * nobr/inline rendering, the enclosing block widget's {@children}, the
+ * enclosing {repeat}'s {stop} and the enclosing dialog's close callback.
+ * The body then behaves as if it rendered in place.
+ *
+ * The body's macros read story state from the store. Run from mutation code
+ * (Story.performAction, a click the code dispatches), it runs in program
+ * order: the code's writes so far are committed first, so the body sees
+ * them, and the code goes on from the state the body leaves (see
+ * runWithCommittedMutations).
+ */
+export function useDetachedBody(): (children: ASTNode[]) => void {
+  const updater = useContext(LocalsUpdateContext);
+  const nobr = useContext(NobrContext);
+  const inline = useContext(InlineContext);
+  const widgetChildren = useContext(WidgetChildrenContext);
+  const repeat = useContext(RepeatContext);
+  const closeDialog = useContext(DialogCloseContext);
+
+  const run = (children: ASTNode[]) => {
+    const locals = liveLocalsView(updater.getValues);
+    const container = document.createElement('div');
+    render(
+      <LocalsUpdateContext.Provider value={updater}>
+        <LocalsValuesContext.Provider value={locals}>
+          <NobrContext.Provider value={nobr}>
+            <InlineContext.Provider value={inline}>
+              <WidgetChildrenContext.Provider value={widgetChildren}>
+                <RepeatContext.Provider value={repeat}>
+                  <DialogCloseContext.Provider value={closeDialog}>
+                    {renderNodes(children, { nobr, inline, locals })}
+                  </DialogCloseContext.Provider>
+                </RepeatContext.Provider>
+              </WidgetChildrenContext.Provider>
+            </InlineContext.Provider>
+          </NobrContext.Provider>
+        </LocalsValuesContext.Provider>
+      </LocalsUpdateContext.Provider>,
+      container,
+    );
+    render(null, container);
+  };
+  return (children) => runWithCommittedMutations(() => run(children));
+}

package/src/components/macros/option-utils.ts

@@ -1,17 +1,21 @@
 import type { ASTNode } from '../../markup/ast';
+import { readWholeQuoted } from './arg-utils';
 
 export function parseVarArgs(rawArgs: string): {
   varName: string;
   placeholder: string;
 } {
-  const match = rawArgs.match(
-    /^\s*(["']?\$[\w.]+["']?)\s*(?:["'](.*)["'])?\s*$/,
-  );
+  // `s`: a quoted placeholder may span lines.
+  const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/s);
   if (!match) {
     return { varName: rawArgs.trim(), placeholder: '' };
   }
   const varName = match[1]!.replace(/["']/g, '');
-  const placeholder = match[2] || '';
+  // A quoted placeholder accepts \" \' and \\ escapes.
+  const quoted = match[2];
+  const placeholder = quoted
+    ? (readWholeQuoted(quoted) ?? quoted.slice(1, -1))
+    : '';
   return { varName, placeholder };
 }
 
@@ -24,7 +28,8 @@ export function extractOptions(children: ASTNode[]): string[] {
     if (node.type === 'macro' && node.name === 'option') {
       const raw = node.rawArgs.trim();
       // Strip surrounding quotes so {option "Long Sword"} gives "Long Sword"
-      const stripped = raw.replace(/^(["'])(.+)\1$/, '$2');
+      const stripped =
+        readWholeQuoted(raw) ?? raw.replace(/^(["'])(.+)\1$/s, '$2');
       options.push(stripped);
     }
   }