@draftably/editor 0.0.0-stage → 0.1.0

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/layout-edits.d.ts

@@ -0,0 +1,58 @@
+import type { Diagram, LayoutSettings, RoutingSettings } from '../model/types';
+import { type Scene } from './compile';
+import { type Fit, type SourceDoc, type Statement, type Word } from './syntax';
+export declare class UnstorableLayout extends Error {
+}
+/** The `layout` attributes for engine settings: the engine's own controls that differ from the defaults. */
+export declare function engineAttrs(settings: LayoutSettings): Array<[string, Word]>;
+/** The `layout` line a scope would get for these settings, or the reason it cannot. */
+export declare function recipeText(scope: string, settings: LayoutSettings): string;
+/** The scope's current `layout` line in `source`, or null when it uses the default recipe. */
+export declare function currentRecipe(source: string, scope: string): string | null;
+/** What a scope's `layout` line says about the drawing, as the Arrange panel shows it. */
+export interface LayoutShape {
+    /** The built-in recipe, or the engine when the line names one. */
+    recipe: string;
+    engine: boolean;
+    direction: 'auto' | 'right' | 'down';
+    fit: Fit | null;
+    gap: number | null;
+    fold: 'auto' | 'never';
+}
+export type ShapeChange = Partial<Pick<LayoutShape, 'direction' | 'fit' | 'gap' | 'fold'>> & {
+    /** Drop an engine for the scope's built-in recipe, keeping what the author said of the result. */
+    builtin?: boolean;
+};
+/** Read a scope's layout line. A scope without one uses the built-in recipe. */
+export declare function layoutShape(source: string, scope: string): LayoutShape;
+/**
+ * Change what a scope's `layout` line says, keeping its recipe or engine. A `row` or `column`
+ * states its direction by name, so it swaps with the other. Soft refinements inside the scope are
+ * removed so the new shape shows; the count is returned. With no change, that is all it does.
+ */
+export declare function setLayoutShape(source: SourceDoc, scene: Scene, scope: string, change: ShapeChange): number;
+/**
+ * Arrange `scope` with the engine in `settings`. Its `layout` line is replaced, keeping what the
+ * author said about the result: `fit`, `min-width`, `min-height` and `direction`, unless
+ * `direction` asks for another. Soft position refinements inside it are removed so the engine's
+ * arrangement shows. Pins, sizes and nested `layout` lines stay. Returns the number of
+ * refinements removed.
+ */
+export declare function setLayoutRecipe(source: SourceDoc, scene: Scene, scope: string, settings: LayoutSettings, direction?: 'right' | 'down'): number;
+/** The `routing` statement for router settings, or null when they are all defaults. */
+export declare function routingStatement(routing: RoutingSettings): Statement | null;
+/** Replace the file's router settings. Defaults are left out; all defaults removes the line. */
+export declare function setRouting(source: SourceDoc, routing: RoutingSettings): void;
+/** Why the position tools stop in a sequence. */
+export declare const LANES_HOLD = "A sequence keeps its lanes and rows, so layout tools have nothing to move.";
+/**
+ * Save a drawing that a layout pass, a timeline step or the brush produced. Such results depend
+ * on the drawing they started from, so they cannot be recomputed from a recipe; instead each
+ * object that moved gets a soft `stay` at its new position, relative to its parent.
+ *
+ * Groups are fitted to their contents first, as the compiler sizes them, so a group whose
+ * children moved left or up moves with them instead of clipping them. Pinned objects never move.
+ * Returns the ids that were given a position. A sequence draws from its lanes and rows, so it
+ * takes no positions.
+ */
+export declare function writeArrangement(source: SourceDoc, drawn: Scene, after: Diagram): string[];

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;

package/dist/types/src/dsl/source-edits.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Targeted changes to `.draft` source lines. Each helper changes, adds or removes whole statements
+ * so comments and unrelated statements are kept.
+ */
+import { bare, quoted, type SourceDoc, type SourceLine, type Statement, type Word } from './syntax';
+export declare const isStatement: (line: SourceLine) => line is Statement;
+export declare const statements: (doc: SourceDoc) => Statement[];
+export declare function statement(command: string, args: Word[], attrs?: Array<[string, Word]>): Statement;
+/** The `node` or `group` declaration of an object. */
+export declare const declaration: (doc: SourceDoc, id: string) => Statement | undefined;
+export declare const edgeStatement: (doc: SourceDoc, id: string) => Statement | undefined;
+export declare const layoutStatement: (doc: SourceDoc, scope: string) => Statement | undefined;
+export declare function getAttr(s: Statement, key: string): Word | undefined;
+/** Set or (with `undefined`) remove an attribute, keeping the order of the others. */
+export declare function setAttr(s: Statement, key: string, value: Word | undefined): void;
+export declare function removeWhere(doc: SourceDoc, test: (s: Statement) => boolean): void;
+/** Insert after the last statement that passes `near`, or at the end of the file. */
+export declare function insertAfter(doc: SourceDoc, s: Statement, near: (s: Statement) => boolean): void;
+/** Add a refinement statement to the refinements section, starting one when there is none. */
+export declare function addRefinement(doc: SourceDoc, s: Statement): void;
+/** Remove the positional refinements (`near`, `nudge`, `stay`, `pin`) for an object. */
+export declare const clearPosition: (doc: SourceDoc, id: string) => void;
+/**
+ * Every statement that mentions `id` as an object: refinements, edges and alignment lists. Its
+ * messages go with it, and they leave the phases and states that list them.
+ */
+export declare function removeReferences(doc: SourceDoc, id: string): void;
+/** Take an object or connection out of every `state` line; drop a line left with no IDs. */
+export declare function removeFromStates(doc: SourceDoc, id: string): void;
+/**
+ * Remove a connection and each mention of it, so its `phase`, `state` and `note` lines still
+ * compile. A phase left with no messages goes too; a comment on its line stays, on a line of its
+ * own.
+ */
+export declare function removeEdge(doc: SourceDoc, id: string): void;
+export declare const num: (n: number) => Word;
+export { bare, quoted };