flowchart-sequence-designer

A TypeScript-first Bun/npm package for building and editing flowchart and sequence diagrams — both programmatically via a fluent API and visually via a React drag-and-drop canvas editor.

🔗 Live demo & developer docs → Open it to drive the editor, switch variants (Flowchart / Question / Journey / Sequence), and copy the same API snippets shown below straight from the docs tab. Every variant boots with a working sample diagram so you can poke without any setup.

Contents

• Quick start
• Install
• Programmatic API
• React UI component
• Framework Wrappers
• Types
• Package structure
• Security
• Troubleshooting
• Building from source

Quick start

import { DiagramEditor } from 'flowchart-sequence-designer/ui';

export default function App() {
  return <DiagramEditor height={520} onChange={(m) => console.log(m)} />;
}

That's it — no provider, no theme setup, no required props. The editor mounts with a sample diagram, a working toolbar, undo/redo, drag-to-pan, scroll-to-zoom, and export buttons for Mermaid / PlantUML / JSON / SVG / PNG. Pass theme="dark" or themeOverrides={…} to brand-match, or initialModel={emptyModel('flowchart')} to start blank.

Install

bun add flowchart-sequence-designer
# or
npm install flowchart-sequence-designer

React 18+ is a peer dependency for the UI components. The core API has zero runtime dependencies.

Programmatic API

Flowchart

import { flowchart } from 'flowchart-sequence-designer';

const diagram = flowchart('Order Flow')
  .node('start',   'Start',           { shape: 'circle' })
  .node('check',   'Payment valid?',  { shape: 'diamond' })
  .node('success', 'Confirm order',   { shape: 'rectangle' })
  .node('fail',    'Reject',          { shape: 'rectangle' })
  .edge('start',   'check')
  .edge('check',   'success', { label: 'Yes' })
  .edge('check',   'fail',    { label: 'No' });

console.log(diagram.toMermaid());

Node shapes

| Shape | Description | |---|---| | rectangle | Standard process box (default) | | diamond | Decision / branch | | circle | Start or end terminal | | parallelogram | Input / output |

Edge options

.edge(from, to, {
  label?: string,
  style?: 'solid' | 'dashed' | 'dotted',
  arrowhead?: 'arrow' | 'open' | 'none',
})

Sequence diagram

import { sequence } from 'flowchart-sequence-designer';

const diagram = sequence('Auth Flow')
  .actor('User')
  .actor('Server')
  .message('User',   'Server', 'POST /login')
  .message('Server', 'User',   '200 OK + token', { style: 'dashed' });

console.log(diagram.toMermaid());

Actors auto-register from message() calls, so you can skip .actor() if you prefer.

Export formats

Every builder exposes the same export methods:

diagram.toMermaid()   // string
diagram.toPlantUML()  // string
diagram.toJSON()      // string (serialised DiagramModel)
diagram.toSVG()       // string (SVG markup)
diagram.toPNG()       // Promise<Blob>  (browser only)

Import

import { fromMermaid, fromJSON } from 'flowchart-sequence-designer';

const model = fromMermaid('graph TD; A-->B; B-->C');
const model2 = fromJSON(jsonString);

Round-trip fidelity: fromMermaid(diagram.toMermaid()) produces an equivalent model.

Exporter / importer round-trip rules

The five export formats trade fidelity for portability. Use this table to pick the one that matches what you need:

| Format | Round-trip | Preserved | Dropped or lossy | |---|---|---|---| | JSON | ✅ full | every field — variant, metadata, waypoint, x/y positions, edge arrowheads, message order | nothing | | Mermaid (flowchart) | partial | node shapes ([] {} (()) [/]), labels, edge connectors (-->, -.->, ---, -.-), edge labels, subgraph → metadata.group | positions, waypoint, metadata.answers, variant. Dotted edges collapse to dashed. | | Mermaid (sequence) | partial | actor order, message arrows (->>, -->>), labels | message metadata, styling overrides | | PlantUML (flowchart) | export-only | edge styles (--> / -[dashed]-> / -[dotted]->), labels, node id | shape distinctions (PlantUML state-diagram syntax is coarser), positions, metadata, variant | | PlantUML (sequence) | export-only | actor order, message style (->, -->), labels | – | | SVG | export-only (rendered) | full visual parity with the canvas — same dot grid, same edge curves, same node styling | – | | PNG | export-only (rendered, browser-only) | same as SVG, rasterized at devicePixelRatio | – |

If you need 100% round-trip fidelity, use JSON. If you need a format that GitHub renders inline in markdown, use Mermaid. If you need a polished image for documentation, use SVG or PNG.

Presets

import {
  presetFlowchartModel,
  presetSequenceModel,
  emptyModel,
} from 'flowchart-sequence-designer/ui';

