@rohal12/spindle 0.52.7 → 0.52.8

package/src/components/macros/VarDisplay.tsx

@@ -3,13 +3,9 @@ import { useContext } from 'preact/hooks';
 import { LocalsValuesContext } from '../../markup/render';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { ownValue, variableNameError } from '../../utils/namespace';
-
-const SIGILS = {
-  variable: '$',
-  temporary: '_',
-  local: '@',
-  transient: '%',
-} as const;
+import { SCOPE_SIGILS } from '../../markup/tokenizer';
+import type { VariableNode } from '../../markup/ast';
+import { display, wrapContent } from './display';
 
 const STORE_NAMESPACES = {
   variable: 'variables',
@@ -17,17 +13,12 @@ const STORE_NAMESPACES = {
   transient: 'transient',
 } as const;
 
-interface VarDisplayProps {
-  name: string;
-  scope: 'variable' | 'temporary' | 'local' | 'transient';
-  className?: string;
-  id?: string;
-}
-
-export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
+/** A `{$name}` (`{_name}`, `{@name}`, `{%name}`) variable display. */
+export function VarDisplay({ node }: { node: VariableNode }) {
+  const { name, scope } = node;
   const resolve = useInterpolate();
-  className = resolve(className);
-  id = resolve(id);
+  const className = resolve(node.className);
+  const id = resolve(node.id);
   const localsValues = useContext(LocalsValuesContext);
   const parts = name.split('.');
   const root = parts[0]!;
@@ -36,11 +27,10 @@ export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
     scope === 'local' ? undefined : ownValue(s[STORE_NAMESPACES[scope]], root),
   );
 
-  const nameError = variableNameError(root, SIGILS[scope] + root);
+  const sigil = SCOPE_SIGILS[scope];
+  const nameError = variableNameError(root, sigil + root);
   if (nameError) {
-    return (
-      <span class="error">{`{${SIGILS[scope]}${name} error: ${nameError}}`}</span>
-    );
+    return <span class="error">{`{${sigil}${name} error: ${nameError}}`}</span>;
   }
 
   let value: unknown;
@@ -61,15 +51,5 @@ export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
     value = (value as Record<string, unknown>)[part];
   }
 
-  const display = value == null ? '' : String(value);
-  if (className || id)
-    return (
-      <span
-        id={id}
-        class={className}
-      >
-        {display}
-      </span>
-    );
-  return <>{display}</>;
+  return wrapContent(className, id, display(value));
 }

package/src/components/macros/Widget.tsx

@@ -1,35 +1,69 @@
 import { registerWidget } from '../../widgets/widget-registry';
 import { astContainsChildren } from '../../widgets/ast-scanner';
-import { registerBlockMacro } from '../../markup/ast';
+import { registerBlockMacro, type ASTNode } from '../../markup/ast';
 import { defineMacro } from '../../define-macro';
 import { checkVariableName } from '../../utils/namespace';
 import { MacroError } from './MacroError';
+import { parseMacroArgs } from './macro-args';
+import type { MacroArgs } from '../../registry';
+
+/** A {widget} definition's name, then its `@` parameters. */
+const WIDGET_PARAMETERS = [
+  { name: 'name', type: 'text', required: true },
+  { name: 'parameters', type: 'expression' },
+] as const;
+
+interface WidgetDef {
+  name: string;
+  params: string[];
+}
 
 /**
- * Read the arguments of a {widget} definition: its name (quotes dropped)
- * and its parameters, the words after it that start with one of the
- * characters of `sigils`.
+ * The widget a {widget} definition's arguments declare: its name and its
+ * parameters, the words after it that start with `@` (docs/widgets.md).
+ * Other words, such as `$name`, are not parameters.
  */
