@draftably/markdown 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,317 @@
+/**
+ * The `.draft` diagram language: a line-based source format that keeps comments, plus a model
+ * parser and a formatter. Adapted from the Meld 0.1 prototype in `reference/meld/original`.
+ *
+ * Source is kept as a list of lines so that edits can change single statements and formatting
+ * keeps every comment and unrelated statement.
+ */
+import { type DiagramAppearance, type Shade } from '../model/appearance';
+import { type EndMarker } from '../model/markers';
+import type { Status } from '../model/status';
+import type { ColorKey, LayoutAlgorithmId, LayoutSettings, PortSide, RoutingSettings, ShapeKind } from '../model/types';
+export declare class DslError extends Error {
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, line?: number, column?: number);
+}
+/** Change marks before `node`, `group` and `edge`, read like a diff, and the status each sets. */
+export declare const MARKS: {
+    readonly '+': "added";
+    readonly '-': "removed";
+    readonly '~': "changed";
+    readonly '.': "context";
+};
+export type Mark = keyof typeof MARKS;
+/** A word in a statement. Quoted words are strings; bare words are identifiers and numbers. */
+export interface Word {
+    value: string;
+    quoted: boolean;
+}
+export interface Statement {
+    kind: 'statement';
+    command: string;
+    /** Change mark written before the command, as in a diff: `+`, `-`, `~` or `.`. */
+    mark?: Mark;
+    args: Word[];
+    attrs: Array<[string, Word]>;
+    /** Inline comment including its `#` or `//` marker. */
+    comment?: string;
+    /** 1-based line in the source this statement was parsed from; 0 when added by an edit. */
+    line: number;
+}
+export type SourceLine = {
+    kind: 'blank';
+} | {
+    kind: 'comment';
+    text: string;
+} | Statement;
+export interface SourceDoc {
+    lines: SourceLine[];
+}
+export declare const bare: (value: string | number) => Word;
+export declare const quoted: (value: string) => Word;
+/**
+ * Split one line into raw tokens, each with its 1-based start column, and a trailing comment.
+ * Quoted tokens keep their quotes.
+ */
+export declare function tokenize(text: string, line?: number): {
+    tokens: string[];
+    columns: number[];
+    comment?: string;
+};
+/** Read source text into lines. Only lexical errors are reported here. */
+export declare function readSource(source: string): SourceDoc;
+export declare function printStatement(s: Statement): string;
+/**
+ * Print source consistently: one space between words, no indentation, at most one blank line in a
+ * row, and a final newline. Comments and statement order are kept.
+ */
+export declare function printSource(doc: SourceDoc): string;
+/** Format source text. Throws `DslError` for lexical errors; semantics are not checked. */
+export declare const formatSource: (source: string) => string;
+export type DslColor = ColorKey | 'auto';
+export type DslShape = Exclude<ShapeKind, 'icon' | 'image'>;
+/** `cells` lays a group's members edge to edge as one object: a sequence, table or byte layout. */
+export type Algorithm = 'flow' | 'row' | 'column' | 'lanes' | 'sequence' | 'cells';
+export interface ModelObject {
+    id: string;
+    type: 'node' | 'group';
+    label: string;
+    parent: string;
+    color: DslColor;
+    /** Explicit shade; omitted means the default for the object type. */
+    shade?: Shade;
+    shape: DslShape;
+    /** From a change mark; unchanged when omitted. */
+    status?: Status;
+    /** With `~`: the label before the change. */
+    was?: string;
+    /** With `~`, nodes only: the shape before the change. */
+    wasShape?: DslShape;
+    /** With `~`, nodes only: the count before the change; 1 means a single box. */
+    wasCount?: number | string;
+    /** A link to open from exported drawings, such as a source file or URL. */
+    href?: string;
+    /**
+     * Nodes only: how many things this one box stands for, drawn as a stack with a badge. A short
+     * symbol such as `N` or `many` stands for an unknown number.
+     */
+    count?: number | string;
+    /**
+     * Groups only: `soft` draws a tint behind the members and `none` draws nothing. Either way the
+     * group is not a layout scope: its members are laid out with the nearest framed container's.
+     */
+    frame?: 'soft' | 'none';
+    /** Groups only: `fold=never` keeps the group's chain in one column even when it is much the tallest. */
+    fold?: 'never';
+    /** Set by the compiler: the soft groups this object sits in below its layout scope, outermost first. */
+    soft?: string[];
+    /** Cells only: how many columns (or units) of its group's grid the cell covers; `var` for a
+     * field of variable length in a byte or bit layout. */
+    span?: number | 'var';
+    line: number;
+}
+export interface ModelEdge {
+    id: string;
+    source: string;
+    target: string;
+    label: string;
+    dashed: boolean;
+    from: PortSide;
+    to: PortSide;
+    /** From a change mark; unchanged when omitted. */
+    status?: Status;
+    /** With `~`: the label before the change. */
+    was?: string;
+    /** `directed=false`: an undirected connection, drawn without an arrowhead. */
+    directed?: false;
+    /** `head=`: the mark at the target end, when it isn't the plain arrow. */
+    head?: EndMarker;
+    /** `tail=`: the mark at the source end, when it has one. */
+    tail?: EndMarker;
+    /** `constraint=false`: drawn and routed, but layout doesn't rank or order by it. */
+    constraint?: false;
+    line: number;
+}
+/** A layout engine run cold over a scope's subtree; see `src/engines/layout-engine.js`. */
+export interface EngineRecipe {
+    algorithm: LayoutAlgorithmId;
+    params: Partial<LayoutSettings>;
+}
+/** Image shapes a drawing can aim for (`fit=`, `vary --fit`): width over height. */
+export declare const FITS: {
+    readonly wide: 2;
+    readonly slide: 1.78;
+    readonly square: 1;
+    readonly page: 0.77;
+    readonly tall: 0.6;
+};
+export type Fit = keyof typeof FITS;
+export interface ModelLayout {
+    scope: string;
+    algorithm: Algorithm;
+    /** Set when the scope is arranged by a layout engine instead of a built-in recipe. */
+    engine?: EngineRecipe;
+    direction: 'auto' | 'right' | 'down';
+    /** `cells` only: columns in each row of the grid; one row or column without it. */
+    columns?: number;
+    /** `cells` only: a byte or bit layout, where each column is one unit of the same width. */
+    unit?: 'bit' | 'byte';
+    /** With `unit`: the width of one unit, and whether unit numbers run above the first row. */
+    unitWidth?: number;
+    ruler?: boolean;
+    /** `flow` only: whether a long run of ranks folds into bands. Engines take `fold` as a param. */
+    fold: 'auto' | 'never';
+    /** Root only: the image shape to aim for; compile tries direction and folding to get closest. */
+    fit?: Fit;
+    gap: number;
+    minWidth: number;
+    minHeight: number;
+    line: number;
+}
+export type Hint = {
+    type: 'order';
+    scope: string;
+    ids: string[];
+    line: number;
+} | {
+    type: 'align';
+    axis: 'x' | 'y';
+    ids: string[];
+    strength: Strength;
+    line: number;
+} | {
+    type: 'near';
+    id: string;
+    ref: string;
+    side: NearSide;
+    gap: number;
+    offset: number;
+    strength: Strength;
+    line: number;
+} | {
+    type: 'nudge';
+    id: string;
+    dx: number;
+    dy: number;
+    line: number;
+} | {
+    type: 'stay';
+    id: string;
+    x: number;
+    y: number;
+    weight: number;
+    line: number;
+} | {
+    type: 'pin';
+    id: string;
+    x: number;
+    y: number;
+    line: number;
+}
+/** `height` is unset for `height=auto`: the title's height at that width, as without a size. */
+ | {
+    type: 'size';
+    id: string;
+    width: number;
+    height?: number;
+    line: number;
+};
+export type Strength = 'prefer' | 'required';
+/**
+ * What `near id ref` places against: `ref` itself when it is a sibling of `id`, else the group
+ * around `ref` that is `id`'s sibling. Undefined when `ref` is not inside one.
+ */
+export declare function nearAnchor(by: Map<string, ModelObject>, id: string, ref: string): string | undefined;
+export type NearSide = 'right' | 'left' | 'above' | 'below';
+export type HintType = Hint['type'];
+export declare const POSITION_HINTS: HintType[];
+export interface Model {
+    title: string;
+    objects: ModelObject[];
+    edges: ModelEdge[];
+    layouts: ModelLayout[];
+    hints: Hint[];
+    /** Router settings from a `routing` statement. */
+    routing: Partial<RoutingSettings>;
+    /** Theme, overrides and color definitions from `theme` and `theme-color` statements. */
+    appearance: DiagramAppearance;
+    /** Source line of the `theme` statement, and of each `theme-color` by `family:shade`. */
+    themeLine: number;
+    colorLines: Map<string, number>;
+    /** Source line of each `legend` entry, in order. */
+    legendLines: number[];
+    /** Source line of each `note`, in order. */
+    noteLines: number[];
+    /** Source line of each `footnote`, in order. */
+    footnoteLines: number[];
+    /** Source line of each ID an emphasis state lists, by `state:id`. */
+    stateLines: Map<string, number>;
+    /** Sequence diagrams: `phase` statements, each a run of messages drawn as a row band. */
+    phases: Array<{
+        id: string;
+        label: string;
+        ids: string[];
+        line: number;
+    }>;
+    /** Sequence diagrams: the `was-order` statement, the older version's message order. */
+    wasOrder?: {
+        ids: string[];
+        line: number;
+    };
+    /** Problems that do not stop the file from drawing, such as a `config` key set twice. */
+    warnings: {
+        code: string;
+        message: string;
+        line: number;
+    }[];
+}
+/** `config` keys and the setting each sets. */
+export declare const CONFIG_KEYS: {
+    readonly 'link-base': "linkBase";
+    readonly editor: "editor";
+    readonly 'strike-removed': "strikeRemoved";
+};
+/** Theme attributes in the file and the override each sets. */
+export declare const THEME_ATTRS: {
+    readonly 'padding-x': "paddingX";
+    readonly 'padding-y': "paddingY";
+    readonly radius: "radius";
+    readonly 'title-font': "titleFont";
+    readonly 'annotation-font': "annotationFont";
+    readonly canvas: "canvas";
+    readonly text: "text";
+    readonly connection: "connection";
+};
+type Param<K extends string> = {
+    key: K;
+    min: number;
+    max: number;
+} | {
+    key: K;
+    choices: readonly string[];
+};
+/**
+ * Layout engines a file can name. `separate` is left out: it only repairs overlaps in the current
+ * drawing, so it cannot be recomputed from the source.
+ */
+export declare const ENGINES: readonly LayoutAlgorithmId[];
+/** Engine settings by source attribute. Ranges match the engine's own limits. */
+export declare const ENGINE_PARAMS: Record<string, Param<keyof LayoutSettings>>;
+/** Router settings by source attribute. Ranges match the router's own limits. */
+export declare const ROUTING_PARAMS: Record<string, Param<keyof RoutingSettings>>;
+/** Source attribute for an engine or router setting. */
+export declare const paramAttr: (table: Record<string, Param<string>>, key: string) => string | undefined;
+export declare const isIdentifier: (s: string) => boolean;
+export declare const COLORS: DslColor[];
+export declare const DSL_SHAPES: DslShape[];
+/** Shapes a node's box can draw as it was: a marker's box is a thin cut, so it has no other shape. */
+export declare const PAST_SHAPES: ("box" | "text" | "pill" | "circle" | "diamond")[];
+/** Parse and validate source. Throws `DslError` with a line number for the first problem. */
+export declare function parseModel(source: string | SourceDoc): Model;
+/**
+ * The container that lays an object out: its parent, or the nearest framed container above it
+ * when its parent is a soft or frameless group. Soft groups are never layout scopes.
+ */
+export declare function layoutParent(by: Map<string, ModelObject>, id: string): string;
+export {};

