sfn-diagram 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,8 @@
 # sfn-diagram
 
 [![npm version](https://img.shields.io/npm/v/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
+[![npm downloads](https://img.shields.io/npm/dm/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
+[![Unit Test](https://github.com/yusufaf/sfn-diagram/actions/workflows/unit-test.yml/badge.svg)](https://github.com/yusufaf/sfn-diagram/actions/workflows/unit-test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Live Playground](https://img.shields.io/badge/playground-live-brightgreen)](https://yusufaf.github.io/sfn-diagram/)
 
@@ -8,6 +10,30 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 
 **▶ [Try it in the live playground](https://yusufaf.github.io/sfn-diagram/)** — paste any ASL definition and preview the diagram instantly, no install required.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="examples/outputs/parallel-dark.svg">
+  <img src="examples/outputs/parallel-light.svg" alt="Example diagram of a Parallel state Step Functions workflow generated by sfn-diagram" width="410">
+</picture>
+
+## Table of Contents
+
+- [What it looks like](#what-it-looks-like)
+- [Why sfn-diagram](#why-sfn-diagram)
+- [Features](#features)
+- [Installation](#installation)
+- [Runtime Support](#runtime-support)
+- [Command-line Usage](#command-line-usage)
+- [Docker](#docker)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Configuration Options](#configuration-options)
+- [Supported State Types](#supported-state-types)
+- [Examples](#examples)
+- [TypeScript Support](#typescript-support)
+- [Use with your framework](#use-with-your-framework)
+- [Ecosystem](#ecosystem)
+- [Contributing](#contributing)
+
 ## What it looks like
 
 Give it an ASL definition like this order-processing workflow ([`examples/order-processing.asl.json`](examples/order-processing.asl.json)):
@@ -57,6 +83,21 @@ stateDiagram-v2
     class OrderComplete successState
 ```
 
+## Why sfn-diagram
+
+There's no shortage of ways to look at a state machine — this is where sfn-diagram fits versus the other two most common options:
+
+| | **sfn-diagram** | AWS Console visualizer | Mermaid Live Editor |
+|---|---|---|---|
+| Input | ASL, CloudFormation/SAM/CDK templates, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
+| Output | SVG, Mermaid, PNG, interactive HTML | Static graph in-browser | Mermaid diagram only |
+| CI / PR integration | [GitHub Action](#github-action) posts a diff overlay on every PR that touches ASL | None | None |
+| Execution overlays | Paints a real run's path/status/duration onto the diagram | Basic per-execution highlighting, console-only | Not applicable |
+| Runs where | CLI, Node, browser, edge runtimes | AWS Console only | Web app only |
+| Automation | Full programmatic API (`generateSvg`, `generateMermaid`, etc.) | None — UI only | None — UI only |
+
+In short: reach for the AWS Console visualizer to eyeball a state machine you already deployed, reach for Mermaid Live if you're hand-drawing a diagram from scratch — reach for sfn-diagram when you want diagrams generated automatically from your actual definition, checked into CI, and diffed on every pull request.
+
 ## Features
 
 - **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
@@ -760,6 +801,120 @@ import type {
 import type { PngOutput, ExportPngParams } from 'sfn-diagram/png';
 ```
 
+## Use with your framework
+
+`generateSvg()` returns an SVG **string** and the core has no DOM dependency, so any
+framework can render a diagram by injecting that string. There is nothing React-specific
+in the core — [`sfn-diagram-react`](packages/sfn-diagram-react/) exists for convenience,
+not necessity.
+
+Each snippet below is the whole integration. See [API Reference](#api-reference) for the
+full option set (`theme`, `layout`, `showIcons`, …) and [`generateMermaid`](#generatemermaidparams)
+if you would rather emit Mermaid than SVG.
+
+**Svelte 5**
+
+```svelte
+<script lang="ts">
+  import { generateSvg } from 'sfn-diagram';
+
+  let { definition } = $props();
+  const svg = $derived(generateSvg({ aslDefinition: definition }).svg);
+</script>
+
+{@html svg}
+```
+
+**Vue 3**
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+const props = defineProps<{ definition: AslDefinition | string }>();
+const svg = computed(() => generateSvg({ aslDefinition: props.definition }).svg);
+</script>
+
+<template>
+  <div v-html="svg" />
+</template>
+```
+
+**Solid**
+
+```tsx
+import { createMemo } from 'solid-js';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+export function SfnDiagram(props: { definition: AslDefinition | string }) {
+  const svg = createMemo(() => generateSvg({ aslDefinition: props.definition }).svg);
+  return <div innerHTML={svg()} />;
+}
+```
+
+**Angular**
+
+`[innerHTML]` strips SVG unless the value is marked trusted, so the sanitizer bypass is required.
+
+```ts
+import { Component, computed, inject, input } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+@Component({
+  selector: 'sfn-diagram',
+  template: `<div [innerHTML]="svg()"></div>`,
+})
+export class SfnDiagramComponent {
+  readonly definition = input.required<AslDefinition | string>();
+  private readonly sanitizer = inject(DomSanitizer);
+
+  readonly svg = computed(() =>
+    this.sanitizer.bypassSecurityTrustHtml(
+      generateSvg({ aslDefinition: this.definition() }).svg
+    )
+  );
+}
+```
+
+**Astro**
+
+Astro runs the frontmatter at build time, so the diagram ships as static markup with
+**zero client-side JavaScript** — the DOM-free core at its best. (Astro also hosts React
+islands, so `sfn-diagram-react` works there too if you need interactivity.)
+
+```astro
+---
+import { generateSvg } from 'sfn-diagram';
+// `?raw` gives the file as a string, which `aslDefinition` accepts directly
+import definition from '../workflows/order-processing.asl.json?raw';
+
+const { svg } = generateSvg({ aslDefinition: definition, theme: 'light' });
+---
+
+<Fragment set:html={svg} />
+```
+
+**Vanilla JS / htmx / anything else**
+
+```js
+import { generateSvg } from 'sfn-diagram';
+
+const response = await fetch('/workflows/order-processing.asl.json');
+const { svg } = generateSvg({ aslDefinition: await response.text() });
+document.querySelector('#diagram').innerHTML = svg;
+```
+
+> **On the "unsafe HTML" APIs.** Every snippet above uses its framework's raw-HTML escape
+> hatch (`{@html}`, `v-html`, `innerHTML`, `dangerouslySetInnerHTML`). The SVG builder
+> HTML-escapes every attribute and text value it emits, following the HTML serialization
+> algorithm, so state names, comments, and choice conditions taken from your ASL are
+> escaped before they reach the string.
+
 ## Ecosystem
 
 ### Playground
@@ -790,7 +945,11 @@ code --install-extension vscode-sfn-diagram-*.vsix
 
 ### React Component
 
-Render diagrams in a React app with the [`sfn-diagram-react`](packages/sfn-diagram-react/) package. It wraps `generateSvg`/`generateMermaid` in a component with the same platform-agnostic core, so it works in any React renderer.
+Render diagrams in a React app with the [`sfn-diagram-react`](https://www.npmjs.com/package/sfn-diagram-react) package ([source](packages/sfn-diagram-react/)). It wraps `generateSvg`/`generateMermaid` in a component with the same platform-agnostic core, so it works in any React renderer. React 18 and 19 are both supported.
+
+```bash
+npm install sfn-diagram-react sfn-diagram react
+```
 
 ```tsx
 import { SfnDiagram } from 'sfn-diagram-react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfn-diagram",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Generate SVG, Mermaid, HTML, and PNG diagrams from AWS Step Functions ASL definitions, CloudFormation/CDK templates, or live AWS state machines",
   "type": "module",
   "packageManager": "pnpm@9.15.9",