@draftably/editor 0.0.0-stage → 0.2.0

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;
+};

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

@@ -0,0 +1,31 @@
+import { type ResolvedAppearance } from './appearance';
+import type { Diagram, Point } from './types';
+/** What is drawn at a point: an opaque fill, and a phase band's tint over it. */
+export interface Surface {
+    fill: string;
+    tint?: {
+        fill: string;
+        opacity: number;
+    };
+}
+/** The tint of each sequence phase band: alternate bands are stronger, so neighbours read apart. */
+export declare const phaseOpacity: (i: number) => 0.12 | 0.03;
+/**
+ * A sequence's panel border only when its lanes leave a participant outside them. Lanes that
+ * hold every participant already bound the exchange, and a second frame around them is cruft.
+ */
+export declare function panelDrawn(doc: Diagram): boolean;
+/**
+ * The surface under a point, as the scene paints it: the canvas, the sequence panel, the
+ * innermost group fill, then a phase band's tint. Halos and label cards take it, so a break in a
+ * line reads as the lane it sits on, not a patch of canvas. A label card is one piece with the
+ * surface under its center, so a label over a group's edge never reads as a half-tinted box. The
+ * group rects are read once here and
+ * not cached on `doc`: the editor's store keeps one `doc` object and updates it in place.
+ */
+export declare function surfaces(doc: Diagram, look: ResolvedAppearance): (p: Point) => Surface;
+/** A halo path's pieces, grouped by the surface under each piece's middle. */
+export declare function haloPieces(under: (p: Point) => Surface, halo: string): {
+    surface: Surface;
+    d: string;
+}[];

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

