flowchart-sequence-designer 1.0.0

package/dist/ui/index.d.cts

@@ -0,0 +1,356 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 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[];
+}
+
+/**
+ * Color palette for the flowchart `<DiagramEditor>`. Every visual surface
+ * pulls from one of these tokens, so overriding any single property via
+ * `themeOverrides` updates every element that uses it. Built-in
+ * `lightTheme` and `darkTheme` are exported as ready-made values.
+ *
+ * Token groups:
+ * - `canvas` / `dot` — background and dot-grid color.
+ * - `nodeFill` / `nodeStroke` / `nodeSelectedFill` — base node styling.
+ * - `edgeColor` — edge stroke and arrowhead color.
+ * - `text*` — type ramp (primary > secondary > muted).
+ * - `panel*` / `ctrls*` / `input*` / `card*` / `section*` — chrome around
+ *   the canvas (side panel, controls, form fields, card rows).
+ * - `labelText` / `hintText` — small-text accents inside chrome.
+ * - `statusBg` / `bannerBg` — bottom validation banner backdrop.
+ * - `btnSec*` / `shapeBtn*` — secondary button surfaces.
+ * - `addFormBg` — accent backdrop for the "add node" form.
+ */
+interface ThemeColors {
+    canvas: string;
+    dot: string;
+    nodeFill: string;
+    nodeStroke: string;
+    nodeSelectedFill: string;
+    edgeColor: string;
+    textPrimary: string;
+    textSecondary: string;
+    textMuted: string;
+    panelBg: string;
+    panelBorder: string;
+    ctrlsBg: string;
+    ctrlsBorder: string;
+    inputBg: string;
+    inputBorder: string;
+    inputText: string;
+    cardBg: string;
+    cardBorder: string;
+    sectionBorder: string;
+    labelText: string;
+    hintText: string;
+    statusBg: string;
+    btnSecBg: string;
+    btnSecText: string;
+    shapeBtnBg: string;
+    shapeBtnBorder: string;
+    addFormBg: string;
+    bannerBg: string;
+}
+interface VariantAccent {
+    color: string;
+    fill: string;
+    border: string;
+    glow: string;
+}
+
+/**
+ * Props for `<DiagramEditor>`. All fields are optional — mounting with no
+ * props renders the flowchart preset on an `auto`-themed canvas with every
+ * export format and import enabled.
+ *
+ * @property initialModel    Initial diagram. If a sequence model is passed,
+ *                           rendering is delegated to `<SequenceEditor>`. If
+ *                           omitted, `presetFlowchartModel(variant)` is used.
+ * @property onChange        Fires after every committed mutation (undo/redo,
+ *                           drag, label edit, etc.). Receives the new model.
+ * @property onExport        Optional sink for exporter output. If omitted, the
+ *                           editor triggers a browser download of `diagram.<ext>`.
+ * @property height          Canvas height; accepts CSS units. Defaults to `600`.
+ * @property allowedExports  Whitelist of export formats to show in the
+ *                           toolbar. Defaults to all formats.
+ * @property allowImport     Show the import button. Defaults to `true`.
+ * @property variant         Initial variant when `initialModel` is omitted.
+ *                           Ignored if `initialModel.variant` is set.
+ * @property theme           `'light'`, `'dark'`, or `'auto'` (follow OS).
+ *                           Defaults to `'auto'`.
+ * @property themeOverrides  Per-property overrides on top of the resolved
+ *                           palette. Useful for brand-matching without forking.
+ */
+interface DiagramEditorProps {
+    initialModel?: DiagramModel;
+    onChange?: (model: DiagramModel) => void;
+    onExport?: (format: ExportFormat, content: string | Blob) => void;
+    height?: number | string;
+    allowedExports?: ExportFormat[];
+    allowImport?: boolean;
+    variant?: DiagramVariant;
+    theme?: 'light' | 'dark' | 'auto';
+    themeOverrides?: Partial<ThemeColors>;
+}
+/**
+ * The all-in-one editor component. Renders a smart router: if the supplied
+ * `initialModel.type` is `sequence`, it delegates to `<SequenceEditor>` with
+ * the same props pass-through. Otherwise it renders the flowchart editor.
+ *
+ * @example
+ * ```tsx
+ * import { DiagramEditor } from 'flowchart-sequence-designer/ui';
+ *
+ * export default function App() {
+ *   return <DiagramEditor height={520} onChange={(m) => console.log(m)} />;
+ * }
+ * ```
+ */
+declare function DiagramEditor(props: DiagramEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Color palette for `<SequenceEditor>`. Sequence diagrams use a smaller
+ * token set than flowcharts — there are no node shapes to color, but there
+ * are `lifeline`, `arrow`, and `actor*` tokens that flowcharts don't need.
+ *
+ * Token groups:
+ * - `canvas` / `dot` — background and dot-grid color.
+ * - `panel*` / `ctrls*` / `input*` / `card*` — chrome around the canvas.
+ * - `text*` — type ramp (primary > secondary > muted).
+ * - `lifeline` — vertical actor lifeline color.
+ * - `arrow` — message arrow + label color.
+ * - `actorFill` / `actorStroke` / `actorText` — actor header box.
+ */
+interface SequenceThemeColors {
+    canvas: string;
+    dot: string;
+    panelBg: string;
+    panelBorder: string;
+    ctrlsBg: string;
+    ctrlsBorder: string;
+    inputBg: string;
+    inputBorder: string;
+    inputText: string;
+    textPrimary: string;
+    textSecondary: string;
+    textMuted: string;
+    cardBg: string;
+    cardBorder: string;
+    lifeline: string;
+    arrow: string;
+    actorFill: string;
+    actorStroke: string;
+    actorText: string;
+}
+/**
+ * Props for `<SequenceEditor>`. Mirrors `DiagramEditorProps` minus the
+ * flowchart-only `variant` field; the theme override type is the
+ * sequence-specific palette.
+ *
+ * @property initialModel    Initial sequence model. Defaults to
+ *                           `presetSequenceModel()` if omitted or if a
+ *                           non-sequence model is passed.
+ * @property onChange        Fires after every committed mutation.
+ * @property onExport        Optional sink for exporter output. If omitted, the
+ *                           editor triggers a browser download of `sequence.<ext>`.
+ * @property height          Canvas height; accepts CSS units. Defaults to `600`.
+ * @property allowedExports  Whitelist of export formats. Defaults to all.
+ * @property allowImport     Show the import button. Defaults to `true`.
+ * @property theme           `'light'`, `'dark'`, or `'auto'` (follow OS).
+ * @property themeOverrides  Per-property overrides on top of the resolved
+ *                           sequence palette. `themeOverrides` passed to
+ *                           `<DiagramEditor>` is forwarded here when
+ *                           `type === 'sequence'`.
+ */
+interface SequenceEditorProps {
+    initialModel?: DiagramModel;
+    onChange?: (model: DiagramModel) => void;
+    onExport?: (format: ExportFormat, content: string | Blob) => void;
+    height?: number | string;
+    allowedExports?: ExportFormat[];
+    allowImport?: boolean;
+    theme?: 'light' | 'dark' | 'auto';
+    themeOverrides?: Partial<SequenceThemeColors>;
+}
+/**
+ * Sequence-diagram specialization of the editor. Accepts the same props as
+ * `<DiagramEditor>` but renders a swim-lane layout with drag-to-reorder
+ * messages and inline label editing.
+ *
+ * @example
+ * ```tsx
+ * import { SequenceEditor, presetSequenceModel } from 'flowchart-sequence-designer/ui';
+ *
+ * <SequenceEditor initialModel={presetSequenceModel()} theme="dark" />
+ * ```
+ */
+declare function SequenceEditor({ initialModel, onChange, onExport, height, allowedExports, allowImport, theme, themeOverrides, }: SequenceEditorProps): react_jsx_runtime.JSX.Element;
+
+interface ToolbarProps {
+    onExport: (format: ExportFormat) => void;
+    onImport?: (text: string) => void;
+    allowedExports?: ExportFormat[];
+    allowImport?: boolean;
+}
+declare function Toolbar({ onExport, onImport, allowedExports, allowImport }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+interface StepEditorProps {
+    nodeId: string;
+    model: DiagramModel;
+    onModelChange: (model: DiagramModel) => void;
+    variant?: DiagramVariant;
+    isDark?: boolean;
+    t?: ThemeColors;
+    acc?: VariantAccent;
+}
+declare function StepEditor({ nodeId, model, onModelChange, variant, isDark, t, acc }: StepEditorProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Built-in sample diagrams shown when a consumer mounts the editor without
+ * an `initialModel`. The goal is for the empty state to look like a real
+ * working diagram, not a blank canvas — so a developer evaluating the
+ * package immediately sees the canvas, edge styles, and side panels with
+ * meaningful content.
+ *
+ * Pass `initialModel={emptyModel(variant)}` (or any model of your own) to
+ * opt out of the preset.
+ */
+
+/**
+ * Return a blank model of the requested type/variant. Useful as
+ * `initialModel={emptyModel('flowchart')}` to opt out of the demo preset.
+ */
+declare function emptyModel(type: DiagramType, variant?: DiagramVariant): DiagramModel;
+/**
+ * Return a fresh, ready-to-edit flowchart model for the requested variant.
+ * The result is a deep clone — callers may mutate freely without affecting
+ * future calls.
+ *
+ * - `flowchart` → 6-node order-processing example with a decision diamond
+ * - `question`  → 1-question / 3-answer routing example
+ * - `journey`   → 5-step linear onboarding sequence
+ */
+declare function presetFlowchartModel(variant?: DiagramVariant): DiagramModel;
+/**
+ * Return a fresh, ready-to-edit sequence model — a 4-message User → App →
+ * Server login flow. Deep-cloned; safe to mutate.
+ */
+declare function presetSequenceModel(): DiagramModel;
+
+export { DiagramEditor, type DiagramEditorProps, SequenceEditor, type SequenceEditorProps, type SequenceThemeColors, StepEditor, type ThemeColors, Toolbar, emptyModel, presetFlowchartModel, presetSequenceModel };