@draftably/runtime 0.2.0 → 0.3.0

package/dist/types/src/dsl/compile.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedAppearance } from '../model/appearance.js';
 import type { CellsChrome, Lane, SequenceLayout } from '../model/types.js';
+import { type Planned } from './corridors.js';
 import { GROUP_HEADER, GROUP_INSET, contentOrigin } from './frame.js';
 import { type Model, type ModelEdge, type ModelLayout, type ModelObject } from './syntax.js';
 /** The single render context. Browser window size changes the camera, never the layout. */
@@ -44,6 +45,8 @@ export interface Diagnostic {
 /** A connection as the file declares it, plus the lane a fold's wrap edge returns along. */
 export interface SceneEdge extends ModelEdge {
     lane?: Lane;
+    /** A forward line's route, planned from its scope's ranks and corridors (`planRoutes`). */
+    plan?: Planned;
     /** A sequence message: the height of its row; it is drawn straight between lifelines there. */
     row?: number;
 }
@@ -149,6 +152,16 @@ export declare function crossings(paths: Array<Array<{
 }>>): number;
 /** The order of up to six items that scores fewest crossings; the first such, from `items`. */
 export declare function fewestCrossings<T>(items: T[], score: (order: T[]) => number): T[];
+/**
+ * The corridors a `flow` scope keeps for lines that skip ranks: the ranks with their stand-ins,
+ * each line's stand-ins by its index in the scope's pairs, and each stand-in's place across the
+ * run, in the scope's coordinates.
+ */
+export interface Corridors {
+    order: string[][];
+    chains: Map<number, string[]>;
+    across: Map<string, number>;
+}
 /**
  * Lay out a model. `arranged` holds world positions from layout engines; scopes that an engine
  * governs take their children's relative placement from it instead of their built-in recipe.

package/dist/types/src/dsl/corridors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Routes for a `flow` scope's forward lines, planned from its ranks as a layered layout routes its
+ * edges: out of the source's trailing side, along a track in each gap the line turns in, down a
+ * corridor through each rank it skips, and into the target's leading side. The ranks' order already
+ * keeps crossings few, so the plan only has to place ports and order each gap's tracks. The router
+ * takes a planned route as it is when it clears every box.
+ */
+import type { Point, Rect } from '../model/types.js';
+export interface PlanLine {
+    id: string;
+    /** Source, the stand-ins of the ranks it skips, target. */
+    chain: string[];
+}
+export interface Planned {
+    points: Point[];
+    fromOffset: number;
+    toOffset: number;
+}
+/**
+ * Space between ports on one side and between neighbouring tracks in a gap, as the router keeps
+ * them: ports `max(portGap, edgeGap)` apart and tracks `edgeGap` apart.
+ */
+export interface Spacing {
+    port: number;
+    track: number;
+}
+/**
+ * Plans each line of `lines`. `order` is the ranks with stand-ins, `box` each real member's drawn
+ * box and `across` each stand-in's place across the run, all in drawing coordinates. Lines that
+ * cannot be planned (a member without a box) are left out.
+ */
+export declare function planRoutes(axis: 'down' | 'right', order: string[][], lines: PlanLine[], box: (id: string) => Rect | undefined, across: (id: string) => number | undefined, spacing?: Spacing): Map<string, Planned>;
+/**
+ * The room each gap between ranks needs for the tracks `planRoutes` lays in it: a standoff from
+ * the boxes either side and a pitch between tracks, by gap index; a gap with no track is absent.
+ * `box` may be a member's slot: only its place across the run counts.
+ */
+export declare function trackRoom(axis: 'down' | 'right', order: string[][], lines: PlanLine[], box: (id: string) => Rect | undefined, across: (id: string) => number | undefined, spacing?: Spacing): number[];

package/dist/types/src/graph-api/core.d.ts

@@ -0,0 +1,125 @@
+import type { Point, RoutingSettings, Side } from '../model/types.js';
+export type Shape = 'box' | 'pill' | 'circle' | 'diamond' | 'text';
+/** How a scope arranges its children: a recipe, or a layout engine as `engine:<name>`. */
+export type Arrange = 'flow' | 'row' | 'column' | 'lanes' | 'sequence' | `engine:${string}`;
+/**
+ * How hard the router works. `full` repairs crossings and evens out lanes; `quick` routes each
+ * line once. `auto` (the default) routes quickly first, and fully when that will stay fast.
+ */
+export type Quality = 'auto' | 'full' | 'quick';
+export interface RoutingOptions extends Partial<RoutingSettings> {
+    quality?: Quality;
+}
+export interface NodeIn {
+    id: string;
+    label?: string;
+    parent?: string;
+    shape?: Shape;
+    /** Fixed size, kept within 40–1200 by 24–1200. Without one, the box fits its label. */
+    width?: number;
+    height?: number;
+}
+export interface GroupIn {
+    id: string;
+    label?: string;
+    parent?: string;
+    /** How the group arranges its own children; `column` by default. */
+    arrange?: Arrange;
+    direction?: 'right' | 'down';
+    gap?: number;
+}
+export interface EdgeIn {
+    /** Unique among edges. Without one, the edge is `e1`, `e2`, … by position. */
+    id?: string;
+    source: string;
+    target: string;
+    label?: string;
+    dashed?: boolean;
+    sourceSide?: Side;
+    targetSide?: Side;
+}
+export interface GraphIn {
+    nodes: NodeIn[];
+    groups?: GroupIn[];
+    edges?: EdgeIn[];
+    /** How the top level is arranged; `flow` by default. */
+    arrange?: Arrange;
+    direction?: 'right' | 'down';
+    gap?: number;
+    fit?: 'wide' | 'slide' | 'square' | 'page' | 'tall';
+    /**
+     * `auto` (the default) folds a long `flow` into rows, like lines of text, when it is much
+     * wider than a 1100×720 page; `never` keeps one row.
+     */
+    fold?: 'auto' | 'never';
+    routing?: RoutingOptions;
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PlacedBox extends Box {
+    parent?: string;
+}
+export interface EdgeOut {
+    source: string;
+    target: string;
+    sourceSide: Side;
+    targetSide: Side;
+    /** From the source's outline to the target's. The host draws the arrowhead at the last point. */
+    points: Point[];
+    /** SVG path data with the rounded corners draftably draws. */
+    path: string;
+    /** The label's box. Draw a backing behind it: other lines may pass under it. */
+    label: Box | null;
+    /** True when the router found no clear way and drew a fallback line. */
+    blocked: boolean;
+}
+export interface Routed {
+    edges: Record<string, EdgeOut>;
+    /** The router mode that drew the lines. */
+    quality: 'full' | 'quick';
+    warnings: string[];
+}
+export interface LayoutResult extends Routed {
+    nodes: Record<string, PlacedBox>;
+    groups: Record<string, PlacedBox>;
+    /** Everything drawn: boxes, lines and labels. */
+    bounds: Box;
+    /** The `.draft` file this graph is. Open it in the viewer, or pass it to `renderSvg`. */
+    draft: string;
+}
+/**
+ * `auto` routes fully when the quick routes predict a full pass within the budget. The full
+ * pass reroutes each line with a crossing or crowded lane against all the others, so its cost
+ * grows with lines times conflicts; this limit keeps it near the 1 s load budget.
+ */
+export declare const AUTO_FULL_LIMIT = 1200;
+/** Place and route a graph the way a `.draft` file with the same content draws. */
+export declare function layout(graph: GraphIn): Promise<LayoutResult>;
+/**
+ * `layout` without a promise, for callers that cannot wait, such as a stand-in for a synchronous
+ * library. It cannot run a layout engine (`engine:` arrangements) or `fit`, which need `layout`.
+ */
+export declare function layoutSync(graph: GraphIn): LayoutResult;
+export interface PlacedNodeIn extends Box {
+    id: string;
+    parent?: string;
+    shape?: Shape;
+}
+export interface PlacedGroupIn extends Box {
+    id: string;
+    parent?: string;
+    /** The title, so lines keep out of its band at the top of the group. */
+    label?: string;
+}
+export interface RouteIn {
+    nodes: PlacedNodeIn[];
+    groups?: PlacedGroupIn[];
+    edges: EdgeIn[];
+    routing?: RoutingOptions;
+}
+/** Route lines between boxes the caller placed. Nothing moves. */
+export declare function route(graph: RouteIn): Routed;

package/dist/types/src/graph-api/cytoscape.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A Cytoscape.js layout: `cytoscape.use(draftablyLayout)`, then
+ * `cy.layout({ name: 'draftably' }).run()`. It places nodes with draftably's layout. Cytoscape
+ * draws edges itself; the routed lines are on `layout.result` for an app that draws its own.
+ */
+import { type RoutingOptions } from './core.js';
+/** The parts of a Cytoscape collection element this layout reads. */
+interface CyElement {
+    id(): string;
+    data(key: string): unknown;
+    isParent(): boolean;
+    parent(): {
+        length: number;
+        id(): string;
+    };
+    isNode(): boolean;
+    outerWidth(): number;
+    outerHeight(): number;
+    source(): {
+        id(): string;
+    };
+    target(): {
+        id(): string;
+    };
+}
+interface CyCollection {
+    nodes(): CyElement[] & {
+        layoutPositions(layout: unknown, options: object, at: (n: CyElement) => {
+            x: number;
+            y: number;
+        }): void;
+    };
+    edges(): CyElement[];
+}
+export interface CytoscapeLayoutOptions {
+    name: 'draftably';
+    eles: CyCollection;
+    cy: unknown;
+    direction?: 'right' | 'down';
+    gap?: number;
+    routing?: RoutingOptions;
+    fit?: boolean;
+    padding?: number;
+    animate?: boolean;
+}
+/** The Cytoscape extension: pass it to `cytoscape.use`. */
+export declare function draftablyLayout(cytoscape: (type: 'layout', name: string, impl: unknown) => void): void;
+export {};

package/dist/types/src/graph-api/dagre.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A stand-in for `dagre.layout(g)`: it reads a graphlib graph and writes the results back into
+ * it the way dagre does, so code that reads `g.node(v).x` or `g.edge(e).points` keeps working.
+ * Node `x` and `y` are centres; edge `points` run from outline to outline; the graph gets `width`
+ * and `height`. Clusters (compound parents) are groups and get a box too.
+ */
+import { type LayoutResult, type RoutingOptions } from './core.js';
+type Label = {
+    [key: string]: unknown;
+};
+/** The graphlib `Graph` methods this reads, from `@dagrejs/graphlib` or `dagre.graphlib`. */
+export interface DagreGraph {
+    nodes(): string[];
+    node(v: string): Label | undefined;
+    edges(): Array<{
+        v: string;
+        w: string;
+        name?: string;
+    }>;
+    edge(e: {
+        v: string;
+        w: string;
+        name?: string;
+    }): Label | undefined;
+    graph(): Label | undefined;
+    parent?(v: string): string | undefined | void;
+    children?(v?: string): string[] | undefined;
+}
+/** Lay out a graphlib graph in place, as `dagre.layout(g)` does. Returns the full result too. */
+export declare function dagreLayout(g: DagreGraph, options?: {
+    routing?: RoutingOptions;
+}): LayoutResult;
+export {};

package/dist/types/src/graph-api/elk.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ELK JSON in, ELK JSON out, so `new DraftablyELK().layout(graph)` can stand in for
+ * `new ELK().layout(graph)` from elkjs. A node with children is a group. Coordinates come back as
+ * elkjs gives them: a node's x and y relative to its parent; an edge's sections and labels relative
+ * to its `container`, the nearest node that holds both of its ends, which is set on each edge.
+ */
+import { type GraphIn, type LayoutResult } from './core.js';
+export interface ElkLabel {
+    id?: string;
+    text?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface ElkPort {
+    id: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    layoutOptions?: Record<string, string>;
+}
+export interface ElkPoint {
+    x: number;
+    y: number;
+}
+export interface ElkEdgeSection {
+    id: string;
+    startPoint: ElkPoint;
+    endPoint: ElkPoint;
+    bendPoints?: ElkPoint[];
+    incomingShape?: string;
+    outgoingShape?: string;
+}
+export interface ElkEdge {
+    id: string;
+    sources: string[];
+    targets: string[];
+    labels?: ElkLabel[];
+    sections?: ElkEdgeSection[];
+    container?: string;
+    layoutOptions?: Record<string, string>;
+}
+export interface ElkNode {
+    id: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    children?: ElkNode[];
+    ports?: ElkPort[];
+    edges?: ElkEdge[];
+    labels?: ElkLabel[];
+    layoutOptions?: Record<string, string>;
+}
+export interface ElkInput {
+    graph: GraphIn;
+    warnings: string[];
+    /** For each ELK edge, the IDs of its pieces: one per source and target pair. */
+    pieces: Map<string, string[]>;
+    /** Whether the drawing is mirrored afterwards, for `LEFT` and `UP`. */
+    mirror?: 'x' | 'y';
+}
+export declare function fromElk(root: ElkNode, extra?: Record<string, string>): ElkInput;
+export declare function toElk(root: ElkNode, out: LayoutResult, { pieces }: ElkInput): ElkNode;
+/** Lay out an ELK graph with draftably and return it as elkjs would. */
+export declare function layoutElk(root: ElkNode, extra?: Record<string, string>, common?: Partial<GraphIn>): Promise<{
+    elk: ElkNode;
+    result: LayoutResult;
+}>;
+/**
+ * A stand-in for elkjs's `ELK` class: the same `layout(graph, { layoutOptions })` call, with
+ * draftably's layout and router. Options draftably does not use are listed in `warnings`.
+ */
+export declare class DraftablyELK {
+    private options;
+    /** Warnings from the last `layout` call, such as ELK options that were not used. */
+    warnings: string[];
+    constructor(options?: {
+        defaultLayoutOptions?: Record<string, string>;
+    });
+    layout(graph: ElkNode, args?: {
+        layoutOptions?: Record<string, string>;
+    }): Promise<ElkNode>;
+    knownLayoutAlgorithms(): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    terminateWorker(): void;
+}

package/dist/types/src/graph-api/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Draftably's layout and router for graphs from any tool: `@draftably/runtime/graph`.
+ *
+ *   const placed = await layout({ nodes, edges });               // draftably's own shape
+ *   const { reactFlow } = await layout({ reactFlow: { nodes, edges } });
+ *   const lines = route({ nodes: placedBoxes, edges });          // lines only
+ *
+ * A keyed call returns the same shape it took, under the same key.
+ */
+import { type GraphIn, type LayoutResult, type RouteIn, type Routed, type RoutingOptions } from './core.js';
+import { type FlowEdge, type FlowEdgeOut, type FlowGraph, type FlowNode, type FlowNodeOut, type FlowOptions, type SvelteFlowNodeOut } from './react-flow.js';
+import { type ElkNode } from './elk.js';
+export { AUTO_FULL_LIMIT, layoutSync } from './core.js';
+export { DraftablyELK } from './elk.js';
+export { dagreLayout } from './dagre.js';
+export { draftablyLayout } from './cytoscape.js';
+export type { ElkEdge, ElkEdgeSection, ElkLabel, ElkNode, ElkPort } from './elk.js';
+export type { DagreGraph } from './dagre.js';
+export type { CytoscapeLayoutOptions } from './cytoscape.js';
+export type * from './core.js';
+export type { DraftablyEdgeData, FlowEdge, FlowEdgeOut, FlowGraph, FlowNode, FlowNodeOut, FlowOptions, SvelteFlowNodeOut, } from './react-flow.js';
+/** Settings a keyed call takes beside its graph. */
+export type Common = Pick<GraphIn, 'arrange' | 'direction' | 'gap' | 'fit' | 'fold' | 'routing'>;
+type FlowLayout<N extends FlowNode, E extends FlowEdge> = FlowGraph<FlowNodeOut<N>, FlowEdgeOut<E>>;
+type SvelteLayout<N extends FlowNode, E extends FlowEdge> = FlowGraph<SvelteFlowNodeOut<N>, FlowEdgeOut<E>>;
+type FlowRouted<N extends FlowNode, E extends FlowEdge> = FlowGraph<N, FlowEdgeOut<E>>;
+export declare function layout(graph: GraphIn): Promise<LayoutResult>;
+export declare function layout<N extends FlowNode, E extends FlowEdge>(input: {
+    reactFlow: FlowGraph<N, E>;
+} & FlowOptions & Common): Promise<{
+    reactFlow: FlowLayout<N, E>;
+    result: LayoutResult;
+}>;
+export declare function layout<N extends FlowNode, E extends FlowEdge>(input: {
+    svelteFlow: FlowGraph<N, E>;
+} & FlowOptions & Common): Promise<{
+    svelteFlow: SvelteLayout<N, E>;
+    result: LayoutResult;
+}>;
+export declare function layout(input: {
+    elk: ElkNode;
+} & Common): Promise<{
+    elk: ElkNode;
+    result: LayoutResult;
+}>;
+export declare function route(graph: RouteIn): Routed;
+export declare function route<N extends FlowNode, E extends FlowEdge>(input: {
+    reactFlow: FlowGraph<N, E>;
+    routing?: RoutingOptions;
+} & FlowOptions): {
+    reactFlow: FlowRouted<N, E>;
+    result: Routed;
+};
+export declare function route<N extends FlowNode, E extends FlowEdge>(input: {
+    svelteFlow: FlowGraph<N, E>;
+    routing?: RoutingOptions;
+} & FlowOptions): {
+    svelteFlow: FlowRouted<N, E>;
+    result: Routed;
+};

package/dist/types/src/graph-api/react-flow.d.ts

@@ -0,0 +1,100 @@
+/**
+ * React Flow (and Svelte Flow, which shares its node and edge shape) in, the same shape out.
+ * Nodes come back with `position` relative to their parent, as sub-flows expect, and a size.
+ * Edges keep their fields and gain `type: 'draftably'` (unless they have a type) and
+ * `data.draftably`: the routed path and label box that `DraftablyEdge` draws.
+ */
+import type { EdgeOut, GraphIn, LayoutResult, RouteIn, Routed, Shape } from './core.js';
+import type { Side } from '../model/types.js';
+/**
+ * The fields of a React Flow 11 or 12 node that layout reads; other fields pass through. No index
+ * signature, so React Flow's own `Node` and `Edge` types fit.
+ */
+export interface FlowNode {
+    id: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    data?: {
+        label?: unknown;
+        [key: string]: unknown;
+    };
+    type?: string;
+    parentId?: string;
+    /** React Flow 11's name for `parentId`. */
+    parentNode?: string;
+    width?: number | null;
+    height?: number | null;
+    measured?: {
+        width?: number;
+        height?: number;
+    };
+    /** React Flow's style object, or Svelte Flow's CSS string. */
+    style?: string | {
+        width?: number | string;
+        height?: number | string;
+    };
+}
+export interface FlowEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: unknown;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+    animated?: boolean;
+    type?: string;
+    data?: Record<string, unknown>;
+}
+export interface FlowGraph<N extends FlowNode = FlowNode, E extends FlowEdge = FlowEdge> {
+    nodes: N[];
+    edges: E[];
+}
+export interface FlowOptions {
+    /** A draftably shape for a node, such as `n => n.type === 'decision' ? 'diamond' : undefined`. */
+    shape?: (node: FlowNode) => Shape | undefined;
+}
+/** What `layout` and `route` add to each edge, under `data.draftably`. */
+export interface DraftablyEdgeData {
+    path: string;
+    points: EdgeOut['points'];
+    label: EdgeOut['label'];
+    sourceSide: Side;
+    targetSide: Side;
+    blocked: boolean;
+}
+/** A Svelte Flow node as `layout` returns it: placed relative to its parent, with its size. */
+export type SvelteFlowNodeOut<N extends FlowNode> = N & {
+    position: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+};
+/** A React Flow node as `layout` returns it: the size is also in its `style`. */
+export type FlowNodeOut<N extends FlowNode> = SvelteFlowNodeOut<N> & {
+    style: Exclude<NonNullable<N['style']>, string> & {
+        width: number;
+        height: number;
+    };
+};
+export type FlowEdgeOut<E extends FlowEdge> = E & {
+    type: string;
+    data: E['data'] & {
+        draftably: DraftablyEdgeData;
+    };
+};
+export declare function fromFlow({ nodes, edges }: FlowGraph, options?: FlowOptions): GraphIn;
+/**
+ * Svelte Flow keeps `style` as a CSS string and sizes a node from `width` and `height`, so its
+ * nodes keep their own style; React Flow nodes also get the size in `style`.
+ */
+export declare function toFlow<N extends FlowNode, E extends FlowEdge>({ nodes, edges }: FlowGraph<N, E>, out: LayoutResult, svelte?: boolean): FlowGraph<FlowNodeOut<N>, FlowEdgeOut<E>>;
+/**
+ * The boxes React Flow shows now, for `route`: each position made absolute through its parents.
+ * A node without a size is skipped, with its edges, until React Flow has measured it.
+ */
+export declare function placedFlow({ nodes, edges }: FlowGraph, options?: FlowOptions): RouteIn;
+export declare function routedFlow<E extends FlowEdge>(edges: E[], routed: Routed): FlowEdgeOut<E>[];

package/dist/types/src/graph-api/transform.d.ts

@@ -0,0 +1,6 @@
+/** Whole-drawing moves for adapters whose library draws in another frame. */
+import type { LayoutResult } from './core.js';
+/** The drawing moved so that its bounds start at (0, 0). */
+export declare function shifted(out: LayoutResult): LayoutResult;
+/** The drawing flipped across its bounds, so a `right` layout reads leftward (or `down` upward). */
+export declare function mirrored(out: LayoutResult, axis: 'x' | 'y'): LayoutResult;

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

@@ -93,6 +93,15 @@ export interface EdgeLayout {
     toOffset?: number;
     /** A sequence message: drawn straight between the two lifelines at this height, not routed. */
     row?: number;
+    /**
+     * Set by the compiler for a forward line in a `flow` scope: its route planned from the ranks.
+     * The quick router takes it as it is when it clears every box.
+     */
+    plan?: {
+        points: Point[];
+        fromOffset: number;
+        toOffset: number;
+    };
 }
 /**
  * A channel between two bands of a fold: a level line at `y`, or an upright one at `x`. With