@rohal12/spindle 0.52.4 → 0.52.6

package/src/define-macro.ts

@@ -11,12 +11,9 @@ import {
 } from 'preact/hooks';
 import { useInterpolate } from './hooks/use-interpolate';
 import { useMergedLocals } from './hooks/use-merged-locals';
+import { useRenderOptions } from './hooks/use-render-options';
 import {
   LocalsUpdateContext,
-  LocalsValuesContext,
-  NobrContext,
-  InlineContext,
-  RawTextContext,
   renderNodes as _renderNodes,
   renderInlineNodes,
 } from './markup/render';
@@ -31,23 +28,34 @@ 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 {
+  parseMacroArgs,
+  readBoundVariable,
+} from './components/macros/macro-args';
 import {
   registerMacro,
   registerMacroText,
   registerSubMacro,
   registerMacroMetadata,
 } from './registry';
-import type { MacroProps, MacroTextContext, ParameterDef } from './registry';
+import type {
+  MacroArgs,
+  MacroProps,
+  MacroTextContext,
+  ParameterDef,
+} from './registry';
 import { registerBlockMacro } from './markup/ast';
 
-export type { MacroTextContext };
+export type { MacroArgs, MacroTextContext, ParameterDef };
 
 export function macroClass(type: string, className?: string): string {
   const base = `macro-${type}`;
   return className ? `${base} ${className}` : base;
 }
 
