@rohal12/spindle 0.51.4 → 0.52.0

package/src/hooks/use-interpolate.ts

@@ -1,17 +1,48 @@
-import { useCallback } from 'preact/hooks';
+import { useCallback, useContext, useMemo } from 'preact/hooks';
 import { useMergedLocals } from './use-merged-locals';
-import { hasInterpolation, interpolate } from '../interpolation';
+import { WidgetChildrenContext } from '../markup/render';
+import {
+  hasInterpolation,
+  interpolateText,
+  type TextScope,
+} from '../interpolation';
+import { errorMessage } from '../utils/error-message';
 
+/**
+ * The scope text-only markup (attribute values, labels) is evaluated in:
+ * store variables, locals and the enclosing block widget's children. The
+ * caller re-renders whenever one of them changes.
+ */
+export function useTextScope(): TextScope {
+  const [variables, temporary, locals, transient] = useMergedLocals();
+  const widgetChildren = useContext(WidgetChildrenContext);
+  return useMemo(
+    () => ({ variables, temporary, locals, transient, widgetChildren }),
+    [variables, temporary, locals, transient, widgetChildren],
+  );
+}
+
+/**
+ * Return a function resolving the markup in a string (a macro label, class
+ * or id) to text. Errors (a macro with no text form, a failing expression)
+ * are logged, and their part of the string is left empty.
+ */
 export function useInterpolate(): (
   s: string | undefined,
 ) => string | undefined {
-  const [variables, temporary, locals, transient] = useMergedLocals();
+  const scope = useTextScope();
 
   return useCallback(
     (s: string | undefined): string | undefined => {
       if (s === undefined || !hasInterpolation(s)) return s;
-      return interpolate(s, variables, temporary, locals, transient);
+      const { text, errors } = interpolateText(s, scope);
+      for (const { macro, error } of errors) {
+        console.error(
+          `spindle: {${macro}} error in "${s}": ${errorMessage(error)}`,
+        );
+      }
+      return text;
     },
-    [variables, temporary, locals, transient],
+    [scope],
   );
 }

package/src/index.tsx

@@ -21,6 +21,7 @@ import { tokenize } from './markup/tokenizer';
 import { buildAST, registerBlockMacro } from './markup/ast';
 import { registerWidget } from './widgets/widget-registry';
 import { astContainsChildren } from './widgets/ast-scanner';
+import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
 import builtinCSS from './styles.css?inline';
@@ -182,7 +183,15 @@ export function boot() {
             );
           const children = node.children as ASTNode[];
           const isBlock = astContainsChildren(children);
