@rohal12/spindle 0.52.6 → 0.52.8

package/src/expression.ts

@@ -132,7 +132,7 @@ export function previousPassage(): Passage | undefined {
  * visited()/rendered() and their has-forms, counting in the counters
  * `counts()` returns. A missing name means the current passage.
  */
-export function countQueries(counts: () => Counts) {
+function countQueries(counts: () => Counts) {
   const count = (name?: string): number =>
     countOf(counts(), name ?? useStoryStore.getState().currentPassage);
   return {
@@ -143,6 +143,31 @@ export function countQueries(counts: () => Counts) {
   };
 }
 
+/**
+ * The history functions of passage code and the story API: the current and
+ * previous passage, and visited()/rendered() with their has-forms, counting
+ * in the counters `visitCounts()` and `renderCounts()` return.
+ */
+export function historyQueries(
+  visitCounts: () => Counts,
+  renderCounts: () => Counts,
+) {
+  const visits = countQueries(visitCounts);
+  const renders = countQueries(renderCounts);
+  return {
+    currentPassage,
+    previousPassage,
+    visited: visits.count,
+    hasVisited: visits.has,
+    hasVisitedAny: visits.any,
+    hasVisitedAll: visits.all,
+    rendered: renders.count,
+    hasRendered: renders.has,
+    hasRenderedAny: renders.any,
+    hasRenderedAll: renders.all,
+  };
+}
+
 let cachedFns: ExpressionFns | null = null;
 let cachedVisitCounts: Counts | null = null;
 let cachedRenderCounts: Counts | null = null;
@@ -159,19 +184,11 @@ export function buildExpressionFns() {
     return cachedFns;
   }
 
-  const visits = countQueries(() => visitCounts);
-  const renders = countQueries(() => renderCounts);
   cachedFns = {
-    currentPassage,
-    previousPassage,
-    visited: visits.count,
-    hasVisited: visits.has,
-    hasVisitedAny: visits.any,
-    hasVisitedAll: visits.all,
-    rendered: renders.count,
-    hasRendered: renders.has,
-    hasRenderedAny: renders.any,
-    hasRenderedAll: renders.all,
+    ...historyQueries(
+      () => visitCounts,
+      () => renderCounts,
+    ),
     random,
     randomInt,
   };
@@ -195,21 +212,24 @@ function namespaceArg(ns: Namespace): Namespace {
   return ns;
 }
 
-/**
- * Evaluate an expression and return its value.
- * e.g. evaluate("$health + 10", variables, temporary) → number
- */
-export function evaluate(
-  expr: string,
+/** The namespaces code runs in, as evaluate() and execute() take them. */
+type Namespaces = [
   variables: Namespace,
   temporary: Namespace,
-  locals: Namespace = EMPTY_NAMESPACE,
-  transient: Namespace = EMPTY_NAMESPACE,
+  locals?: Namespace,
+  transient?: Namespace,
+];
+
+/** Run compiled code in `namespaces`. */
+function run(
+  fn: CompiledExpression,
+  ...[
+    variables,
+    temporary,
+    locals = EMPTY_NAMESPACE,
+    transient = EMPTY_NAMESPACE,
+  ]: Namespaces
 ): unknown {
-  const transformed = transform(expr);
-  // The line break keeps a trailing `// comment` from swallowing the `)`.
-  const body = `return (${transformed}\n);`;
-  const fn = getOrCompile(body, body);
   return fn(
     namespaceArg(variables),
     namespaceArg(temporary),
@@ -219,26 +239,24 @@ export function evaluate(
   );
 }
 
+/**
+ * Evaluate an expression and return its value.
+ * e.g. evaluate("$health + 10", variables, temporary) → number
+ */
+export function evaluate(expr: string, ...namespaces: Namespaces): unknown {
+  const transformed = transform(expr);
+  // The line break keeps a trailing `// comment` from swallowing the `)`.
+  const body = `return (${transformed}\n);`;
+  return run(getOrCompile(body, body), ...namespaces);
+}
+
 /**
  * Execute statements (no return value).
  * e.g. execute("$health = 100; $name = 'Hero'", variables, temporary)
  */
-export function execute(
-  code: string,
-  variables: Namespace,
-  temporary: Namespace,
-  locals: Namespace = EMPTY_NAMESPACE,
-  transient: Namespace = EMPTY_NAMESPACE,
-): void {
+export function execute(code: string, ...namespaces: Namespaces): void {
   const transformed = transform(code, 'statements');
-  const fn = getOrCompile('exec:' + transformed, transformed);
-  fn(
-    namespaceArg(variables),
-    namespaceArg(temporary),
-    namespaceArg(locals),
-    buildExpressionFns(),
-    namespaceArg(transient),
-  );
+  run(getOrCompile('exec:' + transformed, transformed), ...namespaces);
 }
 
 /**

package/src/hooks/use-action.ts

@@ -2,22 +2,15 @@ import { useLayoutEffect, useRef } from 'preact/hooks';
 import {
   registerAction,
   generateActionId,
+  OPTIONAL_ACTION_FIELDS,
   type ActionRegistration,
-  type ActionType,
   type StoryAction,
 } from '../action-registry';
 
-export interface UseActionOptions {
-  type: ActionType;
+/** The action to register, and what its ID is generated from. */
+export interface UseActionOptions extends Omit<StoryAction, 'id'> {
   key: string;
   authorId?: string;
-  label: string;
-  target?: string;
-  variable?: string;
-  options?: string[];
-  value?: unknown;
-  disabled?: boolean;
-  perform: (value?: unknown) => void;
 }
 
 export function useAction(opts: UseActionOptions): string {
@@ -39,11 +32,10 @@ export function useAction(opts: UseActionOptions): string {
       label: opts.label,
       perform: (...args) => performRef.current(...args),
     };
-    if (opts.target !== undefined) action.target = opts.target;
-    if (opts.variable !== undefined) action.variable = opts.variable;
-    if (opts.options !== undefined) action.options = opts.options;
-    if (opts.value !== undefined) action.value = opts.value;
-    if (opts.disabled !== undefined) action.disabled = opts.disabled;
+    for (const field of OPTIONAL_ACTION_FIELDS) {
+      if (opts[field] !== undefined)
+        Object.assign(action, { [field]: opts[field] });
+    }
     return action;
   };
 

package/src/index.tsx

@@ -19,9 +19,7 @@ import {
 import { getMacroRegistry } from './registry';
 import { tokenize } from './markup/tokenizer';
 import { buildAST, registerBlockMacro } from './markup/ast';
-import { registerWidget } from './widgets/widget-registry';
-import { astContainsChildren } from './widgets/ast-scanner';
-import { parseWidgetDef } from './components/macros/Widget';
+import { parseWidgetDef, registerWidgetDef } from './components/macros/Widget';
 import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
@@ -174,23 +172,15 @@ export function boot() {
       const widgetAST = buildAST(widgetTokens);
       for (const node of widgetAST) {
         if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
-          const { name: widgetName, params } = parseWidgetDef(
-            node.rawArgs,
-            '$_@',
-          );
-          const children = node.children as ASTNode[];
-          const isBlock = astContainsChildren(children);
+          // Read and registered as the {widget} macro does
+          const def = parseWidgetDef(node.rawArgs);
           try {
-            registerWidget(widgetName, children, params, isBlock);
+            registerWidgetDef(def, node.children as ASTNode[]);
           } catch (err) {
             // As the {widget} macro refuses it: the others still register
             console.error(
-              `spindle: widget "${widgetName}" in passage "${passage.name}" was not registered: ${errorMessage(err)}`,
+              `spindle: widget "${def.name}" in passage "${passage.name}" was not registered: ${errorMessage(err)}`,
             );
-            continue;
-          }
-          if (isBlock) {
-            registerBlockMacro(widgetName);
           }
         }
       }

package/src/interpolation.ts

@@ -27,6 +27,7 @@ import { getMacro, getMacroText, isSubMacro } from './registry';
 import type { MacroTextContext } from './registry';
 import { getWidget } from './widgets/widget-registry';
 import { splitArgs } from './components/macros/arg-utils';
+import { display } from './components/macros/display';
 import { splitSigilTemplate } from './markup/code-attributes';
 import {
   checkVariableName,
@@ -118,10 +119,6 @@ export function mapTextNodes(
 /** Deep enough for any real nesting; stops a widget that includes itself. */
 const MAX_DEPTH = 100;
 
-function display(value: unknown): string {
-  return value == null ? '' : String(value);
-}
-
 /**
  * The value of a variable reference (`name` without its sigil, with an
  * optional dot path), as `{$name}` shows it in passage text (see
@@ -154,6 +151,17 @@ function resolveVariable(
   return value;
 }
 
+/** Evaluate an expression in `scope`. */
+function evaluateIn(expr: string, scope: TextScope): unknown {
+  return evaluate(
+    expr,
+    scope.variables,
+    scope.temporary,
+    scope.locals,
+    scope.transient,
+  );
+}
+
 class TextEvaluator {
   readonly errors: TextError[] = [];
 
@@ -163,16 +171,6 @@ class TextEvaluator {
     return text;
   }
 
-  private evaluate(expr: string, scope: TextScope): unknown {
-    return evaluate(
-      expr,
-      scope.variables,
-      scope.temporary,
-      scope.locals,
-      scope.transient,
-    );
-  }
-
   private node(node: ASTNode, scope: TextScope, depth: number): string {
     switch (node.type) {
       case 'text':
@@ -190,7 +188,7 @@ class TextEvaluator {
         return this.variable(node.scope, node.name, scope);
       case 'expression':
         try {
-          return display(this.evaluate(node.expression, scope));
+          return display(evaluateIn(node.expression, scope));
         } catch (error) {
           this.errors.push({ macro: 'expression', error });
           return '';
@@ -255,7 +253,7 @@ class TextEvaluator {
           const expr = argExprs[i];
           if (expr !== undefined) {
             try {
-              value = this.evaluate(expr, scope);
+              value = evaluateIn(expr, scope);
             } catch {
               value = undefined;
             }
@@ -279,7 +277,7 @@ class TextEvaluator {
     }
 
     const ctx: MacroTextContext = {
-      evaluate: (expr) => this.evaluate(expr, scope),
+      evaluate: (expr) => evaluateIn(expr, scope),
       renderText: (nodes, locals) =>
         this.nested(
           node.name,
@@ -369,15 +367,7 @@ export function interpolateCode(
       }
     } else {
       try {
-        text += display(
-          evaluate(
-            part.expr,
-            scope.variables,
-            scope.temporary,
-            scope.locals,
-            scope.transient,
-          ),
-        );
+        text += display(evaluateIn(part.expr, scope));
       } catch (error) {
         errors.push({ macro: 'expression', error });
       }
@@ -386,22 +376,28 @@ export function interpolateCode(
   return { text, errors };
 }
 
+/** The namespaces of a TextScope, passed one by one. */
+type ScopeArgs = [
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+  transient?: Record<string, unknown>,
+];
+
+function scopeOf(
+  ...[variables, temporary, locals, transient = {}]: ScopeArgs
+): TextScope {
+  return { variables, temporary, locals, transient };
+}
+
 /**
  * Evaluate text-only markup to a string, throwing the first error met.
  */
 export function interpolate(
   template: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown>,
-  transient: Record<string, unknown> = {},
+  ...namespaces: ScopeArgs
 ): string {
-  const { text, errors } = interpolateText(template, {
-    variables,
-    temporary,
-    locals,
-    transient,
-  });
+  const { text, errors } = interpolateText(template, scopeOf(...namespaces));
   if (errors.length > 0) throw errors[0]!.error;
   return text;
 }
@@ -412,10 +408,7 @@ export function interpolate(
  */
 export function interpolateExpression(
   expr: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown>,
-  transient: Record<string, unknown> = {},
+  ...namespaces: ScopeArgs
 ): string {
-  return display(evaluate(expr, variables, temporary, locals, transient));
+  return display(evaluateIn(expr, scopeOf(...namespaces)));
 }

package/src/js-lexer.ts

@@ -397,6 +397,14 @@ const MALFORMED = -2;
 /** A frame result: the scan stops at index `s` inside it (`STOPPED - s`). */
 const STOPPED = -3;
 
+/**
+ * The result of a frame that closes at `end`. `bodyStarted`: the code inside
+ * started a function or class body. That body replaced the one to come, and
+ * is gone once the frame is closed, so after the frame no body is to come —
+ * a scan that skips the frame must know, as must the frames around it.
+ */
+const frameEnd = (end: number, bodyStarted: boolean) => end * 2 + +bodyStarted;
+
 /** The closers whose search for their frame a frame result may depend on. */
 const CLOSERS = [')', ']', '}'] as const;
 const FRAME_KINDS: readonly Frame['kind'][] = [
@@ -423,11 +431,13 @@ function frameKey(f: Frame): number | undefined {
  */
 export interface JsScanCache {
   /**
-   * Where each `{…}` frame, template literal or `${…}` interpolation closes:
-   * the index of its `}` or closing backtick, `UNCLOSED` or `MALFORMED`. The
-   * code inside such a frame lexes the same whatever surrounds it, given
-   * where it opens and its kind — a stray `)` or `]` inside never closes it
-   * — so a later scan entering the same frame skips to its end.
+   * Where each `{…}` frame, template literal or `${…}` interpolation closes,
+   * as a frame result (`frameEnd`): its `}` or closing backtick, and whether
+   * the code inside started a function or class body; or `UNCLOSED` or
+   * `MALFORMED`. The code inside such a frame lexes the same whatever
+   * surrounds it, given where it opens and its kind — a stray `)` or `]`
+   * inside never closes it — so a later scan entering the same frame skips
+   * to its end.
    */
   braces: Map<number, number>;
   /** Look-ahead bracket matches (`ScanContext.brackets`). */
@@ -457,10 +467,8 @@ export interface JsScanCache {
   stacks: Map<string, number>;
   /**
    * How `(…)` and `[…]` frames end, by the kind of scan and then by the frame
-   * (`parenKey`): `end * 2 + 1` if it closes at `end` and the code inside
-   * started a function or class body (which replaced the one to come, and
-   * can't follow once the frame is closed), `end * 2` otherwise, or
-   * `UNCLOSED`, `MALFORMED` or `STOPPED - s`. Unlike braces, a stray closer inside may close a frame
+   * (`parenKey`): a frame result (`frameEnd`), or `UNCLOSED`, `MALFORMED` or
+   * `STOPPED - s`. Unlike braces, a stray closer inside may close a frame
    * around them, so the code inside lexes the same only around frames for
    * which the closers it met find nothing to close; the key says which
    * closers met none.
@@ -748,15 +756,34 @@ function scan(
     : undefined;
   /**
    * How many function or class bodies to come the scan has started, and with
-   * `parens`, that count when each open frame opened. Code in a `(…)` or
-   * `[…]` that starts one replaces the one to come, and the new one can't
-   * follow once the frame is closed: none is to come then.
+   * `braces` or `parens`, that count when each open frame opened. Code in a
+   * frame that starts one replaces the one to come, and the new one can't
+   * follow once the frame is closed: none is to come then. A scan skipping
+   * the frame learns this from its result (`frameEnd`, `resume`), and counts
+   * the body as started too, for the frames around it to record.
    */
   let bodyStarts = 0;
-  const startsAt: number[] | undefined = parens ? [0] : undefined;
+  const startsAt: number[] | undefined = braces || parens ? [0] : undefined;
   /** A `(…)` or `[…]` frame result found in `parens`, to skip to. */
   let parenTo: { frame: Frame; result: number } | undefined;
 
+  /** The result of the frame at index `k`, closing at `i`. */
+  const closedAt = (k: number) =>
+    frameEnd(i, startsAt !== undefined && bodyStarts !== startsAt[k]);
+
+  /**
+   * Go on after a frame an earlier scan lexed, whose result (`frameEnd`) is
+   * `result`: returns the index it closes at. A body started in it is gone
+   * after it, with the one it replaced.
+   */
+  function resume(result: number): number {
+    if (result % 2 === 1) {
+      pendingBody = undefined;
+      bodyStarts++;
+    }
+    return Math.floor(result / 2);
+  }
+
   /** The closer `c` looked for its frame and found index `k`. */
   function lookedFor(c: (typeof CLOSERS)[number], k: number) {
     if (!lowest) return;
@@ -933,8 +960,8 @@ function scan(
     if (lowest) {
       for (let j = frames.length - 1; j >= k; j--) foldLowest(j);
       lowest.length = k;
-      startsAt!.length = k;
     }
+    if (startsAt) startsAt.length = k;
     frames.length = k;
     if (stackIds) stackIds.length = k;
     for (const list of Object.values(closers)) {
@@ -1034,6 +1061,19 @@ function scan(
     keyNext = f.kind === 'object' || f.kind === 'class';
   }
 
+  /**
+   * Go past frame `f` if an earlier scan lexed it: to just after it, or to
+   * the end of the source when it never closes. Whether it did, or
+   * MALFORMED when that scan found the code malformed.
+   */
+  function skipLexed(f: Frame): boolean | typeof MALFORMED {
+    const end = known(f);
+    if (end === undefined) return false;
+    if (end === MALFORMED) return MALFORMED;
+    i = end === UNCLOSED ? src.length : resume(end) + 1;
+    return true;
+  }
+
   function openBrace() {
     let f: Frame;
     if (pendingBody?.depth === frames.length) {
@@ -1079,12 +1119,11 @@ function scan(
       return;
     }
     const closed = frames[k]!;
+    const result = closedAt(k);
     if (lowest && c !== '}') {
       // Its entry complete, with those of the frames still open in it
       for (let j = frames.length - 1; j > k; j--) foldLowest(j);
-      // Whether code in it started a function or class body: none is to come
-      const bodyStarted = bodyStarts !== startsAt![k];
-      recordParen(k, i * 2 + +bodyStarted);
+      recordParen(k, result);
     }
     truncate(k);
     if (c === ']' && !ctx.lookahead) ctx.brackets.set(closed.open, i);
@@ -1095,7 +1134,7 @@ function scan(
     } else if (c === ']') {
       endPunct(c, false);
     } else {
-      record(closed, i);
+      record(closed, result);
       afterBrace(closed);
     }
   }
@@ -1214,24 +1253,17 @@ function scan(
       } else if (ch === '`') {
         literal(ch, i);
         if (frames.length === 1) return i + 1; // the end of `lexTemplate`
-        record(top(), i);
+        record(top(), closedAt(frames.length - 1));
         i++;
         truncate(frames.length - 1);
         endOperand();
       } else if (ch === '$' && src.charAt(i + 1) === '{') {
         const f = frame('expr', '}', i);
         f.interpolation = true;
-        const end = known(f);
-        if (end === MALFORMED) return malformed();
-        if (end === UNCLOSED) {
-          i = src.length;
-          break;
-        }
-        if (end !== undefined) {
-          // An interpolation an earlier scan lexed: on with the text after it
-          i = end + 1;
-          continue;
-        }
+        // An interpolation an earlier scan lexed: on with the text after it
+        const skipped = skipLexed(f);
+        if (skipped === MALFORMED) return malformed();
+        if (skipped) continue;
         literal('${', i);
         i += 2;
         nesting++;
@@ -1261,15 +1293,10 @@ function scan(
     if (ch === '`') {
       endWord();
       const f = frame('template', '`', i);
-      const end = known(f);
-      if (end === MALFORMED) return malformed();
-      if (end === UNCLOSED) {
-        i = src.length;
-        break;
-      }
-      if (end !== undefined) {
-        // A template literal an earlier scan lexed: on after it
-        i = end + 1;
+      // A template literal an earlier scan lexed: on after it
+      const skipped = skipLexed(f);
+      if (skipped === MALFORMED) return malformed();
+      if (skipped) {
         endOperand();
         continue;
       }
@@ -1291,7 +1318,7 @@ function scan(
       lookedFor('}', k);
       if (frames[k]!.interpolation) {
         endWord();
-        record(frames[k]!, i);
+        record(frames[k]!, closedAt(k));
         truncate(k);
         nesting--;
         literal(ch, i);
@@ -1399,8 +1426,17 @@ function scan(
       }
     }
 
-    // End of an `outer` square bracket
-    if (ch === outer.closer && frames.length === 1) break;
+    // End of an `outer` square bracket: a `]` that closes no `[` within the
+    // innermost braces closes it, over any `(` left open in it, as it closes
+    // a nested `[`. Look-ahead scans record where the `[`s nested in theirs
+    // end (`ctx.brackets`), so one starting at a `[` must find the same.
+    if (
+      ch === outer.closer &&
+      (frames.length === 1 ||
+        (ch === ']' && innermost(']') === 0 && innermost('}') === 0))
+    ) {
+      break;
+    }
 
     // Regular code character
     trackCode(ch);
@@ -1413,7 +1449,7 @@ function scan(
         i = src.length;
         break;
       }
-      i = end;
+      i = resume(end);
       afterBrace(skipped);
       i++;
       continue;
@@ -1432,8 +1468,7 @@ function scan(
         strict!.stopped = true;
         return STOPPED - result;
       }
-      i = Math.floor(result / 2);
-      if (result % 2 === 1) pendingBody = undefined;
+      i = resume(result);
       if (skipped.closer === ')') {
         endPunct(')', skipped.header);
         stmtNext = skipped.header;

package/src/markup/ast.ts

@@ -6,6 +6,7 @@ import {
   type Token,
   type VariableScope,
 } from './tokenizer';
+import { NameSet } from '../utils/macro-names';
 
 export interface TextNode {
   type: 'text';
@@ -51,7 +52,7 @@ export type ASTNode =
   | HtmlNode;
 
 /** Macros that require a closing tag and can contain children */
-const BLOCK_MACROS = new Set([
+const BLOCK_MACROS = new NameSet([
   'if',
   'for',
   'do',
@@ -70,12 +71,12 @@ const BLOCK_MACROS = new Set([
 
 /** Register a custom macro as a block macro so the AST builder nests children. */
 export function registerBlockMacro(name: string): void {
-  BLOCK_MACROS.add(name.toLowerCase());
+  BLOCK_MACROS.add(name);
 }
 
 /** Unregister a custom block macro (for test cleanup). */
 export function unregisterBlockMacro(name: string): void {
-  BLOCK_MACROS.delete(name.toLowerCase());
+  BLOCK_MACROS.delete(name);
 }
 
 /** Map from branch macro name → required parent macro name */

package/src/markup/render.tsx

@@ -588,12 +588,9 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
 
 function ChildrenSlot() {
   const childrenAST = useContext(WidgetChildrenContext);
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
-  const raw = useContext(RawTextContext);
-  const locals = useContext(LocalsValuesContext);
+  const renderOptions = useRenderOptions();
   if (!childrenAST || childrenAST.length === 0) return null;
-  return <>{renderNodes(childrenAST, { nobr, locals, inline, raw })}</>;
+  return <>{renderNodes(childrenAST, renderOptions)}</>;
 }
 
 /**
@@ -669,10 +666,7 @@ function renderSingleNode(node: ASTNode): preact.ComponentChildren {
       return (
         <VarDisplay
           key={key}
-          name={node.name}
-          scope={node.scope}
-          className={node.className}
-          id={node.id}
+          node={node}
         />
       );
 
@@ -680,9 +674,7 @@ function renderSingleNode(node: ASTNode): preact.ComponentChildren {
       return (
         <ExprDisplay
           key={key}
-          expression={node.expression}
-          className={node.className}
-          id={node.id}
+          node={node}
         />
       );