Wireflow

Wireflow is a DSL-based JavaScript diagram renderer for flow diagrams, screen flows, ER diagrams, component diagrams, class diagrams, and sequence diagrams.

It can be used from npm, CDN, or a local bundled file.

Install

npm install @toru_yamauchi/wireflow

import { Wireflow, injectWireflowStyles } from "@toru_yamauchi/wireflow";

injectWireflowStyles();

const wf = new Wireflow(document.getElementById("canvas"), {
  autoFit: true,
});

wf.render(`
layout:
  mode: horizontal
  auto-fit: true

Start:
  Start
  ---
  kind: start

Review:
  Review
  ---
  kind: process

Done:
  Done
  ---
  kind: end

Start -> Review
Review -> Done
`);

CDN

<div data-wireflow-viewport style="height: 420px">
  <div id="canvas"></div>
</div>

<script src="https://cdn.jsdelivr.net/npm/@toru_yamauchi/wireflow/dist/wireflow.min.js"></script>
<script>
  const WF = window.WireflowLib;
  WF.injectWireflowStyles();

  const wf = new WF.Wireflow(document.getElementById("canvas"), {
    autoFit: true,
  });

  wf.render(`
layout:
  mode: horizontal
  auto-fit: true

Input:
  Input
  ---
  kind: screen
  state: accent

Validate:
  Validate
  ---
  kind: decision

Save:
  Save
  ---
  kind: process

Input -> Validate
Validate -> Save:
  on-success: true
`);
</script>

unpkg is also supported:

<script src="https://unpkg.com/@toru_yamauchi/wireflow/dist/wireflow.min.js"></script>

DSL Basics

Wireflow currently uses a YAML-like DSL.

layout:
  mode: horizontal
  auto-fit: true

Home:
  Home
  ---
  kind: screen
  state: accent
  popup: true
  payload: {"title":"Home","desc":"Node details"}

Detail:
  Detail
  ---
  kind: screen

Home:right -> Detail:left:
  label: open

The text above --- is rendered as the node label. The lines below --- are attributes.

Supported Diagram Types

• Flow diagrams
• Screen flows
• ER diagrams
• Component diagrams
• Class diagrams
• Sequence diagrams
• Notes / comments

Node Attributes

Common node attributes:

| Attribute | Example | Description | |---|---|---| | kind | kind: screen | Node kind such as screen, process, decision, start, end, entity, note | | state | state: success | Visual preset: accent, success, warning, danger, muted | | lane | lane: customer | Swimlane name | | x, y | x: 120 | Manual position | | dx, dy | dx: 16 | Position fine tuning | | popup | popup: true | Enables node click/touch popup events | | payload | payload: {"id":"A1"} | JSON data passed to interaction events | | link | link: https://example.com | Opens a URL on click | | target | target: _blank | Link target | | flow-ref | flow-ref: checkout/main | Subflow reference badge and event |

Edge Syntax

A -> B
A --> B
A - B
A -- B
A:right! -> B:left!:
  label: forced ports

Common edge attributes:

| Attribute | Example | Description | |---|---|---| | label | label: submit | Edge label | | stroke | stroke: #15803d | Edge color | | stroke-width | stroke-width: 4 | Edge width | | marker-end | marker-end: none | Removes arrow marker | | route | route: perimeter | Route strategy | | on-success | on-success: true | Success path styling | | on-failure | on-failure: true | Failure path styling | | parallel-group | parallel-group: stream-1 | Parallel edge separation | | bus | bus: api-bus | Shared bus routing |

ER Diagram

layout:
  mode: horizontal
  auto-fit: true

User:
  PK id bigint
  email varchar(255) UNIQUE NOT NULL
  ---
  kind: entity

Order:
  PK id bigint
  FK user_id bigint NOT NULL
  status varchar(20) NOT NULL
  ---
  kind: entity

User 1--0< Order: "orders"

Field mapping can be written with repeated key: lines.

Order 1--0< OrderLog "audit":
  key: id--order_id
  key: user_id--user_id

Component Diagram

layout:
  mode: horizontal
  auto-fit: true

component Order:
  Order
  ---
  x: 80
  y: 170

component Product:
  Product
  ---
  x: 560
  y: 80

component Account:
  Account
  ---
  x: 560
  y: 300

Order:right! -|o- Product:left!:
  Item Code

Order:bottom! -|--o- Account:left!:
  Account Details

-|o- renders a provided interface connection. -|--o- renders an assembly-style connection where the middle segment is dashed.

Sequence Diagram

sequence:
  User:
    User
    ---
    kind: actor

  App:
    App

  API:
    API

  User -> App: Submit
  App -> API: POST /orders
  API --> App: 201 Created
  App --> User: Done

Notes

Input:
  Input
  ---
  kind: screen

Validate:
  Validate
  ---
  kind: process

note Rule:
  Required fields and format checks
  ---
  target: Validate
  state: warning

Input -> Validate

Public API

import {
  Wireflow,
  parseDsl,
  injectWireflowStyles,
  createPopup,
  parseMdWireflow,
  createFlowNavigator,
} from "@toru_yamauchi/wireflow";

Browser global:

const {
  Wireflow,
  parseDsl,
  injectWireflowStyles,
  createPopup,
} = window.WireflowLib;

Popup

createPopup(document.getElementById("canvas"), {
  render: (id, payload) => `
    <h2>${payload?.title ?? id}</h2>
    <p>${payload?.desc ?? ""}</p>
  `,
});

Nodes with popup: true emit wireflow:box-click and can be handled by createPopup().

Editor History

Wireflow supports undo/redo for DSL-changing interactions.

• Undo: Ctrl + Z / Cmd + Z
• Redo: Ctrl + Y / Cmd + Y / Ctrl + Shift + Z
• Change event: wireflow:dsl-change

License

MIT