flowchart-sequence-designer 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,398 @@
+/**
+ * Top-level kind of diagram. `flowchart` uses `nodes` + `edges`; `sequence`
+ * uses `actors` + `messages`. The two are rendered by different editors and
+ * serialized differently in every exporter.
+ */
+type DiagramType = 'flowchart' | 'sequence';
+/**
+ * UI variant for flowchart-type models. `flowchart` is the default linear
+ * graph; `question` is a decision-tree variant whose nodes carry
+ * `metadata.answers`; `journey` is a horizontal user-journey style. The
+ * variant selects styling and a few interactions inside `DiagramEditor`.
+ */
+type DiagramVariant = 'flowchart' | 'question' | 'journey';
+/**
+ * Visual shape of a flowchart node. Defaults to `rectangle`. `diamond` is
+ * conventional for decisions, `circle` for start/end terminators, and
+ * `parallelogram` for I/O.
+ */
+type NodeShape = 'rectangle' | 'diamond' | 'circle' | 'parallelogram';
+/**
+ * Supported export targets.
+ * - `mermaid` / `plantuml` / `json` / `svg` produce a `string`.
+ * - `png` produces a `Blob` (browser-only — uses the Canvas API).
+ */
+type ExportFormat = 'mermaid' | 'plantuml' | 'json' | 'svg' | 'png';
+/**
+ * A flowchart node.
+ *
+ * @property id        Stable, unique-within-model identifier. Used by edges.
+ * @property label     Visible text. Multi-line input is wrapped by the renderer.
+ * @property shape     Visual shape; defaults to `rectangle` when omitted.
+ * @property x         Optional canvas x-coordinate. When omitted, the renderer
+ *                     auto-positions on first paint.
+ * @property y         Optional canvas y-coordinate. Same defaulting as `x`.
+ * @property metadata  Free-form bag for variant-specific data (e.g.
+ *                     `metadata.group` for journey columns, `metadata.answers`
+ *                     for question branches). Round-trips through JSON only.
+ */
+interface DiagramNode {
+    id: string;
+    label: string;
+    shape?: NodeShape;
+    x?: number;
+    y?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A directed edge between two flowchart nodes.
+ *
+ * @property id         Stable, unique-within-model identifier.
+ * @property from       Source node id. Must match an existing `DiagramNode.id`.
+ * @property to         Target node id. Must match an existing `DiagramNode.id`.
+ * @property label      Optional edge label rendered at the midpoint.
+ * @property style      Line style. `solid` is default; `dashed` maps to
+ *                      Mermaid `-.->` and PlantUML `-[dashed]->`; `dotted`
+ *                      maps to Mermaid `-..->` and PlantUML `-[dotted]->`.
+ * @property arrowhead  Arrow style at the target end. `arrow` is default.
+ * @property waypoint   Optional manual waypoint in canvas coordinates. When
+ *                      set, the edge is routed as two cubic segments meeting
+ *                      at this point. Persisted in JSON exports; ignored by
+ *                      Mermaid/PlantUML serializers (those formats don't
+ *                      encode routing).
+ */
+interface DiagramEdge {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+    style?: 'solid' | 'dashed' | 'dotted';
+    arrowhead?: 'arrow' | 'none' | 'open';
+    waypoint?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * A single message in a sequence diagram.
+ *
+ * @property id     Stable, unique-within-model identifier.
+ * @property from   Source actor name. Must appear in the model's `actors` list.
+ * @property to     Target actor name. Must appear in the model's `actors` list.
+ * @property label  Message text rendered above the arrow.
+ * @property style  Arrow style. `solid` is default; `dashed` is conventional
+ *                  for asynchronous or return messages.
+ */
+interface SequenceMessage {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    style?: 'solid' | 'dashed';
+}
+/**
+ * The serialized shape of any diagram. Flowchart-type models populate
+ * `nodes`/`edges`; sequence-type models populate `actors`/`messages`. Both
+ * sub-shapes coexist on a single union to keep the JSON exporter / importer
+ * straightforward.
+ *
+ * @property type      Discriminator — selects which sub-shape is active.
+ * @property variant   UI variant. Only meaningful when `type === 'flowchart'`.
+ * @property title     Optional human-readable diagram title.
+ * @property nodes     Flowchart nodes. Always present (empty for sequence
+ *                     models) so the type stays uniform.
+ * @property edges     Flowchart edges. Always present (empty for sequence
+ *                     models).
+ * @property actors    Ordered list of actor names. Sequence models only.
+ * @property messages  Ordered list of messages between actors. Sequence
+ *                     models only.
+ */
+interface DiagramModel {
+    type: DiagramType;
+    variant?: DiagramVariant;
+    title?: string;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    actors?: string[];
+    messages?: SequenceMessage[];
+}
+/**
+ * A single problem found by `Model.validate()`.
+ *
+ * @property kind     Category of the problem:
+ *                    - `dangling-from`: edge `from` references a missing node.
+ *                    - `dangling-to`: edge `to` references a missing node.
+ *                    - `duplicate-node-id`: two nodes share an `id`.
+ *                    - `duplicate-edge-id`: two edges share an `id`.
+ * @property id       Identifier of the offending node or edge.
+ * @property message  Human-readable description suitable for surfacing in UI.
+ */
+interface ValidationError {
+    kind: 'dangling-from' | 'dangling-to' | 'duplicate-node-id' | 'duplicate-edge-id';
+    id: string;
+    message: string;
+}
+
+/**
+ * Mutable builder around a `DiagramModel`. Every public mutator returns
+ * `this` so callers can chain (`new Model('flowchart').addNode(...).addEdge(...)`).
+ * Call `.toJSON()` to extract a deep-cloned plain model suitable for
+ * serialization or for handing to the editor components.
+ *
+ * All add/update operations validate immediately and throw on collisions or
+ * dangling references. For non-throwing, batch-style structural checks call
+ * `.validate()` instead.
+ */
+declare class Model {
+    private data;
+    /**
+     * Create an empty model.
+     *
+     * @param type     Top-level kind — `flowchart` or `sequence`.
+     * @param title    Optional human-readable title.
+     * @param variant  Optional UI variant (flowchart models only).
+     */
+    constructor(type: DiagramType, title?: string, variant?: DiagramVariant);
+    /**
+     * Rehydrate a `Model` from a previously serialized `DiagramModel`. The
+     * incoming data is deep-cloned, so future mutations on the returned `Model`
+     * do not affect the caller's object.
+     */
+    static fromData(data: DiagramModel): Model;
+    /** Set the UI variant. No-op semantics for sequence models. */
+    setVariant(variant: DiagramVariant): this;
+    /**
+     * Append a node. Throws if a node with the same id already exists. The
+     * input is shallow-cloned, so later mutations of the caller's object do
+     * not leak in.
+     */
+    addNode(node: DiagramNode): this;
+    /**
+     * Patch an existing node in place. Throws if the id is not found. The id
+     * field itself cannot be patched — to rename, remove + re-add.
+     */
+    updateNode(id: string, patch: Partial<Omit<DiagramNode, 'id'>>): this;
+    /**
+     * Remove a node and every edge that referenced it as `from` or `to`. Safe
+     * to call on a missing id (no-op).
+     */
+    removeNode(id: string): this;
+    /**
+     * Append an edge. Throws on duplicate id or if either endpoint references
+     * an unknown node — the model never holds dangling edges from this entry
+     * point. (Importers can still construct dangling edges; call `validate()`
+     * to detect them.)
+     */
+    addEdge(edge: DiagramEdge): this;
+    /**
+     * Surface structural problems without throwing. Returns an array of
+     * `ValidationError`s; empty array means the model is well-formed. Used by
+     * the editor's status banner and by external tooling.
+     */
+    validate(): ValidationError[];
+    /** Remove an edge by id. Safe to call on a missing id (no-op). */
+    removeEdge(id: string): this;
+    /** Append a sequence actor. Duplicate names are silently ignored. */
+    addActor(name: string): this;
+    /**
+     * Append a sequence message. The actors referenced by `from`/`to` are not
+     * validated here — callers are expected to register them via `addActor()`
+     * first.
+     */
+    addMessage(message: SequenceMessage): this;
+    /**
+     * Return a deep-cloned plain `DiagramModel`. Safe to mutate by the caller;
+     * mutations do not flow back into this `Model`.
+     */
+    toJSON(): DiagramModel;
+}
+
+/**
+ * Fluent builder for flowchart-type diagrams. Wraps `Model` with shorter
+ * method names tuned for one-shot construction in tests and scripts, and
+ * with convenience exporters for every supported `ExportFormat`.
+ *
+ * @example
+ * ```ts
+ * const svg = flowchart('Login')
+ *   .node('start', 'Begin', { shape: 'circle' })
+ *   .node('check', 'Authenticated?', { shape: 'diamond' })
+ *   .edge('start', 'check')
+ *   .toSVG();
+ * ```
+ */
+declare class FlowchartBuilder {
+    private model;
+    /** @param title Optional human-readable diagram title. */
+    constructor(title?: string);
+    /**
+     * Append a node. Defaults `shape` to `rectangle` when omitted from `options`.
+     * Throws on duplicate id.
+     */
+    node(id: string, label: string, options?: Partial<Omit<DiagramNode, 'id' | 'label'>>): this;
+    /**
+     * Append an edge with an auto-generated id. The id is derived from the
+     * current edge list to avoid collisions with imported models.
+     */
+    edge(from: string, to: string, options?: Partial<Omit<DiagramEdge, 'id' | 'from' | 'to'>>): this;
+    /** Remove a node and every edge that references it. */
+    removeNode(id: string): this;
+    /** Remove an edge by id. */
+    removeEdge(id: string): this;
+    /** Patch an existing node. See `Model.updateNode`. */
+    updateNode(id: string, patch: Partial<Omit<DiagramNode, 'id'>>): this;
+    /** Return the underlying `Model` for advanced operations or validation. */
+    getModel(): Model;
+    /** Serialize as Mermaid `flowchart TD` source. */
+    toMermaid(): string;
+    /** Serialize as PlantUML activity-diagram source. */
+    toPlantUML(): string;
+    /** Serialize as the package's JSON shape (full round-trip fidelity). */
+    toJSON(): string;
+    /** Render to a standalone SVG string. */
+    toSVG(): string;
+    /** Render to a PNG `Blob`. Browser-only (uses the Canvas API). */
+    toPNG(): Promise<Blob>;
+}
+/** Convenience constructor — `flowchart('My Diagram')` is `new FlowchartBuilder('My Diagram')`. */
+declare function flowchart(title?: string): FlowchartBuilder;
+
+/**
+ * Fluent builder for sequence-type diagrams. Mirrors `FlowchartBuilder` but
+ * over `actors`/`messages` instead of `nodes`/`edges`.
+ *
+ * @example
+ * ```ts
+ * const puml = sequence('Checkout')
+ *   .actor('User')
+ *   .message('User', 'Server', 'POST /pay')
+ *   .replyMessage('Server', 'User', '200 OK')
+ *   .toPlantUML();
+ * ```
+ */
+declare class SequenceBuilder {
+    private model;
+    /** @param title Optional human-readable diagram title. */
+    constructor(title?: string);
+    /** Register an actor. Duplicates are silently ignored. */
+    actor(name: string): this;
+    /**
+     * Append a message. Both endpoints are auto-registered as actors if not
+     * already present. The id is derived from the current message list.
+     */
+    message(from: string, to: string, label: string, options?: Partial<Pick<SequenceMessage, 'style'>>): this;
+    /** Convenience for a `dashed`-style return message. */
+    replyMessage(from: string, to: string, label: string): this;
+    /** Return the underlying `Model` for advanced operations or validation. */
+    getModel(): Model;
+    /** Serialize as Mermaid `sequenceDiagram` source. */
+    toMermaid(): string;
+    /** Serialize as PlantUML sequence-diagram source. */
+    toPlantUML(): string;
+    /** Serialize as the package's JSON shape (full round-trip fidelity). */
+    toJSON(): string;
+}
+/** Convenience constructor — `sequence('My Diagram')` is `new SequenceBuilder('My Diagram')`. */
+declare function sequence(title?: string): SequenceBuilder;
+
+/**
+ * Serialize a `DiagramModel` to Mermaid source. Dispatches between
+ * `graph TD` (flowchart) and `sequenceDiagram` based on `model.type`.
+ *
+ * **Round-trip notes (flowchart):**
+ * - Node shapes `rectangle`, `diamond`, `circle`, `parallelogram` map to
+ *   `[ ]`, `{ }`, `(( ))`, `[/ /]` respectively.
+ * - Edge style `solid` → `-->`, `dashed` and `dotted` → `-.->` (Mermaid
+ *   collapses dotted to dashed). `arrowhead: 'none'` strips the head.
+ * - `waypoint`, `metadata`, and `variant` are **dropped** — Mermaid has no
+ *   way to encode routing or arbitrary metadata.
+ *
+ * **Round-trip notes (sequence):**
+ * - Message style `solid` → `->>`, `dashed` → `-->>`.
+ */
+declare function toMermaid(model: DiagramModel): string;
+
+/**
+ * Serialize a `DiagramModel` to PlantUML source. Dispatches between the
+ * state-diagram form (flowchart) and the sequence-diagram form based on
+ * `model.type`.
+ *
+ * **Round-trip notes (flowchart):**
+ * - Edge style maps `solid` → `-->`, `dashed` → `-[dashed]->`,
+ *   `dotted` → `-[dotted]->`.
+ * - Node shapes are emitted via the `state ".." as id < >` syntax; some
+ *   shape information is lossy (PlantUML state diagrams don't distinguish
+ *   every shape this package supports).
+ * - `waypoint`, `metadata`, and `variant` are **dropped**.
+ *
+ * **Round-trip notes (sequence):**
+ * - Actor order is preserved; message style `solid` → `->`, `dashed` → `-->`.
+ */
+declare function toPlantUML(model: DiagramModel): string;
+
+/**
+ * Serialize a `DiagramModel` to pretty-printed JSON. This is the canonical
+ * round-trip format: every field — including `variant`, `waypoint`,
+ * `metadata.group`, and `metadata.answers` — survives a round trip through
+ * `toJSON` + `fromJSON` unchanged.
+ */
+declare function toJSON(model: DiagramModel): string;
+
+/**
+ * Render a `DiagramModel` to a standalone SVG string. The output mirrors the
+ * editor canvas: dot-grid background, soft drop-shadowed nodes, smooth
+ * cubic-bezier edges. No external assets — the result is fully inline and
+ * pasteable into HTML, README files, or PR descriptions.
+ *
+ * Layout is computed identically to the editor's hit-test pass (same width
+ * estimation, padding, and question-card sizing), so an exported SVG matches
+ * what you see on screen.
+ *
+ * Works in Node, Bun, and the browser (no DOM APIs needed).
+ */
+declare function toSVG(model: DiagramModel): string;
+/**
+ * Render a `DiagramModel` to a PNG `Blob`. Routes the SVG output through an
+ * `<img>` and a `<canvas>` at `devicePixelRatio` scale, so the result is
+ * crisp on hi-DPI displays.
+ *
+ * **Browser-only.** Throws if called in a Node/Bun environment (the Canvas
+ * API is not available). For server-side PNG rendering, pipe `toSVG()` output
+ * through a library like `@resvg/resvg-js`.
+ */
+declare function toPNG(model: DiagramModel): Promise<Blob>;
+
+/**
+ * Parse Mermaid source into a `Model`. Auto-detects `flowchart` /
+ * `sequenceDiagram` from the directive line and dispatches accordingly.
+ *
+ * **What is preserved:**
+ * - Flowcharts: node shapes (`[]` / `{}` / `(())` / `[/]`), node labels,
+ *   edge connectors (`-->`, `-.->`, `---`, `-.-`), edge labels, and
+ *   `subgraph` grouping (stored on `node.metadata.group`).
+ * - Sequence: actor declarations, message arrows (`->>`, `-->>`), labels.
+ * - Frontmatter `title: ...` blocks are lifted into `model.title`.
+ *
+ * **What is dropped or normalized:**
+ * - `mermaid.initialize(...)` blocks, `%%{init: ...}%%` directives, and
+ *   click handlers — stripped before parsing.
+ * - Dotted edges collapse to `dashed` (Mermaid's dot/dash style is lossy).
+ * - Node positions, `waypoint`, and any package-specific metadata other
+ *   than `group` are not present in Mermaid and so cannot round-trip.
+ */
+declare function fromMermaid(mermaid: string): Model;
+
+/**
+ * Rehydrate a `Model` from the package's JSON shape. Accepts either the raw
+ * JSON string or an already-parsed `DiagramModel` (handy when the caller has
+ * received the data from a typed source).
+ *
+ * Validation here is minimal — only the structural fields needed by the
+ * downstream renderer (`type`, `nodes`, `edges`) are checked. For deeper
+ * checks call `model.validate()` after import.
+ *
+ * @throws If `json` is not a valid `DiagramModel` shape.
+ */
+declare function fromJSON(json: string | DiagramModel): Model;
+
+export { type DiagramEdge, type DiagramModel, type DiagramNode, type DiagramType, type DiagramVariant, type DiagramEdge as Edge, type ExportFormat, FlowchartBuilder, Model, type DiagramNode as Node, type NodeShape, SequenceBuilder, type SequenceMessage, flowchart, fromJSON, fromMermaid, sequence, toJSON, toMermaid, toPNG, toPlantUML, toSVG };