@draftably/editor 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: ("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/lib/engine-tasks.d.ts

@@ -0,0 +1,88 @@
+import { type CandidateResult, type CandidateSpec, type ComparisonConfig } from '../engines/explorer-engine.js';
+import { type LayoutOptions, type LayoutResult } from '../engines/layout-engine.js';
+import { type Timeline } from '../engines/sculpt-engine.js';
+import { type RouteInput, type RoutingOptions, type RoutingResult } from '../engines/routing-engine.js';
+import { type Scene } from '../dsl/compile';
+import { type ViewState } from '../dsl/project';
+import type { Diagram } from '../model/types';
+export type EngineTask = {
+    kind: 'layout';
+    doc: Diagram;
+    options: LayoutOptions;
+} | {
+    kind: 'candidate';
+    baseline: Diagram;
+    spec: CandidateSpec;
+    config: ComparisonConfig;
+} | {
+    kind: 'timeline';
+    doc: Diagram;
+    options: LayoutOptions;
+}
+/** A diagram file variant, compiled exactly as the file would be. */
+ | {
+    kind: 'source';
+    source: string;
+    spec: CandidateSpec;
+}
+/** Full-quality routes for a drawing shown meanwhile with quick routes. */
+ | {
+    kind: 'route';
+    input: RouteInput;
+    options: RoutingOptions;
+}
+/** A diagram file compiled: laid out, not routed. */
+ | {
+    kind: 'compile';
+    source: string;
+}
+/** A diagram file compiled, projected with the editor's view and routed, as the viewer shows it. */
+ | {
+    kind: 'scene';
+    source: string;
+    view: ViewState;
+};
+/** A compiled file and its routes, keyed by the projected document they were drawn for. */
+export interface SceneResult {
+    scene: Scene;
+    fingerprint: string;
+    routing: RoutingResult;
+}
+export type EngineResult<T extends EngineTask> = T extends {
+    kind: 'layout';
+} ? LayoutResult : T extends {
+    kind: 'candidate' | 'source';
+} ? CandidateResult : T extends {
+    kind: 'route';
+} ? RoutingResult : T extends {
+    kind: 'scene';
+} ? SceneResult : T extends {
+    kind: 'compile';
+} ? Scene : Timeline;
+export declare function runEngineTask(task: EngineTask): Promise<LayoutResult | CandidateResult | Timeline | RoutingResult | SceneResult | Scene>;
+/**
+ * Run a short task in one worker that stays up, so frequent work such as recompiling a file after
+ * each edit pays no start-up cost. Without workers the task runs on the main thread.
+ */
+export declare function runShared<T extends EngineTask>(input: T): Promise<EngineResult<T>>;
+export declare class CancelledError extends Error {
+    constructor();
+}
+export interface RunningTask<T> {
+    promise: Promise<T>;
+    /** Stop the computation. The promise rejects with `CancelledError`. */
+    cancel(): void;
+    /** `worker`, or `main thread` when workers are unavailable. */
+    thread: () => string;
+}
+/** Computations to run at once: one core stays with the page. */
+export declare const poolSize: () => number;
+/** Call `work` for each index up to `count`, with at most `poolSize()` calls going at once. */
+export declare function inPool(count: number, work: (index: number) => Promise<void>): Promise<void>;
+/**
+ * Run an engine computation in a worker. If the browser blocks workers, the same computation
+ * runs on the main thread instead.
+ */
+export declare function startEngineTask<T extends EngineTask>(input: T, { timeout }?: {
+    timeout?: number;
+}): RunningTask<EngineResult<T>>;

package/dist/types/src/lib/font-data.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The bundled diagram fonts as data URLs, for SVG exports that must render without the app.
+ * The browser loads this module only when exporting; the CLI bundles it.
+ */
+import type { ResolvedAppearance } from '../model/appearance';
+/** `@font-face` rules for the faces an appearance draws with. */
+export declare function fontFaceCss(look: ResolvedAppearance): string;
+/** Make the bundled faces available to the page, so the canvas draws with measured fonts. */
+export declare function registerFonts(): void;

package/dist/types/src/lib/saved-diagram.d.ts

@@ -0,0 +1,4 @@
+/** Where the editor keeps the browser's diagram. The site reads it too: same origin. */
+export declare const STORAGE_KEY = "diagram-studio-v5";
+/** The title of the diagram kept in this browser, if there is one. */
+export declare function savedTitle(): string;

package/dist/types/src/lib/scene-cache.d.ts

@@ -0,0 +1,4 @@
+/** The compiled file stored for `source` by this build, if any. */
+export declare function cachedScene<T>(source: string): Promise<T | undefined>;
+/** Store the compiled file for `source`, keeping the most recently stored few. */
+export declare function cacheScene(source: string, value: unknown): Promise<void>;

package/dist/types/src/lib/svg-export.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deep-copy an SVG subtree with computed styles inlined and editor-only parts removed. An object
+ * with a link (`data-href`) is wrapped in `<a>`, its target written by `href`. The source element
+ * must be attached to the document.
+ */
+export declare function materializeSvg<T extends SVGElement>(original: T, href?: (href: string) => string): T;
+export declare const serializeSvg: (node: Node) => string;
+export declare function createSvgElement<K extends keyof SVGElementTagNameMap>(tag: K, attrs?: Record<string, string | number>): SVGElementTagNameMap[K];
+export declare const escapeXml: (value: unknown) => string;
+export declare function downloadBlob(blob: Blob, name: string): void;
+/** A download name from the diagram's title: `My plan` → `my-plan.svg`. */
+export declare function fileName(title: string, extension: string): string;
+export declare const downloadText: (text: string, name: string, type: string) => void;
+/** Rasterize an SVG string at `scale` (2× unless given), within browser canvas limits. */
+export declare function svgToPng(svg: string, scale?: number): Promise<Blob>;