@draftably/editor 0.0.0-stage → 0.1.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: ("text" | "diamond" | "circle" | "box" | "pill")[];
+/** 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/dsl/translate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Translate one committed editor edit into source statements.
+ *
+ * The editor works on a projected `Diagram`. When an edit is committed, the document before and
+ * after it are compared and the supported differences become targeted source changes: model edits
+ * become declarations, and moves become relative preferences. Geometry the translator does not
+ * write snaps back when the source is reprojected, so nothing unsaved looks saved. Changes the
+ * file cannot express are rejected outright.
+ */
+import type { DiagramAppearance } from '../model/appearance';
+import type { Diagram } from '../model/types';
+import { type Scene } from './compile';
+import { type SourceDoc } from './syntax';
+export declare class UnsupportedEdit extends Error {
+}
+export interface EditInput {
+    source: SourceDoc;
+    scene: Scene;
+    before: Diagram;
+    after: Diagram;
+    label: string;
+    /** Selected ids when the edit was committed; moves and resizes apply to these. */
+    selection: string[];
+}
+export interface EditResult {
+    source: SourceDoc;
+    /** Editor ids of new objects and connections, mapped to their ids in the source. */
+    ids: Map<string, string>;
+    /** Short descriptions of saved refinements, for the status message. */
+    notes: string[];
+    /** Objects a move placed `near` a neighbour, with where they were dropped. */
+    drops: Drop[];
+}
+/** A dropped object: where it was let go in the drawing, and that point in its parent. */
+export interface Drop {
+    id: string;
+    x: number;
+    y: number;
+    local: {
+        x: number;
+        y: number;
+    };
+}
+/** Replace the `near` of each dropped object with a `stay` at the exact point it was dropped. */
+export declare function keepDropped(source: SourceDoc, drops: Drop[]): void;
+export declare function translateEdit(input: EditInput): EditResult;
+/**
+ * Write a diagram appearance as the file's `theme` line and `theme-color` statements. Statements
+ * for colors that are no longer defined are removed; the rest are updated in place, so comments
+ * next to them stay.
+ */
+export declare function writeAppearance(source: SourceDoc, appearance: DiagramAppearance): void;
+/**
+ * Write soft `stay` anchors at their current positions for objects around an accepted refinement:
+ * every top-level object, and the siblings of each edited object and of its containers. Later
+ * additions then move nearby objects instead of rearranging distant ones. Objects that already
+ * have a position refinement keep it. Returns the anchored ids.
+ */
+export declare function anchorSurroundings(source: SourceDoc, drawn: Scene, edited: string[]): string[];
+/**
+ * Let the automatic recipe rearrange a group again: remove soft refinements for everything inside
+ * it (pins and sizes stay), and anchor what is around it so the rest of the drawing holds.
+ */
+export declare function reflowGroup(source: SourceDoc, scene: Scene, groupId: string): number;
+/**
+ * Objects that moved between two compiled versions although no changed statement mentions them
+ * (or a container of theirs). Only the outermost moved object of a subtree is listed.
+ */
+export declare function movedOutsideEdit(previous: Scene, next: Scene, previousSource: SourceDoc, nextSource: SourceDoc): string[];

package/dist/types/src/editor/Editor.d.ts

@@ -0,0 +1,6 @@
+import { type CanvasProps } from '../components/canvas/Canvas';
+import type { DiagramSession } from '../state/session';
+/** One live diagram: the canvas for `session`. A page can show any number of them. */
+export declare function Editor(props: CanvasProps & {
+    session: DiagramSession;
+}): import("solid-js").JSX.Element;

package/dist/types/src/editor/element.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `<draft-editor>`: the editor as a custom element, for any framework or plain HTML. Its `source`
+ * attribute or property sets the text; every kept edit fires `draft-change` with the new text.
+ * It mounts when added to the page and stops its session when removed.
+ */
+import { type MountedEditor } from './mount';
+export interface DraftEditorElement extends HTMLElement {
+    source: string;
+    readonly editor?: MountedEditor;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'draft-editor': DraftEditorElement;
+    }
+}

package/dist/types/src/editor/mount.d.ts

@@ -0,0 +1,23 @@
+import { type DiagramSession, type SessionOptions } from '../state/session';
+import '../styles/app.css';
+export interface MountOptions extends SessionOptions {
+    /** The `.draft` text to edit. */
+    source: string;
+    /** Receives the new text after every kept edit, undo and redo. */
+    onChange?: (source: string) => void;
+}
+export interface MountedEditor {
+    session: DiagramSession;
+    /** The text as the editor holds it now. */
+    source(): string;
+    /** Show text the host changed. Resolves once it is drawn. */
+    update(source: string): Promise<void>;
+    /** Remove the editor and stop its session. */
+    destroy(): void;
+}
+/**
+ * Edit one diagram inside `host`: the canvas with selection, dragging, inline editing and its
+ * shortcuts. Each edit is written back to the source and reported through `onChange`. Give the
+ * host a size; the canvas fills it.
+ */
+export declare function mountEditor(host: HTMLElement, options: MountOptions): MountedEditor;

package/dist/types/src/import/browser.d.ts

@@ -0,0 +1,3 @@
+import type { ImportResult } from './import-core';
+/** Convert a supported text diagram without changing the current document. */
+export declare function importBrowser(source: string, filename?: string): Promise<ImportResult>;

package/dist/types/src/import/detect.d.ts

@@ -0,0 +1,31 @@
+/** A bounded dispatcher, not a parser. Ambiguous plain text never becomes D2 by guess. */
+export type KnownFormat = 'native' | 'mermaid' | 'dot' | 'd2' | 'plantuml' | 'dbml' | 'nomnoml';
+export interface DetectedSource {
+    status: 'detected';
+    format: KnownFormat;
+    source: string;
+    via: 'explicit' | 'extension' | 'fence' | 'signature';
+    /** One-based source line where the extracted content begins. */
+    startLine: number;
+}
+export interface FencedSource {
+    format: KnownFormat;
+    source: string;
+    startLine: number;
+}
+export type Detection = DetectedSource | {
+    status: 'choose-fence';
+    blocks: FencedSource[];
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/** Focused conventional fences: <=3 leading spaces, backticks or tildes, closed.
+ * A Markdown document is never sent wholesale to a diagram parser.
+ * This intentionally does not implement every CommonMark container rule.
+ */
+export declare function fencedSources(text: string): FencedSource[];
+export declare function detectSource(source: string, options?: {
+    filename?: string;
+    format?: KnownFormat;
+}): Detection;

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

@@ -0,0 +1,3 @@
+import { type ImportResult } from './import-core';
+/** Convert DOT and verify the generated source before exposing it to callers. */
+export declare function importDot(source: string, title?: string): ImportResult;

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;