-          registerWidget(widgetName, children, params, isBlock);
+          try {
+            registerWidget(widgetName, children, params, isBlock);
+          } 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)}`,
+            );
+            continue;
+          }
           if (isBlock) {
             registerBlockMacro(widgetName);
           }

package/src/interpolation.ts

@@ -1,129 +1,427 @@
+/**
+ * Text-only markup: HTML attribute values, image alt text and link titles,
+ * and macro labels resolve the inline markup of passage text (variables,
+ * expressions, macros, widgets) to a string.
+ *
+ * Such a value is parsed with the passage tokenizer in text mode, so `{…}`
+ * means the same as in passage text, and its AST is evaluated directly to a
+ * string rather than rendered: the result is ready during the render that
+ * needs it (so it goes through the usual attribute handling, boolean
+ * attributes and live properties included), costs no DOM work, and is
+ * recomputed whenever the variables or locals the caller subscribes to
+ * change. Macros take part through their text form (MacroDefinition.text);
+ * one without a text form (inputs, links, {set}, …) has nothing to put in a
+ * string, so it is reported instead of being run or shown as source.
+ */
 import { evaluate } from './expression';
-import { scanBalancedBrace } from './markup/tokenizer';
-
-/** Detects any {…} block that starts with a sigil ($, _, @, %). */
-const INTERP_TEST = /\{[\$_@%]\w/;
+import { tokenize } from './markup/tokenizer';
+import { buildAST } from './markup/ast';
+import type { ASTNode, MacroNode, TextNode } from './markup/ast';
+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 { splitSigilTemplate } from './markup/code-attributes';
+import {
+  checkVariableName,
+  createNamespace,
+  ownValue,
+  type Namespace,
+} from './utils/namespace';
 
+/** Whether a string may contain markup (anything but plain text). */
 export function hasInterpolation(s: string): boolean {
-  return INTERP_TEST.test(s);
+  return s.includes('{') || s.includes('}');
 }
 
-function resolveDotPath(root: unknown, parts: string[]): unknown {
-  let value = root;
-  for (let i = 1; i < parts.length; i++) {
-    // Primitives box on access, so `{$name.length}` works too.
-    if (value == null) return undefined;
-    value = (value as Record<string, unknown>)[parts[i]!];
-  }
-  return value;
+/** The scope text-only markup is evaluated in. */
+export interface TextScope {
+  variables: Record<string, unknown>;
+  temporary: Record<string, unknown>;
+  locals: Record<string, unknown>;
+  transient: Record<string, unknown>;
+  /** Invocation children of the enclosing block widget, for `{@children}`. */
+  widgetChildren?: ASTNode[] | null;
+}
+
+/** A macro, expression or markup error met while evaluating text. */
+export interface TextError {
+  /** The macro name, or `expression` / `markup`. */
+  macro: string;
+  error: unknown;
 }
 
+export interface TextResult {
+  text: string;
+  errors: TextError[];
+}
+
+export type ParsedText = { nodes: ASTNode[] } | { error: unknown };
+
+const parseCache = new Map<string, ParsedText>();
+const PARSE_CACHE_LIMIT = 2000;
+
 /**
- * Evaluate an expression string and return its stringified result.
- * Uses the full expression evaluator from expression.ts.
+ * Parse text-only markup into AST nodes, or the error the AST builder
+ * reports for it (an unclosed or mismatched macro). Results are cached.
  */
-export function interpolateExpression(
-  expr: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown>,
-  transient: Record<string, unknown> = {},
-): string {
-  const value = evaluate(expr, variables, temporary, locals, transient);
+export function parseText(template: string): ParsedText {
+  let parsed = parseCache.get(template);
+  if (parsed === undefined) {
+    try {
+      parsed = { nodes: buildAST(tokenize(template, { text: true })) };
+    } catch (error) {
+      parsed = { error };
+    }
+    if (parseCache.size >= PARSE_CACHE_LIMIT) parseCache.clear();
+    parseCache.set(template, parsed);
+  }
+  return parsed;
+}
+
+/** Map the text nodes of an AST (macro bodies and branches included). */
+export function mapTextNodes(
+  nodes: ASTNode[],
+  fn: (value: string) => string,
+): ASTNode[] {
+  return nodes.map((node): ASTNode => {
+    switch (node.type) {
+      case 'text':
+        return { type: 'text', value: fn(node.value) } satisfies TextNode;
+      case 'html':
+        return { ...node, children: mapTextNodes(node.children, fn) };
+      case 'macro': {
+        const copy: MacroNode = {
+          ...node,
+          children: mapTextNodes(node.children, fn),
+        };
+        if (node.branches) {
+          copy.branches = node.branches.map((b) => ({
+            ...b,
+            children: mapTextNodes(b.children, fn),
+          }));
+        }
+        return copy;
+      }
+      default:
+        return node;
+    }
+  });
+}
+
+/** 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);
 }
 
-function resolveSimple(
-  ref: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown>,
-  transient: Record<string, unknown>,
-): string {
-  const prefix = ref[0]!;
-  const path = ref.slice(1);
-  const parts = path.split('.');
-  const root = parts[0]!;
+type VariableKind = 'variable' | 'temporary' | 'local' | 'transient';
 
-  let value: unknown;
-  if (prefix === '$') {
-    value = variables[root];
-  } else if (prefix === '_') {
-    value = temporary[root];
-  } else if (prefix === '%') {
-    value = transient[root];
-  } else {
-    value = locals[root];
+const KIND_SIGILS = {
+  variable: '$',
+  temporary: '_',
+  local: '@',
+  transient: '%',
+} as const;
+
+/**
+ * The value of a variable reference (`name` without its sigil, with an
+ * optional dot path), as `{$name}` shows it in passage text (see
+ * VarDisplay): the variable is read from its namespace's own entries only,
+ * so an unset `$toString` is undefined, and one named `__proto__` throws.
+ */
+function resolveVariable(
+  scope: TextScope,
+  kind: VariableKind,
+  name: string,
+): unknown {
+  const parts = name.split('.');
+  const root = parts[0]!;
+  checkVariableName(root, KIND_SIGILS[kind] + root);
+  const store =
+    kind === 'variable'
+      ? scope.variables
+      : kind === 'temporary'
+        ? scope.temporary
+        : kind === 'transient'
+          ? scope.transient
+          : scope.locals;
+  // Own entries only, as the expression engine reads them
+  let value = ownValue(store, root);
+  // Primitives box on access, so `{$name.length}` works too.
+  for (let i = 1; i < parts.length; i++) {
+    if (value == null) return undefined;
+    value = (value as Record<string, unknown>)[parts[i]!];
   }
+  return value;
+}
 
-  if (parts.length > 1) {
-    value = resolveDotPath(value, parts);
+class TextEvaluator {
+  readonly errors: TextError[] = [];
+
+  nodes(nodes: ASTNode[], scope: TextScope, depth: number): string {
+    let text = '';
+    for (const node of nodes) text += this.node(node, scope, depth);
+    return text;
   }
 
-  return value == null ? '' : String(value);
-}
+  private evaluate(expr: string, scope: TextScope): unknown {
+    return evaluate(
+      expr,
+      scope.variables,
+      scope.temporary,
+      scope.locals,
+      scope.transient,
+    );
+  }
 
-export function interpolate(
-  template: string,
-  variables: Record<string, unknown>,
-  temporary: Record<string, unknown>,
-  locals: Record<string, unknown>,
-  transient: Record<string, unknown> = {},
-): string {
-  // Manual scan: process {…} blocks containing sigils.
-  // Simple dot-path refs use the fast resolver; everything else falls back
-  // to the full expression evaluator.
-  let result = '';
-  let i = 0;
-
-  while (i < template.length) {
-    if (template[i] !== '{') {
-      // Accumulate plain text
-      const nextBrace = template.indexOf('{', i);
-      if (nextBrace === -1) {
-        result += template.slice(i);
-        break;
+  private node(node: ASTNode, scope: TextScope, depth: number): string {
+    switch (node.type) {
+      case 'text':
+        return node.value;
+      case 'variable':
+        if (node.scope === 'local' && node.name === 'children') {
+          // As {@children} in a widget body: the invocation's children, in
+          // the scope of the body.
+          const children = scope.widgetChildren;
+          if (!children) return '';
+          return this.nested('children', children, scope, depth, {
+            widgetChildren: null,
+          });
+        }
+        return this.variable(node.scope, node.name, scope);
+      case 'expression':
+        try {
+          return display(this.evaluate(node.expression, scope));
+        } catch (error) {
+          this.errors.push({ macro: 'expression', error });
+          return '';
+        }
+      case 'html':
+        return this.nodes(node.children, scope, depth);
+      case 'macro':
+        return this.macro(node, scope, depth);
+      default: {
+        const _exhaustive: never = node;
+        return _exhaustive;
       }
-      result += template.slice(i, nextBrace);
-      i = nextBrace;
-      continue;
     }
+  }
 
-    // Found { — check if it starts a sigil expression
-    i++; // skip {
+  /** A variable reference, or '' and an error if it can't be one. */
+  private variable(kind: VariableKind, name: string, scope: TextScope): string {
+    try {
+      return display(resolveVariable(scope, kind, name));
+    } catch (error) {
+      // Reported as passage text reports it: `{$__proto__ error: …}`
+      this.errors.push({ macro: KIND_SIGILS[kind] + name, error });
+      return '';
+    }
+  }
 
-    const sigil = template[i];
-    if (sigil !== '$' && sigil !== '_' && sigil !== '@' && sigil !== '%') {
-      // Not an interpolation — emit the { as text
-      result += '{';
-      continue;
+  private nested(
+    macro: string,
+    nodes: ASTNode[],
+    scope: TextScope,
+    depth: number,
+    changes: Partial<TextScope> = {},
+  ): string {
+    if (depth >= MAX_DEPTH) {
+      this.errors.push({
+        macro,
+        error: new Error('markup nested too deeply (a widget using itself?)'),
+      });
+      return '';
     }
+    return this.nodes(nodes, { ...scope, ...changes }, depth + 1);
+  }
 
-    // Scan for balanced closing }, ignoring braces inside strings
-    const j = scanBalancedBrace(template, i);
+  private macro(node: MacroNode, scope: TextScope, depth: number): string {
+    // Rendering ignores a stray sub-macro too (see renderMacro).
+    if (isSubMacro(node.name)) return '';
 
-    if (j === -1) {
-      // Unbalanced — emit as text
-      result += '{';
-      continue;
+    const widget = getWidget(node.name);
+    if (widget) {
+      let locals = scope.locals;
+      // Parameterized widgets get their own scope (see WidgetInvocation):
+      // a missing or failing argument is undefined.
+      if (widget.params.length > 0) {
+        const argExprs = node.rawArgs ? splitArgs(node.rawArgs) : [];
+        locals = createNamespace(scope.locals);
+        widget.params.forEach((param, i) => {
+          let value: unknown;
+          const expr = argExprs[i];
+          if (expr !== undefined) {
+            try {
+              value = this.evaluate(expr, scope);
+            } catch {
+              value = undefined;
+            }
+          }
+          locals[param.startsWith('@') ? param.slice(1) : param] = value;
+        });
+      }
+      return this.nested(node.name, widget.body, scope, depth, {
+        locals,
+        widgetChildren: node.children.length > 0 ? node.children : null,
+      });
     }
 
-    const inner = template.slice(i, j);
-    i = j + 1; // skip past closing }
+    const text = getMacroText(node.name);
+    if (!text) {
+      const message = getMacro(node.name)
+        ? `{${node.name}} has no text form, so it can't be used in an attribute value or label`
+        : `unknown macro {${node.name}}`;
+      this.errors.push({ macro: node.name, error: new Error(message) });
+      return '';
+    }
 