presetFlowchartModel('flowchart')  // 6-node order flow with one decision
presetFlowchartModel('question')   // 1-question / 3-answer router
presetFlowchartModel('journey')    // 5-step onboarding sequence
presetSequenceModel()              // 3-actor login handshake

emptyModel('flowchart')            // { type:'flowchart', variant:'flowchart', nodes:[], edges:[] }
emptyModel('flowchart', 'journey') // same with variant: 'journey'
emptyModel('sequence')             // { type:'sequence', nodes:[], edges:[], actors:[], messages:[] }

All presets return a deep clone — mutate the result freely.

Working with the model directly

import { Model } from 'flowchart-sequence-designer';

const m = new Model('flowchart');         // new Model(type, title?, variant?)
m.addNode({ id: 'a', label: 'Step A', shape: 'rectangle' });
m.addNode({ id: 'b', label: 'Step B', shape: 'rectangle' });
m.addEdge({ id: 'e1', from: 'a', to: 'b', label: 'next' });

// Rehydrate from a saved DiagramModel:
// const m2 = Model.fromData(savedJson);

React UI component

Import from the /ui sub-entry to keep React out of the bundle for non-UI consumers:

import { DiagramEditor } from 'flowchart-sequence-designer/ui';

Basic usage

<DiagramEditor />

Mounted without an initialModel the editor boots with a small working sample diagram for the chosen variant — a 6-node order-flow for flowchart, a role-picker for question, a 5-step onboarding for journey, and a 3-actor login handshake for the SequenceEditor. This gives anyone evaluating the package something to interact with from the first render. To start blank instead:

import { DiagramEditor, emptyModel } from 'flowchart-sequence-designer/ui';

<DiagramEditor initialModel={emptyModel('flowchart')} />

The presets are also exported in case you want to hydrate them from your own code: presetFlowchartModel(variant?) and presetSequenceModel().

All props

<DiagramEditor
  initialModel={model}          // pre-load a DiagramModel
  onChange={(m) => save(m)}     // fires on every node/edge change
  onExport={(fmt, content) => …} // intercept exports instead of auto-downloading
  height="100%"                 // any CSS height (default: 600)
  variant="flowchart"           // 'flowchart' | 'question' | 'journey'
  theme="auto"                  // 'light' | 'dark' | 'auto'
  allowedExports={['json','svg']} // restrict visible export buttons
  allowImport={true}            // show/hide the Import button
  themeOverrides={{             // optional per-color overrides
    canvas: '#0b0f1a',
    nodeSelectedFill: '#1f2a44',
  }}
/>

Diagram variants

| Variant | Description | |---|---| | flowchart | General purpose — any shapes, freeform connections | | question | Each node is a question with lettered answer options (A, B, C…). Each answer has its own connection port. | | journey | Numbered milestone steps — user path or process walkthrough |

Editor features

Canvas

• Drag nodes to reposition (snaps to 24px grid)
• Scroll to zoom in/out (pinch to zoom on touch)
• Drag the canvas background to pan (one-finger pan on touch)
• Double-click a node to rename it inline
• Dashed alignment guides appear when a dragged node lines up with a sibling's edge or center, and it snaps within 4 px
• Bottom-right minimap — click or drag to pan the viewport
• Accessibility: every node, port, and control is keyboard-reachable with a visible focus ring; selection / add / delete actions announce via an aria-live status region; the edge-flow animation honours prefers-reduced-motion

Connecting nodes

• Hover a node to reveal the bottom port dot, then drag it to another node
• Question variant: each answer row has its own port dot — drag it to route that answer to a specific node

Node Navigator (left panel)

• Lists all nodes with shape badge, label, and connection counts
• Search/filter by name
• Click any row to jump to that node and center the canvas on it
• Collapses to a slim icon strip

Step Editor (right panel)

• Appears when a node is selected
• Edit the node name, change its shape
• Manage branches / answer options (add, remove, reorder)
• Question variant shows connection status per answer

Context menu (right-click)

• On canvas: Add node at cursor, Re-center, Undo, Redo
• On node: Rename, Duplicate, Disconnect all edges, Delete
• On edge: Style (solid/dashed/dotted), Arrowhead, Reset routing, Delete
• On touch devices: long-press the canvas (~550ms) opens the canvas menu

Keyboard shortcuts

