@draftably/mermaid 0.0.0-stage → 0.2.0

package/dist/types/src/model/markers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The marks at a connection's ends, `head=` and `tail=` in a file. The canvas and the CLI draw
+ * them from these definitions, so both give the same geometry.
+ */
+import type { Point, Rect } from './types';
+/** What `head=` and `tail=` accept. A plain edge is `head=arrow tail=none`. */
+export declare const MARKERS: readonly ["arrow", "none", "triangle", "open-triangle", "diamond", "open-diamond", "circle", "cross"];
+export type EndMarker = (typeof MARKERS)[number];
+export interface MarkerShape {
+    w: number;
+    h: number;
+    /** Where the marker sits on its line, at the height of its middle. */
+    x: number;
+    d: string;
+    /** Solid marks take the line's ink. Open marks take the surface, which hides what is under. */
+    fill: 'ink' | 'surface' | 'none';
+    /** How far short of the end its line stops; the mark fills that gap, tip on the end. */
+    stop: number;
+}
+/** Each marker points along +x, in drawing units. `arrow` is the original open chevron. */
+export declare const MARKER_SHAPES: Record<Exclude<EndMarker, 'none'>, MarkerShape>;
+export declare const MARKER_STROKE = 1.5;
+/** The `<marker>` box for an end. A tail's mark turns to face away from the line. */
+export declare const markerBox: (kind: Exclude<EndMarker, "none">, tail: boolean) => {
+    markerWidth: number;
+    markerHeight: number;
+    refX: number;
+    refY: number;
+    orient: string;
+};
+/** The fill a marker takes on this line and surface. */
+export declare function markerFill(kind: Exclude<EndMarker, 'none'>, ink: string, surface: string): string;
+type Ends = {
+    directed?: boolean;
+    head?: EndMarker;
+    tail?: EndMarker;
+};
+/** An undirected edge has no marks, whatever else it holds. */
+export declare const headOf: (e: Ends) => EndMarker;
+export declare const tailOf: (e: Ends) => EndMarker;
+/** Whether an edge has anything beyond the plain arrow, which labels and lines ignore. */
+export declare const hasMarkers: (e: Ends) => boolean;
+/** A route with each end pulled back to its marker's stop, so no line runs through a mark. */
+export declare function stoppedPoints(points: Point[], e: Ends): Point[];
+/** The room an edge's marks take. A label keeps off them. */
+export declare function markerRects(points: Point[], e: Ends): Rect[];
+export {};

