@dskripchenko/diagrams 1.0.2 → 1.2.0

package/dist/index.d.ts

@@ -1,18 +1,217 @@
+declare interface Accessibility {
+    title?: string;
+    description?: string;
+}
+
+declare interface ActivationEvent {
+    kind: 'activate' | 'deactivate';
+    actor: string;
+    sourceLine: number;
+}
+
 /**
  * Measures with a table of glyph widths. Deterministic, which also makes it
  * the measurer for tests and snapshots.
  */
 export declare const approximateMeasurer: TextMeasurer;
 
+declare type ArrowHead = 'none' | 'arrow' | 'open' | 'cross';
+
+declare type AttributeKey = 'PK' | 'FK' | 'UK';
+
+declare interface BlockEndEvent {
+    kind: 'block-end';
+    sourceLine: number;
+}
+
+/** `group` is PlantUML's labelled block: its text is the tab. */
+declare type BlockKind = 'loop' | 'alt' | 'opt' | 'par' | 'critical' | 'break' | 'rect' | 'group';
+
+declare interface BlockSectionEvent {
+    kind: 'block-section';
+    /** `else`, `and` or `option`. */
+    keyword: 'else' | 'and' | 'option';
+    text: string;
+    sourceLine: number;
+}
+
+declare interface BlockStartEvent {
+    kind: 'block-start';
+    block: BlockKind;
+    /** Guard text; for `rect`, empty. */
+    text: string;
+    /** `rect` only: the validated background colour. */
+    color?: string;
+    sourceLine: number;
+}
+
+declare type BoundaryKind = 'boundary' | 'enterprise' | 'system' | 'container' | 'node';
+
+declare interface C4Boundary {
+    id: string;
+    kind: BoundaryKind;
+    label: string;
+    /** The type line: `$type` of `Boundary` and deployment nodes. */
+    type?: string;
+    description?: string;
+    parent?: string;
+    style?: ElementStyle;
+}
+
+declare interface C4Diagram {
+    type: 'c4';
+    kind: C4Kind;
+    title?: string;
+    direction: 'TB' | 'LR';
+    /** Elements in declaration order. */
+    elements: Map<string, C4Element>;
+    /** Boundaries and deployment nodes in declaration order. */
+    boundaries: Map<string, C4Boundary>;
+    /** Everything a scope contains, in declaration order (scope id `''` is the root). */
+    children: Map<string, string[]>;
+    relations: C4Relation[];
+    /** `UpdateLayoutConfig`. */
+    shapeInRow: number;
+    boundaryInRow: number;
+    accessibility: Accessibility;
+}
+
+declare interface C4Element {
+    id: string;
+    level: ElementLevel;
+    shape: ElementShape;
+    external: boolean;
+    label: string;
+    /** `$techn` of containers and components. */
+    techn?: string;
+    /** `$type` of persons and systems: replaces the default type line. */
+    type?: string;
+    description?: string;
+    /** The boundary or deployment node it is declared in. */
+    parent?: string;
+    style?: ElementStyle;
+}
+
+declare type C4Kind = 'C4Context' | 'C4Container' | 'C4Component' | 'C4Dynamic' | 'C4Deployment';
+
+declare interface C4Relation {
+    from: string;
+    to: string;
+    label: string;
+    techn?: string;
+    description?: string;
+    direction?: RelDirection;
+    /** Which ends carry an arrowhead. */
+    arrows: 'end' | 'start' | 'both';
+    /** `Lay_*`: a layout hint only, not drawn. */
+    hidden: boolean;
+    /** The number shown in front of the label (C4Dynamic and `RelIndex`). */
+    index?: string;
+    style?: {
+        line?: string;
+        text?: string;
+    };
+    line: number;
+    column: number;
+}
+
+/** How many rows of one entity relate to one row of the other. */
+declare type Cardinality = 'one' | 'zero-one' | 'one-many' | 'zero-many';
+
+declare interface ClassDiagram {
+    type: 'class';
+    direction: Direction;
+    classes: Map<string, ClassNode>;
+    relations: ClassRelation[];
+    notes: ClassNote[];
+    namespaces: Map<string, ClassNamespace>;
+    classDefs: Map<string, UserStyle>;
+    accessibility: Accessibility;
+}
+
+/** `$` after a member: static (underlined); `*`: abstract (italic). */
+declare type Classifier = 'static' | 'abstract';
+
+declare interface ClassMember {
+    kind: 'attribute' | 'method';
+    /** What the box shows: generics as `<…>`, a method's return type after a colon. */
+    text: string;
+    visibility?: Visibility;
+    classifier?: Classifier;
+}
+
+declare interface ClassNamespace {
+    id: string;
+}
+
+declare interface ClassNode {
+    id: string;
+    /** The name the box shows: a `["label"]`, or the id with its generic parameter. */
+    label: string;
+    /** `T` of `class Square~T~`. */
+    generic?: string;
+    /** `interface`, `abstract`, … as written between `<<` and `>>`. */
+    annotations: string[];
+    attributes: ClassMember[];
+    methods: ClassMember[];
+    namespace?: string;
+    classes: string[];
+    style?: UserStyle;
+    link?: {
+        href: string;
+        tooltip?: string;
+        target?: string;
+    };
+}
+
+declare interface ClassNote {
+    /** The class the note is attached to; none for a free-standing note. */
+    target?: string;
+    text: string;
+}
+
+declare interface ClassRelation {
+    from: string;
+    to: string;
+    fromEnd: RelationEnd;
+    toEnd: RelationEnd;
+    /** `..` rather than `--`: dependency, realization, dashed link. */
+    dashed: boolean;
+    fromCardinality?: string;
+    toCardinality?: string;
+    label?: string;
+}
+
 /**
  * The best measurer the environment offers: a canvas when there is one,
  * otherwise the glyph table.
  */
 export declare function defaultMeasurer(): TextMeasurer;
 
