@rohal12/spindle 0.52.6 → 0.52.8

package/src/components/macros/Print.tsx

@@ -1,5 +1,6 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
+import { display } from './display';
 
 defineMacro({
   name: 'print',
@@ -8,9 +9,7 @@ defineMacro({
   merged: true,
   render({ rawArgs }, ctx) {
     try {
-      const result = ctx.evaluate!(rawArgs);
-      const display = result == null ? '' : String(result);
-      return ctx.wrap(display);
+      return ctx.wrap(display(ctx.evaluate!(rawArgs)));
     } catch (err) {
       return (
         <MacroError
@@ -21,7 +20,6 @@ defineMacro({
     }
   },
   text({ rawArgs }, ctx) {
-    const result = ctx.evaluate(rawArgs);
-    return result == null ? '' : String(result);
+    return display(ctx.evaluate(rawArgs));
   },
 });

package/src/components/macros/Radiobutton.tsx

@@ -1,10 +1,11 @@
 import { defineMacro } from '../../define-macro';
+import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
 
 defineMacro({
   name: 'radiobutton',
   storeVar: true,
   parameters: [
-    { name: 'variable', type: 'variable', required: true },
+    VARIABLE_PARAMETER,
     { name: 'value', type: 'text', required: true },
     { name: 'label', type: 'text' },
   ],
@@ -12,13 +13,10 @@ defineMacro({
     const radioValue = ctx.args.value ?? '';
     const label = ctx.args.label ?? '';
 
-    ctx.useAction({
+    useVariableAction(ctx, {
       type: 'radiobutton',
       key: `$${ctx.varName}:${radioValue}`,
-      authorId: ctx.id,
       label: label || radioValue,
-      variable: ctx.varName,
-      value: ctx.value,
       perform: () => ctx.setValue!(radioValue),
     });
 

package/src/components/macros/Repeat.tsx

@@ -1,5 +1,6 @@
 import { createContext } from 'preact';
 import { defineMacro } from '../../define-macro';
+import { DELAY_PARAMETER } from './macro-args';
 
 export const RepeatContext = createContext<{ stop: () => void }>({
   stop: () => {},
@@ -9,7 +10,7 @@ defineMacro({
   name: 'repeat',
   block: true,
   interpolate: true,
-  parameters: [{ name: 'delay', type: 'delay', required: true }],
+  parameters: [DELAY_PARAMETER],
   render({ children = [] }, ctx) {
     const { useState, useEffect, useCallback } = ctx.hooks;
 

package/src/components/macros/Switch.tsx

@@ -1,26 +1,19 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import type { Branch } from '../../markup/ast';
+import { selectBranch } from './branches';
 
 /**
  * The first {case} branch whose value equals `value`, else the {default}
  * branch, else null. Throws what a case expression throws.
  */
-function selectBranch(
+function selectCase(
   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;
+  // The first branch holds the content before the first {case}
+  return selectBranch(branches.slice(1), (expr) => value === evaluate(expr));
 }
 
 defineMacro({
@@ -43,7 +36,7 @@ defineMacro({
 
     let branch: Branch | null;
     try {
-      branch = selectBranch(switchValue, branches, ctx.evaluate!);
+      branch = selectCase(switchValue, branches, ctx.evaluate!);
     } catch (err) {
       return (
         <MacroError
@@ -56,7 +49,7 @@ defineMacro({
     return branch && <>{ctx.renderNodes(branch.children)}</>;
   },
   text({ rawArgs, branches = [] }, ctx) {
-    const branch = selectBranch(ctx.evaluate(rawArgs), branches, ctx.evaluate);
+    const branch = selectCase(ctx.evaluate(rawArgs), branches, ctx.evaluate);
     return branch ? ctx.renderText(branch.children) : '';
   },
 });

package/src/components/macros/Timed.tsx

@@ -1,16 +1,21 @@
-import { parseDelay } from '../../utils/parse-delay';
 import { defineMacro } from '../../define-macro';
+import { DELAY_PARAMETER, parseMacroArgs } from './macro-args';
+import { wrapContent } from './display';
+
+/** The parameters of {timed} and of each {next}: the delay before it shows. */
+const TIMED_PARAMETERS = [DELAY_PARAMETER] as const;
 
 defineMacro({
   name: 'timed',
   subMacros: ['next'],
   interpolate: true,
+  parameters: TIMED_PARAMETERS,
   render({ branches = [] }, ctx) {
     const { useState, useEffect, useMemo } = ctx.hooks;
 
     const sections = useMemo(() => {
       return branches.map((branch) => ({
-        delay: branch.rawArgs ? parseDelay(branch.rawArgs) : 0,
+        delay: parseMacroArgs(branch.rawArgs, TIMED_PARAMETERS).delay ?? 0,
         nodes: branch.children,
         className: branch.className,
         id: branch.id,
@@ -35,21 +40,12 @@ defineMacro({
     if (visibleIndex < 0) return ctx.wrap(null);
 
     const section = sections[visibleIndex]!;
-    const content = ctx.renderNodes(section.nodes);
-    const sectionClass = ctx.resolve!(section.className);
-    const sectionId = ctx.resolve!(section.id);
-
-    const inner =
-      sectionClass || sectionId ? (
-        <span
-          id={sectionId}
-          class={sectionClass}
-        >
-          {content}
-        </span>
-      ) : (
-        content
-      );
-    return ctx.wrap(inner);
+    return ctx.wrap(
+      wrapContent(
+        ctx.resolve!(section.className),
+        ctx.resolve!(section.id),
+        ctx.renderNodes(section.nodes),
+      ),
+    );
   },
 });

package/src/components/macros/Type.tsx

@@ -1,10 +1,11 @@
 import { defineMacro } from '../../define-macro';
+import { DELAY_PARAMETER } from './macro-args';
 
 defineMacro({
   name: 'type',
   block: true,
   interpolate: true,
-  parameters: [{ name: 'delay', type: 'delay', required: true }],
+  parameters: [DELAY_PARAMETER],
   render({ children = [] }, ctx) {
     const { useState, useEffect, useRef } = ctx.hooks;
     const speed = ctx.args.delay ?? 0;

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) {