-export interface MacroContext {
+export interface MacroContext<A = MacroArgs> {
+  /** The arguments, read into the declared parameters (see ParameterDef). */
+  args: A;
   className?: string;
   id?: string;
   resolve?: (s: string | undefined) => string | undefined;
@@ -86,7 +94,9 @@ export interface MacroContext {
   };
 }
 
-export interface MacroDefinition {
+export interface MacroDefinition<
+  P extends readonly ParameterDef[] = ParameterDef[],
+> {
   name: string;
   subMacros?: string[];
   block?: boolean;
@@ -94,14 +104,20 @@ export interface MacroDefinition {
   merged?: boolean;
   storeVar?: boolean;
   description?: string;
-  parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  parameters?: P;
+  render: (
+    props: MacroProps,
+    ctx: MacroContext<MacroArgs<P>>,
+  ) => 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;
+  text?: (
+    props: MacroProps,
+    ctx: MacroTextContext & { args: MacroArgs<P> },
+  ) => string;
 }
 
 const sharedHooks = {
@@ -114,10 +130,12 @@ const sharedHooks = {
   useContext,
 };
 
-export function defineMacro(
-  config: MacroDefinition,
+export function defineMacro<const P extends readonly ParameterDef[] = []>(
+  config: MacroDefinition<P>,
   source: 'builtin' | 'user' = 'builtin',
 ): void {
+  const parameters: readonly ParameterDef[] = config.parameters ?? [];
+
   function Wrapper(props: MacroProps) {
     // className/id resolved first (interpolate may transform them)
     let className = props.className;
@@ -131,10 +149,7 @@ 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 renderOptions = useRenderOptions();
     const renderNodes = (
       nodes: ASTNode[],
       options?: {
@@ -143,15 +158,9 @@ export function defineMacro(
         inline?: boolean;
         raw?: boolean;
       },
-    ) =>
-      _renderNodes(nodes, {
-        nobr,
-        inline,
-        raw,
-        locals: localsValues,
-        ...options,
-      });
-    const ctx: MacroContext = {
+    ) => _renderNodes(nodes, { ...renderOptions, ...options });
+    const ctx: MacroContext<MacroArgs<P>> = {
+      args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
       collectText,
       sourceLocation: currentSourceLocation,
       parseVarArgs,
@@ -183,8 +192,7 @@ export function defineMacro(
     }
 
     if (config.storeVar) {
-      const firstToken =
-        props.rawArgs.trim().split(/\s+/)[0]?.replace(/["']/g, '') ?? '';
+      const firstToken = readBoundVariable(props.rawArgs).replace(/["']/g, '');
 
       if (firstToken.startsWith('%')) {
         return h(
@@ -220,7 +228,16 @@ export function defineMacro(
   }
 
   registerMacro(config.name, Wrapper);
-  registerMacroText(config.name, config.text);
+  const text = config.text;
+  registerMacroText(
+    config.name,
+    text &&
+      ((props, ctx) =>
+        text(props, {
+          ...ctx,
+          args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
+        })),
+  );
 
   // Store metadata for tooling API
   const isBlock =
@@ -234,7 +251,7 @@ export function defineMacro(
     interpolate: config.interpolate,
     merged: config.merged,
     description: config.description,
-    parameters: config.parameters,
+    parameters: config.parameters && [...config.parameters],
     source,
   });
 

package/src/execute-mutation.ts

@@ -9,9 +9,18 @@ import {
 import { useStoryStore } from './store';
 import type { StoryState, VariableNamespaces } from './store';
 import { execute } from './expression';
-import { deepClone, deepEqual } from './class-registry';
-import { deleteByPath, getByPath, setByPath } from './utils/object-path';
-import { asNamespace } from './utils/namespace';
+import {
+  applyChange,
+  deepClone,
+  deepEqual,
+  diffPaths,
+  isApplied,
+  isMergeable,
+  mergeKeys,
+  type PathChange,
+} from './structural';
+import { getByPath } from './utils/object-path';
+import { asNamespace, hasOwn } from './utils/namespace';
 
 type NamespaceName = keyof VariableNamespaces;
 
@@ -21,11 +30,6 @@ const NAMESPACES: readonly NamespaceName[] = [
   'transient',
 ];
 
-/** A write to one property path of a namespace, or its deletion. */
-type PathChange =
-  | { path: string[]; deleted: false; value: unknown }
-  | { path: string[]; deleted: true };
-
 /**
  * The state of one executing mutation. The code reads and writes `work`.
  * `base` is what `work` started as, with every write made elsewhere during
@@ -76,80 +80,6 @@ export function frozenCopy<T>(value: T): T {
   return freeze(cloneValue(value), true);
 }
 
-/**
- * Objects merged property by property: plain objects and (registered)
- * class instances. Arrays, Map, Set, Date and RegExp are values that are
- * replaced as a whole, since their elements have no stable identity to
- * merge by (a shift moves every index).
- */
-export function isMergeable(value: unknown): value is Record<string, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    !(value instanceof Map) &&
-    !(value instanceof Set) &&
-    !(value instanceof Date) &&
-    !(value instanceof RegExp)
-  );
-}
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
-
-/** Collect the property paths where `work` differs from `base`. */
-function diff(
-  base: Record<string, unknown>,
-  work: Record<string, unknown>,
-  path: string[],
-  changes: PathChange[],
-  ancestors: Set<object>,
-): void {
-  // Stop at cycles; shared (non-cyclic) references are visited per path.
-  if (ancestors.has(work)) return;
-  ancestors.add(work);
-  for (const key of Object.keys(work)) {
-    const b = base[key];
-    const w = work[key];
-    if (!hasOwn(base, key)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    } else if (Object.is(b, w)) {
-      // The same value (an untouched subtree of an Immer update)
-      continue;
-    } else if (
-      isMergeable(b) &&
-      isMergeable(w) &&
-      Object.getPrototypeOf(b) === Object.getPrototypeOf(w)
-    ) {
-      diff(b, w, [...path, key], changes, ancestors);
-    } else if (!deepEqual(b, w)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    }
-  }
-  for (const key of Object.keys(base)) {
-    if (!hasOwn(work, key))
-      changes.push({ path: [...path, key], deleted: true });
-  }
-  ancestors.delete(work);
-}
-
-/** Whether `ns` already holds what `change` would write. */
-function isApplied(ns: Record<string, unknown>, change: PathChange): boolean {
-  const parent = getByPath(ns, change.path.slice(0, -1));
-  if (parent === null || typeof parent !== 'object') return change.deleted;
-  const key = change.path[change.path.length - 1]!;
-  if (!hasOwn(parent, key)) return change.deleted;
-  return (
-    !change.deleted &&
-    deepEqual((parent as Record<string, unknown>)[key], change.value)
-  );
-}
-
-function applyChange(ns: Record<string, unknown>, change: PathChange): void {
-  if (change.deleted) deleteByPath(ns, change.path);
-  else setByPath(ns, change.path, change.value);
-}
-
 /**
  * Apply a write that reached the store while mutations execute to their
  * `work` and `base` copies (see MutationScope), so the code sees it and
@@ -381,11 +311,9 @@ function commitScopes(commits: readonly Commit[]): void {
   const all = commits.map(({ scope, keepRunning }) => ({
     scope,
     keepRunning,
-    changes: NAMESPACES.map((ns) => {
-      const list: PathChange[] = [];
-      diff(scope.base[ns], scope.work[ns], [], list, new Set());
-      return [ns, list] as const;
-    }),
+    changes: NAMESPACES.map(
+      (ns) => [ns, diffPaths(scope.base[ns], scope.work[ns])] as const,
+    ),
   }));
   const changed = all.filter(({ changes }) =>
     changes.some(([, list]) => list.length > 0),
@@ -450,16 +378,8 @@ const running = (): Commit[] =>
 function resync(scope: MutationScope): void {
   const state = useStoryStore.getState();
   for (const ns of NAMESPACES) {
-    const work = scope.work[ns];
-    const stored = state[ns];
-    for (const key of Object.keys(work)) {
-      if (!hasOwn(stored, key)) delete work[key];
-    }
-    for (const key of Object.keys(stored)) {
-      if (!hasOwn(work, key) || !deepEqual(work[key], stored[key])) {
-        work[key] = deepClone(stored[key]);
-      }
-    }
+    // Root by root: a root that differs is replaced with a copy of the store's
+    mergeKeys(scope.work[ns], scope.work[ns], state[ns]);
   }
   scope.base = cloneNamespaces(state);
 }

package/src/hooks/use-render-options.ts

@@ -0,0 +1,26 @@
+import { useContext } from 'preact/hooks';
+import {
+  InlineContext,
+  LocalsValuesContext,
+  NobrContext,
+  RawTextContext,
+} from '../markup/render';
+
+/**
+ * The renderNodes() options of the enclosing content: nobr, inline and raw
+ * rendering and the locals in scope. A macro or widget body rendered with
+ * them renders as the content around it does.
+ */
+export function useRenderOptions(): {
+  nobr: boolean;
+  inline: boolean;
+  raw: boolean;
+  locals: Record<string, unknown>;
+} {
+  return {
+    nobr: useContext(NobrContext),
+    inline: useContext(InlineContext),
+    raw: useContext(RawTextContext),
+    locals: useContext(LocalsValuesContext),
+  };
+}

package/src/markup/render.tsx

@@ -9,6 +9,7 @@ import { markdownToHtml } from './markdown';
 import { h } from 'preact';
 import type { ASTNode, HtmlNode, MacroNode } from './ast';
 import { useTextScope } from '../hooks/use-interpolate';
+import { useRenderOptions } from '../hooks/use-render-options';
 import {
   hasInterpolation,
   interpolateCode,
@@ -524,11 +525,8 @@ function resolveAttributeValue(
 
 function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const scope = useTextScope();
-  const nobr = useContext(NobrContext);
-  const locals = useContext(LocalsValuesContext);
-  const inRaw = useContext(RawTextContext);
+  const { nobr, locals, raw: inRaw, inline: parentInline } = useRenderOptions();
   const inSvg = useContext(SvgContext);
-  const parentInline = useContext(InlineContext);
   const tag = node.tag.toLowerCase();
   const isSvgRoot = tag === 'svg';
   const isRawRoot = !inRaw && (isSvgRoot || PREFORMATTED_ELEMENTS.has(tag));

package/src/registry.ts

@@ -67,12 +67,60 @@ export function isSubMacro(name: string): boolean {
   return subMacros.has(name.toLowerCase());
 }
 
+/**
+ * How a macro argument is read (see components/macros/macro-args.ts).
+ * Quoted strings accept `\"`, `\'` and `\\` escapes.
+ * - `expression`: code, as written (the default).
+ * - `variable`: a variable reference such as `$name` or `"$name"`, as written.
+ * - `string`: one quoted string; anything else leaves the argument unset.
+ * - `text`: one quoted string, or text with any loose quotes stripped.
+ * - `names`: a comma-separated list of names (`@item, @i`).
+ * - `delay`: a duration (`2s`, `500ms`, `300`) in milliseconds.
+ * - `number`: a number.
+ * - `flag`: a keyword, the parameter's name, at the start or end; a boolean.
+ * - `separator`: a word (`of`) or `=` separating the parameters before it
+ *   from those after it; a boolean.
+ * - `options`: keywords, the names of its `parameters`, each followed by a
+ *   quoted string or a number unless it is a flag.
+ */
+export type ParameterType =
+  | 'expression'
+  | 'variable'
+  | 'string'
+  | 'text'
+  | 'names'
+  | 'delay'
+  | 'number'
+  | 'flag'
+  | 'separator'
+  | 'options';
+
 export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
+  type?: ParameterType;
+  /** The options of an `options` parameter. */
+  parameters?: readonly ParameterDef[];
 }
 
+type ArgValue<T, D> = T extends 'flag' | 'separator'
+  ? boolean
+  : T extends 'names'
+    ? string[] | undefined
+    : T extends 'delay' | 'number'
+      ? number | undefined
+      : T extends 'options'
+        ? D extends { parameters: infer Q extends readonly ParameterDef[] }
+          ? Partial<MacroArgs<Q>>
+          : Partial<MacroArgs>
+        : string | undefined;
+
+/** The arguments of a macro declaring `parameters`, by parameter name. */
+export type MacroArgs<P extends readonly ParameterDef[] = ParameterDef[]> = {
+  [D in P[number] as D['name']]: ArgValue<D['type'], D>;
+};
+
 export interface MacroMetadata {
   name: string;
   block: boolean;