sfn-diagram-react 0.4.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ npm install sfn-diagram-react sfn-diagram
 pnpm add sfn-diagram-react sfn-diagram
 ```
 
-`react` and `sfn-diagram` are peer dependencies.
+`react` and `sfn-diagram` are peer dependencies. `sfn-diagram >= 1.6.0` is required — earlier versions don't have the options this package forwards (`collapse`, `catchHandling`, `showVariables`, `generateHtml`, and `edgeOverrides`' qualified-id form).
 
 ## Usage
 
@@ -58,20 +58,160 @@ emphasized, and per-state duration and retry counts are annotated.
 `history` accepts a `GetExecutionHistory` events array, the raw command output, or a
 JSON string of either. In the browser, pass the JSON string.
 
+`history` and `before` (diff mode, below) cannot be combined — core has no API for
+overlaying an execution onto a diff. Combining them calls `onError` and renders `null`,
+the same way any other invalid input is handled.
+
+**`format="mermaid"` combined with `history` ignores every other diagram option** —
+`catchHandling`, `collapse`, `edgeStyle`, `showVariables`, and the rest. Core's
+Mermaid execution-overlay function (`generateMermaidExecution`) accepts only the ASL
+definition, `history`, `layout`, and `theme`; unlike the plain Mermaid path
+(`generateMermaid`), which honours the full option set. The SVG execution overlay is
+unaffected — it honours every option.
+
+### Interactive viewer (`format="html"`)
+
+Set `format="html"` to render the full interactive pan/zoom/search viewer instead of
+static markup. Since embedding a complete HTML *document* is only possible in an
+`<iframe>`, that's what this renders — as a sandboxed `srcDoc`, not a same-origin embed.
+Consequences worth knowing:
+
+- Page CSS does not reach the iframe's content — style it via the diagram options
+  (`theme`, `customColors` are not exposed by this package yet — file an issue if you
+  need them) rather than page-level CSS.
+- The iframe has no intrinsic height; size it yourself (`style={{ height: 600 }}`, or a
+  wrapper with a fixed aspect ratio).
+- `onStateClick` does not fire from inside it — clicks inside a sandboxed iframe never
+  reach the parent document's event handlers.
+- `history` cannot be combined with `format="html"` — core's `generateHtml` accepts
+  neither `history` nor a diff. Combining them calls `onError` and renders `null`.
+
+```tsx
+<SfnDiagram definition={definition} format="html" style={{ height: 600, width: '100%' }} />
+```
+
+Give the iframe a `title` (defaults to `'Step Functions diagram'`) when a page renders
+more than one, so screen readers can tell them apart.
+
+### Diff mode
+
+Pass `before` to render a diff instead of a plain diagram: `definition` becomes the
+*after* side and `before` the original side. Added, modified, and removed states are
+coloured (green / yellow / red) instead of the machine's normal styling.
+
+```tsx
+<SfnDiagram before={previousDefinition} definition={definition} />
+```
+
+- `before` accepts an ASL object or a JSON string, same as `definition`.
+- `before` cannot be combined with `history` or `format="html"` — core has no diff API
+  for either combination. Combining them calls `onError` and renders `null`.
+- The **SVG diff** (`generateDiff`) honours every diagram option this package forwards
+  (`collapse`, `catchHandling`, `showIcons`, and the rest).
+- The **Mermaid diff** (`generateMermaidDiff`) accepts only the two definitions — every
+  other prop (`layout`, `theme`, `collapse`, …) is silently ignored in `format="mermaid"`
+  diff mode.
+
+### `onStateClick`
+
+Fires when a state node is clicked, SVG format only:
+
+```tsx
+<SfnDiagram
+    definition={definition}
+    onStateClick={({ stateId }) => console.log('clicked', stateId)}
+/>
+```
+
+- Not invoked for `format="mermaid"` (no clickable elements) or `format="html"` (the
+  sandboxed iframe's clicks never reach the parent document).
+- `stateId` is the graph node id, which equals the state name for every state whose
+  name is unique across the machine. A nested state whose name repeats elsewhere in the
+  machine gets an id qualified by its scope — read it off the rendered `data-state-id`
+  attribute rather than assuming the bare name.
+- No click listener is attached at all when `onStateClick` is omitted.
+
+### Imperative handle
+
+`SfnDiagram` forwards a `ref` exposing `{ getSvg(): string | null }` — the rendered SVG
+markup for `format="svg"`, or `null` for every other format (including an errored
+render):
+
+```tsx
+const ref = useRef<SfnDiagramHandle>(null)
+<SfnDiagram definition={definition} ref={ref} />
+// later: ref.current?.getSvg()
+```
+
+There is no programmatic zoom/pan control — core doesn't expose the interactive
+viewer's controller from a public subpath yet, so a meaningful pan/zoom handle needs a
+core change first.
+
+### `useSfnDiagram`
+
+For the raw output — the SVG/HTML string, Mermaid code, dimensions, and metadata —
+without mounting anything, use the hook `<SfnDiagram>` is built on:
+
+```tsx
+import { useSfnDiagram } from 'sfn-diagram-react'
+
+function DownloadSvgButton({ definition }: { definition: object }) {
+    const result = useSfnDiagram({ definition })
+    if (result.type !== 'svg') return null
+
+    const href = `data:image/svg+xml;base64,${btoa(result.svg)}`
+    return (
+        <a download="diagram.svg" href={href}>
+            Download SVG
+        </a>
+    )
+}
+```
+
+It accepts the same option-bearing props as `<SfnDiagram>` (`before`, `definition`,
+`format`, `history`, plus every diagram option below) — just not the presentational
+ones (`className`, `onError`, `onStateClick`, `style`, `title`). Errors are returned as
+`{ type: 'error', error }` rather than thrown.
+
 ## Props
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `definition` | `object \| string` | — (required) | ASL definition as an object or JSON string |
-| `format` | `'svg' \| 'mermaid'` | `'svg'` | Render an SVG diagram or emit Mermaid code |
-| `history` | `HistoryEvent[] \| GetExecutionHistoryCommandOutput \| string` | — | Execution history; when set, renders an execution overlay |
-| `layout` | `'TB' \| 'LR' \| 'RL' \| 'BT'` | `'TB'` | Graph layout direction |
-| `theme` | `'light' \| 'dark' \| CustomTheme` | `'light'` | Diagram theme |
-| `onError` | `(error: Error) => void` | — | Called when the definition fails to parse/render |
-| `className` | `string` | — | Applied to the wrapper element |
-| `style` | `React.CSSProperties` | — | Applied to the wrapper element |
-
-When the definition is invalid the component renders `null` and (if provided) calls `onError`.
+| Prop | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `before` | `object \| string` | — | svg, mermaid | The *original* side of a diff; `definition` becomes the *after* side. See [Diff mode](#diff-mode). |
+| `catchHandling` | `'hide' \| 'show'` | `'show'` | svg, mermaid¹ | `'hide'` drops Catch error edges and handler-only nodes. |
+| `className` | `string` | — | all | Applied to the wrapper element (`div`, `pre`, or `iframe`). |
+| `collapse` | `string[] \| boolean` | — | svg, mermaid¹ | Collapse Parallel/Map containers into a placeholder node. `true` collapses every container; an array collapses only the named ones. |
+| `definition` | `object \| string` | — (required) | all | ASL definition as an object or JSON string. |
+| `edgeOverrides` | `Record<string, EdgeStyleOverride>` | — | svg only | Per-edge style overrides keyed by `GraphEdge.id` (preferred, e.g. `Route->Work#choice#1`) or the legacy bare `${from}->${to}` (broad-matches every edge between that pair). |
+| `edgeStyle` | `'straight' \| 'curved' \| 'orthogonal'` | `'curved'` | svg, mermaid¹ | Edge path rendering style. |
+| `format` | `'svg' \| 'mermaid' \| 'html'` | `'svg'` | — | Output format. See [Interactive viewer](#interactive-viewer-formathtml) for `'html'`. |
+| `history` | `HistoryEvent[] \| GetExecutionHistoryCommandOutput \| string` | — | svg, mermaid | Execution history; when set, renders an execution overlay. See [Execution overlay](#execution-overlay). |
+| `iconPosition` | `'left' \| 'top' \| 'right'` | `'left'` | svg only | Position of AWS service icons relative to the node label. |
+| `iconSize` | `number` | `24` | svg only | Size of AWS service icons in pixels. |
+| `layout` | `'TB' \| 'LR' \| 'RL' \| 'BT'` | `'TB'` | svg, mermaid | Graph layout direction. |
+| `nodeOverrides` | `Record<string, Partial<NodeStyle>>` | — | svg only | Per-node style overrides keyed by graph node id. |
+| `onError` | `(error: Error) => void` | — | all | Called when the definition fails to parse/render. |
+| `onStateClick` | `(params: { event, stateId }) => void` | — | svg only | See [`onStateClick`](#onstateclick). |
+| `showIcons` | `boolean` | `false` | svg only | Whether to display AWS service icons on Task state nodes. |
+| `showVariables` | `boolean` | `true` | svg, mermaid¹ | Whether to annotate nodes with the variables they assign via ASL `Assign`. |
+| `style` | `React.CSSProperties` | — | all | Applied to the wrapper element. |
+| `theme` | `'light' \| 'dark' \| CustomTheme` | `'light'` | svg, mermaid | Diagram theme. |
+| `title` | `string` | `'Step Functions diagram'` | html only | Accessible title for the rendered iframe. |
+
+¹ Ignored when `format="mermaid"` is combined with `history` — see
+[Execution overlay](#execution-overlay). Applies normally to plain `format="mermaid"`
+(no `history`). `format="mermaid"` diff mode (the `before` prop) is a separate
+carve-out with its own rule — see [Diff mode](#diff-mode).
+
+When the definition is invalid the component renders `null` and (if provided) calls
+`onError`.
+
+**Memoize object-valued props.** `collapse` (as an array), `nodeOverrides`,
+`edgeOverrides`, and a `CustomTheme` object for `theme` are all things a consumer might
+inline in JSX. An inline object or array is referentially unstable — a different
+reference on every render — which re-triggers this component's internal memo and a
+full re-layout each time, even though nothing actually changed. Hoist them to a
+constant or wrap them in `useMemo` if you re-render often.
 
 ## License
 

package/dist/index.cjs

@@ -1,59 +1,200 @@
+'use client'
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react = require("react");
 let sfn_diagram = require("sfn-diagram");
 let react_jsx_runtime = require("react/jsx-runtime");
-//#region src/SfnDiagram.tsx
-function SfnDiagram({ className, definition, format = "svg", history, layout = "TB", onError, style, theme = "light" }) {
-	const asl = (0, react.useMemo)(() => typeof definition === "string" ? definition : JSON.stringify(definition), [definition]);
-	const result = (0, react.useMemo)(() => {
+//#region src/useSfnDiagram.ts
+function toAslString(params) {
+	const { definition } = params;
+	return typeof definition === "string" ? definition : JSON.stringify(definition);
+}
+function omitUndefinedValues(options) {
+	const result = {};
+	for (const key of Object.keys(options)) if (options[key] !== void 0) result[key] = options[key];
+	return result;
+}
+/**
+* Generate a Step Functions diagram and return the raw output - SVG or HTML
+* markup, Mermaid code, dimensions, and metadata - without rendering it.
+*
+* This is the same generation logic `<SfnDiagram>` runs internally, exposed
+* directly for a consumer who needs the underlying string or metadata rather
+* than mounted markup - for example, building a data URI for `<img src>`, a
+* download button, or a custom render target.
+*
+* @param params - The same option-bearing props `<SfnDiagram>` accepts, minus
+* the presentational ones (`className`, `onError`, `onStateClick`, `style`,
+* `title`).
+* @returns A {@link SfnDiagramResult} discriminated union. Errors are returned
+* as `{ type: 'error', error }` rather than thrown.
+*
+* @example
+* ```tsx
+* function DownloadSvgButton({ definition }: { definition: object }) {
+*     const result = useSfnDiagram({ definition })
+*     if (result.type !== 'svg') return null
+*
+*     const href = `data:image/svg+xml;base64,${btoa(result.svg)}`
+*     return <a download="diagram.svg" href={href}>Download SVG</a>
+* }
+* ```
+*/
+function useSfnDiagram(params) {
+	const { before, catchHandling, collapse, definition, edgeOverrides, edgeStyle, format = "svg", history, iconPosition, iconSize, layout = "TB", nodeOverrides, showIcons, showVariables, theme = "light" } = params;
+	const asl = (0, react.useMemo)(() => toAslString({ definition }), [definition]);
+	const beforeAsl = (0, react.useMemo)(() => before === void 0 ? void 0 : toAslString({ definition: before }), [before]);
+	return (0, react.useMemo)(() => {
 		try {
-			if (format === "mermaid") return {
-				type: "mermaid",
-				code: (history ? (0, sfn_diagram.generateMermaidExecution)({
+			const diagramOptions = omitUndefinedValues({
+				catchHandling,
+				collapse,
+				edgeOverrides,
+				edgeStyle,
+				iconPosition,
+				iconSize,
+				layout,
+				nodeOverrides,
+				showIcons,
+				showVariables,
+				theme
+			});
+			if (beforeAsl !== void 0) {
+				if (history) throw new Error("history and before cannot be combined");
+				if (format === "html") throw new Error("before and format=\"html\" cannot be combined");
+				if (format === "mermaid") {
+					const output = (0, sfn_diagram.generateMermaidDiff)({
+						after: asl,
+						before: beforeAsl
+					});
+					return {
+						code: output.code,
+						metadata: output.metadata,
+						type: "mermaid"
+					};
+				}
+				const output = (0, sfn_diagram.generateDiff)({
+					after: asl,
+					before: beforeAsl,
+					...diagramOptions
+				});
+				return {
+					height: output.height,
+					metadata: output.metadata,
+					svg: output.svg,
+					type: "svg",
+					width: output.width
+				};
+			}
+			if (format === "html") {
+				if (history) throw new Error("history and format=\"html\" cannot be combined");
+				const output = (0, sfn_diagram.generateHtml)({
 					aslDefinition: asl,
-					history
-				}) : (0, sfn_diagram.generateMermaid)({ aslDefinition: asl })).code
-			};
-			return {
-				type: "svg",
-				svg: (history ? (0, sfn_diagram.generateExecution)({
+					...diagramOptions
+				});
+				return {
+					height: output.height,
+					html: output.html,
+					metadata: output.metadata,
+					type: "html",
+					width: output.width
+				};
+			}
+			if (format === "mermaid") {
+				const output = history ? (0, sfn_diagram.generateMermaidExecution)({
 					aslDefinition: asl,
 					history,
-					layout,
-					theme
-				}) : (0, sfn_diagram.generateSvg)({
+					...diagramOptions
+				}) : (0, sfn_diagram.generateMermaid)({
 					aslDefinition: asl,
-					layout,
-					theme
-				})).svg
+					...diagramOptions
+				});
+				return {
+					code: output.code,
+					metadata: output.metadata,
+					type: "mermaid"
+				};
+			}
+			const output = history ? (0, sfn_diagram.generateExecution)({
+				aslDefinition: asl,
+				history,
+				...diagramOptions
+			}) : (0, sfn_diagram.generateSvg)({
+				aslDefinition: asl,
+				...diagramOptions
+			});
+			return {
+				height: output.height,
+				metadata: output.metadata,
+				svg: output.svg,
+				type: "svg",
+				width: output.width
 			};
 		} catch (err) {
 			return {
-				type: "error",
-				error: err instanceof Error ? err : new Error(String(err))
+				error: err instanceof Error ? err : new Error(String(err)),
+				type: "error"
 			};
 		}
 	}, [
 		asl,
+		beforeAsl,
+		catchHandling,
+		collapse,
+		edgeOverrides,
+		edgeStyle,
 		format,
 		history,
+		iconPosition,
+		iconSize,
 		layout,
+		nodeOverrides,
+		showIcons,
+		showVariables,
 		theme
 	]);
-	if (result.type === "error") {
+}
+//#endregion
+//#region src/SfnDiagram.tsx
+const SfnDiagram = (0, react.forwardRef)(function SfnDiagram({ className, onError, onStateClick, style, title = "Step Functions diagram", ...diagramParams }, ref) {
+	const result = useSfnDiagram(diagramParams);
+	(0, react.useImperativeHandle)(ref, () => ({ getSvg: () => result.type === "svg" ? result.svg : null }), [result]);
+	const handleStateClick = (0, react.useCallback)((event) => {
+		const stateId = (event.target instanceof Element ? event.target : null)?.closest("[data-state-id]")?.getAttribute("data-state-id");
+		if (stateId) onStateClick?.({
+			event,
+			stateId
+		});
+	}, [onStateClick]);
+	const reportedResult = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		if (result.type !== "error") {
+			reportedResult.current = null;
+			return;
+		}
+		if (reportedResult.current === result) return;
+		reportedResult.current = result;
 		onError?.(result.error);
-		return null;
-	}
+	}, [onError, result]);
+	if (result.type === "error") return null;
 	if (result.type === "mermaid") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
 		className,
 		style,
 		children: result.code
 	});
+	if (result.type === "html") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("iframe", {
+		className,
+		sandbox: "allow-scripts",
+		srcDoc: result.html,
+		style,
+		title
+	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		className,
 		dangerouslySetInnerHTML: { __html: result.svg },
+		onClick: onStateClick ? handleStateClick : void 0,
 		style
 	});
-}
+});
 //#endregion
 exports.SfnDiagram = SfnDiagram;
+exports.useSfnDiagram = useSfnDiagram;

package/dist/index.d.cts

@@ -1,33 +1,124 @@
-import * as _$react from "react";
-import { ExecutionHistoryInput, LayoutDirection, ThemeOption } from "sfn-diagram";
 
-//#region src/SfnDiagram.d.ts
-interface SfnDiagramProps {
-  className?: string;
+import { DiagramOptions, DiffOutput, ExecutionHistoryInput, ExecutionOutput, HtmlOutput, MermaidDiffOutput, MermaidExecutionOutput, MermaidOutput, SvgOutput } from "sfn-diagram";
+//#region src/useSfnDiagram.d.ts
+interface UseSfnDiagramParams extends Pick<DiagramOptions, 'catchHandling' | 'collapse' | 'edgeOverrides' | 'edgeStyle' | 'iconPosition' | 'iconSize' | 'layout' | 'nodeOverrides' | 'showIcons' | 'showVariables' | 'theme'> {
+  /**
+   * When set, `definition` is treated as the *after* side of a diff and `before`
+   * as the *original* side: the rendered diagram highlights added, modified, and
+   * removed states rather than the plain machine. Accepts an ASL object or a
+   * JSON string. Cannot be combined with `history` or `format="html"` - core has
+   * no diff API for either combination.
+   *
+   * The Mermaid diff (`generateMermaidDiff`) ignores every option in this
+   * type's `Pick<DiagramOptions, ...>` list - `layout`, `theme`, and the rest -
+   * since core's diff-specific function accepts only the two definitions. The
+   * SVG diff honours them.
+   */
+  before?: object | string;
   definition: object | string;
-  format?: 'mermaid' | 'svg';
+  /**
+   * Output format. `'svg'` and `'mermaid'` render static markup; `'html'` renders
+   * the interactive pan/zoom/search viewer as a self-contained HTML document.
+   * Cannot be combined with `history`.
+   * @default 'svg'
+   */
+  format?: 'html' | 'mermaid' | 'svg';
   /**
    * Optional execution history. When provided, the diagram is rendered as an
    * execution overlay: states are coloured by outcome, the taken path is
    * emphasized, and per-state duration / retry counts are annotated.
    * Accepts a GetExecutionHistory events array, the raw command output, or a
-   * JSON string of either.
+   * JSON string of either. Cannot be combined with `format="html"`.
    */
   history?: ExecutionHistoryInput;
-  layout?: LayoutDirection;
+}
+/** Result of {@link useSfnDiagram} - the raw output of whichever core function the params select. */
+type SfnDiagramResult = {
+  error: Error;
+  type: 'error';
+} | {
+  height: number;
+  html: string;
+  metadata: HtmlOutput['metadata'];
+  type: 'html';
+  width: number;
+} | {
+  code: string;
+  metadata: MermaidDiffOutput['metadata'] | MermaidExecutionOutput['metadata'] | MermaidOutput['metadata'];
+  type: 'mermaid';
+} | {
+  height: number;
+  metadata: DiffOutput['metadata'] | ExecutionOutput['metadata'] | SvgOutput['metadata'];
+  svg: string;
+  type: 'svg';
+  width: number;
+};
+/**
+ * Generate a Step Functions diagram and return the raw output - SVG or HTML
+ * markup, Mermaid code, dimensions, and metadata - without rendering it.
+ *
+ * This is the same generation logic `<SfnDiagram>` runs internally, exposed
+ * directly for a consumer who needs the underlying string or metadata rather
+ * than mounted markup - for example, building a data URI for `<img src>`, a
+ * download button, or a custom render target.
+ *
+ * @param params - The same option-bearing props `<SfnDiagram>` accepts, minus
+ * the presentational ones (`className`, `onError`, `onStateClick`, `style`,
+ * `title`).
+ * @returns A {@link SfnDiagramResult} discriminated union. Errors are returned
+ * as `{ type: 'error', error }` rather than thrown.
+ *
+ * @example
+ * ```tsx
+ * function DownloadSvgButton({ definition }: { definition: object }) {
+ *     const result = useSfnDiagram({ definition })
+ *     if (result.type !== 'svg') return null
+ *
+ *     const href = `data:image/svg+xml;base64,${btoa(result.svg)}`
+ *     return <a download="diagram.svg" href={href}>Download SVG</a>
+ * }
+ * ```
+ */
+export declare function useSfnDiagram(params: UseSfnDiagramParams): SfnDiagramResult;
+//#endregion
+//#region src/SfnDiagram.d.ts
+interface SfnDiagramProps extends UseSfnDiagramParams {
+  className?: string;
   onError?: (error: Error) => void;
+  /**
+   * Called when a state node is clicked. SVG format only - a click inside the
+   * sandboxed `format="html"` iframe does not reach this handler, and Mermaid
+   * output has no clickable elements. `stateId` is the graph node id, which
+   * equals the state name for every state whose name is unique across the
+   * machine; for a nested state whose name repeats elsewhere in the machine the
+   * id is qualified by its scope, so read it off the rendered `data-state-id`
+   * rather than assuming the bare name.
+   */
+  onStateClick?: (params: OnStateClickParams) => void;
   style?: React.CSSProperties;
-  theme?: ThemeOption;
+  /**
+   * Accessible title for the rendered iframe when `format` is `'html'`. Ignored
+   * for every other format. Set this when a page renders more than one diagram
+   * so screen readers can distinguish between them.
+   * @default 'Step Functions diagram'
+   */
+  title?: string;
+}
+/** Parameters passed to {@link SfnDiagramProps.onStateClick}. */
+interface OnStateClickParams {
+  event: React.MouseEvent<HTMLDivElement>;
+  stateId: string;
+}
+/**
+ * Imperative handle exposed via `ref` on {@link SfnDiagram}. There is no
+ * programmatic zoom/pan control - core has no public API for it yet (the
+ * interactive viewer's controller is not exported from a public subpath) -
+ * this handle only surfaces the rendered markup.
+ */
+interface SfnDiagramHandle {
+  /** The rendered SVG markup for `format="svg"`, or `null` for every other format (including an errored render). */
+  getSvg(): string | null;
 }
-declare function SfnDiagram({
-  className,
-  definition,
-  format,
-  history,
-  layout,
-  onError,
-  style,
-  theme
-}: SfnDiagramProps): _$react.JSX.Element | null;
+export declare const SfnDiagram: import("react").ForwardRefExoticComponent<SfnDiagramProps & import("react").RefAttributes<SfnDiagramHandle>>;
 //#endregion
-export { SfnDiagram, type SfnDiagramProps };
+export type { OnStateClickParams, SfnDiagramHandle, SfnDiagramProps, SfnDiagramResult, UseSfnDiagramParams };

package/dist/index.d.ts

@@ -1,33 +1,124 @@
-import * as _$react from "react";
-import { ExecutionHistoryInput, LayoutDirection, ThemeOption } from "sfn-diagram";
 
-//#region src/SfnDiagram.d.ts
-interface SfnDiagramProps {
-  className?: string;
+import { DiagramOptions, DiffOutput, ExecutionHistoryInput, ExecutionOutput, HtmlOutput, MermaidDiffOutput, MermaidExecutionOutput, MermaidOutput, SvgOutput } from "sfn-diagram";
+//#region src/useSfnDiagram.d.ts
+interface UseSfnDiagramParams extends Pick<DiagramOptions, 'catchHandling' | 'collapse' | 'edgeOverrides' | 'edgeStyle' | 'iconPosition' | 'iconSize' | 'layout' | 'nodeOverrides' | 'showIcons' | 'showVariables' | 'theme'> {
+  /**
+   * When set, `definition` is treated as the *after* side of a diff and `before`
+   * as the *original* side: the rendered diagram highlights added, modified, and
+   * removed states rather than the plain machine. Accepts an ASL object or a
+   * JSON string. Cannot be combined with `history` or `format="html"` - core has
+   * no diff API for either combination.
+   *
+   * The Mermaid diff (`generateMermaidDiff`) ignores every option in this
+   * type's `Pick<DiagramOptions, ...>` list - `layout`, `theme`, and the rest -
+   * since core's diff-specific function accepts only the two definitions. The
+   * SVG diff honours them.
+   */
+  before?: object | string;
   definition: object | string;
-  format?: 'mermaid' | 'svg';
+  /**
+   * Output format. `'svg'` and `'mermaid'` render static markup; `'html'` renders
+   * the interactive pan/zoom/search viewer as a self-contained HTML document.
+   * Cannot be combined with `history`.
+   * @default 'svg'
+   */
+  format?: 'html' | 'mermaid' | 'svg';
   /**
    * Optional execution history. When provided, the diagram is rendered as an
    * execution overlay: states are coloured by outcome, the taken path is
    * emphasized, and per-state duration / retry counts are annotated.
    * Accepts a GetExecutionHistory events array, the raw command output, or a
-   * JSON string of either.
+   * JSON string of either. Cannot be combined with `format="html"`.
    */
   history?: ExecutionHistoryInput;
-  layout?: LayoutDirection;
+}
+/** Result of {@link useSfnDiagram} - the raw output of whichever core function the params select. */
+type SfnDiagramResult = {
+  error: Error;
+  type: 'error';
+} | {
+  height: number;
+  html: string;
+  metadata: HtmlOutput['metadata'];
+  type: 'html';
+  width: number;
+} | {
+  code: string;
+  metadata: MermaidDiffOutput['metadata'] | MermaidExecutionOutput['metadata'] | MermaidOutput['metadata'];
+  type: 'mermaid';
+} | {
+  height: number;
+  metadata: DiffOutput['metadata'] | ExecutionOutput['metadata'] | SvgOutput['metadata'];
+  svg: string;
+  type: 'svg';
+  width: number;
+};
+/**
+ * Generate a Step Functions diagram and return the raw output - SVG or HTML
+ * markup, Mermaid code, dimensions, and metadata - without rendering it.
+ *
+ * This is the same generation logic `<SfnDiagram>` runs internally, exposed
+ * directly for a consumer who needs the underlying string or metadata rather
+ * than mounted markup - for example, building a data URI for `<img src>`, a
+ * download button, or a custom render target.
+ *
+ * @param params - The same option-bearing props `<SfnDiagram>` accepts, minus
+ * the presentational ones (`className`, `onError`, `onStateClick`, `style`,
+ * `title`).
+ * @returns A {@link SfnDiagramResult} discriminated union. Errors are returned
+ * as `{ type: 'error', error }` rather than thrown.
+ *
+ * @example
+ * ```tsx
+ * function DownloadSvgButton({ definition }: { definition: object }) {
+ *     const result = useSfnDiagram({ definition })
+ *     if (result.type !== 'svg') return null
+ *
+ *     const href = `data:image/svg+xml;base64,${btoa(result.svg)}`
+ *     return <a download="diagram.svg" href={href}>Download SVG</a>
+ * }
+ * ```
+ */
+export declare function useSfnDiagram(params: UseSfnDiagramParams): SfnDiagramResult;
+//#endregion
+//#region src/SfnDiagram.d.ts
+interface SfnDiagramProps extends UseSfnDiagramParams {
+  className?: string;
   onError?: (error: Error) => void;
+  /**
+   * Called when a state node is clicked. SVG format only - a click inside the
+   * sandboxed `format="html"` iframe does not reach this handler, and Mermaid
+   * output has no clickable elements. `stateId` is the graph node id, which
+   * equals the state name for every state whose name is unique across the
+   * machine; for a nested state whose name repeats elsewhere in the machine the
+   * id is qualified by its scope, so read it off the rendered `data-state-id`
+   * rather than assuming the bare name.
+   */
+  onStateClick?: (params: OnStateClickParams) => void;
   style?: React.CSSProperties;
-  theme?: ThemeOption;
+  /**
+   * Accessible title for the rendered iframe when `format` is `'html'`. Ignored
+   * for every other format. Set this when a page renders more than one diagram
+   * so screen readers can distinguish between them.
+   * @default 'Step Functions diagram'
+   */
+  title?: string;
+}
+/** Parameters passed to {@link SfnDiagramProps.onStateClick}. */
+interface OnStateClickParams {
+  event: React.MouseEvent<HTMLDivElement>;
+  stateId: string;
+}
+/**
+ * Imperative handle exposed via `ref` on {@link SfnDiagram}. There is no
+ * programmatic zoom/pan control - core has no public API for it yet (the
+ * interactive viewer's controller is not exported from a public subpath) -
+ * this handle only surfaces the rendered markup.
+ */
+interface SfnDiagramHandle {
+  /** The rendered SVG markup for `format="svg"`, or `null` for every other format (including an errored render). */
+  getSvg(): string | null;
 }
-declare function SfnDiagram({
-  className,
-  definition,
-  format,
-  history,
-  layout,
-  onError,
-  style,
-  theme
-}: SfnDiagramProps): _$react.JSX.Element | null;
+export declare const SfnDiagram: import("react").ForwardRefExoticComponent<SfnDiagramProps & import("react").RefAttributes<SfnDiagramHandle>>;
 //#endregion
-export { SfnDiagram, type SfnDiagramProps };
+export type { OnStateClickParams, SfnDiagramHandle, SfnDiagramProps, SfnDiagramResult, UseSfnDiagramParams };

package/dist/index.js

@@ -1,58 +1,198 @@
-import { useMemo } from "react";
-import { generateExecution, generateMermaid, generateMermaidExecution, generateSvg } from "sfn-diagram";
+'use client'
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef } from "react";
+import { generateDiff, generateExecution, generateHtml, generateMermaid, generateMermaidDiff, generateMermaidExecution, generateSvg } from "sfn-diagram";
 import { jsx } from "react/jsx-runtime";
-//#region src/SfnDiagram.tsx
-function SfnDiagram({ className, definition, format = "svg", history, layout = "TB", onError, style, theme = "light" }) {
-	const asl = useMemo(() => typeof definition === "string" ? definition : JSON.stringify(definition), [definition]);
-	const result = useMemo(() => {
+//#region src/useSfnDiagram.ts
+function toAslString(params) {
+	const { definition } = params;
+	return typeof definition === "string" ? definition : JSON.stringify(definition);
+}
+function omitUndefinedValues(options) {
+	const result = {};
+	for (const key of Object.keys(options)) if (options[key] !== void 0) result[key] = options[key];
+	return result;
+}
+/**
+* Generate a Step Functions diagram and return the raw output - SVG or HTML
+* markup, Mermaid code, dimensions, and metadata - without rendering it.
+*
+* This is the same generation logic `<SfnDiagram>` runs internally, exposed
+* directly for a consumer who needs the underlying string or metadata rather
+* than mounted markup - for example, building a data URI for `<img src>`, a
+* download button, or a custom render target.
+*
+* @param params - The same option-bearing props `<SfnDiagram>` accepts, minus
+* the presentational ones (`className`, `onError`, `onStateClick`, `style`,
+* `title`).
+* @returns A {@link SfnDiagramResult} discriminated union. Errors are returned
+* as `{ type: 'error', error }` rather than thrown.
+*
+* @example
+* ```tsx
+* function DownloadSvgButton({ definition }: { definition: object }) {
+*     const result = useSfnDiagram({ definition })
+*     if (result.type !== 'svg') return null
+*
+*     const href = `data:image/svg+xml;base64,${btoa(result.svg)}`
+*     return <a download="diagram.svg" href={href}>Download SVG</a>
+* }
+* ```
+*/
+function useSfnDiagram(params) {
+	const { before, catchHandling, collapse, definition, edgeOverrides, edgeStyle, format = "svg", history, iconPosition, iconSize, layout = "TB", nodeOverrides, showIcons, showVariables, theme = "light" } = params;
+	const asl = useMemo(() => toAslString({ definition }), [definition]);
+	const beforeAsl = useMemo(() => before === void 0 ? void 0 : toAslString({ definition: before }), [before]);
+	return useMemo(() => {
 		try {
-			if (format === "mermaid") return {
-				type: "mermaid",
-				code: (history ? generateMermaidExecution({
+			const diagramOptions = omitUndefinedValues({
+				catchHandling,
+				collapse,
+				edgeOverrides,
+				edgeStyle,
+				iconPosition,
+				iconSize,
+				layout,
+				nodeOverrides,
+				showIcons,
+				showVariables,
+				theme
+			});
+			if (beforeAsl !== void 0) {
+				if (history) throw new Error("history and before cannot be combined");
+				if (format === "html") throw new Error("before and format=\"html\" cannot be combined");
+				if (format === "mermaid") {
+					const output = generateMermaidDiff({
+						after: asl,
+						before: beforeAsl
+					});
+					return {
+						code: output.code,
+						metadata: output.metadata,
+						type: "mermaid"
+					};
+				}
+				const output = generateDiff({
+					after: asl,
+					before: beforeAsl,
+					...diagramOptions
+				});
+				return {
+					height: output.height,
+					metadata: output.metadata,
+					svg: output.svg,
+					type: "svg",
+					width: output.width
+				};
+			}
+			if (format === "html") {
+				if (history) throw new Error("history and format=\"html\" cannot be combined");
+				const output = generateHtml({
 					aslDefinition: asl,
-					history
-				}) : generateMermaid({ aslDefinition: asl })).code
-			};
-			return {
-				type: "svg",
-				svg: (history ? generateExecution({
+					...diagramOptions
+				});
+				return {
+					height: output.height,
+					html: output.html,
+					metadata: output.metadata,
+					type: "html",
+					width: output.width
+				};
+			}
+			if (format === "mermaid") {
+				const output = history ? generateMermaidExecution({
 					aslDefinition: asl,
 					history,
-					layout,
-					theme
-				}) : generateSvg({
+					...diagramOptions
+				}) : generateMermaid({
 					aslDefinition: asl,
-					layout,
-					theme
-				})).svg
+					...diagramOptions
+				});
+				return {
+					code: output.code,
+					metadata: output.metadata,
+					type: "mermaid"
+				};
+			}
+			const output = history ? generateExecution({
+				aslDefinition: asl,
+				history,
+				...diagramOptions
+			}) : generateSvg({
+				aslDefinition: asl,
+				...diagramOptions
+			});
+			return {
+				height: output.height,
+				metadata: output.metadata,
+				svg: output.svg,
+				type: "svg",
+				width: output.width
 			};
 		} catch (err) {
 			return {
-				type: "error",
-				error: err instanceof Error ? err : new Error(String(err))
+				error: err instanceof Error ? err : new Error(String(err)),
+				type: "error"
 			};
 		}
 	}, [
 		asl,
+		beforeAsl,
+		catchHandling,
+		collapse,
+		edgeOverrides,
+		edgeStyle,
 		format,
 		history,
+		iconPosition,
+		iconSize,
 		layout,
+		nodeOverrides,
+		showIcons,
+		showVariables,
 		theme
 	]);
-	if (result.type === "error") {
+}
+//#endregion
+//#region src/SfnDiagram.tsx
+const SfnDiagram = forwardRef(function SfnDiagram({ className, onError, onStateClick, style, title = "Step Functions diagram", ...diagramParams }, ref) {
+	const result = useSfnDiagram(diagramParams);
+	useImperativeHandle(ref, () => ({ getSvg: () => result.type === "svg" ? result.svg : null }), [result]);
+	const handleStateClick = useCallback((event) => {
+		const stateId = (event.target instanceof Element ? event.target : null)?.closest("[data-state-id]")?.getAttribute("data-state-id");
+		if (stateId) onStateClick?.({
+			event,
+			stateId
+		});
+	}, [onStateClick]);
+	const reportedResult = useRef(null);
+	useEffect(() => {
+		if (result.type !== "error") {
+			reportedResult.current = null;
+			return;
+		}
+		if (reportedResult.current === result) return;
+		reportedResult.current = result;
 		onError?.(result.error);
-		return null;
-	}
+	}, [onError, result]);
+	if (result.type === "error") return null;
 	if (result.type === "mermaid") return /* @__PURE__ */ jsx("pre", {
 		className,
 		style,
 		children: result.code
 	});
+	if (result.type === "html") return /* @__PURE__ */ jsx("iframe", {
+		className,
+		sandbox: "allow-scripts",
+		srcDoc: result.html,
+		style,
+		title
+	});
 	return /* @__PURE__ */ jsx("div", {
 		className,
 		dangerouslySetInnerHTML: { __html: result.svg },
+		onClick: onStateClick ? handleStateClick : void 0,
 		style
 	});
-}
+});
 //#endregion
-export { SfnDiagram };
+export { SfnDiagram, useSfnDiagram };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sfn-diagram-react",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "description": "React component for AWS Step Functions ASL diagrams",
     "type": "module",
     "sideEffects": false,
@@ -28,7 +28,7 @@
     "scripts": {
         "build": "tsdown",
         "dev": "tsdown --watch",
-        "test": "vitest run",
+        "test": "pnpm run build && vitest run",
         "typecheck": "tsc --noEmit",
         "lint": "eslint .",
         "prepublishOnly": "pnpm run build && pnpm run validate",
@@ -39,13 +39,17 @@
     "keywords": [
         "aws",
         "step-functions",
+        "stepfunctions",
         "react",
+        "component",
         "diagram",
         "asl",
         "state-machine",
         "visualization",
         "svg",
-        "mermaid"
+        "mermaid",
+        "html",
+        "typescript"
     ],
     "author": "Yusuf Afzal",
     "license": "MIT",
@@ -57,14 +61,14 @@
     "bugs": {
         "url": "https://github.com/yusufaf/sfn-diagram/issues"
     },
-    "homepage": "https://github.com/yusufaf/sfn-diagram/tree/main/packages/sfn-diagram-react#readme",
+    "homepage": "https://sfn.yusufaf.dev/ecosystem/react/",
     "peerDependencies": {
         "react": "^18.0.0 || ^19.0.0",
-        "sfn-diagram": "^1.1.1"
+        "sfn-diagram": "^1.6.0"
     },
     "devDependencies": {
-        "@arethetypeswrong/cli": "^0.18.2",
-        "@testing-library/jest-dom": "^6.6.0",
+        "@arethetypeswrong/cli": "^0.18.5",
+        "@testing-library/jest-dom": "^7.0.1",
         "@testing-library/react": "^16.0.0",
         "@types/react": "^18.3.0",
         "@types/react-dom": "^18.3.0",
@@ -73,9 +77,9 @@
         "react": "^18.3.0",
         "react-dom": "^18.3.0",
         "sfn-diagram": "workspace:*",
-        "tsdown": "^0.21.7",
+        "tsdown": "^0.23.0",
         "typescript": "^5.9.2",
-        "vite": "^6.3.0",
-        "vitest": "^3.2.6"
+        "vite": "^8.3.0",
+        "vitest": "^4.1.11"
     }
 }