-    // Try simple dot-path match first
-    if (/^[\$_@%][\w.]+$/.test(inner)) {
-      result += resolveSimple(inner, variables, temporary, locals, transient);
-    } else {
-      result += interpolateExpression(
-        inner,
-        variables,
-        temporary,
-        locals,
-        transient,
+    const ctx: MacroTextContext = {
+      evaluate: (expr) => this.evaluate(expr, scope),
+      renderText: (nodes, locals) =>
+        this.nested(
+          node.name,
+          nodes,
+          scope,
+          depth,
+          locals ? { locals: withLocals(scope.locals, locals) } : {},
+        ),
+    };
+    try {
+      return text(
+        {
+          rawArgs: node.rawArgs,
+          className: node.className,
+          id: node.id,
+          children: node.children,
+          branches: node.branches,
+        },
+        ctx,
       );
+    } catch (error) {
+      this.errors.push({ macro: node.name, error });
+      return '';
+    }
+  }
+}
+
+/**
+ * The locals `ns` with `added` (keys without `@`) on top, as a namespace
+ * (see utils/namespace.ts). A name no namespace can hold throws.
+ */
+function withLocals(ns: Namespace, added: Record<string, unknown>): Namespace {
+  for (const key of Object.keys(added)) checkVariableName(key, `@${key}`);
+  return createNamespace(ns, added);
+}
+
+/** Evaluate parsed text-only markup to a string. */
+export function renderText(nodes: ASTNode[], scope: TextScope): TextResult {
+  const evaluator = new TextEvaluator();
+  const text = evaluator.nodes(nodes, scope, 0);
+  return { text, errors: evaluator.errors };
+}
+
+/**
+ * Evaluate text-only markup. Markup that doesn't parse (an unclosed
+ * `{if}`) is reported and kept as written.
+ */
+export function interpolateText(
+  template: string,
+  scope: TextScope,
+): TextResult {
+  if (!hasInterpolation(template)) return { text: template, errors: [] };
+  const parsed = parseText(template);
+  if ('error' in parsed) {
+    return {
+      text: template,
+      errors: [{ macro: 'markup', error: parsed.error }],
+    };
+  }
+  return renderText(parsed.nodes, scope);
+}
+
+const SIGIL_KINDS = {
+  $: 'variable',
+  _: 'temporary',
+  '@': 'local',
+  '%': 'transient',
+} as const;
+
+/**
+ * Resolve the sigil references in the value of a code attribute (see
+ * isCodeAttribute): `{$x}`, `{_x.y}`, `{$n + 1}`. Everything else, other
+ * braces included, is literal text, passed through `decode` when given.
+ * A reference whose expression fails is reported and left empty.
+ */
+export function interpolateCode(
+  template: string,
+  scope: TextScope,
+  decode?: (text: string) => string,
+): TextResult {
+  const errors: TextError[] = [];
+  let text = '';
+  for (const part of splitSigilTemplate(template)) {
+    if ('text' in part) {
+      text += decode ? decode(part.text) : part.text;
+    } else if ('verbatim' in part) {
+      text += part.verbatim;
+    } else if (/^[$_@%][\w.]+$/.test(part.expr)) {
+      const kind = SIGIL_KINDS[part.expr[0] as keyof typeof SIGIL_KINDS];
+      try {
+        text += display(resolveVariable(scope, kind, part.expr.slice(1)));
+      } catch (error) {
+        errors.push({ macro: part.expr, error });
+      }
+    } else {
+      try {
+        text += display(
+          evaluate(
+            part.expr,
+            scope.variables,
+            scope.temporary,
+            scope.locals,
+            scope.transient,
+          ),
+        );
+      } catch (error) {
+        errors.push({ macro: 'expression', error });
+      }
     }
   }
+  return { text, errors };
+}
+
+/**
+ * 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> = {},
+): string {
+  const { text, errors } = interpolateText(template, {
+    variables,
+    temporary,
+    locals,
+    transient,
+  });
+  if (errors.length > 0) throw errors[0]!.error;
+  return text;
+}
 
-  return result;
+/**
+ * Evaluate an expression string and return its stringified result.
+ * Uses the full expression evaluator from expression.ts.
+ */
+export function interpolateExpression(
+  expr: string,
+  variables: Record<string, unknown>,
+  temporary: Record<string, unknown>,
+  locals: Record<string, unknown>,
+  transient: Record<string, unknown> = {},
+): string {
+  return display(evaluate(expr, variables, temporary, locals, transient));
 }