@rohal12/spindle 0.52.7 → 0.52.8

package/dist/pkg/macro-registry.json

@@ -182,6 +182,13 @@
       "next"
     ],
     "interpolate": true,
+    "parameters": [
+      {
+        "name": "delay",
+        "type": "delay",
+        "required": true
+      }
+    ],
     "source": "builtin"
   },
   {
@@ -208,6 +215,17 @@
     "name": "widget",
     "block": true,
     "subMacros": [],
+    "parameters": [
+      {
+        "name": "name",
+        "type": "text",
+        "required": true
+      },
+      {
+        "name": "parameters",
+        "type": "expression"
+      }
+    ],
     "source": "builtin"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.52.7",
+  "version": "0.52.8",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/action-registry.ts

@@ -29,6 +29,15 @@ export interface StoryAction {
   perform: (value?: unknown) => void;
 }
 
+/** The fields of a StoryAction that are left out when unset. */
+export const OPTIONAL_ACTION_FIELDS = [
+  'target',
+  'variable',
+  'options',
+  'value',
+  'disabled',
+] as const;
+
 /** A mounted control's hold on its action ID. */
 export interface ActionRegistration {
   /**

package/src/class-registry.ts

@@ -1,10 +1,6 @@
 // Class registry for preserving class instances across clone/save/load cycles.
 
-import { setOwn } from './structural';
-import { hasOwn } from './utils/namespace';
-
-// Copying and comparing story values live with the structural diff
-export { deepClone, deepEqual, type DeepCloneOptions } from './structural';
+import { hasOwn, setOwn } from './utils/namespace';
 
 type Constructor = new (...args: any[]) => any;
 

package/src/components/Passage.tsx

@@ -8,7 +8,7 @@ import {
 import { tokenize } from '../markup/tokenizer';
 import { buildAST, type ASTNode } from '../markup/ast';
 import { renderNodes, NobrContext } from '../markup/render';
-import { useStoryStore } from '../store';
+import { useStoryFields } from '../hooks/use-story-fields';
 import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
 import { emitFromRender } from '../event-emitter';
@@ -40,6 +40,21 @@ export function renderPassageContent(passage: PassageData) {
   return renderNodes(ast, nobr ? { nobr: true } : undefined);
 }
 
+/**
+ * The content of a special passage shown with every passage (PassageHeader,
+ * PassageFooter, PassageDone), or null. One that fails to render is logged
+ * and left out, so it can't take the passage down with it.
+ */
+function renderSpecialPassage(passage: PassageData | undefined) {
+  if (!passage) return null;
+  try {
+    return renderPassageContent(passage);
+  } catch (err) {
+    console.error(`spindle: Error in ${passage.name}:`, err);
+    return null;
+  }
+}
+
 interface PassageProps {
   passage: PassageData;
   dataTransition?: string;
@@ -59,7 +74,7 @@ export function Passage({
   dataTransition,
   navigationId,
 }: PassageProps) {
-  const storyData = useStoryStore((s) => s.storyData);
+  const { storyData } = useStoryFields('storyData');
   const isCodePassage = CODE_PASSAGES.has(passage.name);
   const [doneReady, setDoneReady] = useState(false);
 
@@ -76,35 +91,21 @@ export function Passage({
     }
   }, [passage.content, passage.name]);
 
-  const headerPassage = isCodePassage
-    ? undefined
-    : storyData?.passages.get('PassageHeader');
-  const footerPassage = isCodePassage
-    ? undefined
-    : storyData?.passages.get('PassageFooter');
-  const donePassage = isCodePassage
-    ? undefined
-    : storyData?.passages.get('PassageDone');
-
-  const headerContent = useMemo(() => {
-    if (!headerPassage) return null;
-    try {
-      return renderPassageContent(headerPassage);
-    } catch (err) {
-      console.error('spindle: Error in PassageHeader:', err);
-      return null;
-    }
-  }, [headerPassage?.content]);
+  // Code passages are shown without the special passages
+  const special = (name: string) =>
+    isCodePassage ? undefined : storyData?.passages.get(name);
+  const headerPassage = special('PassageHeader');
+  const footerPassage = special('PassageFooter');
+  const donePassage = special('PassageDone');
 
-  const footerContent = useMemo(() => {
-    if (!footerPassage) return null;
-    try {
-      return renderPassageContent(footerPassage);
-    } catch (err) {
-      console.error('spindle: Error in PassageFooter:', err);
-      return null;
-    }
-  }, [footerPassage?.content]);
+  const headerContent = useMemo(
+    () => renderSpecialPassage(headerPassage),
+    [headerPassage?.content],
+  );
+  const footerContent = useMemo(
+    () => renderSpecialPassage(footerPassage),
+    [footerPassage?.content],
+  );
 
   // Defer PassageDone to after DOM commit
   useEffect(() => {
@@ -112,15 +113,10 @@ export function Passage({
     return () => setDoneReady(false);
   }, [passage.name]);
 
-  const doneContent = useMemo(() => {
-    if (!doneReady || !donePassage) return null;
-    try {
-      return renderPassageContent(donePassage);
-    } catch (err) {
-      console.error('spindle: Error in PassageDone:', err);
-      return null;
-    }
-  }, [doneReady, donePassage?.content]);
+  const doneContent = useMemo(
+    () => (doneReady ? renderSpecialPassage(donePassage) : null),
+    [doneReady, donePassage?.content],
+  );
 
   // Signal that this passage's DOM is committed (after descendants' layout
   // effects, before paint). Runs once per mount: PassageDisplay keys the

package/src/components/PassageDialog.tsx

@@ -3,7 +3,7 @@ import { useCallback, useLayoutEffect, useMemo, useRef } from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes, NobrContext } from '../markup/render';
-import { useStoryStore } from '../store';
+import { useStoryFields } from '../hooks/use-story-fields';
 import { emitFromRender } from '../event-emitter';
 import { useModalFocus } from '../hooks/use-modal-focus';
 import { errorMessage } from '../utils/error-message';
@@ -38,7 +38,7 @@ export function PassageDialog({
   onCloseRef.current = onClose;
   const stableOnClose = useCallback(() => onCloseRef.current(), []);
 
-  const storyData = useStoryStore((s) => s.storyData);
+  const { storyData } = useStoryFields('storyData');
 
   const passage = passageName
     ? storyData?.passages.get(passageName)

package/src/components/StoryInterface.tsx

@@ -1,5 +1,5 @@
 import { useMemo } from 'preact/hooks';
-import { useStoryStore } from '../store';
+import { useStoryFields } from '../hooks/use-story-fields';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderInlineNodes, NobrContext } from '../markup/render';
@@ -9,7 +9,7 @@ const DEFAULT_MARKUP =
   '<header class="story-menubar">{story-title}{back}{forward}{restart}{quicksave}{quickload}{saves}{settings}</header>\n{passage}';
 
 export function StoryInterface() {
-  const storyData = useStoryStore((s) => s.storyData);
+  const { storyData } = useStoryFields('storyData');
 
   const overridePassage = storyData?.passages.get('StoryInterface');
   const markup =

package/src/components/macros/Checkbox.tsx

@@ -1,21 +1,16 @@
 import { defineMacro } from '../../define-macro';
+import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
 
 defineMacro({
   name: 'checkbox',
   storeVar: true,
-  parameters: [
-    { name: 'variable', type: 'variable', required: true },
-    { name: 'label', type: 'text' },
-  ],
+  parameters: [VARIABLE_PARAMETER, { name: 'label', type: 'text' }],
   render(_props, ctx) {
     const label = ctx.args.label ?? '';
 
-    ctx.useAction({
+    useVariableAction(ctx, {
       type: 'checkbox',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
       label: label || ctx.varName || '',
-      variable: ctx.varName,
       value: !!ctx.value,
       perform: (v) => ctx.setValue!(v !== undefined ? !!v : !ctx.value),
     });

package/src/components/macros/Computed.tsx

@@ -1,7 +1,7 @@
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { readState } from '../../execute-mutation';
-import { deepEqual } from '../../class-registry';
+import { deepEqual } from '../../structural';
 import { defineMacro } from '../../define-macro';
 import { MacroError, logMacroError } from './MacroError';
 import { checkVariableName } from '../../utils/namespace';

package/src/components/macros/Cycle.tsx

@@ -1,10 +1,11 @@
 import { defineMacro } from '../../define-macro';
+import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
 
 defineMacro({
   name: 'cycle',
   block: true,
   storeVar: true,
-  parameters: [{ name: 'variable', type: 'variable', required: true }],
+  parameters: [VARIABLE_PARAMETER],
   render({ children = [] }, ctx) {
     const options = ctx.extractOptions(children);
 
@@ -16,14 +17,10 @@ defineMacro({
       ctx.setValue!(options[nextIndex]);
     };
 
-    ctx.useAction({
+    useVariableAction(ctx, {
       type: 'cycle',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
       label: ctx.value == null ? options[0] || '' : String(ctx.value),
-      variable: ctx.varName,
       options,
-      value: ctx.value,
       perform: (v) => {
         if (v !== undefined) {
           ctx.setValue!(v);

package/src/components/macros/ExprDisplay.tsx

@@ -1,41 +1,24 @@
 import { evaluate } from '../../expression';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { display, wrapContent } from './display';
+import type { ExpressionNode } from '../../markup/ast';
 
-interface ExprDisplayProps {
-  expression: string;
-  className?: string;
-  id?: string;
-}
-
-export function ExprDisplay({ expression, className, id }: ExprDisplayProps) {
+/** An expression display: `{$hp + 1}`. */
+export function ExprDisplay({ node }: { node: ExpressionNode }) {
+  const { expression } = node;
   const resolve = useInterpolate();
-  className = resolve(className);
-  id = resolve(id);
+  const className = resolve(node.className);
+  const id = resolve(node.id);
   const [variables, temporary, localsValues, transient] = useMergedLocals();
 
-  let display: string;
+  let text: string;
   try {
-    const value = evaluate(
-      expression,
-      variables,
-      temporary,
-      localsValues,
-      transient,
+    text = display(
+      evaluate(expression, variables, temporary, localsValues, transient),
     );
-    display = value == null ? '' : String(value);
   } catch {
-    display = `{error: ${expression}}`;
+    text = `{error: ${expression}}`;
   }
-
-  if (className || id)
-    return (
-      <span
-        id={id}
-        class={className}
-      >
-        {display}
-      </span>
-    );
-  return <>{display}</>;
+  return wrapContent(className, id, text);
 }

package/src/components/macros/If.tsx

@@ -1,6 +1,23 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import type { Branch } from '../../markup/ast';
+import { selectBranch } from './branches';
+import { wrapContent } from './display';
+
+/**
+ * The {if}/{elseif}/{else} branch whose condition holds, else the {else}
+ * branch, else null: the chain ends at its first bare branch. Throws what a
+ * condition throws.
+ */
+function selectIfBranch(
+  branches: Branch[],
+  evaluate: (expr: string) => unknown,
+): Branch | null {
+  const end = branches.findIndex((branch) => branch.rawArgs === '');
+  return selectBranch(end < 0 ? branches : branches.slice(0, end + 1), (expr) =>
+    Boolean(evaluate(expr)),
+  );
+}
 
 defineMacro({
   name: 'if',
@@ -8,49 +25,26 @@ defineMacro({
   interpolate: true,
   merged: true,
   render({ branches = [] }, ctx) {
-    function renderBranch(branch: Branch) {
-      const children = ctx.renderNodes(branch.children);
-      const cls = ctx.resolve!(branch.className);
-      const branchId = ctx.resolve!(branch.id);
-      if (cls || branchId)
-        return (
-          <span
-            id={branchId}
-            class={cls}
-          >
-            {children}
-          </span>
-        );
-      return <>{children}</>;
-    }
-
-    for (const branch of branches) {
-      if (branch.rawArgs === '') {
-        return renderBranch(branch);
-      }
-
-      try {
-        if (ctx.evaluate!(branch.rawArgs)) {
-          return renderBranch(branch);
-        }
-      } catch (err) {
-        return (
-          <MacroError
-            macro="if"
-            error={err}
-          />
-        );
-      }
+    let branch: Branch | null;
+    try {
+      branch = selectIfBranch(branches, ctx.evaluate!);
+    } catch (err) {
+      return (
+        <MacroError
+          macro="if"
+          error={err}
+        />
+      );
     }
-
-    return null;
+    if (!branch) return null;
+    return wrapContent(
+      ctx.resolve!(branch.className),
+      ctx.resolve!(branch.id),
+      ctx.renderNodes(branch.children),
+    );
   },
   text({ branches = [] }, ctx) {
-    for (const branch of branches) {
-      if (branch.rawArgs === '' || ctx.evaluate(branch.rawArgs)) {
-        return ctx.renderText(branch.children);
-      }
-    }
-    return '';
+    const branch = selectIfBranch(branches, ctx.evaluate);
+    return branch ? ctx.renderText(branch.children) : '';
   },
 });

package/src/components/macros/Include.tsx

@@ -1,4 +1,5 @@
 import { useStoryStore } from '../../store';
+import { useStoryFields } from '../../hooks/use-story-fields';
 import { tokenize } from '../../markup/tokenizer';
 import { buildAST } from '../../markup/ast';
 import { NobrContext } from '../../markup/render';
@@ -16,7 +17,7 @@ defineMacro({
     { name: 'passage', type: 'expression', required: true },
   ],
   render(_props, ctx) {
-    const storyData = useStoryStore((s) => s.storyData);
+    const { storyData } = useStoryFields('storyData');
 
     const { inline } = ctx.args;
     const passageName = evaluatePassageName(ctx.args.passage, ctx.evaluate!);

package/src/components/macros/Listbox.tsx

@@ -1,21 +1,19 @@
 import { defineMacro } from '../../define-macro';
+import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
+import { display } from './display';
 
 defineMacro({
   name: 'listbox',
   subMacros: ['option'],
   storeVar: true,
-  parameters: [{ name: 'variable', type: 'variable', required: true }],
+  parameters: [VARIABLE_PARAMETER],
   render({ children = [] }, ctx) {
     const options = ctx.extractOptions(children);
 
-    ctx.useAction({
+    useVariableAction(ctx, {
       type: 'listbox',
-      key: `$${ctx.varName}`,
-      authorId: ctx.id,
       label: ctx.varName!,
-      variable: ctx.varName,
       options,
-      value: ctx.value,
       perform: (v) => {
         if (v !== undefined) ctx.setValue!(String(v));
       },
@@ -25,7 +23,7 @@ defineMacro({
       <select
         id={ctx.id}
         class={ctx.cls}
-        value={ctx.value == null ? '' : String(ctx.value)}
+        value={display(ctx.value)}
         onChange={(e) => ctx.setValue!((e.target as HTMLSelectElement).value)}
       >
         {options.map((opt) => (

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;