| Shortcut | Action | |---|---| | Ctrl+Z | Undo | | Ctrl+Y / Ctrl+Shift+Z | Redo | | Ctrl+0 | Fit all nodes in view | | Ctrl+C / Ctrl+V | Copy and paste the current selection (internal edges preserved, +24 px offset on paste) | | Ctrl+D | Duplicate the current selection | | Delete / Backspace | Remove the current selection | | Escape | Deselect, cancel in-flight edge drag, close context menu | | Arrow keys | Nudge selection by 1 grid unit (Shift = 4 units) | | Alt+Arrow | Traverse to the nearest node in that direction from the current selection | | Shift+click | Toggle a node in/out of the current selection | | Shift+drag (empty canvas) | Box-select — add every intersected node to the selection | | Double-click edge label | Rename the edge label inline | | Drag edge midpoint | Route the edge through a waypoint (right-click → Reset routing to clear) |

Export / Import

• Toolbar exports to Mermaid, PlantUML, JSON, SVG, PNG
• Import accepts Mermaid syntax or JSON

Theming

<DiagramEditor theme="dark" />    // force dark
<DiagramEditor theme="light" />   // force light
<DiagramEditor theme="auto" />    // follows system prefers-color-scheme (default)

To match the editor to a host application's brand, pass themeOverrides — a Partial<ThemeColors> that is shallow-merged on top of the resolved light/dark palette:

import { DiagramEditor, type ThemeColors } from 'flowchart-sequence-designer/ui';

const brand: Partial<ThemeColors> = {
  canvas: '#0b1020',
  nodeFill: '#111a2e',
  nodeStroke: '#2b3a5a',
  nodeSelectedFill: '#1a2447',
  edgeColor: '#7b8aa6',
  textPrimary: '#e6edf7',
};

<DiagramEditor theme="dark" themeOverrides={brand} />;

Every field on ThemeColors (canvas, nodeFill, nodeStroke, edgeColor, panelBg, inputBg, …) is overridable. Sequence diagrams accept the same prop with a slightly different shape — Partial<SequenceThemeColors> — also exported from flowchart-sequence-designer/ui.

SequenceEditor

<DiagramEditor> auto-delegates to <SequenceEditor> when handed a sequence model, but you can also mount it directly to avoid the type-check redirect:

import { SequenceEditor, presetSequenceModel } from 'flowchart-sequence-designer/ui';

<SequenceEditor
  initialModel={presetSequenceModel()}
  height={520}
  theme="dark"
  onChange={(m) => save(m)}
/>

SequenceEditor props (mirrors DiagramEditorProps minus variant):

| Prop | Type | Default | Notes | |---|---|---|---| | initialModel | DiagramModel | preset | Must have type: 'sequence'. Falls back to the preset if a non-sequence model is passed. | | onChange | (m: DiagramModel) => void | – | Fires on every committed mutation. | | onExport | (format, content) => void | download | Receives string for text formats, Blob for PNG. | | height | number \| string | 600 | Any CSS height. | | allowedExports | ExportFormat[] | all | Whitelist of toolbar export buttons. | | allowImport | boolean | true | Show the Import button. | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | auto follows OS prefers-color-scheme. | | themeOverrides | Partial<SequenceThemeColors> | – | Per-property palette overrides. |

Sequence-specific interactions:

• Drag a message row by its handle to reorder messages.
• Double-click a message label to rename inline.
• Drag the column header of an actor to reorder lifelines.

Restricting exports and import

// Only allow JSON and SVG download
<DiagramEditor allowedExports={['json', 'svg']} />

// Hide the import button entirely
<DiagramEditor allowImport={false} />

// Handle exports yourself (e.g. send to an API)
<DiagramEditor
  onExport={(format, content) => {
    if (format === 'json') myApi.save(content as string);
  }}
/>

Framework Wrappers

| Framework | Package | Docs | |-----------|---------|------| | Angular | @flowchart-sequence-designer/angular | Docs & Demo | | Vue | @flowchart-sequence-designer/vue | Docs & Demo |

Types

Core entry (flowchart-sequence-designer)

import type {
  DiagramModel,
  DiagramNode,
  DiagramEdge,
  DiagramVariant,
  DiagramType,
  NodeShape,
  ExportFormat,
  SequenceMessage,
  ValidationError,
} from 'flowchart-sequence-designer';

import {
  Model,                 // class — build / query / validate diagrams
  flowchart,             // fluent FlowchartBuilder factory
  sequence,              // fluent SequenceBuilder factory
  toMermaid, fromMermaid,
  toPlantUML,
  toJSON, fromJSON,
  toSVG, toPNG,
} from 'flowchart-sequence-designer';

UI entry (flowchart-sequence-designer/ui)

import {
  DiagramEditor,         // flowchart / question / journey editor
  SequenceEditor,        // sequence diagram editor
  Toolbar,               // standalone toolbar (used internally)
  StepEditor,            // node property panel (used internally)
  presetFlowchartModel,  // starter model for flowchart variants
  presetSequenceModel,   // starter model for sequence
  emptyModel,            // blank model factory
} from 'flowchart-sequence-designer/ui';

