@draftably/markdown 0.0.0-stage → 0.2.0

package/dist/types/packages/markdown/src/core.d.ts

@@ -0,0 +1,110 @@
+import type { Diagnostic } from '@draftably/runtime';
+import type { FenceOptions } from './metadata.js';
+export { resolveSource } from './source.js';
+export { parseFenceOptions } from './metadata.js';
+export type { Diagnostic } from '@draftably/runtime';
+export interface DraftDocument {
+    path?: string;
+}
+export interface DraftAsset {
+    fileName: string;
+    mediaType: 'image/svg+xml';
+    bytes: Uint8Array;
+}
+export interface AssetReference {
+    fileName: string;
+    url: string;
+}
+export interface DraftDocumentResult {
+    version: 1;
+    assets: readonly AssetReference[];
+    clientModules: readonly string[];
+    dependencies: readonly string[];
+    diagnostics: readonly Diagnostic[];
+}
+export interface SourceDependency {
+    documentPath: string;
+    dependencyPath: string;
+    missing: boolean;
+    watchPath?: string;
+}
+export type EmitAsset = (asset: DraftAsset, context: {
+    document: DraftDocument;
+    fenceIndex: number;
+}) => Promise<{
+    url: string;
+}>;
+export interface DraftMarkdownOptions {
+    emitAsset: EmitAsset;
+    errors?: 'fail' | 'placeholder';
+    /**
+     * `convert` draws ```mermaid fences that hold a flowchart or sequence as Draftably images and
+     * leaves every other Mermaid family as a code block. `off` (default) leaves all of them.
+     */
+    mermaid?: 'convert' | 'off';
+    interactive?: MarkdownInteractiveBridge;
+    render?: {
+        includeSource?: boolean;
+        links?: {
+            mode: 'none';
+        } | {
+            mode: 'safe';
+            baseUrl?: string;
+            target?: '_self' | '_blank';
+            cacheKey?: string;
+            resolve?: (request: {
+                itemId: string;
+                href: string;
+            }) => string | null;
+        };
+        limits?: {
+            maxSourceChars?: number;
+            maxSourceBytes?: number;
+            maxOutputBytes?: number;
+            maxObjects?: number;
+            maxEdges?: number;
+            maxDepth?: number;
+        };
+        signal?: AbortSignal;
+    };
+    sources?: {
+        rootDir: string;
+        onDependency?: (dependency: SourceDependency) => void;
+    };
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+export interface DraftViewerInitV1 {
+    version: 1;
+    key: string;
+    source: string;
+    state: string | null;
+    label: string;
+    policyId: string;
+}
+export interface MarkdownInteractiveBridge {
+    clientModuleUrl: string;
+    policyId: string;
+    emitInit(data: DraftViewerInitV1): Promise<{
+        fileName: string;
+        url: string;
+    }>;
+}
+/** Native source for a Mermaid fence, or null when the fence stays as code. */
+export declare function mermaidSource(text: string, location: Diagnostic['location'], options: DraftMarkdownOptions): Promise<{
+    source: string | null;
+    alt?: string;
+    diagnostics: Diagnostic[];
+}>;
+export declare function makeDiagnostic(code: string, message: string, location?: Diagnostic['location'], related?: Diagnostic['related']): Diagnostic;
+export declare function contentHash(value: string | Uint8Array): string;
+export declare function hostFailure(error: unknown, message?: string): Error;
+export declare function isHostFailure(error: unknown): boolean;
+export declare function isNoPlaceholder(error: unknown): boolean;
+export declare function prepare(source: string, metadata: FenceOptions, location: Diagnostic['location'], document: DraftDocument, fenceIndex: number, options: DraftMarkdownOptions): Promise<{
+    node: Record<string, unknown>;
+    asset?: AssetReference;
+    diagnostics: Diagnostic[];
+    dependency?: string;
+    extraAssets?: AssetReference[];
+    clientModule?: string;
+}>;

package/dist/types/packages/markdown/src/files.d.ts

@@ -0,0 +1,12 @@
+import type { EmitAsset, MarkdownInteractiveBridge } from './core.js';
+export interface FileAssets {
+    directory: string;
+    emitAsset: EmitAsset;
+    emitInit: MarkdownInteractiveBridge['emitInit'];
+    copyTo(directory: string): Promise<void>;
+}
+/** Create a content-addressed Node file store for generated SVG and viewer JSON assets. */
+export declare function createFileAssets(options: {
+    directory: string;
+    publicPath: string;
+}): FileAssets;

package/dist/types/packages/markdown/src/index.d.ts

@@ -0,0 +1,3 @@
+export { parseFenceOptions } from './core.js';
+export type { FenceOptions } from './metadata.js';
+export type { AssetReference, Diagnostic, DraftAsset, DraftDocument, DraftDocumentResult, DraftMarkdownOptions, DraftViewerInitV1, EmitAsset, MarkdownInteractiveBridge, SourceDependency, } from './core.js';

package/dist/types/packages/markdown/src/markdown-it-helpers.d.ts

@@ -0,0 +1,9 @@
+export declare function isDraftFenceInfo(info: string): boolean;
+export interface HtmlImage {
+    url: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+export declare function escapeHtml(value: string): string;
+export declare function imageHtml(image: HtmlImage): string;

package/dist/types/packages/markdown/src/markdown-it.d.ts

@@ -0,0 +1,30 @@
+import { type DraftDocumentResult, type DraftMarkdownOptions } from './core.js';
+export interface DraftMarkdownItEnvironment {
+    draftably?: {
+        documentPath?: string;
+    };
+    [key: string]: unknown;
+}
+interface Token {
+    type: string;
+    info?: string;
+    content?: string;
+    map?: number[] | null;
+    children?: Token[] | null;
+}
+interface MarkdownItRenderHost<Tokens> {
+    parse(source: string, env?: unknown): Tokens[];
+    options: unknown;
+    renderer: {
+        render(tokens: Tokens[], options: unknown, env?: unknown): string;
+    };
+}
+export declare function createMarkdownItDraft(options: DraftMarkdownOptions): {
+    plugin: (instance: unknown) => void;
+    prepare: (tokens: Token[], env?: DraftMarkdownItEnvironment) => Promise<DraftDocumentResult>;
+    render: (md: MarkdownItRenderHost<unknown>, source: string, env?: DraftMarkdownItEnvironment) => Promise<{
+        html: string;
+        manifest: DraftDocumentResult;
+    }>;
+};
+export {};

package/dist/types/packages/markdown/src/mermaid.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from '@draftably/runtime';
+export declare function isMermaidCandidate(text: string): boolean;
+/** Native source for a Mermaid flowchart or sequence, or null to leave the fence to Mermaid. */
+export declare function convertMermaid(text: string, location: Diagnostic['location']): Promise<{
+    source: string | null;
+    alt?: string;
+    diagnostics: Diagnostic[];
+}>;

package/dist/types/packages/markdown/src/metadata.d.ts

@@ -0,0 +1,9 @@
+export interface FenceOptions {
+    id?: string;
+    alt?: string;
+    caption?: string;
+    src?: string;
+    mode?: string;
+    state?: string;
+}
+export declare function parseFenceOptions(info: string): FenceOptions;

package/dist/types/packages/markdown/src/remark.d.ts

@@ -0,0 +1,21 @@
+import { type DraftMarkdownOptions } from './core.js';
+interface Node {
+    type: string;
+    lang?: string | null;
+    meta?: string | null;
+    value?: string;
+    children?: Node[];
+    position?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+    };
+}
+interface FileLike {
+    path?: string;
+    data?: Record<string, unknown>;
+}
+/** Convert parser-recognized `draft` code nodes, and opted-in Mermaid ones, into static image nodes. */
+export default function remarkDraft(options: DraftMarkdownOptions): (tree: Node, file: FileLike) => Promise<void>;
+export {};

package/dist/types/packages/markdown/src/source.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveSource(src: string, documentPath: string, rootDir: string): Promise<{
+    source: string;
+    path: string;
+}>;

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

@@ -0,0 +1,91 @@
+import type { ResolvedAppearance } from '../model/appearance';
+/** Width of a marker's bar, centred on the seam it marks. */
+export declare const MARKER_WIDTH = 8;
+/** How far a marker's bar runs past the cells, so a line meets it clear of their corners. */
+export declare const MARKER_TAIL = 16;
+/** Height of a cells group's title band for a title type of this line height. */
+export declare const cellsBandFor: (lineHeight: number) => number;
+export interface CellInput {
+    id: string;
+    label: string;
+    marker: boolean;
+    /** Columns the cell covers in a grid. */
+    span?: number;
+    /** From a `size` line. */
+    size?: {
+        width: number;
+        height?: number;
+    };
+}
+export interface CellBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A cell's own size: one line of title when it fits in `MAX_CELL`, wrapped when it does not. */
+export declare function cellSize(c: CellInput, look: ResolvedAppearance): {
+    w: number;
+    h: number;
+};
+/**
+ * Cells edge to edge, in rows of `columns` columns filled in order; a cell's `span` covers that
+ * many columns, and a cell that does not fit the rest of a row starts the next one. Without
+ * `columns`, the cells form one row (`right`) or one column (`down`). Each column is as wide as
+ * its widest single cell, widened at its last column for a wider spanning cell, and each row is
+ * as tall as its tallest cell. Cells narrower than `minWidth` in all, the title band's width,
+ * widen the last column.
+ *
+ * A marker takes no room: in one row or column, its bar sits on the seam before the next cell
+ * and spans the band above as well, so it cuts the whole object, and runs a short tail past the
+ * cells where lines meet it.
+ */
+export declare function layoutCells(cells: CellInput[], shape: {
+    direction: 'right' | 'down';
+    columns?: number;
+}, look: ResolvedAppearance, minWidth?: number): {
+    boxes: Map<string, CellBox>;
+    w: number;
+    h: number;
+};
+/** Width of one unit of a byte or bit layout, and the units in each row, unless the file says. */
+export declare const UNIT_WIDTH: {
+    readonly bit: 24;
+    readonly byte: 48;
+};
+export declare const UNIT_COLUMNS: {
+    readonly bit: 32;
+    readonly byte: 16;
+};
+export interface UnitCells {
+    /** Each field's main box: the longest piece, which holds its title. */
+    boxes: Map<string, CellBox>;
+    /** The other pieces of a field that runs on past a row's end. */
+    pieces: Map<string, CellBox[]>;
+    /** Fields of variable length, drawn with broken ends. */
+    open: string[];
+    /** Unit numbers above the first row: their centres, and the room they take above the cells. */
+    ruler?: {
+        h: number;
+        ticks: Array<{
+            x: number;
+            label: string;
+        }>;
+    };
+    w: number;
+    h: number;
+}
+/**
+ * A byte or bit layout: every unit has one width, so a field's width is its size. Rows hold
+ * `columns` units. A field longer than the rest of its row runs on into the next rows; a field of
+ * variable length (`span: 'var'`) fills the rest of its row, or a whole row, with broken ends.
+ * Every row has the height of the tallest title.
+ */
+export declare function layoutUnits(cells: Array<CellInput & {
+    open?: boolean;
+}>, shape: {
+    unit: 'bit' | 'byte';
+    columns?: number;
+    unitWidth?: number;
+    ruler: boolean;
+}, look: ResolvedAppearance): UnitCells;

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,162 @@
+import { type ResolvedAppearance } from '../model/appearance';
+import type { CellsChrome, Lane, SequenceLayout } from '../model/types';
+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 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[];
+/**
+ * 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/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;