-/** The diagram type a source declares on its first line, or null. */
+/** Time passes: a gap, with an optional text (PlantUML `...` / `...text...`). */
+declare interface DelayEvent {
+    kind: 'delay';
+    text: string;
+    sourceLine: number;
+}
+
+declare interface DestroyEvent {
+    kind: 'destroy';
+    actor: string;
+    sourceLine: number;
+}
+
+/**
+ * The diagram type of a source, or null: a Mermaid source declares it on its
+ * first line; a PlantUML one is recognised from its statements and reported
+ * as the type it is drawn as (`sequence`, or `flowchart` for use case,
+ * component, deployment and activity diagrams).
+ */
 export declare function detect(source: string): DiagramType | null;
 
+/** The syntax of a source: PlantUML when it starts with `@start…`, else Mermaid. */
+export declare function detectSyntax(source: string): Syntax;
+
 /**
  * The one error every parser and layout throws.
  *
@@ -34,7 +233,119 @@ export declare class DiagramError extends Error {
     constructor(message: string, line?: number, column?: number, hint?: string | undefined);
 }
 
-export declare type DiagramType = 'pie' | 'gantt' | 'flowchart' | 'sequence' | 'state';
+export declare type DiagramType = 'pie' | 'gantt' | 'flowchart' | 'sequence' | 'state' | 'timeline' | 'xychart' | 'mindmap' | 'er' | 'class' | 'c4' | 'journey' | 'quadrant' | 'kanban' | 'requirement' | 'architecture' | 'sankey' | 'gitgraph' | 'block' | 'timing' | 'salt';
+
+declare type Direction = 'TB' | 'BT' | 'LR' | 'RL';
+
+/** A rule across the whole diagram with a title in the middle (PlantUML `== text ==`). */
+declare interface DividerEvent {
+    kind: 'divider';
+    text: string;
+    sourceLine: number;
+}
+
+/** Line ends; the UML ones (triangle, diamonds, open arrow) come from PlantUML. */
+declare type EdgeEnd = 'none' | 'arrow' | 'circle' | 'cross' | 'triangle' | 'diamond' | 'diamond-open' | 'open-arrow';
+
+declare type ElementLevel = 'person' | 'system' | 'container' | 'component';
+
+declare type ElementShape = 'box' | 'person' | 'db' | 'queue';
+
+/** Validated colours from `UpdateElementStyle` / `UpdateBoundaryStyle`. */
+declare interface ElementStyle {
+    fill?: string;
+    stroke?: string;
+    text?: string;
+}
+
+declare interface ErAttribute {
+    type: string;
+    name: string;
+    keys: AttributeKey[];
+    comment?: string;
+}
+
+declare interface ErDiagram {
+    type: 'er';
+    direction: Direction;
+    entities: Map<string, ErEntity>;
+    relationships: ErRelationship[];
+    classDefs: Map<string, UserStyle>;
+    accessibility: Accessibility;
+}
+
+declare interface ErEntity {
+    id: string;
+    /** What the box shows: the alias from `ID["Alias"]`, or the id. */
+    label: string;
+    attributes: ErAttribute[];
+    classes: string[];
+    style?: UserStyle;
+}
+
+declare interface ErRelationship {
+    from: string;
+    to: string;
+    /** Cardinality at the `from` entity, written on the left of the line. */
+    fromCardinality: Cardinality;
+    toCardinality: Cardinality;
+    /** `--` (identifying, solid) or `..` (non-identifying, dashed). */
+    identifying: boolean;
+    label: string;
+}
+
+declare interface Flowchart {
+    type: 'flowchart';
+    direction: Direction;
+    nodes: Map<string, FlowNode>;
+    edges: FlowEdge[];
+    subgraphs: Map<string, FlowSubgraph>;
+    classDefs: Map<string, UserStyle>;
+    accessibility: Accessibility;
+}
+
+declare interface FlowEdge {
+    from: string;
+    to: string;
+    stroke: Stroke;
+    start: EdgeEnd;
+    end: EdgeEnd;
+    /** Ranks the edge spans at least: `-->` 1, `--->` 2. */
+    length: number;
+    text?: string;
+    markdown: boolean;
+    style?: UserStyle;
+}
+
+declare interface FlowNode {
+    id: string;
+    /** Label source; the id when the node never got text. */
+    text: string;
+    markdown: boolean;
+    shape: ShapeKind;
+    classes: string[];
+    style?: UserStyle;
+    link?: {
+        href: string;
+        tooltip?: string;
+        target?: string;
+    };
+    tooltip?: string;
+    /** The subgraph the node belongs to. */
+    subgraph?: string;
+}
+
+declare interface FlowSubgraph {
+    id: string;
+    title: string;
+    markdown: boolean;
+    parent?: string;
+    direction?: Direction;
+    classes: string[];
+    style?: UserStyle;
+    /** The frame's shape: a package, a node, a cloud… (PlantUML containers); a rectangle by default. */
+    kind?: ShapeKind;
+}
 
 export declare interface FontSpec {
     /** Pixels. */
@@ -44,8 +355,152 @@ export declare interface FontSpec {
     style?: 'normal' | 'italic';
 }
 
+declare interface GanttDiagram {
+    type: 'gantt';
+    title?: string;
+    dateFormat: string;
+    axisFormat: string;
+    /** True when `axisFormat` was written; otherwise the renderer may pick a shorter one. */
+    axisFormatSet: boolean;
+    tickInterval?: TickInterval;
+    excludes: string[];
+    includes: string[];
+    /** 'on' (default), 'off', or a style for the marker line. */
+    todayMarker: string;
+    topAxis: boolean;
+    inclusiveEndDates: boolean;
+    sections: string[];
+    tasks: GanttTask[];
+    /** Excluded days within the chart's span, merged into ranges, for shading. */
+    excludedRanges: {
+        start: number;
+        end: number;
+    }[];
+    accessibility: Accessibility;
+}
+
+declare interface GanttTags {
+    done: boolean;
+    active: boolean;
+    crit: boolean;
+    milestone: boolean;
+}
+
+declare interface GanttTask {
+    id: string;
+    name: string;
+    /** Section name; '' for tasks before the first `section`. */
+    section: string;
+    tags: GanttTags;
+    /** Milliseconds since the epoch, UTC. */
+    start: number;
+    end: number;
+    /**
+     * Where the bar is drawn to. Differs from `end` only when excluded days
+     * stretched the task: the bar stops at the last working day rather than
+     * running across the weekend that follows it.
+     */
+    renderEnd: number;
+    href?: string;
+    line: number;
+}
+
+declare type LineStyle = 'solid' | 'dotted';
+
+declare interface MessageEvent_2 {
+    kind: 'message';
+    from: string;
+    to: string;
+    line: LineStyle;
+    head: ArrowHead;
+    /** `<<->>`: an arrowhead at both ends. */
+    bidirectional: boolean;
+    text: string;
+    /** `+` before the target: the target is activated by this message. */
+    activateTarget: boolean;
+    /** `-` before the target: the sender's activation ends with this message. */
+    deactivateSource: boolean;
+    /** The autonumber shown next to the message, if numbering is on. */
+    number?: number;
+    sourceLine: number;
+}
+
+declare interface MindmapDiagram {
+    type: 'mindmap';
+    root: MindmapNode;
+    accessibility: Accessibility;
+}
+
+declare interface MindmapNode {
+    id: string;
+    /** The text as written; `markdown` says whether `**` and `*` style it. */
+    label: string;
+    markdown: boolean;
+    shape: MindmapShape;
+    /** `::icon(…)` is read and kept, but not drawn: there is no icon font to draw it with. */
+    icon?: string;
+    /** `:::name` classes, kept for tools; Mermaid's mind maps have no classDef to apply them. */
+    classes: string[];
+    children: MindmapNode[];
+    line: number;
+    column: number;
+}
+
+declare type MindmapShape = 'default' | 'square' | 'rounded' | 'circle' | 'bang' | 'cloud' | 'hexagon';
+
+declare interface NoteEvent {
+    kind: 'note';
+    placement: 'left' | 'right' | 'over';
+    /** One participant, or two for `over A,B`. */
+    actors: string[];
+    text: string;
+    sourceLine: number;
+}
+
 /** Parses without laying out: the diagram's structure, for tools and tests. */
-export declare function parse(source: string): unknown;
+export declare function parse(source: string, options?: {
+    syntax?: Syntax;
+}): unknown;
+
+export declare interface ParsedPlantUml {
+    kind: PlantUmlKind;
+    model: PlantUmlModel;
+}
+
+export declare function parsePlantUml(source: string): ParsedPlantUml;
+
+declare interface Participant {
+    id: string;
+    /** Label source; `<br>` breaks lines. */
+    label: string;
+    kind: ParticipantKind;
+    /** Index into `boxes`, when declared inside a `box`. */
+    box?: number;
+    /** Declared with `create`: drawn where it is first used rather than at the top. */
+    created: boolean;
+}
+
+declare interface ParticipantBox {
+    label?: string;
+    /** Validated CSS colour, or undefined for no fill. */
+    color?: string;
+}
+
+declare type ParticipantKind = 'participant' | 'actor' | 'boundary' | 'control' | 'entity' | 'database' | 'collections' | 'queue';
+
+/** The PlantUML diagram kinds this package reads. */
+export declare type PlantUmlKind = 'sequence' | 'activity' | 'description' | 'class' | 'state' | 'er' | 'c4' | 'mindmap' | 'wbs' | 'gantt' | 'timing' | 'salt';
+
+/** The kind of a `@startuml` diagram, recognised from its statements. */
+export declare function plantUmlKind(list: readonly Statement[]): PlantUmlKind;
+
+declare type PlantUmlModel = SequenceDiagram | Flowchart | ClassDiagram | StateDiagram | ErDiagram | C4Diagram | MindmapDiagram | GanttDiagram | TimingDiagram | SaltDiagram;
+
+/** The symbol at one end of a relationship. */
+declare type RelationEnd = 'none' | 'inheritance' | 'composition' | 'aggregation' | 'arrow';
+
+/** A layout hint: where `to` should be relative to `from`. */
+declare type RelDirection = 'up' | 'down' | 'left' | 'right';
 
 /**
  * Renders a diagram to an SVG string.
@@ -55,6 +510,8 @@ export declare function parse(source: string): unknown;
 export declare function render(source: string, options?: RenderOptions): RenderResult;
 
 export declare interface RenderOptions {
+    /** The source's syntax; recognised from its first line when omitted (`@startuml` → PlantUML). */
+    syntax?: Syntax;
     /** How text is measured; defaults to a canvas in the browser and a glyph table elsewhere. */
     measureText?: TextMeasurer;
     /**
@@ -78,6 +535,170 @@ export declare interface RenderResult {
     type: string;
 }
 
+/** Grid lines: none, outer border (`+`), all (`#`), columns (`!`), rows (`-`). */
+declare type SaltBorder = 'none' | 'outer' | 'all' | 'columns' | 'rows';
+
+declare interface SaltDiagram {
+    type: 'salt';
+    root: SaltWidget;
+    title?: string;
+    accessibility: Accessibility;
+}
+
+declare type SaltWidget = {
+    kind: 'text';
+    text: string;
+    bold: boolean;
+} | {
+    kind: 'button';
+    text: string;
+} | {
+    kind: 'input';
+    text: string;
+} | {
+    kind: 'checkbox';
+    text: string;
+    checked: boolean;
+} | {
+    kind: 'radio';
+    text: string;
+    checked: boolean;
+} | {
+    kind: 'droplist';
+    text: string;
+} | {
+    kind: 'empty';
+} | {
+    kind: 'separator';
+    style: 'dotted' | 'double' | 'dashed' | 'solid';
+} | {
+    kind: 'grid';
+    border: SaltBorder;
+    rows: SaltWidget[][];
+    title?: string;
+    scroll: boolean;
+} | {
+    kind: 'tabs';
+    tabs: string[];
+    selected: number;
+    vertical: boolean;
+} | {
+    kind: 'menu';
+    items: string[];
+} | {
+    kind: 'tree';
+    items: {
+        depth: number;
+        text: string;
+    }[];
+};
+
+declare interface SequenceDiagram {
+    type: 'sequence';
+    title?: string;
+    participants: Participant[];
+    boxes: ParticipantBox[];
+    events: SequenceEvent[];
+    accessibility: Accessibility;
+    /** No participants repeated at the bottom (PlantUML `hide footbox`). */
+    hideFootbox?: boolean;
+}
+
+declare type SequenceEvent = MessageEvent_2 | NoteEvent | ActivationEvent | BlockStartEvent | BlockSectionEvent | BlockEndEvent | DestroyEvent | DividerEvent | DelayEvent | SpaceEvent;
+
+declare type ShapeKind = 'rect' | 'round' | 'stadium' | 'subroutine' | 'cylinder' | 'circle' | 'doublecircle' | 'asymmetric' | 'rhombus' | 'hexagon' | 'parallelogram' | 'parallelogram-alt' | 'trapezoid' | 'trapezoid-alt' | 'start' | 'end' | 'fork' | 'choice' | 'actor' | 'usecase' | 'component' | 'interface' | 'node' | 'cloud' | 'folder' | 'frame' | 'artifact' | 'note' | 'file' | 'queue' | 'storage' | 'stack' | 'person' | 'collections' | 'boundary' | 'control' | 'entity' | 'text';
+
+declare interface Signal {
+    id: string;
+    label: string;
+    kind: SignalKind;
+    /** Robust signals: the levels, bottom to top. */
+    states: string[];
+    changes: SignalChange[];
+    /** Clocks: the period, the high part of it, the first rising edge. */
+    clock?: {
+        period: number;
+        pulse: number;
+        offset: number;
+    };
+}
+
+declare interface SignalChange {
+    at: number;
+    state: string;
+}
+
+declare type SignalKind = 'robust' | 'concise' | 'binary' | 'clock';
+
+/** Extra vertical space (PlantUML `|||` / `||45||`). */
+declare interface SpaceEvent {
+    kind: 'space';
+    height: number;
+    sourceLine: number;
+}
+
+declare interface StateComposite {
+    id: string;
+    name: string;
+    parent?: string;
+    /** A concurrent region: no title, drawn dashed inside its composite. */
+    region: boolean;
+    direction?: Direction;
+    classes: string[];
+    style?: UserStyle;
+}
+
+declare interface StateDiagram {
+    type: 'state';
+    direction: Direction;
+    states: Map<string, StateNode>;
+    composites: Map<string, StateComposite>;
+    transitions: StateTransition[];
+    notes: StateNote[];
+    classDefs: Map<string, UserStyle>;
+    accessibility: Accessibility;
+}
+
+declare type StateKind = 'state' | 'start' | 'end' | 'choice' | 'fork' | 'join';
+
+declare interface Statement {
+    /** The statement text, trimmed. */
+    text: string;
+    /** 1-based line. */
+    line: number;
+    /** 1-based column of the first character of `text`. */
+    column: number;
+}
+
+declare interface StateNode {
+    id: string;
+    kind: StateKind;
+    /** Display name; the id unless `state "…" as id` gave one. */
+    name: string;
+    descriptions: string[];
+    /** The composite or region it sits in. */
+    parent?: string;
+    classes: string[];
+    style?: UserStyle;
+}
+
+declare interface StateNote {
+    target: string;
+    side: 'left' | 'right';
+    text: string;
+}
+
+declare interface StateTransition {
+    from: string;
+    to: string;
+    label?: string;
+}
+
+declare type Stroke = 'normal' | 'thick' | 'dotted' | 'invisible';
+
+/** The text syntaxes this package reads. */
+export declare type Syntax = 'mermaid' | 'plantuml';
+
 export declare type TextMeasurer = (text: string, font: FontSpec) => TextSize;
 
 export declare interface TextSize {
@@ -88,4 +709,43 @@ export declare interface TextSize {
 /** Variable name → light-theme default. The documented theming surface. */
 export declare const THEME_VARIABLES: Readonly<Record<string, string>>;
 
+declare interface TickInterval {
+    unit: 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M';
+    step: number;
+}
+
+declare interface TimingDiagram {
+    type: 'timing';
+    title?: string;
+    signals: Signal[];
+    messages: TimingMessage[];
+    highlights: TimingHighlight[];
+    accessibility: Accessibility;
+}
+
+declare interface TimingHighlight {
+    from: number;
+    to: number;
+    text: string;
+    color?: string;
+}
+
+declare interface TimingMessage {
+    from: string;
+    to: string;
+    at: number;
+    /** The arrival time; equal to `at` unless the message took time. */
+    until: number;
+    text: string;
+}
+
+declare interface UserStyle {
+    /** For the shape or line. */
+    shape: Record<string, string>;
+    /** For the text. */
+    text: Record<string, string>;
+}
+
+declare type Visibility = '+' | '-' | '#' | '~';
+
 export { }