@rohal12/spindle 0.52.5 → 0.52.6

package/src/components/macros/Set.tsx

@@ -1,36 +1,10 @@
 import { defineMacro } from '../../define-macro';
-import { MacroError } from './MacroError';
+import { useRunOnce } from './MacroError';
 
 defineMacro({
   name: 'set',
+  parameters: [{ name: 'code', type: 'expression', required: true }],
   render({ rawArgs }, ctx) {
-    const ran = ctx.hooks.useRef(false);
-    // Boxed: anything can be thrown, including null and other falsy values
-    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
-
-    if (!ran.current) {
-      ran.current = true;
-
-      try {
-        ctx.mutate(rawArgs);
-      } catch (err) {
-        failure.current = { error: err };
-        console.error(
-          `spindle: Error in {set ${rawArgs}}${ctx.sourceLocation()}:`,
-          err,
-        );
-      }
-    }
-
-    if (failure.current) {
-      return (
-        <MacroError
-          macro="set"
-          error={failure.current.error}
-        />
-      );
-    }
-
-    return null;
+    return useRunOnce('set', rawArgs, () => ctx.mutate(rawArgs));
   },
 });

package/src/components/macros/Switch.tsx

@@ -1,9 +1,32 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
+import type { Branch } from '../../markup/ast';
+
+/**
+ * The first {case} branch whose value equals `value`, else the {default}
+ * branch, else null. Throws what a case expression throws.
+ */
+function selectBranch(
+  value: unknown,
+  branches: Branch[],
+  evaluate: (expr: string) => unknown,
+): Branch | null {
+  let defaultBranch: Branch | null = null;
+  for (let i = 1; i < branches.length; i++) {
+    const branch = branches[i]!;
+    if (branch.rawArgs === '') {
+      defaultBranch = branch;
+    } else if (value === evaluate(branch.rawArgs)) {
+      return branch;
+    }
+  }
+  return defaultBranch;
+}
 
 defineMacro({
   name: 'switch',
   subMacros: ['case', 'default'],
+  parameters: [{ name: 'expression', type: 'expression', required: true }],
   merged: true,
   render({ rawArgs, branches = [] }, ctx) {
     let switchValue: unknown;
@@ -18,46 +41,22 @@ defineMacro({
       );
     }
 
-    let defaultBranch: (typeof branches)[number] | null = null;
-    for (let i = 1; i < branches.length; i++) {
-      const branch = branches[i]!;
-      if (branch.rawArgs === '') {
-        defaultBranch = branch;
-        continue;
-      }
-
-      try {
-        const caseValue = ctx.evaluate!(branch.rawArgs);
-        if (switchValue === caseValue) {
-          return <>{ctx.renderNodes(branch.children)}</>;
-        }
-      } catch (err) {
-        return (
-          <MacroError
-            macro="case"
-            error={err}
-          />
-        );
-      }
-    }
-
-    if (defaultBranch) {
-      return <>{ctx.renderNodes(defaultBranch.children)}</>;
+    let branch: Branch | null;
+    try {
+      branch = selectBranch(switchValue, branches, ctx.evaluate!);
+    } catch (err) {
+      return (
+        <MacroError
+          macro="case"
+          error={err}
+        />
+      );
     }
 
-    return null;
+    return branch && <>{ctx.renderNodes(branch.children)}</>;
   },
   text({ rawArgs, branches = [] }, ctx) {
-    const switchValue = ctx.evaluate(rawArgs);
-    let defaultBranch: (typeof branches)[number] | null = null;
-    for (let i = 1; i < branches.length; i++) {
-      const branch = branches[i]!;
-      if (branch.rawArgs === '') {
-        defaultBranch = branch;
-      } else if (switchValue === ctx.evaluate(branch.rawArgs)) {
-        return ctx.renderText(branch.children);
-      }
-    }
-    return defaultBranch ? ctx.renderText(defaultBranch.children) : '';
+    const branch = selectBranch(ctx.evaluate(rawArgs), branches, ctx.evaluate);
+    return branch ? ctx.renderText(branch.children) : '';
   },
 });

package/src/components/macros/Textarea.tsx

@@ -1,29 +1,3 @@
-import { defineMacro } from '../../define-macro';
+import { defineInputMacro } from './input-macro';
 
-defineMacro({
-  name: 'textarea',
-  storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { placeholder } = ctx.parseVarArgs(rawArgs);
-
-    ctx.useAction({
-      type: 'textarea',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
-      label: placeholder || ctx.varName!,
-      variable: ctx.varName,
-      value: ctx.value,
-      perform: (v) => ctx.setValue!(v !== undefined ? String(v) : ''),
-    });
-
-    return (
-      <textarea
-        id={ctx.id}
-        class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
-        placeholder={placeholder}
-        onInput={(e) => ctx.setValue!((e.target as HTMLTextAreaElement).value)}
-      />
-    );
-  },
-});
+defineInputMacro('textarea');