@@ -0,0 +1,277 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type Side = 'left' | 'right' | 'top' | 'bottom';
+export type PortSide = Side | 'auto';
+export type Direction = 'RIGHT' | 'DOWN';
+export type Theme = 'light' | 'dark';
+import type { DiagramAppearance, Shade } from './appearance';
+import type { EndMarker } from './markers';
+import type { Spot, Status } from './status';
+export type ShapeKind = 'box' | 'pill' | 'circle' | 'diamond' | 'text' | 'icon' | 'image'
+/** A seam between two cells of a `cells` group. */
+ | 'marker';
+/** A color family: a built-in one, one the file defines, or `auto` for the theme's surface. */
+export type ColorKey = string;
+export type LabelMode = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'detached';
+export interface DiagramNode {
+    id: string;
+    title: string;
+    /** Title before a change, from `was=` on a `~` line. */
+    was?: string;
+    /** Shape before a change, from `was-shape=` on a `~` line. */
+    wasShape?: ShapeKind;
+    /** Count before a change, from `was-count=` on a `~` line; 1 means a single box. */
+    wasCount?: number | string;
+    /** A link to open from exported drawings. */
+    href?: string;
+    /** How many things this box stands for, or a symbol such as `N`; drawn as a stack with a badge. */
+    count?: number | string;
+    /** A cell's columns (or units), or `var` for a field of variable length. */
+    span?: number | 'var';
+    parentId?: string;
+    image?: string;
+    /** A sequence participant: length of the dashed lifeline below the box. */
+    lifeline?: number;
+}
+export interface DiagramGroup {
+    id: string;
+    title: string;
+    /** Title before a change, from `was=` on a `~` line. */
+    was?: string;
+    /** A link to open from exported drawings. */
+    href?: string;
+    parentId?: string;
+    /** `soft` draws a tint behind the members instead of a frame; `none` draws nothing. */
+    frame?: 'soft' | 'none';
+    /** Lines the title wraps to, when more than one; the header grows by a line for each. */
+    titleLines?: number;
+    /** A soft group's tint: rectangles relative to the group's top left; the first holds the label. */
+    hull?: Rect[];
+}
+export interface DiagramEdge {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    /** Label before a change, from `was=` on a `~` line. */
+    was?: string;
+    directed: boolean;
+    /** The mark at the target end, when it isn't the plain arrow; see `headOf`. */
+    head?: EndMarker;
+    /** The mark at the source end, when it has one; see `tailOf`. */
+    tail?: EndMarker;
+    emphasis: boolean;
+    dashed: boolean;
+    /** How it differs between two versions of the diagram. */
+    status?: Status;
+    /** How the drawn emphasis state treats it; see `withState`. */
+    spot?: Spot;
+}
+export interface NodeLayout extends Rect {
+    manual?: boolean;
+    pinned?: boolean;
+}
+export interface EdgeLayout {
+    fromSide?: PortSide;
+    toSide?: PortSide;
+    labelDx?: number;
+    labelDy?: number;
+    waypoints?: Point[];
+    /** The reading direction of the layout that places both ends; the edge runs along it. */
+    flow?: 'right' | 'down';
+    /** Set by the compiler for a fold's wrap edge: the line it returns along, between two bands. */
+    lane?: Lane;
+    /** From a lane, at route time: where along its target's side the edge arrives, off centre. */
+    toOffset?: number;
+    /** A sequence message: drawn straight between the two lifelines at this height, not routed. */
+    row?: number;
+}
+/**
+ * A channel between two bands of a fold: a level line at `y`, or an upright one at `x`. With
+ * `leave`, the edge leaves its source's side and turns onto the lane at that coordinate; with
+ * `enter`, it runs on along the lane to that coordinate and turns into its target's side.
+ * With `out`, it is a return or skip lane beyond both ends.
+ */
+export type Lane = ({
+    y: number;
+} | {
+    x: number;
+}) & {
+    leave?: number;
+    enter?: number;
+    /**
+     * A lane beyond both ends, outside their band: the edge leaves by the side facing it, runs
+     * along it, and at `enter` turns into the target's side that faces back toward the source.
+     */
+    out?: boolean;
+    /**
+     * With `out`: the gap beside the target holds another edge's label, so the edge arrives square
+     * on the target's face toward the lane, at `enter` (its middle), instead of turning into that gap.
+     */
+    face?: boolean;
+};
+export interface LabelLayout {
+    mode?: LabelMode;
+    dx?: number;
+    dy?: number;
+    width?: number;
+    leader?: boolean;
+}
+export interface ContainerLayout {
+    direction: 'inherit' | Direction;
+    padding: number;
+    manualSize: boolean;
+    /** Set for a `cells` group: its members touch, under a title band this tall. */
+    cellsBand?: number;
+    /** A byte or bit layout's extra marks, relative to the group's top-left corner. */
+    cellsChrome?: CellsChrome;
+}
+/** What a byte or bit layout draws besides its cells. */
+export interface CellsChrome {
+    /** Unit numbers in a strip under the title band. */
+    ruler?: {
+        y: number;
+        h: number;
+        ticks: Array<{
+            x: number;
+            label: string;
+        }>;
+    };
+    /** Further pieces of fields that run on past a row's end, by field. */
+    pieces?: Record<string, Rect[]>;
+    /** Fields of variable length, drawn with broken ends. */
+    open?: string[];
+}
+export type IntentRole = 'start' | 'end';
+export type IntentPlacement = 'top-left' | 'left-center' | 'center' | 'top-center' | 'top-right' | 'right-center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export type LayoutIntent = Partial<Record<IntentRole, {
+    id: string;
+    placement: IntentPlacement;
+}>>;
+export interface NodeStyle {
+    shape: ShapeKind;
+    color: ColorKey;
+    /** Numeric shade; omitted means the default for the object (500 for nodes, 100 for groups). */
+    shade?: Shade;
+    icon: string;
+    /** How it differs between two versions of the diagram. */
+    status?: Status;
+    /** How the drawn emphasis state treats it; see `withState`. */
+    spot?: Spot;
+}
+export type LayoutAlgorithmId = 'compound-flow' | 'boundary-align' | 'compound-spring' | 'tidy' | 'stress' | 'force' | 'flow' | 'layered' | 'tree' | 'grid' | 'separate';
+export type AspectSetting = 'canvas' | '1' | '1.333' | '1.6' | '2' | '0.75';
+export interface LayoutSettings {
+    algorithm: LayoutAlgorithmId;
+    direction: Direction;
+    mode: 'pass' | 'rebuild';
+    maxMove: number;
+    stability: number;
+    iterations: number;
+    nodeGap: number;
+    rankGap: number;
+    edgeLength: number;
+    repulsion: number;
+    flowStrength: number;
+    alignment: number;
+    compactness: number;
+    gridStrength: number;
+    aspect: AspectSetting;
+    fold: 'auto' | 'never';
+    respectDirection: boolean;
+    ordering: 'stable' | 'crossings';
+    rootId: string;
+    respectManual: boolean;
+    growContainers: boolean;
+    boundaryPull: number;
+    hierarchySweeps: number;
+    groupGap: number;
+}
+export interface RoutingSettings {
+    clearance: number;
+    portGap: number;
+    edgeGap: number;
+    bendPenalty: number;
+    crossingPenalty: number;
+    sharedPenalty: number;
+    parallelPenalty: number;
+    portStability: number;
+    fanoutPenalty: number;
+    passes: number;
+    cornerRadius: number;
+    standoff: number;
+}
+export interface DiagramSettings extends LayoutSettings {
+    snap: boolean;
+    showManual: boolean;
+    routing: RoutingSettings;
+}
+export interface Camera {
+    x: number;
+    y: number;
+    k: number;
+}
+export interface Diagram {
+    schemaVersion: 2;
+    id: string;
+    title: string;
+    graph: {
+        nodes: DiagramNode[];
+        edges: DiagramEdge[];
+        groups: DiagramGroup[];
+    };
+    layout: {
+        nodes: Record<string, NodeLayout>;
+        edges: Record<string, EdgeLayout>;
+        labels: Record<string, LabelLayout>;
+        containers: Record<string, ContainerLayout>;
+        intent: LayoutIntent;
+        /** A sequence diagram's frame and the row bands of its `phase` statements. */
+        sequence?: SequenceLayout;
+    };
+    styles: Record<string, NodeStyle>;
+    collapsed: string[];
+    settings: DiagramSettings;
+    camera: Camera;
+    /** Editor light or dark mode; independent of the diagram's appearance. */
+    theme: Theme;
+    /** Diagram theme, overrides and color definitions. Saved with the diagram. */
+    appearance: DiagramAppearance;
+}
+export type NodeGeometry = Record<string, NodeLayout>;
+/** The panel a sequence diagram is drawn on, and a row band for each `phase`. */
+export interface SequenceLayout {
+    panel: Rect;
+    phases: SequencePhase[];
+    /** Left edge for phase labels, when a note in the left margin widens the panel past them. */
+    phaseX?: number;
+    /** Spots of the notes that sit in a side margin, by index in `appearance.notes`. */
+    notes?: Array<Rect | null>;
+    /** With `notes`: the panel without those margins, for drawings with their notes in the frame. */
+    inner?: Rect;
+    /**
+     * From `was-order`: each message's row and the phase bands in the older message order, and how
+     * much further that order runs down the panel.
+     */
+    before?: {
+        rows: Record<string, number>;
+        phases: SequencePhase[];
+        grow: number;
+    };
+}
+export type SequencePhase = {
+    id: string;
+    label: string;
+    y: number;
+    h: number;
+};
+/** Any object that can be selected: a shape, a container, or a connection. */
+export type Entity = DiagramNode | DiagramGroup | DiagramEdge;