package/dist/types/src/model/note.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Notes: sentences on a diagram that never move its layout, from `note` statements. An anchored
+ * note (`near=`) is placed after layout in free space beside its object or sequence message; a
+ * note without one sits in the frame under the subtitle. The viewer, `inspect --svg` and the
+ * editor's exports all place and draw them from here.
+ */
+import { type ResolvedAppearance } from './appearance';
+import type { BoundedRoute } from './bounds';
+import { type Run } from './rich-text';
+import type { Diagram, Point, Rect } from './types';
+export declare const NOTE_SIDES: readonly ["below", "above", "left", "right"];
+export type NoteSide = (typeof NOTE_SIDES)[number];
+export interface Note {
+    text: string;
+    /** The node, group or sequence message the note sits beside; the frame when unset. */
+    near?: string;
+    /** Which side of `near`; `below` when unset, or `right` for a message. */
+    side?: NoteSide;
+    /** Wrap width; `NOTE_WIDTH` when unset. */
+    width?: number;
+}
+/**
+ * A note with its box and wrapped lines. `inFrame` notes sit under the subtitle; `overlaps` is set
+ * on an anchored note when no clear spot was found.
+ */
+export interface PlacedNote {
+    note: Note;
+    rect: Rect;
+    /** Wrapped lines, each as runs of plain text and links. */
+    lines: Run[][];
+    inFrame?: boolean;
+    overlaps?: boolean;
+}
+/** The side a note sits on: its `side`, or by default right of a message and below anything else. */
+export declare const noteSide: (doc: Diagram, note: Note) => NoteSide;
+/** Default wrap width, and the room between a note and its object. */
+export declare const NOTE_WIDTH = 280;
+/** Room between a note's panel and its text. */
+export declare const NOTE_PAD: {
+    x: number;
+    y: number;
+};
+/** The note's wrapped lines and box size, at 0,0. */
+export declare function noteBox(look: ResolvedAppearance, note: Note): PlacedNote;
+/**
+ * Spots in a sequence's side margins, by index in `notes`, for notes on the messages in `rows`.
+ * `left` and `right` are the margins' inner edges and `top` the highest a note goes. A note is
+ * level with its row, or pushed down clear of the note above it. The panel grows round these, so
+ * no note here can cover the drawing.
+ */
+export declare function marginNotes(look: ResolvedAppearance, notes: readonly Note[], rows: ReadonlyMap<string, number>, { left, right, top }: {
+    left: number;
+    right: number;
+    top: number;
+}): (Rect | null)[];
+/**
+ * Place every anchored note beside its object or message, clear of shapes, group borders, lines
+ * and earlier notes when a nearby spot allows it. Frame notes, and notes whose object is not drawn,
+ * come back `inFrame` at 0,0 for `diagramFrame` to place.
+ */
+export declare function placeNotes(doc: Diagram, look: ResolvedAppearance, rects: ReadonlyMap<string, Rect>, routes: readonly BoundedRoute[]): PlacedNote[];
+/**
+ * SVG markup for placed notes: a quiet panel with a bar on its left edge, then the text. Links
+ * are `<a>` elements with `href` as `write` gives it.
+ */
+export declare function noteMarkup(look: ResolvedAppearance, notes: readonly PlacedNote[], write?: (href: string) => string | null): string;
+/**
+ * Where a note dropped at `p` belongs: beside the closest object or (in a sequence) message, on
+ * the side of it `p` is on. Inside several objects the smallest wins, so a note dropped on a
+ * shape in a group goes to the shape. Undefined when nothing is within reach.
+ */
+export declare function noteAnchor(p: Point, rects: ReadonlyMap<string, Rect>, messages?: readonly BoundedRoute[]): {
+    near: string;
+    side: NoteSide;
+} | undefined;

package/dist/types/src/model/rich-text.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prose with links, for notes and footnotes: `[#1997](https://github.com/org/repo/pull/1997)`
+ * draws `#1997` as a link. Lines wrap exactly as the plain words would, so a link never moves
+ * anything; each line comes back as runs with their offsets, for SVG `<a>` and click targets.
+ */
+import { type TypeProfile } from './fonts';
+export interface Run {
+    text: string;
+    href?: string;
+    /** Offset from the line's start, and width. */
+    x: number;
+    w: number;
+}
+/** The text as drawn, with every link written as its label. */
+export declare const plainText: (text: string) => string;
+/** Every link's target, in order. */
+export declare const textLinks: (text: string) => string[];
+/** The text's lines at `width`, each as runs of plain text and links. */
+export declare function richLines(text: string, width: number, type: TypeProfile): Run[][];
+/**
+ * One line's content inside its `<text>`: plain runs as text, links as an underlined `<tspan>` in
+ * `link`, wrapped in `<a>` with `href` as `write` gives it.
+ */
+export declare function runsMarkup(runs: Run[], link: string, write: (href: string) => string | null): string;

package/dist/types/src/model/routes.d.ts