package/src/components/macros/Textbox.tsx

@@ -1,30 +1,3 @@
-import { defineMacro } from '../../define-macro';
+import { defineInputMacro } from './input-macro';
 
-defineMacro({
-  name: 'textbox',
-  storeVar: true,
-  render({ rawArgs }, ctx) {
-    const { placeholder } = ctx.parseVarArgs(rawArgs);
-
-    ctx.useAction({
-      type: 'textbox',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
-      label: placeholder || ctx.varName!,
-      variable: ctx.varName,
-      value: ctx.value,
-      perform: (v) => ctx.setValue!(v !== undefined ? String(v) : ''),
-    });
-
-    return (
-      <input
-        type="text"
-        id={ctx.id}
-        class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
-        placeholder={placeholder}
-        onInput={(e) => ctx.setValue!((e.target as HTMLInputElement).value)}
-      />
-    );
-  },
-});
+defineInputMacro('textbox', 'text');

package/src/components/macros/Type.tsx

@@ -1,13 +1,13 @@
-import { parseDelay } from '../../utils/parse-delay';
 import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'type',
   block: true,
   interpolate: true,
-  render({ rawArgs, children = [] }, ctx) {
+  parameters: [{ name: 'delay', type: 'delay', required: true }],
+  render({ children = [] }, ctx) {
     const { useState, useEffect, useRef } = ctx.hooks;
-    const speed = parseDelay(rawArgs);
+    const speed = ctx.args.delay ?? 0;
     const containerRef = useRef<HTMLSpanElement>(null);
     const [totalChars, setTotalChars] = useState(0);
     const [visibleChars, setVisibleChars] = useState(0);

package/src/components/macros/Unset.tsx

@@ -1,52 +1,29 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
-import { MacroError } from './MacroError';
+import { useRunOnce } from './MacroError';
 
 defineMacro({
   name: 'unset',
+  parameters: [{ name: 'variable', type: 'variable', required: true }],
   render({ rawArgs }, ctx) {
-    const ran = ctx.hooks.useRef(false);
-    // Boxed: anything can be thrown, including null and other falsy values
-    const failure = ctx.hooks.useRef<{ error: unknown } | null>(null);
-
-    if (!ran.current) {
-      ran.current = true;
+    return useRunOnce('unset', rawArgs, () => {
       const state = useStoryStore.getState();
-      const name = rawArgs.trim();
+      const name = ctx.args.variable ?? '';
 
-      try {
-        if (name.startsWith('$')) {
-          state.deleteVariable(name.slice(1));
-        } else if (name.startsWith('_')) {
-          state.deleteTemporary(name.slice(1));
-        } else if (name.startsWith('%')) {
-          state.deleteTransient(name.slice(1));
-        } else if (name.startsWith('@')) {
-          // Throws outside a locals scope ({for}, widget, {link}, {button})
-          ctx.update(name.slice(1), undefined);
-        } else {
-          throw new Error(
-            `{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
-          );
-        }
-      } catch (err) {
-        failure.current = { error: err };
-        console.error(
-          `spindle: Error in {unset ${rawArgs}}${ctx.sourceLocation()}:`,
-          err,
+      if (name.startsWith('$')) {
+        state.deleteVariable(name.slice(1));
+      } else if (name.startsWith('_')) {
+        state.deleteTemporary(name.slice(1));
+      } else if (name.startsWith('%')) {
+        state.deleteTransient(name.slice(1));
+      } else if (name.startsWith('@')) {
+        // Throws outside a locals scope ({for}, widget, {link}, {button})
+        ctx.update(name.slice(1), undefined);
+      } else {
+        throw new Error(
+          `{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`,
         );
       }
-    }
-
-    if (failure.current) {
-      return (
-        <MacroError
-          macro="unset"
-          error={failure.current.error}
-        />
-      );
-    }
-
-    return null;
+    });
   },
 });

package/src/components/macros/Watch.tsx

@@ -1,99 +1,30 @@
 import { defineMacro } from '../../define-macro';
 import { addMacroTrigger, removeTrigger } from '../../triggers';
-import type { WatchOptions } from '../../triggers';
-import { isWhitespace, readQuoted, readWholeQuoted } from './arg-utils';
-
-const WORD_RE = /\w+/y;
-const DIGITS_RE = /\d+/y;
-
-/** Match the sticky regex `re` at `pos`, returning the matched text. */
-function matchAt(re: RegExp, src: string, pos: number): string | null {
-  re.lastIndex = pos;
-  return re.exec(src)?.[0] ?? null;
-}
-
-/**
- * Parse `{watch "condition" keyword value …}`: a quoted condition followed
- * by keyword options (`goto "X"`, `dialog "X"`, `run "X"`, `name "X"`,
- * `priority N`, `once`). Quoted strings accept `\"`, `\'` and `\\` escapes.
- * Returns `null` when the arguments do not start with a quoted condition.
- */
-export function parseWatchArgs(
-  rawArgs: string,
-): { condition: string; options: WatchOptions } | null {
-  const raw = rawArgs.trim();
-  const cond = readQuoted(raw, 0);
-  if (!cond) return null;
-
-  const options: WatchOptions = {};
-  let i = cond.end;
-  while (i < raw.length) {
-    const key = matchAt(WORD_RE, raw, i);
-    if (!key) {
-      // Skip whitespace and stray characters, or a stray quoted string.
-      i = readQuoted(raw, i)?.end ?? i + 1;
-      continue;
-    }
-    i += key.length;
-
-    // A value is a quoted string or a digit run, after whitespace.
-    let val: string | undefined;
-    let j = i;
-    while (j < raw.length && isWhitespace(raw[j]!)) j++;
-    if (j > i) {
-      const quoted = readQuoted(raw, j);
-      const digits = quoted ? null : matchAt(DIGITS_RE, raw, j);
-      if (quoted) {
-        val = quoted.value;
-        i = quoted.end;
-      } else if (digits) {
-        val = digits;
-        i = j + digits.length;
-      }
-    }
-
-    switch (key) {
-      case 'goto':
-        options.goto = val;
-        break;
-      case 'dialog':
-        options.dialog = val;
-        break;
-      case 'run':
-        options.run = val;
-        break;
-      case 'name':
-        options.name = val;
-        break;
-      case 'priority':
-        options.priority = val ? Number(val) : 0;
-        break;
-      case 'once':
-        options.once = true;
-        break;
-    }
-  }
-
-  return { condition: cond.value, options };
-}
-
-/**
- * Parse the watcher name of `{unwatch "name"}`: a quoted string, with the
- * same escapes as `{watch}`, or a bare name.
- */
-export function parseUnwatchName(rawArgs: string): string {
-  const raw = rawArgs.trim();
-  return readWholeQuoted(raw) ?? raw.replace(/^['"]|['"]$/g, '');
-}
 
 defineMacro({
   name: 'watch',
-  render(props, ctx) {
+  // {watch "condition" goto "X" dialog "X" run "X" name "X" priority N once}
+  parameters: [
+    { name: 'condition', type: 'string', required: true },
+    {
+      name: 'options',
+      type: 'options',
+      parameters: [
+        { name: 'goto', type: 'string' },
+        { name: 'dialog', type: 'string' },
+        { name: 'run', type: 'string' },
+        { name: 'name', type: 'string' },
+        { name: 'priority', type: 'number' },
+        { name: 'once', type: 'flag' },
+      ],
+    },
+  ],
+  render(_props, ctx) {
     const { hooks } = ctx;
 
-    const parsed = parseWatchArgs(props.rawArgs);
-    if (!parsed) return null;
-    const { condition, options } = parsed;
+    // Without a quoted condition there is nothing to watch.
+    const { condition, options } = ctx.args;
+    if (condition === undefined) return null;
 
     // Register during render (like {set}) — triggers survive navigation
     // and are cleaned up via resetTriggers() on restart or {unwatch}.
@@ -110,8 +41,9 @@ defineMacro({
 
 defineMacro({
   name: 'unwatch',
-  render(props, ctx) {
-    const name = parseUnwatchName(props.rawArgs);
+  parameters: [{ name: 'name', type: 'text', required: true }],
+  render(_props, ctx) {
+    const name = ctx.args.name ?? '';
 
     const ran = ctx.hooks.useRef(false);
     if (!ran.current) {

package/src/components/macros/WidgetInvocation.tsx

@@ -1,28 +1,12 @@
-import {
-  useContext,
-  useState,
-  useCallback,
-  useRef,
-  useMemo,
-} from 'preact/hooks';
-import {
-  LocalsValuesContext,
-  LocalsUpdateContext,
-  NobrContext,
-  InlineContext,
-  WidgetChildrenContext,
-  RawTextContext,
-  renderNodes,
-} from '../../markup/render';
+import { useMemo } from 'preact/hooks';
+import { WidgetChildrenContext, 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';
+import { createNamespace } from '../../utils/namespace';
+import { useRenderOptions } from '../../hooks/use-render-options';
+import { LocalsScope } from './locals-scope';
 
 export { splitArgs };
 
@@ -33,60 +17,14 @@ interface WidgetInvocationProps {
   invocationChildren?: ASTNode[];
 }
 
-function WidgetBody({
-  body,
-  parentValues,
-  ownKeys,
-}: {
-  body: ASTNode[];
-  parentValues: Record<string, unknown>;
-  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(
-    () => createNamespace(parentValues, ownKeys, localMutations),
-    [parentValues, ownKeys, localMutations],
-  );
-
-  const valuesRef = useRef(localState);
-  valuesRef.current = localState;
-
-  const getValues = useCallback(() => valuesRef.current, []);
-  const update = useCallback((key: string, value: unknown) => {
-    // 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.
-    checkVariableName(key, `@${key}`);
-    valuesRef.current = withEntry(valuesRef.current, key, value);
-    setLocalMutations((prev) => ({ ...prev, [key]: value }));
-  }, []);
-  const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
-
-  return (
-    <LocalsUpdateContext.Provider value={updater}>
-      <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(body, { nobr, inline, raw, locals: localState })}
-      </LocalsValuesContext.Provider>
-    </LocalsUpdateContext.Provider>
-  );
-}
-
 export function WidgetInvocation({
   body,
   params,
   rawArgs,
   invocationChildren,
 }: WidgetInvocationProps) {
-  const parentValues = useContext(LocalsValuesContext);
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
-  const raw = useContext(RawTextContext);
+  const renderOptions = useRenderOptions();
+  const parentValues = renderOptions.locals;
   const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
     useMergedLocals();
 
@@ -97,7 +35,7 @@ export function WidgetInvocation({
   if (params.length === 0) {
     return (
       <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, { nobr, inline, raw, locals: parentValues })}
+        {renderNodes(body, renderOptions)}
       </WidgetChildrenContext.Provider>
     );
   }
@@ -137,7 +75,7 @@ export function WidgetInvocation({
 
   return (
     <WidgetChildrenContext.Provider value={childrenValue}>
-      <WidgetBody
+      <LocalsScope
         body={body}
         parentValues={parentValues}
         ownKeys={ownKeys}

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

@@ -9,6 +9,7 @@ import {
   WidgetChildrenContext,
 } from '../../markup/render';
 import type { ASTNode } from '../../markup/ast';
+import { useRenderOptions } from '../../hooks/use-render-options';
 import { liveLocalsView } from '../../utils/live-locals';
 import { runWithCommittedMutations } from '../../execute-mutation';
 import { RepeatContext } from './Repeat';
@@ -35,8 +36,7 @@ import { DialogCloseContext } from '../PassageDialog';
  */
 export function useDetachedBody(): (children: ASTNode[]) => void {
   const updater = useContext(LocalsUpdateContext);
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
+  const { nobr, inline } = useRenderOptions();
   const widgetChildren = useContext(WidgetChildrenContext);
   const repeat = useContext(RepeatContext);
   const closeDialog = useContext(DialogCloseContext);

package/src/components/macros/input-macro.ts

@@ -0,0 +1,48 @@
+import { h } from 'preact';
+import { defineMacro } from '../../define-macro';
+
+/**
+ * Define a text input macro, `{name $var "placeholder"}`: an `<input>` of
+ * `type` (or, without one, a `<textarea>`) bound to the story variable.
+ * `toValue` turns what the reader types, or an automation action's value
+ * (`undefined` when it has none), into the variable's value: by default,
+ * the text.
+ */
+export function defineInputMacro(
+  name: 'textbox' | 'numberbox' | 'textarea',
+  type?: 'text' | 'number',
+  toValue = (input: unknown): unknown =>
+    input !== undefined ? String(input) : '',
+): void {
+  defineMacro({
+    name,
+    storeVar: true,
+    parameters: [
+      { name: 'variable', type: 'variable', required: true },
+      { name: 'placeholder', type: 'string' },
+    ],
+    render(_props, ctx) {
+      const placeholder = ctx.args.placeholder ?? '';
+
+      ctx.useAction({
+        type: name,
+        key: `$${ctx.varName}`,
+        authorId: ctx.id,
+        label: placeholder || ctx.varName!,
+        variable: ctx.varName,
+        value: ctx.value,
+        perform: (v) => ctx.setValue!(toValue(v)),
+      });
+
+      return h(type ? 'input' : 'textarea', {
+        type,
+        id: ctx.id,
+        class: ctx.cls,
+        value: ctx.value == null ? '' : String(ctx.value),
+        placeholder,
+        onInput: (e: Event) =>
+          ctx.setValue!(toValue((e.target as HTMLInputElement).value)),
+      });
+    },
+  });
+}

package/src/components/macros/locals-scope.tsx

@@ -0,0 +1,60 @@
+import { useState, useCallback, useRef, useMemo } from 'preact/hooks';
+import {
+  LocalsValuesContext,
+  LocalsUpdateContext,
+  renderNodes,
+} from '../../markup/render';
+import type { ASTNode } from '../../markup/ast';
+import { useRenderOptions } from '../../hooks/use-render-options';
+import {
+  checkVariableName,
+  createNamespace,
+  withEntry,
+} from '../../utils/namespace';
+
+/**
+ * Render `body` in a new locals scope: the locals of `parentValues`, with
+ * `ownKeys` (an iteration's loop variables, a widget's parameters) on top.
+ * Locals the body assigns are kept in this scope.
+ */
+export function LocalsScope({
+  body,
+  parentValues,
+  ownKeys,
+}: {
+  body: ASTNode[];
+  parentValues: Record<string, unknown>;
+  ownKeys: Record<string, unknown>;
+}) {
+  const options = useRenderOptions();
+  const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
+    {},
+  );
+
+  const localState = useMemo(
+    () => createNamespace(parentValues, ownKeys, localMutations),
+    [parentValues, ownKeys, localMutations],
+  );
+
+  const valuesRef = useRef(localState);
+  valuesRef.current = localState;
+
+  const getValues = useCallback(() => valuesRef.current, []);
+  const update = useCallback((key: string, value: unknown) => {
+    // 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.
+    checkVariableName(key, `@${key}`);
+    valuesRef.current = withEntry(valuesRef.current, key, value);
+    setLocalMutations((prev) => ({ ...prev, [key]: value }));
+  }, []);
+  const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
+
+  return (
+    <LocalsUpdateContext.Provider value={updater}>
+      <LocalsValuesContext.Provider value={localState}>
+        {renderNodes(body, { ...options, locals: localState })}
+      </LocalsValuesContext.Provider>
+    </LocalsUpdateContext.Provider>
+  );
+}