package/dist/types/src/runtime/svg-renderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A standalone SVG of a projected diagram for terminal and agent inspection. It draws with the
+ * same appearance, shapes and title wrapping as the canvas and embeds the fonts it uses.
+ */
+import { type ResolvedAppearance } from '../model/appearance';
+import type { Diagram, Rect } from '../model/types';
+/** How an object's `href` is written into the file; as written unless the caller says. */
+export interface SvgOptions {
+    href?: (href: string) => string;
+    /** Writes a link in note or footnote text; null draws the text without a link. */
+    textHref?: (href: string) => string | null;
+    /** Draw every emphasis state as its own panel. */
+    states?: boolean;
+    /** Host-owned policies used by the portable runtime. */
+    idPrefix?: string;
+    fontCss?: string;
+    title?: string;
+    description?: string;
+    styleNonce?: string;
+    linkTarget?: '_self' | '_blank';
+    metadata?: string;
+    maxOutputBytes?: number;
+}
+export declare class SvgLimitError extends Error {
+}
+/**
+ * A sequence diagram's panel, a light surface with a border that bounds the exchange, and a row
+ * band for each phase with its label in a tab at the left edge. Drawn under everything else.
+ */
+export declare function sequenceBackdrop(doc: Diagram, look: ResolvedAppearance): {
+    panel: string[];
+    phases: string[];
+};
+/** Inset of a phase label from its band's top left corner. */
+export declare const PHASE_TAB = 8;
+/** A thin stripe across the top of a box, inside its rounded corners. */
+export declare function accentPath(r: Rect, radius: number): string;
+export declare function renderSvg(doc: Diagram, opts?: SvgOptions): string;

package/dist/types/src/server/file-session.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface SessionInfo {
+    name: string;
+    path: string;
+    source: string;
+    revision: string;
+    /** Where the file's relative links start: its git root, or its folder outside a repository. */
+    root: string;
+}
+/** The nearest folder at or above `dir` that holds `.git`, or `dir` when there is none. */
+export declare function gitRoot(dir: string): string;
+export declare const revisionOf: (source: string) => string;
+export interface FileSession {
+    readonly file: string;
+    /** Handle `/api/...` requests. Returns false for anything else. */
+    handle(req: IncomingMessage, res: ServerResponse): boolean;
+    close(): void;
+}
+export declare function createFileSession(file: string): FileSession;

package/dist/types/src/server/workspace.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface WorkspaceFile {
+    /** Path relative to the workspace root, with forward slashes. */
+    path: string;
+    title: string;
+    /** The `subtitle` line, when the file has one near its top. */
+    subtitle?: string;
+    modified: number;
+}
+export interface WorkspaceInfo {
+    name: string;
+    root: string;
+    files: WorkspaceFile[];
+}
+export interface Workspace {
+    readonly root: string;
+    /** Handle `/api/...` requests. Returns false for anything else. */
+    handle(req: IncomingMessage, res: ServerResponse): boolean;
+    close(): void;
+}
+export declare function createWorkspace(root: string): Workspace;