@rohal12/spindle 0.45.0 → 0.46.0

package/package.json

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

package/src/define-macro.ts

@@ -88,7 +88,7 @@ export interface MacroDefinition {
   storeVar?: boolean;
   description?: string;
   parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => VNode | null;
+  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
 }
 
 const sharedHooks = {

package/src/types-drift-check.ts

@@ -23,3 +23,71 @@ import type { parseStoryVariables as PublishedParse } from '../types/tooling';
 const _parseSourceToPublished: typeof PublishedParse = {} as typeof SourceParse;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const _parsePublishedToSource: typeof SourceParse = {} as typeof PublishedParse;
+
+// Custom macro API: the published MacroContext/MacroDefinition must match the
+// ones defineMacro() actually passes and accepts.
+import type {
+  MacroContext as SourceMacroContext,
+  MacroDefinition as SourceMacroDefinition,
+} from './define-macro';
+import type { MacroProps as SourceMacroProps } from './registry';
+import type { ASTNode as SourceASTNode } from './markup/ast';
+import type {
+  MacroContext as PublishedMacroContext,
+  MacroDefinition as PublishedMacroDefinition,
+  MacroProps as PublishedMacroProps,
+  ASTNode as PublishedASTNode,
+} from '../types/index';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _ctxSourceToPublished: PublishedMacroContext = {} as SourceMacroContext;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _ctxPublishedToSource: SourceMacroContext = {} as PublishedMacroContext;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _defSourceToPublished: PublishedMacroDefinition =
+  {} as SourceMacroDefinition;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _defPublishedToSource: SourceMacroDefinition =
+  {} as PublishedMacroDefinition;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _propsSourceToPublished: PublishedMacroProps = {} as SourceMacroProps;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _propsPublishedToSource: SourceMacroProps = {} as PublishedMacroProps;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _astSourceToPublished: PublishedASTNode = {} as SourceASTNode;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _astPublishedToSource: SourceASTNode = {} as PublishedASTNode;
+
+// A typical custom macro written against the published types must type-check,
+// and misuse of the hooks must not (no `any` leaking through).
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _exampleMacro: PublishedMacroDefinition = {
+  name: 'counter',
+  block: true,
+  render(props, ctx) {
+    const [count, setCount] = ctx.hooks.useState(0);
+    const countIsNumber: number = count;
+    setCount((n) => n + 1);
+    // @ts-expect-error -- state setter is typed by the initial value
+    setCount('one');
+    const ref = ctx.hooks.useRef<HTMLSpanElement>(null);
+    ctx.hooks.useEffect(() => {
+      ref.current?.focus();
+      return () => undefined;
+    }, [count]);
+    // @ts-expect-error -- deps must be an array
+    ctx.hooks.useEffect(() => undefined, 'count');
+    const doubled: number = ctx.hooks.useMemo(() => count * 2, [count]);
+    const body = ctx.renderNodes(props.children ?? [], { nobr: true });
+    const label: string = ctx.collectText(props.children ?? []);
+    return ctx.wrap(
+      ctx.h(
+        'span',
+        { ref, class: ctx.cls, title: label },
+        body,
+        countIsNumber,
+        doubled,
+      ),
+    );
+  },
+};

package/types/index.d.ts

@@ -1,3 +1,14 @@
+import type { ComponentChildren, VNode, h } from 'preact';
+import type {
+  useState,
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+  useMemo,
+  useContext,
+} from 'preact/hooks';
+
 // Format metadata (used by twee-ts)
 export declare const name: string;
 export declare const version: string;
@@ -242,6 +253,68 @@ export interface MacroMetadata {
   parameters?: ParameterDef[];
 }
 
+/** Plain text in a parsed passage. */
+export interface TextNode {
+  type: 'text';
+  value: string;
+}
+
+/** A variable display such as `{$hp}`, `{_tmp}`, `{@local}` or `{%transient}`. */
+export interface VariableNode {
+  type: 'variable';
+  name: string;
+  scope: 'variable' | 'temporary' | 'local' | 'transient';
+  className?: string;
+  id?: string;
+}
+
+/** An expression display such as `{= $hp * 2}`. */
+export interface ExpressionNode {
+  type: 'expression';
+  expression: string;
+  className?: string;
+  id?: string;
+}
+
+/** One branch of a block macro (`{elseif}`, `{else}`, `{case}`, ...). */
+export interface Branch {
+  rawArgs: string;
+  className?: string;
+  id?: string;
+  children: ASTNode[];
+}
+
+/** A macro invocation, with its body and branches for block macros. */
+export interface MacroNode {
+  type: 'macro';
+  name: string;
+  rawArgs: string;
+  children: ASTNode[];
+  branches?: Branch[];
+  className?: string;
+  id?: string;
+}
+
+/** An HTML element written in passage markup. */
+export interface HtmlNode {
+  type: 'html';
+  tag: string;
+  attributes: Record<string, string>;
+  children: ASTNode[];
+}
+
+/**
+ * A node of a parsed passage. Macros receive their body as `props.children`
+ * and render it with `ctx.renderNodes()`.
+ * @see {@link ../../src/markup/ast.ts} for the implementation.
+ */
+export type ASTNode =
+  | TextNode
+  | VariableNode
+  | ExpressionNode
+  | MacroNode
+  | HtmlNode;
+
 /**
  * Props passed to a macro's render function.
  * @see {@link ../../src/registry.ts} for the implementation.
@@ -250,13 +323,8 @@ export interface MacroProps {
   rawArgs: string;
   className?: string;
   id?: string;
-  children?: any[];
-  branches?: Array<{
-    rawArgs: string;
-    className?: string;
-    id?: string;
-    children: any[];
-  }>;
+  children?: ASTNode[];
+  branches?: Branch[];
 }
 
 /**
@@ -278,8 +346,9 @@ export interface UseActionOptions {
 
 /**
  * Context object passed to a macro's render function alongside props.
- * Internal Preact/AST types are represented as `any` since consumers
- * may not have Preact type definitions installed.
+ *
+ * Rendering helpers and hooks are Preact's own (`preact` is a dependency of
+ * 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 {
@@ -301,26 +370,38 @@ export interface MacroContext {
   setValue?: (value: unknown) => void;
   getValue?: () => unknown;
   evaluate?: (expr: string) => unknown;
-  collectText: (nodes: any[]) => string;
+  /** Concatenate the text nodes of an AST (e.g. a macro body holding a passage name). */
+  collectText: (nodes: ASTNode[]) => string;
+  /** Source location of the current passage, for error messages. */
   sourceLocation: () => string;
   parseVarArgs: (rawArgs: string) => { varName: string; placeholder: string };
-  extractOptions: (children: any[]) => string[];
-  wrap: (content: any) => any;
+  /** Collect the labels of `{option}` sub-macros in a macro body. */
+  extractOptions: (children: ASTNode[]) => string[];
+  /** Wrap content in a `<span>` carrying the macro's class/id, or a fragment if it has neither. */
+  wrap: (content: ComponentChildren) => VNode<any>;
   useAction: (opts: UseActionOptions) => string;
-  h: (type: any, props: any, ...children: any[]) => any;
+  /** Preact's `h` (createElement). */
+  h: typeof h;
+  /** Render AST nodes as block content (markdown, `<p>` wrapping unless nobr). */
   renderNodes: (
-    nodes: any[],
-    options?: { nobr?: boolean; locals?: Record<string, unknown> },
-  ) => any;
-  renderInlineNodes: (nodes: any[]) => any;
+    nodes: ASTNode[],
+    options?: {
+      nobr?: boolean;
+      locals?: Record<string, unknown>;
+      inline?: boolean;
+    },
+  ) => ComponentChildren;
+  /** Render AST nodes as inline content (no markdown block processing). */
+  renderInlineNodes: (nodes: ASTNode[]) => ComponentChildren;
+  /** Preact hooks, shared with Spindle's own Preact instance. */
   hooks: {
-    useState: any;
-    useRef: any;
-    useEffect: any;
-    useLayoutEffect: any;
-    useCallback: any;
-    useMemo: any;
-    useContext: any;
+    useState: typeof useState;
+    useRef: typeof useRef;
+    useEffect: typeof useEffect;
+    useLayoutEffect: typeof useLayoutEffect;
+    useCallback: typeof useCallback;
+    useMemo: typeof useMemo;
+    useContext: typeof useContext;
   };
 }
 
@@ -330,14 +411,21 @@ export interface MacroContext {
  */
 export interface MacroDefinition {
   name: string;
+  /** Sub-macro names (e.g. `['option']`); a non-empty list makes the macro a block macro. */
   subMacros?: string[];
+  /** Accept a `{name}...{/name}` body. Inferred from `subMacros` when omitted. */
   block?: boolean;
+  /** Resolve `{$var}` interpolation in the macro's class/id (`ctx.resolve`). */
   interpolate?: boolean;
+  /** Provide `ctx.merged` and `ctx.evaluate` (variables, temporaries, locals, transients). */
   merged?: boolean;
+  /** Bind the first argument as a story variable (`ctx.varName`, `ctx.value`, `ctx.setValue`). */
   storeVar?: boolean;
+  /** Tooling hint: one-line description shown by editors. */
   description?: string;
+  /** Tooling hint: positional parameters. */
   parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => any;
+  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
 }
 
 /**