@@ -0,0 +1,170 @@
+import { type PriorRoute, type Route, type RoutingResult } from '../engines/routing-engine.js';
+import { type ResolvedAppearance } from './appearance';
+import { type VisibleGraph } from './graph';
+import type { Diagram, EdgeLayout, Point, Rect, ShapeKind, Side } from './types';
+export declare const SIDE_VECTORS: Record<Side, Point>;
+/** Where a connection meets a shape's outline on the given side. */
+export declare function portPoint(shape: ShapeKind, r: Rect, side: Side, offset?: number): Point;
+/** Side of `r` facing `p`. */
+export declare function sideToward(r: Rect, p: Point): Side;
+export interface EdgeLabelBox extends Point {
+    w: number;
+    h: number;
+    score?: number;
+}
+/** Lines and borders a label may sit on only when nothing better is free. */
+export interface LabelAvoid {
+    /** Other edges' routes. Routes that leave from this edge's first point share its trunk. */
+    routes?: Point[][];
+    /** Thin strips along group borders. */
+    borders?: Rect[];
+    /** The marks at line ends. A spot that hides one costs as much as a line through the text. */
+    marks?: Rect[];
+    /** The open group that holds both ends. A spot not inside it costs a little less than a line. */
+    home?: Rect;
+}
+/** One edge label for `placeEdgeLabels`: its text, its route, and what it should keep clear of. */
+export interface LabelJob {
+    label: string;
+    points: Point[];
+    avoid?: LabelAvoid;
+    /** The user's nudge, added to the chosen spot. */
+    dx?: number;
+    dy?: number;
+}
+/**
+ * Place every edge label at once, after all routes exist. Each label takes a spot on its own
+ * route that covers no shape, group title or other label, and crosses as few other lines as it
+ * can; a label closer to another than its own height costs as much as a line beside it. Labels
+ * with a clean spot go first, then one repair sweep moves each label to its best spot given all
+ * the others. Only a label with every spot near its route blocked moves away from it, and then as
+ * little as possible.
+ */
+export declare function placeEdgeLabels(jobs: LabelJob[], obstacles: Rect[], look?: ResolvedAppearance, fixed?: Rect[]): EdgeLabelBox[];
+/**
+ * Choose a label spot on the edge's own route, clear of the labels already placed: see
+ * `placeEdgeLabels`.
+ */
+export declare function placeEdgeLabel(label: string, points: Point[], obstacles: Rect[], existing?: Rect[], look?: ResolvedAppearance, avoid?: LabelAvoid): EdgeLabelBox;
+export interface DrawnRoute extends Route {
+    label: EdgeLabelBox | null;
+    path: string;
+    /**
+     * Short pieces of the line where it crosses another line or a group's frame: the only places a
+     * canvas-colored halo is drawn under it, so the crossing reads as a clean break. Empty when the
+     * line crosses nothing.
+     */
+    halo: string;
+    /**
+     * For a line to or from a cell with no side on its group's outline: the stretch from the outline
+     * across other cells to that cell's edge. It is drawn over the cells, with a dot at the edge.
+     */
+    cross?: [Point, Point];
+}
+export interface SceneRoutes {
+    routes: DrawnRoute[];
+    result: RoutingResult;
+}
+/**
+ * An edge's routing settings, with its lane turned into bends and sides: out of the source to
+ * the lane, along it, and into the target. A lane with `leave` or `enter` turns at that coordinate beside
+ * the source or target, to meet it side on. A lane that no longer lies between the two ends (a
+ * node was dragged across it) is ignored, as is any lane on an edge with its own bends.
+ */
+export declare function laneBends(cfg: EdgeLayout, a: Rect, b: Rect): EdgeLayout;
+export declare function routeInput(doc: Diagram, vg: VisibleGraph, all: Map<string, Rect>): {
+    nodes: ({
+        shape: ShapeKind;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        id: string;
+        title: string;
+        was?: string;
+        wasShape?: ShapeKind;
+        wasCount?: number | string;
+        href?: string;
+        count?: number | string;
+        span?: number | "var";
+        parentId?: string;
+        image?: string;
+        lifeline?: number;
+    } | {
+        parentId?: string | undefined;
+        frame?: boolean | undefined;
+        shape: ShapeKind;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        id: string;
+        title: string;
+    })[];
+    groups: {
+        titleHeight?: number | undefined;
+        collapsed: boolean;
+        titleWidth: number;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        id: string;
+        title: string;
+        was?: string;
+        href?: string;
+        parentId?: string;
+        frame?: "soft" | "none";
+        titleLines?: number;
+        hull?: Rect[];
+    }[];
+    edges: {
+        from: string;
+        to: string;
+        cfg: EdgeLayout;
+        a: string;
+        b: string;
+        id: string;
+        label: string;
+        was?: string;
+        directed: boolean;
+        head?: import("./markers").EndMarker;
+        tail?: import("./markers").EndMarker;
+        emphasis: boolean;
+        dashed: boolean;
+        status?: import("./status.js").Status;
+        spot?: import("./status.js").Spot;
+    }[];
+};
+/**
+ * A labelled route with no run the label clears slides one bend along, so one run holds the label
+ * away from the bend; a label on the corner reads as part of neither run. `w` and `h` are the
+ * label's box. The bend moves the least that gives a run the label plus `LABEL_RUN` at each end,
+ * or as close to that as the route allows while the label still clears both ends. The move stands
+ * only when the route stays out of every box, crosses no more lines and runs beside no more.
+ */
+export declare function roomForLabel(points: Point[], w: number, h: number, boxes: Rect[], others: Point[][]): Point[];
+/** Add label positions and SVG paths to raw routes. */
+export declare function drawRoutes(doc: Diagram, vg: VisibleGraph, rects: Map<string, Rect>, result: RoutingResult): DrawnRoute[];
+/** Width of the halo under a connection, in drawing units. */
+export declare const HALO_WIDTH = 8;
+/** How far a halo piece runs each way from a crossing, along the line. */
+export declare const HALO_REACH = 7;
+/**
+ * The lines, by index, that another line's halo would cut at a mark. A halo there leaves half a
+ * mark, or on a short line almost nothing, so these lines stay whole.
+ */
+export declare function wholeLines(lines: {
+    points: Point[];
+    marks: Rect[];
+}[]): Set<number>;
+/** The pieces of `points` around each place it crosses `others` or a frame's border, as a path. */
+export declare function haloPath(points: Point[], others: Point[][], frames: Rect[]): string;
+/** Full routes already computed for this drawing, or null. */
+export declare function knownRoutes(doc: Diagram, vg: VisibleGraph, rects: Map<string, Rect>): RoutingResult | null;
+/** Record full routes computed elsewhere (the engine worker) for this drawing. */
+export declare function rememberRoutes(doc: Diagram, vg: VisibleGraph, rects: Map<string, Rect>, result: RoutingResult): void;
+export declare function computeRoutes(doc: Diagram, vg: VisibleGraph, rects: Map<string, Rect>, options?: {
+    previous?: PriorRoute[];
+    quick?: boolean;
+}): SceneRoutes;