package/dist/types/src/import/import-core.d.ts

@@ -0,0 +1,105 @@
+/** Build native source from the facts retained by an importer. */
+import type { EndMarker } from '../model/markers';
+export type Format = 'dot' | 'mermaid' | 'd2';
+export type Impact = 'syntax' | 'semantics' | 'appearance' | 'layout' | 'security' | 'limit';
+export interface Diagnostic {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    impact: Impact;
+    message: string;
+    line?: number;
+    column?: number;
+    foreignIds?: string[];
+}
+export interface NativeObject {
+    id: string;
+    kind: 'node' | 'group';
+    label: string;
+    parent?: string;
+    shape?: 'box' | 'pill' | 'circle' | 'diamond' | 'text';
+    color?: string;
+    shade?: number;
+}
+export interface NativeEdge {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    directed: boolean;
+    head?: EndMarker;
+    tail?: EndMarker;
+    dashed?: boolean;
+    constraint?: false;
+    fromSide?: 'left' | 'right' | 'top' | 'bottom';
+    toSide?: 'left' | 'right' | 'top' | 'bottom';
+}
+export interface NativeLayout {
+    scope: string;
+    kind: 'flow' | 'column' | 'row' | 'sequence';
+    direction?: 'right' | 'down';
+}
+export interface NativeColor {
+    name: string;
+    fill: string;
+    stroke: string;
+    ink: string;
+}
+export interface NativePhase {
+    id: string;
+    label: string;
+    members: string[];
+}
+export interface NativeNote {
+    text: string;
+    near?: string;
+    side?: 'left' | 'right' | 'above' | 'below';
+}
+export interface NativePlan {
+    title: string;
+    objects: NativeObject[];
+    edges: NativeEdge[];
+    layouts: NativeLayout[];
+    colors: NativeColor[];
+    /** Sequence diagrams only. */
+    phases?: NativePhase[];
+    notes?: NativeNote[];
+}
+export interface IdMapping {
+    kind: string;
+    foreign: string;
+    native: string;
+}
+export interface ImportResult {
+    status: 'ready' | 'needs-review' | 'failed';
+    format: Format;
+    family: string;
+    diagnostics: Diagnostic[];
+    /** Absent on every fatal error; callers must not apply a partial graph. */
+    nativeSource?: string;
+    facts?: NativePlan;
+    ids: IdMapping[];
+    requires: string[];
+}
+export declare const LIMITS: Readonly<{
+    sourceBytes: number;
+    objects: 500;
+    edges: 1200;
+    depth: 12;
+    labelChars: number;
+    totalLabelBytes: number;
+    outputBytes: number;
+    nativeSourceChars: 300000;
+}>;
+export declare class Ids {
+    readonly entries: IdMapping[];
+    private readonly byForeign;
+    private readonly taken;
+    get(kind: string, foreign: string, preferred?: string): string;
+}
+export declare const quote: (value: string) => string;
+export declare const blankPlan: (title: string) => NativePlan;
+export declare function inputLimit(source: string): Diagnostic[];
+export declare function finish(format: Format, family: string, plan: NativePlan, diagnostics: Diagnostic[], ids: Ids): ImportResult;
+/** Only an explicit hex color is accepted. No CSS, URL, or Graphviz colorscheme interpretation. */
+export declare function hex(value: string | undefined): string | undefined;
+export declare function applyColor(plan: NativePlan, o: NativeObject, fill?: string, stroke?: string, ink?: string): void;

