sequence-flow

KO | EN

gitlite — search

#json #graphql #windows #anthropic #command-line #ai #markdown #php #tensorflow #chatgpt

(★ 9)

Mermaid to React Flow Diagram for Sequence Diagrams

File Explorer

ZIP Download

- - test.yml
- globals.css
- layout.tsx
- page.tsx
- - color-utils.ts
  - editor-workbench.tsx
  - examples.ts
  - journey-catalog-data.ts
  - journey-catalog.tsx
  - journeys.ts
  - minify-mermaid.ts
  - playground.tsx
  - themes.ts
- - button.tsx
- hero-install.tsx
- install-command.tsx
- theme-provider.tsx
- theme-toggle.tsx
- utils.ts
- - registry.json
  - sequence-diagram-demo.json
  - sequence-diagram.json
- apple-icon.png
- favicon.ico
- icon-16x16.png
- icon-192x192.png
- icon-32x32.png
- icon-48x48.png
- icon-512x512.png
- icon-black-16x16.png
- icon-black-180x180.png
- icon-black-192x192.png
- icon-black-32x32.png
- icon-black-48x48.png
- icon-black-512x512.png
- icon-black.svg
- icon-dark-32x32.png
- icon-light-32x32.png
- icon-white-16x16.png
- icon-white-180x180.png
- icon-white-192x192.png
- icon-white-32x32.png
- icon-white-48x48.png
- icon-white-512x512.png
- icon-white.svg
- icon.svg
- logo-black.svg
- logo-white.svg
- opengraph-image.png
- placeholder-logo.png
- placeholder-logo.svg
- placeholder-user.jpg
- placeholder.jpg
- placeholder.svg
- sequence-flow.js
- twitter-image.png
- - SKILL.md
- - journey-editor.spec.ts
- journey-html.test.ts
- journey-markdown.test.ts
- layout.test.ts
- public-api.test.ts
- registry.test.ts
- sequence-parser.test.ts
.gitignore
components.json
LICENSE
next.config.mjs
package.json
playwright.config.ts
pnpm-lock.yaml
postcss.config.mjs
README.md
registry.json
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Sequence Flow is a small, open-source developer primitive from [Canadian AI](https://canadian-ai.ca) for rendering Mermaid `sequenceDiagram` syntax as an interactive React Flow canvas and chaining multiple diagrams into progressive journeys.

It is intentionally narrow: install the component into a React application, pass Mermaid text to `SequenceDiagram` or a `JourneySlide[]` to `JourneyPlayer`, and render readable technical flows with pan, zoom, hover highlighting, activation bars, return messages, notes, self-messages, grouping boxes, and guided walkthroughs.

## Install

```bash
npx shadcn@latest add canadian-ai/sequence-flow/sequence-diagram
```

This GitHub source registry is the canonical install path. The hosted endpoint remains available for backwards compatibility:

```bash
npx shadcn@latest add https://sequence-flow.canadian-ai.app/r/sequence-diagram.json
```

`registry.json` is the source of truth for the component definition. The generated `public/r/*.json` files are a compatibility layer for existing consumers of the hosted registry URL.

## Pass a sequence flow

Use `SequenceDiagram` in any height-constrained container:

```tsx
import { SequenceDiagram } from "@/components/ui/sequence-diagram"

const chart = `sequenceDiagram
    participant B as Browser
    participant S as Server
    B->>S: Request
    S-->>B: Response`

export function Example() {
  return (
    <div className="h-[400px]">
      <SequenceDiagram chart={chart} />
    </div>
  )
}
```

## Pass a journey as JSON / TypeScript

A journey is an array of `JourneySlide` objects. Each slide owns a standalone Mermaid sequence diagram plus optional title, caption, and per-message commentary.

```tsx
import {
  JourneyPlayer,
  type JourneySlide,
} from "@/components/ui/sequence-diagram"

const journey: JourneySlide[] = [
  {
    id: "request",
    title: "Step 1 — Request",
    caption: "The browser sends a request to the API.",
    chart: `sequenceDiagram
      participant B as Browser
      participant A as API
      B->>A: GET /products`,
  },
  {
    id: "response",
    title: "Step 2 — Response",
    caption: "The API returns the result to the browser.",
    chart: `sequenceDiagram
      participant B as Browser
      participant A as API
      B->>A: GET /products
      A-->>B: 200 OK`,
  },
]

export function JourneyExample() {
  return <JourneyPlayer slides={journey} />
}
```

You can also provide `messageCaptions` on each slide when you want narration to appear as individual messages reveal. Journey caption surfaces use the host's `card` / `card-foreground` tokens so narration stays readable even when the host OS color scheme differs from a locally selected journey theme.

### Journey pacing

Journey reveals are paced for reading rather than micro-interaction speed. Sequence Flow uses a conservative **160 WPM** default based on sixth-grade reading/fluency research, adds a short orientation beat for technical labels, and uses a **650 ms** traveling packet so the eye can follow each edge. Even a one-word label gets at least **1.6 seconds** before the next message starts, while longer labels receive proportionally more time up to a bounded maximum.

Use a Mermaid `%% duration: <ms>` annotation when a specific message needs a deliberate custom hold. The `speed` prop still scales the full animation schedule.

## Write a journey in Markdown

`parseJourneyMarkdown` lets you author the same `JourneySlide[]` model in a readable Markdown document. Each `##` heading becomes a slide, ordinary Markdown becomes the slide caption, and a fenced `mermaid` block contains the diagram.

````md
# Request lifecycle

A progressive walkthrough for the request path.

## Step 1 — Request


The browser begins the request lifecycle.

```mermaid
sequenceDiagram
  participant B as Browser
  participant A as API
  B->>A: GET /products
```

## Step 2 — Response



The response completes the round trip.

```mermaid
sequenceDiagram
  participant B as Browser
  participant A as API
  B->>A: GET /products
  A-->>B: 200 OK
```
````

Then compile and render it:

```tsx
import {
  JourneyPlayer,
  parseJourneyMarkdown,
} from "@/components/ui/sequence-diagram"

const markdown = `...`
const journey = parseJourneyMarkdown(markdown)

export function JourneyExample() {
  return <JourneyPlayer slides={journey.slides} />
}
```

Supported Markdown annotations:

- `` sets the slide ID.
- Repeated `` annotations populate `messageCaptions` in reveal order.
- `` is accepted as an alias for `@message`.
- A top-level `#` heading is returned as the document title.
- Text before the first slide is returned as the document description.

If `messageCaptions` is omitted, `JourneyPlayer` can still reuse `%% tooltip:` annotations inside Mermaid as step commentary.

## Live editor

The demo site includes two mobile-responsive editor tabs:

- **Sequence flow** — edit Mermaid sequence syntax, preview the canvas, tune the theme, and export the diagram.
- **Journey** — switch between **Markdown** and **JSON**, preview the progressive walkthrough, choose a live theme, and copy the full React usage.

The code views are designed for full copy-and-paste usage so the rendered example and the integration snippet stay next to each other.

## Test suite

The repository includes regression coverage for the public component surface:

- sequence parser behavior and Mermaid annotations
- journey Markdown parsing and validation
- layout graph generation and reveal scheduling
- shadcn registry completeness for the Journey runtime
- browser smoke coverage for the Journey editor and theme controls

Run the unit/integration suite with:

```bash
pnpm test
```

Run browser smoke tests with:

```bash
pnpm dlx playwright@1.54.2 install chromium
pnpm test:e2e
```

The GitHub Actions workflow runs unit/integration tests, a production Next.js build, and browser smoke coverage for every pull request.

## What this repo is

- A reusable React component for technical diagrams.
- A progressive journey player for multi-step technical walkthroughs.
- A Markdown-to-`JourneySlide[]` compiler for annotated journey documents.
- A small Mermaid-compatible parser and layout layer for sequence diagrams.
- A shadcn registry package developers can copy directly into their applications.
- A demo playground for testing diagrams, journeys, and the component API.

## What this repo is not

- A hosted diagramming SaaS.
- A project-management or collaboration product.
- A backend service or proprietary Canadian AI runtime.
- Documentation for Canadian AI's private platform internals.

The public repository contains only the generic developer-facing primitive. Canadian AI's internal runtime, application architecture, and proprietary platform implementation remain in private repositories.

## Supported syntax

Sequence Flow supports the most common `sequenceDiagram` primitives:

- `participant` and `actor`
- synchronous and asynchronous messages
- dashed return messages
- activation and deactivation bars
- self-messages
- notes
- participant grouping boxes

Unsupported control-flow blocks are ignored gracefully so partial diagrams can still render.

## Development

```bash
pnpm install
pnpm dev
```

Open `http://localhost:3000` to use the playground.

## License

sequence-flow

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

sequence-flow

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README