@rohal12/spindle 0.51.3 → 0.52.0

package/src/define-macro.ts

@@ -15,13 +15,17 @@ import {
   LocalsUpdateContext,
   LocalsValuesContext,
   NobrContext,
+  InlineContext,
+  RawTextContext,
   renderNodes as _renderNodes,
   renderInlineNodes,
 } from './markup/render';
 import type { ASTNode } from './markup/ast';
-import { executeMutation } from './execute-mutation';
+import { executeMutation, readState } from './execute-mutation';
 import { evaluate } from './expression';
 import { useStoryStore } from './store';
+import { getByPath, setByPath } from './utils/object-path';
+import { RESERVED_NAME } from './utils/namespace';
 import { useAction } from './hooks/use-action';
 import type { UseActionOptions } from './hooks/use-action';
 import { collectText } from './utils/extract-text';
@@ -29,12 +33,15 @@ import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
 import {
   registerMacro,
+  registerMacroText,
   registerSubMacro,
   registerMacroMetadata,
 } from './registry';
-import type { MacroProps, ParameterDef } from './registry';
+import type { MacroProps, MacroTextContext, ParameterDef } from './registry';
 import { registerBlockMacro } from './markup/ast';
 
+export type { MacroTextContext };
+
 export function macroClass(type: string, className?: string): string {
   const base = `macro-${type}`;
   return className ? `${base} ${className}` : base;
@@ -89,6 +96,12 @@ export interface MacroDefinition {
   description?: string;
   parameters?: ParameterDef[];
   render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  /**
+   * The macro's text form, used where markup becomes a string: HTML
+   * attribute values, image alt text and link titles, macro labels. Without
+   * one, the macro can't be used there and is reported as an error.
+   */
+  text?: (props: MacroProps, ctx: MacroTextContext) => string;
 }
 
 const sharedHooks = {
@@ -101,33 +114,6 @@ const sharedHooks = {
   useContext,
 };
 
-/** Traverse a dot-path on an object, returning the nested value. */
-function getByPath(obj: Record<string, unknown>, segments: string[]): unknown {
-  let current: unknown = obj;
-  for (const seg of segments) {
-    if (current == null || typeof current !== 'object') return undefined;
-    current = (current as Record<string, unknown>)[seg];
-  }
-  return current;
-}
-
-/** Set a nested value by dot-path segments on an (Immer draft) object. */
-function setByPath(
-  obj: Record<string, unknown>,
-  segments: string[],
-  value: unknown,
-): void {
-  let target: Record<string, unknown> = obj;
-  for (let i = 0; i < segments.length - 1; i++) {
-    const seg = segments[i]!;
-    if (target[seg] == null || typeof target[seg] !== 'object') {
-      target[seg] = {};
-    }
-    target = target[seg] as Record<string, unknown>;
-  }
-  target[segments[segments.length - 1]!] = value;
-}
-
 export function defineMacro(
   config: MacroDefinition,
   source: 'builtin' | 'user' = 'builtin',
@@ -146,11 +132,25 @@ export function defineMacro(
     // Always-on: cssClass + mutation
     const { update, getValues } = useContext(LocalsUpdateContext);
     const nobr = useContext(NobrContext);
+    const inline = useContext(InlineContext);
+    const raw = useContext(RawTextContext);
     const localsValues = useContext(LocalsValuesContext);
     const renderNodes = (
       nodes: ASTNode[],
-      options?: { nobr?: boolean; locals?: Record<string, unknown> },
-    ) => _renderNodes(nodes, { nobr, locals: localsValues, ...options });
+      options?: {
+        nobr?: boolean;
+        locals?: Record<string, unknown>;
+        inline?: boolean;
+        raw?: boolean;
+      },
+    ) =>
+      _renderNodes(nodes, {
+        nobr,
+        inline,
+        raw,
+        locals: localsValues,
+        ...options,
+      });
     const ctx: MacroContext = {
       collectText,
       sourceLocation: currentSourceLocation,
@@ -196,17 +196,22 @@ export function defineMacro(
 
       const varExpr = firstToken.replace(/["']/g, '').replace(/^\$/, '');
       const segments = varExpr.split('.');
+      if (segments.includes(RESERVED_NAME)) {
+        return h(
+          'span',
+          { class: 'error' },
+          `{${config.name}}: "$${varExpr}" cannot be bound: ${RESERVED_NAME} is reserved`,
+        );
+      }
       ctx.varName = varExpr;
       ctx.value = useStoryStore((s) => getByPath(s.variables, segments));
-      ctx.getValue = () =>
-        getByPath(useStoryStore.getState().variables, segments);
+      // In program order, also when mutation code performs the input
+      ctx.getValue = () => getByPath(readState().variables, segments);
       ctx.setValue = (value: unknown) => {
         useStoryStore.setState((state) => {
-          setByPath(
-            state.variables as Record<string, unknown>,
-            segments,
-            value,
-          );
+          setByPath(state.variables, segments, value, {
+            createMissing: true,
+          });
         });
       };
     }
@@ -215,6 +220,7 @@ export function defineMacro(
   }
 
   registerMacro(config.name, Wrapper);
+  registerMacroText(config.name, config.text);
 
   // Store metadata for tooling API
   const isBlock =