package/dist/types/src/import/mermaid-facade.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Tested against mermaid 12.2.0. Uses its internal DB behind a narrow, checked boundary.
+ * This file parses only; it neither renders Mermaid nor attaches interaction callbacks.
+ * Call in an isolated Node worker with a DOM, or in a dedicated browser Mermaid instance.
+ */
+export declare const MERMAID_VERSION: "12.2.0";
+export type ParserDiagnostic = {
+    code: string;
+    severity: 'warning' | 'error';
+    message: string;
+    line?: number;
+    column?: number;
+    locationKind?: 'source' | 'parser-relative';
+};
+export type FlowVertex = {
+    id: string;
+    text: string;
+    type?: string;
+    labelType: string;
+    classes: string[];
+    styles: string[];
+    link?: string;
+    icon?: string;
+    img?: string;
+    props?: Record<string, unknown>;
+};
+export type FlowEdge = {
+    start: string;
+    end: string;
+    text: string;
+    type?: string;
+    stroke?: string;
+    id?: string;
+    isUserDefinedId: boolean;
+    labelType: string;
+    classes: string[];
+    style: string[];
+    length?: number;
+    interpolate?: string;
+    animate?: boolean;
+    animation?: string;
+};
+export type FlowGroup = {
+    id: string;
+    title: string;
+    nodes: string[];
+    dir?: string;
+    labelType: string;
+    classes: string[];
+    metadata?: Record<string, unknown>;
+};
+export type FlowClass = {
+    id: string;
+    styles: string[];
+    textStyles: string[];
+};
+export type FlowSnapshot = {
+    format: 'mermaid';
+    family: 'flowchart';
+    parserVersion: typeof MERMAID_VERSION;
+    direction: string;
+    vertices: FlowVertex[];
+    edges: FlowEdge[];
+    groups: FlowGroup[];
+    classes: FlowClass[];
+    defaultEdgeStyle: string[];
+    defaultEdgeInterpolate?: string;
+};
+/** One entry of Mermaid's ordered sequence log; `kind` is its LINETYPE name. */
+export type SequenceEvent = {
+    kind: string;
+    from?: string;
+    to?: string;
+    text: string;
+    placement?: 'left' | 'right' | 'over';
+    central: boolean;
+};
+export type SequenceActor = {
+    id: string;
+    name: string;
+    type: string;
+    box?: number;
+    links: string[];
+};
+export type SequenceBox = {
+    name?: string;
+    fill?: string;
+};
+export type SequenceSnapshot = {
+    format: 'mermaid';
+    family: 'sequence';
+    parserVersion: typeof MERMAID_VERSION;
+    title?: string;
+    actors: SequenceActor[];
+    boxes: SequenceBox[];
+    events: SequenceEvent[];
+    created: string[];
+    destroyed: string[];
+};
+export type ParseFlowResult = {
+    ok: true;
+    snapshot: FlowSnapshot | SequenceSnapshot;
+    diagnostics: ParserDiagnostic[];
+} | {
+    ok: false;
+    diagnostics: ParserDiagnostic[];
+};
+type MermaidApi = Pick<(typeof import('mermaid'))['default'], 'initialize' | 'mermaidAPI'>;
+/** DB strings contain Mermaid entity sentinels; preserve entity spelling for text decoding. */
+export declare function restoreEntitySpelling(value: string): string;
+/**
+ * Use an unattached HTML template only. Its content is inert and is never adopted into the page.
+ * Caller supplies the browser document or the dedicated worker's JSDOM document.
+ * Markdown markers deliberately remain visible; native Markdown rendering is not assumed.
+ */
+export declare function makePlainLabel(document: Document): (value: string) => string;
+export declare function preflightMermaidFlow(source: string): ParserDiagnostic[];
+/** Each factory owns a serialized queue because Mermaid maintains parser/configuration state. */
+export declare function createMermaidFlowParser(load: () => Promise<MermaidApi>): (source: string) => Promise<ParseFlowResult>;
+export {};

package/dist/types/src/import/mermaid-importer.d.ts

@@ -0,0 +1,4 @@
+import { type ImportResult } from './import-core';
+import { type ParseFlowResult } from './mermaid-facade';
+/** Convert a checked Mermaid snapshot into valid native source. */
+export declare function importMermaidFlow(parsed: ParseFlowResult, plainText: (value: string) => string, title?: string): ImportResult;

package/dist/types/src/import/mermaid-sequence.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mermaid `sequenceDiagram` -> native source. Participants become nodes and messages become edges
+ * in file order. Native sequences have no fragments, so each top-level branch of a block becomes
+ * a phase band, and the warning says that the branch logic is gone.
+ */
+import { type Diagnostic, type ImportResult } from './import-core';
+import type { SequenceSnapshot } from './mermaid-facade';
+export declare function mapMermaidSequence(snapshot: SequenceSnapshot, plainText: (value: string) => string, title: string, diagnostics: Diagnostic[]): ImportResult;