@rohal12/spindle 0.52.5 → 0.52.7

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/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/js-lexer.ts

@@ -397,6 +397,14 @@ const MALFORMED = -2;
 /** A frame result: the scan stops at index `s` inside it (`STOPPED - s`). */
 const STOPPED = -3;
 
+/**
+ * The result of a frame that closes at `end`. `bodyStarted`: the code inside
+ * started a function or class body. That body replaced the one to come, and
+ * is gone once the frame is closed, so after the frame no body is to come —
+ * a scan that skips the frame must know, as must the frames around it.
+ */
+const frameEnd = (end: number, bodyStarted: boolean) => end * 2 + +bodyStarted;
+
 /** The closers whose search for their frame a frame result may depend on. */
 const CLOSERS = [')', ']', '}'] as const;
 const FRAME_KINDS: readonly Frame['kind'][] = [
@@ -423,11 +431,13 @@ function frameKey(f: Frame): number | undefined {
  */
 export interface JsScanCache {
   /**
-   * Where each `{…}` frame, template literal or `${…}` interpolation closes:
-   * the index of its `}` or closing backtick, `UNCLOSED` or `MALFORMED`. The
-   * code inside such a frame lexes the same whatever surrounds it, given
-   * where it opens and its kind — a stray `)` or `]` inside never closes it
-   * — so a later scan entering the same frame skips to its end.
+   * Where each `{…}` frame, template literal or `${…}` interpolation closes,
+   * as a frame result (`frameEnd`): its `}` or closing backtick, and whether
+   * the code inside started a function or class body; or `UNCLOSED` or
+   * `MALFORMED`. The code inside such a frame lexes the same whatever
+   * surrounds it, given where it opens and its kind — a stray `)` or `]`
+   * inside never closes it — so a later scan entering the same frame skips
+   * to its end.
    */
   braces: Map<number, number>;
   /** Look-ahead bracket matches (`ScanContext.brackets`). */
@@ -457,10 +467,8 @@ export interface JsScanCache {
   stacks: Map<string, number>;
   /**
    * How `(…)` and `[…]` frames end, by the kind of scan and then by the frame
-   * (`parenKey`): `end * 2 + 1` if it closes at `end` and the code inside
-   * started a function or class body (which replaced the one to come, and
-   * can't follow once the frame is closed), `end * 2` otherwise, or
-   * `UNCLOSED`, `MALFORMED` or `STOPPED - s`. Unlike braces, a stray closer inside may close a frame
+   * (`parenKey`): a frame result (`frameEnd`), or `UNCLOSED`, `MALFORMED` or
+   * `STOPPED - s`. Unlike braces, a stray closer inside may close a frame
    * around them, so the code inside lexes the same only around frames for
    * which the closers it met find nothing to close; the key says which
    * closers met none.
@@ -748,15 +756,34 @@ function scan(
     : undefined;
   /**
    * How many function or class bodies to come the scan has started, and with
-   * `parens`, that count when each open frame opened. Code in a `(…)` or
-   * `[…]` that starts one replaces the one to come, and the new one can't
-   * follow once the frame is closed: none is to come then.
+   * `braces` or `parens`, that count when each open frame opened. Code in a
+   * frame that starts one replaces the one to come, and the new one can't
+   * follow once the frame is closed: none is to come then. A scan skipping
+   * the frame learns this from its result (`frameEnd`, `resume`), and counts
+   * the body as started too, for the frames around it to record.
    */
   let bodyStarts = 0;
-  const startsAt: number[] | undefined = parens ? [0] : undefined;
+  const startsAt: number[] | undefined = braces || parens ? [0] : undefined;
   /** A `(…)` or `[…]` frame result found in `parens`, to skip to. */
   let parenTo: { frame: Frame; result: number } | undefined;
 
+  /** The result of the frame at index `k`, closing at `i`. */
+  const closedAt = (k: number) =>
+    frameEnd(i, startsAt !== undefined && bodyStarts !== startsAt[k]);
+
+  /**
+   * Go on after a frame an earlier scan lexed, whose result (`frameEnd`) is
+   * `result`: returns the index it closes at. A body started in it is gone
+   * after it, with the one it replaced.
+   */
+  function resume(result: number): number {
+    if (result % 2 === 1) {
+      pendingBody = undefined;
+      bodyStarts++;
+    }
+    return Math.floor(result / 2);
+  }
+
   /** The closer `c` looked for its frame and found index `k`. */
   function lookedFor(c: (typeof CLOSERS)[number], k: number) {
     if (!lowest) return;
@@ -933,8 +960,8 @@ function scan(
     if (lowest) {
       for (let j = frames.length - 1; j >= k; j--) foldLowest(j);
       lowest.length = k;
-      startsAt!.length = k;
     }
+    if (startsAt) startsAt.length = k;
     frames.length = k;
     if (stackIds) stackIds.length = k;
     for (const list of Object.values(closers)) {
@@ -1034,6 +1061,19 @@ function scan(
     keyNext = f.kind === 'object' || f.kind === 'class';
   }
 
+  /**
+   * Go past frame `f` if an earlier scan lexed it: to just after it, or to
+   * the end of the source when it never closes. Whether it did, or
+   * MALFORMED when that scan found the code malformed.
+   */
+  function skipLexed(f: Frame): boolean | typeof MALFORMED {
+    const end = known(f);
+    if (end === undefined) return false;
+    if (end === MALFORMED) return MALFORMED;
+    i = end === UNCLOSED ? src.length : resume(end) + 1;
+    return true;
+  }
+
   function openBrace() {
     let f: Frame;
     if (pendingBody?.depth === frames.length) {
@@ -1079,12 +1119,11 @@ function scan(
       return;
     }
     const closed = frames[k]!;
+    const result = closedAt(k);
     if (lowest && c !== '}') {
       // Its entry complete, with those of the frames still open in it
       for (let j = frames.length - 1; j > k; j--) foldLowest(j);
-      // Whether code in it started a function or class body: none is to come
-      const bodyStarted = bodyStarts !== startsAt![k];
-      recordParen(k, i * 2 + +bodyStarted);
+      recordParen(k, result);
     }
     truncate(k);
     if (c === ']' && !ctx.lookahead) ctx.brackets.set(closed.open, i);
@@ -1095,7 +1134,7 @@ function scan(
     } else if (c === ']') {
       endPunct(c, false);
     } else {
-      record(closed, i);
+      record(closed, result);
       afterBrace(closed);
     }
   }
@@ -1214,24 +1253,17 @@ function scan(
       } else if (ch === '`') {
         literal(ch, i);
         if (frames.length === 1) return i + 1; // the end of `lexTemplate`
-        record(top(), i);
+        record(top(), closedAt(frames.length - 1));
         i++;
         truncate(frames.length - 1);
         endOperand();
       } else if (ch === '$' && src.charAt(i + 1) === '{') {
         const f = frame('expr', '}', i);
         f.interpolation = true;
-        const end = known(f);
-        if (end === MALFORMED) return malformed();
-        if (end === UNCLOSED) {
-          i = src.length;
-          break;
-        }
-        if (end !== undefined) {
-          // An interpolation an earlier scan lexed: on with the text after it
-          i = end + 1;
-          continue;
-        }
+        // An interpolation an earlier scan lexed: on with the text after it
+        const skipped = skipLexed(f);
+        if (skipped === MALFORMED) return malformed();
+        if (skipped) continue;
         literal('${', i);
         i += 2;
         nesting++;
@@ -1261,15 +1293,10 @@ function scan(
     if (ch === '`') {
       endWord();
       const f = frame('template', '`', i);
-      const end = known(f);
-      if (end === MALFORMED) return malformed();
-      if (end === UNCLOSED) {
-        i = src.length;
-        break;
-      }
-      if (end !== undefined) {
-        // A template literal an earlier scan lexed: on after it
-        i = end + 1;
+      // A template literal an earlier scan lexed: on after it
+      const skipped = skipLexed(f);
+      if (skipped === MALFORMED) return malformed();
+      if (skipped) {
         endOperand();
         continue;
       }
@@ -1291,7 +1318,7 @@ function scan(
       lookedFor('}', k);
       if (frames[k]!.interpolation) {
         endWord();
-        record(frames[k]!, i);
+        record(frames[k]!, closedAt(k));
         truncate(k);
         nesting--;
         literal(ch, i);
@@ -1399,8 +1426,17 @@ function scan(
       }
     }
 
-    // End of an `outer` square bracket
-    if (ch === outer.closer && frames.length === 1) break;
+    // End of an `outer` square bracket: a `]` that closes no `[` within the
+    // innermost braces closes it, over any `(` left open in it, as it closes
+    // a nested `[`. Look-ahead scans record where the `[`s nested in theirs
+    // end (`ctx.brackets`), so one starting at a `[` must find the same.
+    if (
+      ch === outer.closer &&
+      (frames.length === 1 ||
+        (ch === ']' && innermost(']') === 0 && innermost('}') === 0))
+    ) {
+      break;
+    }
 
     // Regular code character
     trackCode(ch);
@@ -1413,7 +1449,7 @@ function scan(
         i = src.length;
         break;
       }
-      i = end;
+      i = resume(end);
       afterBrace(skipped);
       i++;
       continue;
@@ -1432,8 +1468,7 @@ function scan(
         strict!.stopped = true;
         return STOPPED - result;
       }
-      i = Math.floor(result / 2);
-      if (result % 2 === 1) pendingBody = undefined;
+      i = resume(result);
       if (skipped.closer === ')') {
         endPunct(')', skipped.header);
         stmtNext = skipped.header;

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;

package/types/index.d.ts

@@ -239,6 +239,35 @@ export interface StorageQuota {
   estimateSupported: boolean;
 }
 
+/**
+ * How a macro argument is read into `ctx.args`. 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.
+ * @see {@link ../../src/registry.ts} for the implementation.
+ */
+export type ParameterType =
+  | 'expression'
+  | 'variable'
+  | 'string'
+  | 'text'
+  | 'names'
+  | 'delay'
+  | 'number'
+  | 'flag'
+  | 'separator'
+  | 'options';
+
 /**
  * Parameter metadata for a macro definition.
  * @see {@link ../../src/registry.ts} for the implementation.
@@ -247,8 +276,32 @@ export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
+  /** How the argument is read (default `expression`). */
+  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;
+
+/**
+ * A macro's arguments (`ctx.args`), by parameter name.
+ * @see {@link ../../src/registry.ts} for the implementation.
+ */
+export type MacroArgs<P extends readonly ParameterDef[] = ParameterDef[]> = {
+  [D in P[number] as D['name']]: ArgValue<D['type'], D>;
+};
+
 /**
  * Metadata about a registered macro, returned by `Story.getMacroRegistry()`.
  * @see {@link ../../src/registry.ts} for the implementation.
@@ -363,7 +416,9 @@ export interface UseActionOptions {
  * this package), so `ctx.hooks.useState<T>()`, `ctx.h()` etc. are fully typed.
  * @see {@link ../../src/define-macro.ts} for the implementation.
  */
-export interface MacroContext {
+export interface MacroContext<A = MacroArgs> {
+  /** The arguments, read into the macro's declared `parameters`. */
+  args: A;
   className?: string;
   id?: string;
   resolve?: (s: string | undefined) => string | undefined;
@@ -437,7 +492,9 @@ export interface MacroTextContext {
  * Configuration object for `Story.defineMacro()`.
  * @see {@link ../../src/define-macro.ts} for the implementation.
  */
-export interface MacroDefinition {
+export interface MacroDefinition<
+  P extends readonly ParameterDef[] = ParameterDef[],
+> {
   name: string;
   /** Sub-macro names (e.g. `['option']`); a non-empty list makes the macro a block macro. */
   subMacros?: string[];
@@ -451,15 +508,21 @@ export interface MacroDefinition {
   storeVar?: boolean;
   /** Tooling hint: one-line description shown by editors. */
   description?: string;
-  /** Tooling hint: positional parameters. */
-  parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  /** The parameters: read into `ctx.args`, and shown by tooling. */
+  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;
 }
 
 /**

package/types/tooling.d.ts

@@ -1,7 +1,39 @@
+/**
+ * How a macro argument is read into `ctx.args`. 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;
+  /** How the argument is read (default `expression`). */
+  type?: ParameterType;
+  /** The options of an `options` parameter. */
+  parameters?: readonly ParameterDef[];
 }
 
 export interface MacroMetadata {
@@ -24,7 +56,7 @@ export interface MacroDefinition {
   merged?: boolean;
   storeVar?: boolean;
   description?: string;
-  parameters?: ParameterDef[];
+  parameters?: readonly ParameterDef[];
   render: (...args: any[]) => any;
   text?: (...args: any[]) => string;
 }