@draftably/markdown 0.1.0 → 0.2.1

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

@@ -0,0 +1,53 @@
+/**
+ * Routing channels inside groups.
+ *
+ * A group leaves `GROUP_INSET` between its members and its border. That is padding, not room for
+ * a line: a line routed through it runs beside a member and along the border at once. When a
+ * connection has to travel inside a group (a member boxed in by its neighbours, or a link between
+ * two of the group's children that can't go straight across), the group grows a channel on one
+ * side, wide enough for each such line to run a full standoff from the members,
+ * the border and each other. A link between children takes the side of them both ends lean
+ * toward, and a return (up or left) takes the left or top when they lean neither way, so a
+ * forward line and its return don't cross. The compiler lays the scene out once, plans channels
+ * from that geometry, and lays it out again with them.
+ */
+import type { ModelEdge } from './syntax';
+/**
+ * Room a group leaves round its content: the inset on the left, right and bottom (at least
+ * `GROUP_INSET`), and extra room under the title band on top (0 without a channel there).
+ */
+export interface Channel {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    /** How many lines each side's channel was planned for. */
+    lines: Record<Side, number>;
+}
+/** Channels may grow the drawing's area by this much at most. */
+export declare const CHANNEL_BUDGET = 1.1;
+/**
+ * Drop the channels that carry fewest lines until the drawing laid out with the rest (`measure`)
+ * is within `CHANNEL_BUDGET` of its area without any (`plain`).
+ */
+export declare function trimChannels(plan: Map<string, Channel>, plain: number, measure: (channels: Map<string, Channel>) => number): Map<string, Channel>;
+interface Box {
+    id: string;
+    type: string;
+    parent: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type Side = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Channels for the scene laid out as `objects`. A group is keyed by id; groups with no traffic
+ * are left out.
+ */
+export declare function planChannels(objects: Box[], edges: ModelEdge[], routing?: {
+    edgeGap?: number;
+    portGap?: number;
+    standoff?: number;
+}): Map<string, Channel>;
+export {};

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

@@ -0,0 +1,175 @@
+import { type ResolvedAppearance } from '../model/appearance';
+import type { CellsChrome, Lane, SequenceLayout } from '../model/types';
+import { type Planned } from './corridors';
+import { GROUP_HEADER, GROUP_INSET, contentOrigin } from './frame';
+import { type Model, type ModelEdge, type ModelLayout, type ModelObject } from './syntax';
+/** The single render context. Browser window size changes the camera, never the layout. */
+export declare const RENDER_CONTEXT: {
+    readonly width: 1100;
+    readonly height: 720;
+};
+export { GROUP_HEADER, GROUP_INSET, contentOrigin };
+export interface SceneObject extends ModelObject {
+    /** World (diagram) coordinates. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Position relative to the parent's content origin; `pin` and `stay` use these. */
+    localX: number;
+    localY: number;
+    /** Local position from the automatic recipe alone, before refinements; `nudge` offsets this. */
+    baseX: number;
+    baseY: number;
+    depth: number;
+    /** Sequence participants: how far the dashed lifeline runs below the box. */
+    lifeline?: number;
+    /** Soft groups: the tint's rectangles, relative to the group's top left; the first holds the label. */
+    hull?: Array<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+    /** Groups: lines the title wraps to, when more than one. */
+    titleLines?: number;
+}
+export interface Diagnostic {
+    level: 'error' | 'warning' | 'info';
+    code: string;
+    message: string;
+    /** Source line of the rule involved, when there is one. */
+    line?: number;
+    ids: string[];
+}
+/** 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;
+}
+export interface Scene {
+    model: Model;
+    title: string;
+    objects: SceneObject[];
+    byId: Map<string, SceneObject>;
+    edges: SceneEdge[];
+    diagnostics: Diagnostic[];
+    /** The file's resolved appearance: the spacing and type every size above was computed with. */
+    look: ResolvedAppearance;
+    /** Rulers and run-on pieces of byte and bit layouts, by group. */
+    cells: Map<string, CellsChrome>;
+    /** Sequence diagrams: the panel they are drawn on and their phases' row bands. */
+    sequence?: SequenceLayout;
+}
+type Size = {
+    w: number;
+    h: number;
+};
+type Pos = {
+    x: number;
+    y: number;
+};
+export declare function compile(source: string): Promise<Scene>;
+/**
+ * Check source synchronously: every error `compile` can report, without running layout engines
+ * (they never add errors). Engine-governed scopes keep their built-in recipe in the result.
+ */
+export declare function checkSource(source: string): Scene;
+/**
+ * The scene as layout sees it, for edits that write positions: soft and frameless groups left
+ * out, and each object under the container that lays it out, which its local position is
+ * relative to.
+ */
+export declare function layoutView(scene: Scene): Scene;
+/** How far a soft refinement may give way before `check` warns that it no longer holds. */
+export declare const RELAXED_WARNING = 16;
+/** Solver budget for engine recipes; the same budget Compare and the timeline use. */
+export declare const ENGINE_ITERATIONS = 640;
+/** A labelled edge between two siblings, with the room its label needs across and down a gap. */
+interface LabelRoom {
+    a: string;
+    b: string;
+    w: number;
+    h: number;
+}
+export declare function layoutFor(m: Model, scope: string): ModelLayout;
+/**
+ * Size of a node: its requested size, or the default width with a height that fits the title in
+ * the theme's type and padding. A requested size is kept exactly; `overflow` reports a title that
+ * no longer fits in it.
+ */
+export declare function leafSize(o: ModelObject, size: {
+    width: number;
+    height?: number;
+} | undefined, look: ResolvedAppearance): {
+    w: number;
+    h: number;
+    overflow: boolean;
+};
+/**
+ * Longest-path ranks, in declaration order. Cycles are broken first: a depth-first walk from the
+ * sources (then any node not yet reached), in declaration order, sets aside each edge that returns
+ * to a node still on the walk. A loop therefore keeps its path along the reading direction and
+ * only its return edge runs backwards.
+ */
+export declare function rankLayers(ids: string[], pairs: Array<[string, string]>): string[][];
+/** A folded run: each band's ids in reading order, and the axis the bands read along. */
+export interface Fold {
+    bands: string[][];
+    axis: 'right' | 'down';
+}
+/**
+ * Fold a long run of ranks into bands, like lines of text: each band starts again at the
+ * beginning of the reading direction, and the bands stack across it. A run that is longer than
+ * the render context and more than `FOLD_ASPECT` times its depth is cut only between ranks (where
+ * no box spans the cut), into the fewest bands that bring it within both. Within a quarter of an
+ * even share, a cut is chosen for the fewest edges across it, keeping each decision with its
+ * branches and each loop whole, before an exact balance. Other runs are returned unchanged.
+ *
+ * `plan` is the same run laid out without its edge labels. Whether to fold, how many bands and
+ * where to cut are decided on it, so relabelling an edge never adds a band or moves a cut: the
+ * labels only widen the gaps they need inside their own band.
+ */
+export declare function foldRanks(items: Array<{
+    id: string;
+    w: number;
+    h: number;
+}>, positions: Map<string, Pos>, axis: 'right' | 'down', gap: number, pairs: Array<[string, string]>, rooms?: LabelRoom[], decisions?: Set<string>, plan?: Map<string, Pos>, { aspect, fewest, room, }?: {
+    aspect?: number;
+    fewest?: number;
+    room?: number;
+}): {
+    positions: Map<string, Pos>;
+    fold?: Fold;
+};
+/** How many times orthogonal paths, given as points along and across, cross one another. */
+export declare function crossings(paths: Array<Array<{
+    u: number;
+    v: number;
+}>>): 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.
+ *
+ * Nodes are laid out on slots: their size in the reference appearance (the default theme, with
+ * the file's own overrides), so a theme switch keeps rows, order and positions. Each node is drawn
+ * at its theme's size in its slot. A slot grows only where the theme's size is larger
+ * than the scope's gap can absorb (`SLOT_SPILL`), or where spilling would bring two boxes closer
+ * than `MIN_GAP`. With `slots`, objects come out at their slot size (the engines' input).
+ */
+export declare function layoutModel(m: Model, arranged?: Map<string, Pos & Size>, slots?: boolean): Scene;

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';
+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/dsl/frame.d.ts

@@ -0,0 +1,38 @@
+/** Group frame metrics shared by the compiler, the projection and the translator. */
+/** Space between a group's frame and its content, on the sides and bottom. */
+export declare const GROUP_INSET = 24;
+/**
+ * Space between a group's top edge and its content in the default theme; the title sits in it.
+ * Themes with taller titles reserve more (`ResolvedAppearance.groupHeader`).
+ */
+export declare const GROUP_HEADER = 48;
+/**
+ * Horizontal room a group title needs besides its text: the icon and gap before it (33) and the
+ * frame controls after it (64), as `GroupView` and the SVG export truncate titles.
+ */
+export declare const GROUP_TITLE_CHROME: number;
+/** Room a soft group's tint leaves round its members, and above them for its label. */
+export declare const SOFT_PAD = 10;
+export declare const SOFT_LABEL = 18;
+/** Where a soft group's label sits in its tint: in the annotation face, at the top left. */
+export declare const SOFT_TITLE: {
+    x: number;
+    y: number;
+};
+/** Corner radius of each rectangle of a tint; small, so joined rectangles read as one shape. */
+export declare const SOFT_RADIUS = 6;
+/** Dash of a sequence participant's lifeline; quieter than a message line. */
+export declare const LIFELINE: {
+    dash: string;
+    width: number;
+};
+/** Top-left of a group's content area, which its children's local positions are relative to. */
+export declare const contentOrigin: (group: {
+    x: number;
+    y: number;
+}, header?: number) => {
+    x: number;
+    y: number;
+};
+/** Horizontal room a `cells` group's title needs besides its text: padding and the collapse control. */
+export declare const CELLS_TITLE_CHROME: number;

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

@@ -0,0 +1,23 @@
+import type { Lane } from '../model/types';
+import type { ModelEdge } from './syntax';
+interface Box {
+    id: string;
+    type: string;
+    shape?: string;
+    parent: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A scope arranged along a reading axis, with its fold's bands when it folded. */
+export interface FlowScope {
+    scope: string;
+    axis: 'right' | 'down';
+    bands?: string[][];
+}
+export declare function returnLanes(flows: FlowScope[], edges: ModelEdge[], byId: Map<string, Box>, taken: Set<string>, labelSize?: (label: string) => {
+    w: number;
+    h: number;
+}): Map<string, Lane>;
+export {};

package/dist/types/src/dsl/legend-notes.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './compile';
+import type { Model } from './syntax';
+export declare function legendNotes(m: Model): Diagnostic[];

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

@@ -0,0 +1,39 @@
+import type { Diagram, Rect } from '../model/types';
+import type { Scene } from './compile';
+/** Editor state that is not part of the source and survives a reprojection. */
+export type ViewState = Partial<Pick<Diagram, 'settings' | 'camera' | 'theme' | 'collapsed'>>;
+export declare function projectScene(scene: Scene, view?: ViewState): Diagram;
+export interface CanonicalGeometry {
+    nodes: Array<{
+        id: string;
+        parent: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+    routes: Array<{
+        id: string;
+        points: Array<{
+            x: number;
+            y: number;
+        }>;
+    }>;
+}
+/** Rectangles for everything visible, as the canvas draws them. */
+export declare function visibleRects(doc: Diagram): {
+    vg: import("../model/graph").VisibleGraph;
+    rects: Map<string, Rect>;
+};
+/**
+ * Node rectangles and route points for a projected document. Edge label positions are left out:
+ * the browser measures label text with real fonts, which Node cannot reproduce.
+ */
+export declare function canonicalGeometry(doc: Diagram): CanonicalGeometry;
+export declare function measured(doc: Diagram, rects: Map<string, Rect>, routes: Array<{
+    id: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}>): CanonicalGeometry;