import type {
  DiagramEditorProps,
  SequenceEditorProps,
  ThemeColors,           // flowchart theme palette
  SequenceThemeColors,   // sequence theme palette
} from 'flowchart-sequence-designer/ui';

DiagramModel

interface DiagramModel {
  type: 'flowchart' | 'sequence';
  variant?: DiagramVariant;    // 'flowchart' | 'question' | 'journey' (flowchart-type only)
  title?: string;
  nodes: DiagramNode[];        // always present (empty array for sequence models)
  edges: DiagramEdge[];        // always present (empty array for sequence models)
  actors?: string[];           // sequence models only — ordered actor names
  messages?: SequenceMessage[]; // sequence models only — ordered messages
}

DiagramNode

interface DiagramNode {
  id: string;
  label: string;
  shape?: 'rectangle' | 'diamond' | 'circle' | 'parallelogram';
  x?: number;
  y?: number;
  metadata?: Record<string, unknown>;
  // question variant: metadata.answers = string[]
}

DiagramEdge

interface DiagramEdge {
  id: string;
  from: string;
  to: string;
  label?: string;
  style?: 'solid' | 'dashed' | 'dotted';
  arrowhead?: 'arrow' | 'none' | 'open';
  waypoint?: { x: number; y: number }; // manual routing point (JSON only)
}

SequenceMessage

interface SequenceMessage {
  id: string;
  from: string;            // actor name
  to: string;              // actor name
  label: string;
  style?: 'solid' | 'dashed';
}

ValidationError

interface ValidationError {
  kind: 'dangling-from' | 'dangling-to' | 'duplicate-node-id' | 'duplicate-edge-id';
  id: string;
  message: string;
}

Package structure

flowchart-sequence-designer/
├── dist/
│   ├── index.js / index.cjs / index.d.ts   ← core (no React)
│   └── ui/
│       └── index.js / index.cjs / index.d.ts ← React UI
└── src/
    ├── core/          # types, Model, FlowchartBuilder, SequenceBuilder
    ├── exporters/     # mermaid, plantuml, json, svg, png
    ├── importers/     # mermaid, json
    └── ui/            # DiagramEditor, SequenceEditor, Toolbar, hooks

The "." export gives you the core API; "./ui" gives you the React components. Consumers that only use the programmatic API never pull in React.

Security

This package takes security seriously:

• Input sanitization — All user-provided text is sanitized before rendering (HTML tags, javascript:/data:/vbscript: URIs, on* event handlers, and control characters are stripped). See src/core/sanitize.ts.
• Resource limits — Importers enforce hard caps (500 nodes, 2000 edges, 100 actors, 2000 messages, 2MB input) to prevent resource exhaustion.
• Prototype pollution defense — JSON importer strips __proto__, constructor, and prototype keys recursively.
• SVG export — Defence-in-depth: sanitize first, then XML-escape. Safe even if consumed by less-strict parsers.
• No eval / innerHTML — The codebase never uses dynamic code execution or raw HTML injection.
• CodeQL — Automated security scanning runs weekly and on every PR.
• Dependabot — Dependency updates monitored weekly.

To report a vulnerability, see SECURITY.md.

Troubleshooting

toPNG throws in Node / Bun server context

toPNG requires the browser Canvas API. Use toSVG on the server and pipe the output through @resvg/resvg-js:

import { toSVG } from 'flowchart-sequence-designer';
import { Resvg } from '@resvg/resvg-js';

const svg = toSVG(model);
const png = new Resvg(svg).render().asPng();

Peer dependency warning for React

The package lists react >= 17 as a peer dependency. If your project uses React 18 or 19 you may see a warning — it is safe to ignore. All features are tested against React 19.

Canvas renders blank / empty

Ensure the height prop is set to a numeric value (height={600}) rather than "100%". A percentage height requires the parent element to have an explicit height, which browsers often don't enforce in flex containers.

Large diagrams feel sluggish

The canvas is SVG-based and renders every node each frame during drag. For diagrams with more than ~200 nodes, consider reducing the number of simultaneously visible nodes or splitting the diagram into sections. Node dimensions are memoized per render cycle, so layout recalculations are batched.

Mermaid import drops some features

Mermaid import is intentionally lossy — it preserves shapes, edge styles, labels, titles, and subgraph grouping, but drops canvas positions, waypoints, per-edge metadata, and the diagram variant (question, journey). These fields have no Mermaid syntax equivalent. Use JSON export/import for a full lossless round-trip.

Building from source

bun install
bun run build        # outputs to dist/
bun test             # 105 tests
bun run typecheck    # tsc --noEmit
bun run lint         # eslint
bun run format:check # prettier --check