-export function parseWidgetDef(
-  rawArgs: string,
-  sigils = '@',
-): { name: string; params: string[] } {
-  const [first, ...rest] = rawArgs.trim().split(/\s+/);
+function widgetDef({
+  name = '',
+  parameters = '',
+}: MacroArgs<typeof WIDGET_PARAMETERS>): WidgetDef {
   return {
-    name: first!.replace(/["']/g, ''),
-    params: rest.filter((word) => sigils.includes(word[0]!)),
+    name,
+    params: parameters.split(/\s+/).filter((word) => word.startsWith('@')),
   };
 }
 
+/** Read the arguments of a {widget} definition (see widgetDef). */
+export function parseWidgetDef(rawArgs: string): WidgetDef {
+  return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
+}
+
+/**
+ * Register the widget a definition declares, with its body. Widgets whose
+ * body renders {@children} take a closing tag, so they are registered as
+ * block macros too: passages parsed later nest their content. A parameter
+ * that no namespace can hold throws (see registerWidget), registering
+ * nothing.
+ */
+export function registerWidgetDef(
+  { name, params }: WidgetDef,
+  body: ASTNode[],
+): void {
+  const isBlock = astContainsChildren(body);
+  registerWidget(name, body, params, isBlock);
+  if (isBlock) registerBlockMacro(name);
+}
+
 defineMacro({
   name: 'widget',
   block: true,
-  render({ rawArgs, children = [] }, ctx) {
-    let parsed: ReturnType<typeof parseWidgetDef> | undefined;
+  parameters: WIDGET_PARAMETERS,
+  render({ children = [] }, ctx) {
+    let parsed: WidgetDef | undefined;
     let error: unknown;
     try {
       // Refuse `@` parameters that no namespace can hold
-      const def = parseWidgetDef(rawArgs);
+      const def = widgetDef(ctx.args);
       for (const param of def.params) checkVariableName(param.slice(1), param);
       parsed = def;
     } catch (err) {
@@ -41,12 +75,7 @@ defineMacro({
     const paramsKey = params.join(',');
 
     ctx.hooks.useLayoutEffect(() => {
-      if (!parsed) return;
-      // Widgets whose body renders {@children} take a closing tag; register
-      // them as block macros so passages parsed later nest their content.
-      const isBlock = astContainsChildren(children);
-      registerWidget(name, children, params, isBlock);
-      if (isBlock) registerBlockMacro(name);
+      if (parsed) registerWidgetDef(parsed, children);
     }, [name, childrenKey, paramsKey]);
 
     if (error) {

package/src/components/macros/branches.ts

@@ -0,0 +1,18 @@
+import type { Branch } from '../../markup/ast';
+
+/**
+ * The branch a conditional block ({if}, {switch}) shows: the first of
+ * `branches` whose argument `matches`, else the last bare one ({else},
+ * {default}), else null. Throws what `matches` throws.
+ */
+export function selectBranch(
+  branches: Branch[],
+  matches: (rawArgs: string) => boolean,
+): Branch | null {
+  let fallback: Branch | null = null;
+  for (const branch of branches) {
+    if (branch.rawArgs === '') fallback = branch;
+    else if (matches(branch.rawArgs)) return branch;
+  }
+  return fallback;
+}

package/src/components/macros/display.ts

@@ -0,0 +1,19 @@
+import { h, Fragment, type ComponentChildren, type VNode } from 'preact';
+
+/** The text a value is shown as: nothing for null and undefined. */
+export function display(value: unknown): string {
+  return value == null ? '' : String(value);
+}
+
+/**
+ * `content` in a `<span>` carrying `className` and `id`, or in a fragment if
+ * it has neither.
+ */
+export function wrapContent(
+  className: string | undefined,
+  id: string | undefined,
+  content: ComponentChildren,
+): VNode<any> {
+  if (className || id) return h('span', { id, class: className }, content);
+  return h(Fragment, null, content);
+}

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

@@ -1,5 +1,34 @@
 import { h } from 'preact';
-import { defineMacro } from '../../define-macro';
+import { defineMacro, type MacroContext } from '../../define-macro';
+import type { UseActionOptions } from '../../hooks/use-action';
+import { display } from './display';
+
+/** The story variable a `storeVar` macro binds: its first parameter. */
+export const VARIABLE_PARAMETER = {
+  name: 'variable',
+  type: 'variable',
+  required: true,
+} as const;
+
+/**
+ * Register the automation action of a macro bound to a story variable: keyed
+ * by the variable (or `key`), with the variable's value unless `action`
+ * gives another.
+ */
+export function useVariableAction(
+  ctx: Pick<MacroContext, 'useAction' | 'id' | 'varName' | 'value'>,
+  action: Omit<UseActionOptions, 'key' | 'authorId' | 'variable'> & {
+    key?: string;
+  },
+): string {
+  return ctx.useAction({
+    key: `$${ctx.varName}`,
+    authorId: ctx.id,
+    variable: ctx.varName,
+    value: ctx.value,
+    ...action,
+  });
+}
 
 /**
  * Define a text input macro, `{name $var "placeholder"}`: an `<input>` of
@@ -17,20 +46,13 @@ export function defineInputMacro(
   defineMacro({
     name,
     storeVar: true,
-    parameters: [
-      { name: 'variable', type: 'variable', required: true },
-      { name: 'placeholder', type: 'string' },
-    ],
+    parameters: [VARIABLE_PARAMETER, { name: 'placeholder', type: 'string' }],
     render(_props, ctx) {
       const placeholder = ctx.args.placeholder ?? '';
 
-      ctx.useAction({
+      useVariableAction(ctx, {
         type: name,
-        key: `$${ctx.varName}`,
-        authorId: ctx.id,
         label: placeholder || ctx.varName!,
-        variable: ctx.varName,
-        value: ctx.value,
         perform: (v) => ctx.setValue!(toValue(v)),
       });
 
@@ -38,7 +60,7 @@ export function defineInputMacro(
         type,
         id: ctx.id,
         class: ctx.cls,
-        value: ctx.value == null ? '' : String(ctx.value),
+        value: display(ctx.value),
         placeholder,
         onInput: (e: Event) =>
           ctx.setValue!(toValue((e.target as HTMLInputElement).value)),

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

@@ -232,6 +232,13 @@ function readGroup(
       : unset(rest);
 }
 
+/** The duration a timing macro ({repeat}, {type}, {timed}/{next}) waits. */
+export const DELAY_PARAMETER = {
+  name: 'delay',
+  type: 'delay',
+  required: true,
+} as const;
+
 /** Read `rawArgs` into the declared `parameters` (see above). */
 export function parseMacroArgs<const P extends readonly ParameterDef[]>(
   rawArgs: string,

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

@@ -1,5 +1,4 @@
 import type { ASTNode } from '../../markup/ast';
-import { readWholeQuoted } from './arg-utils';
 import { parseMacroArgs } from './macro-args';
 
 /** `$var "placeholder"`, the arguments of the input macros. */
@@ -14,18 +13,22 @@ export function parseVarArgs(rawArgs: string): {
   return { varName: variable.replace(/["']/g, ''), placeholder };
 }
 
+/** The parameters of an `{option}` sub-macro: its value. */
+const OPTION_PARAMETERS = [{ name: 'value', type: 'string' }] as const;
+
 /**
- * Walk AST children to find {option} macro nodes, returning their rawArgs as values.
+ * Walk AST children to find {option} macro nodes, returning their values.
  */
 export function extractOptions(children: ASTNode[]): string[] {
   const options: string[] = [];
   for (const node of children) {
     if (node.type === 'macro' && node.name === 'option') {
-      const raw = node.rawArgs.trim();
-      // Strip surrounding quotes so {option "Long Sword"} gives "Long Sword"
-      const stripped =
-        readWholeQuoted(raw) ?? raw.replace(/^(["'])(.+)\1$/s, '$2');
-      options.push(stripped);
+      // {option "Long Sword"} gives `Long Sword`. A value that isn't one
+      // quoted string loses a matching pair of quotes around it, if any.
+      const { value } = parseMacroArgs(node.rawArgs, OPTION_PARAMETERS);
+      options.push(
+        value ?? node.rawArgs.trim().replace(/^(["'])(.+)\1$/s, '$2'),
+      );
     }
   }
   return options;

package/src/define-macro.ts

@@ -1,4 +1,4 @@
-import { h, Fragment } from 'preact';
+import { h } from 'preact';
 import type { VNode, ComponentChildren } from 'preact';
 import {
   useContext,
@@ -28,6 +28,7 @@ import type { UseActionOptions } from './hooks/use-action';
 import { collectText } from './utils/extract-text';
 import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
+import { wrapContent } from './components/macros/display';
 import {
   parseMacroArgs,
   readBoundVariable,
@@ -177,11 +178,8 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       mutate: (code: string) => executeMutation(code, getValues(), update),
       update,
       getValues,
-      wrap: (content: ComponentChildren): VNode<any> => {
-        if (className || id)
-          return h('span', { id, class: className }, content);
-        return h(Fragment, null, content);
-      },
+      wrap: (content: ComponentChildren): VNode<any> =>
+        wrapContent(className, id, content),
     };
 
     if (config.merged) {

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);
           }
         }
       }