package/dist/types/src/model/status.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Change status: how an object or connection differs between two versions of a diagram, drawn
+ * the same way by the canvas, `inspect --svg` and the exports.
+ *
+ * A file with change marks is a diff, and in a diff color means change and nothing else:
+ * unchanged shapes turn neutral, containers become quiet outlines, unchanged lines go grey, and
+ * only added (green), changed (amber) and removed (red) objects keep a hue, as a tinted fill with
+ * a strong border. Each status also has a border weight, dash, fade or marker, so a diff still
+ * reads in grayscale. A removed title stays readable; `config strike-removed=on` strikes it.
+ */
+import { type LegendEntry, type ResolvedAppearance, type Swatch } from './appearance';
+import type { Diagram, DiagramEdge } from './types';
+export type Status = 'same' | 'added' | 'removed' | 'changed' | 'context';
+/**
+ * How an emphasis state draws an object or connection: in focus (a heavier border or line),
+ * ringed (in focus where nothing else fades, so it also takes an accent ring or line), or dimmed
+ * (faded and neutral, like a `.` context line). Unset means it draws as usual.
+ */
+export type Spot = 'focus' | 'ring' | 'dim';
+export declare const STATUSES: Status[];
+/** Legend order and wording, after a count; `same` needs no entry. */
+export declare const STATUS_LABELS: Partial<Record<Status, string>>;
+export interface StatusCount {
+    status: Status;
+    /** Objects with the mark. */
+    count: number;
+    /** Connections with the mark. */
+    lines: number;
+}
+/**
+ * A legend entry's text: how many objects carry the mark and what it means, then how many
+ * connections, so five added boxes and their five lines read "5 added · 5 lines", not "10 added".
+ */
+export declare const statusLabel: ({ status, count, lines }: StatusCount) => string;
+export interface StatusPaint {
+    /** Line color for connections; shapes take theirs from `statusSwatch`. */
+    stroke?: string;
+    width?: number;
+    dash?: string;
+    opacity: number;
+    /** Strike the title through. */
+    strike: boolean;
+    /** Fade of the title text alone, on top of `opacity`. */
+    inkFade?: number;
+    /** Draw the removed marker, a minus in a disc, on the shape's top-right corner. */
+    marker?: boolean;
+    /** Draw an accent ring around the shape (`haloInk`). */
+    halo?: boolean;
+}
+/** The removed marker's radius and its inset from a shape's top-right corner. */
+export declare const MARKER: {
+    r: number;
+    inset: number;
+};
+/** Room between a shape and its focus ring. */
+export declare const HALO_GAP = 4;
+/** The accent a ringed object or connection is drawn with: the theme's second accent. */
+export declare const haloInk: (look: ResolvedAppearance) => string;
+/** The paint for a change status, with an emphasis state's weight or fade on top. */
+export declare function statusPaint(look: ResolvedAppearance, status?: Status, spot?: Spot): StatusPaint;
+/** Whether the document is a diff: any object or connection carries a change mark. */
+export declare const isDiff: (doc: Diagram) => boolean;
+/**
+ * In a diff, the swatch a status draws a shape with: a pale tint of its hue with a strong border
+ * and dark ink, or the neutral surface (a quiet outline for containers) when unchanged.
+ */
+export declare function statusSwatch(look: ResolvedAppearance, status: Status | undefined, kind: 'node' | 'group'): Swatch;
+/** A connection's color: its status hue, or quiet grey for an unchanged line in a diff. */
+export declare const edgeInk: (look: ResolvedAppearance, edge: DiagramEdge, diff: boolean) => string;
+/**
+ * The document drawn in emphasis state `id`. Listed objects (a group with all its members) and
+ * listed connections are in focus, and so is a connection between two focused nodes. With
+ * `rest=dim`, everything else fades, except the containers that hold something in focus, so the
+ * context still reads. With `rest=plain` nothing fades, so focus also takes an accent ring.
+ * Nothing moves.
+ */
+export declare function withState(doc: Diagram, id: string): Diagram;
+/**
+ * The marks a document uses that the legend explains, in legend order, each with how many
+ * objects and connections carry it, so the key doubles as the change's size.
+ */
+export declare function usedStatuses(doc: Diagram): StatusCount[];
+/** The color key's rows: a diff draws no family colors, so it lists only its statuses. */
+export declare const drawnLegend: (doc: Diagram) => LegendEntry[];

package/dist/types/src/model/styles.d.ts

@@ -0,0 +1,13 @@
+import type { NodeStyle, ShapeKind } from './types';
+export declare const SHAPES: ShapeKind[];
+export declare const SHAPE_LABELS: Record<ShapeKind, string>;
+/** Icons offered in the inspector for a shape. */
+export declare const NODE_ICONS: string[];
+/** Styles for version 1 node types, used only when migrating old files. */
+export declare const LEGACY_TYPE_STYLE: Record<string, NodeStyle>;
+export declare const DEFAULT_STYLE: NodeStyle;
+/** Default size for a new shape of the given kind. */
+export declare function defaultShapeSize(shape: ShapeKind): {
+    w: number;
+    h: number;
+};