reladraw 0.16.0 → 0.17.0

package/dist/ast.d.ts

@@ -40,6 +40,12 @@ export declare const SIDE_AXIS: Record<Side, Axis>;
 export declare const POSITIONS: readonly ["top-left", "top-center", "top-right", "left-center", "center", "right-center", "bottom-left", "bottom-center", "bottom-right"];
 export type Position = (typeof POSITIONS)[number];
 export declare function isPosition(word: string): word is Position;
+/**
+ * For a missing name like `bin.left`, whose last part is a side or a point:
+ * the hint that the part is a separate word after the box's full name,
+ * `host.bin left`. `names` is every box's name; empty when there is no such box.
+ */
+export declare function partWordHint(name: string, names: Iterable<string>): string;
 /**
  * A part of a node that a placement may name: its text, one of its four sides,
  * or one of its nine points. Written as a separate word after the node's name
@@ -88,7 +94,69 @@ export declare const BOUNDARY_PARTS: readonly string[];
 export interface PlacementTarget {
     name: string;
     part?: Part;
+    /**
+     * How far along a side, or across the whole box: `server 3/4 down`,
+     * `3/4 down server` (design.org 4.7, 5.2). With a side, it is one point on
+     * that side; without, a line through the box on the fraction's axis.
+     */
+    fraction?: Fraction;
+    /** A point written out rather than named: `between a and b`, `down from a and left from b`, `2 below c bottom`. */
+    point?: PointExpr;
+}
+/**
+ * A fraction of the way along: `3/4 down` and `1/4 up` run along a left or
+ * right side, `1/3 across` along a top or bottom one, counted from the left
+ * unless it says `from right`.
+ */
+export interface Fraction {
+    value: number;
+    along: 'down' | 'up' | 'across';
+    from?: 'left' | 'right';
+    /** As written, to quote back: `3/4 down`, `1/3 across from right`. */
+    written: string;
+    /** Written before the name (`3/4 down x`) rather than after it (`x 3/4 down`). */
+    first?: boolean;
 }
+/** The axis a fraction measures along. */
+export declare function fractionAxis(fraction: Fraction): Axis;
+/** The words that start a line from a thing, in `down from a and left from b`. */
+export declare const WAYS: readonly ["up", "down", "left", "right"];
+export type Way = (typeof WAYS)[number];
+/**
+ * A point said in words (design.org 4.2–4.4). Every one is worked out from
+ * named things, so moving them moves it.
+ */
+export type PointExpr = {
+    kind: 'between';
+    a: PlacementTarget;
+    b: PlacementTarget;
+    /** `at 1/3`: that far across the gap, measured from `a`. Absent is halfway. */
+    at?: number;
+    atWritten?: string;
+    /** `(span: both)`: as a region, the gap stretched over both boxes on the other axis. */
+    span?: 'both';
+} | {
+    kind: 'from';
+    /**
+     * The line giving the point its place across or up and down, in the
+     * order written. `even` is `even with x`: the level line through x,
+     * which says no way the point lies from it.
+     */
+    lines: [{
+        way: Way | 'even';
+        target: PlacementTarget;
+    }, {
+        way: Way | 'even';
+        target: PlacementTarget;
+    }];
+} | {
+    kind: 'moved';
+    distance: string;
+    direction: Direction;
+    from: PlacementTarget;
+};
+/** A point written out, as the author would write it. */
+export declare function describePoint(point: PointExpr): string;
 /**
  * Naming more than one target places the node against the box that just bounds
  * them all — `right of borg and bare` clears both. It is a single target that
@@ -121,6 +189,16 @@ export interface OffsetPlacement {
      * that does not say. Absent means take the node's.
      */
     gap?: string;
+    /**
+     * `3 below and 2 right of a`: a different distance on each axis, which
+     * stands in for `gap` (design.org 5.2).
+     */
+    gaps?: Partial<Record<Axis, string>>;
+    /**
+     * `center 12 right of a center`: the part of this box the distance is
+     * measured from, rather than its facing side (design.org 5.2).
+     */
+    own?: Part;
     line: number;
 }
 /** `level with docker` — share a side or a center line, with no gap in between. */
@@ -181,6 +259,17 @@ export declare const PLACEMENT_KEYS: readonly ["gap"];
  * range against each other.
  */
 export declare const CONTENTS_KEYS: readonly ["widths", "align"];
+/**
+ * What `layout: column (…)` and `layout: row (…)` take in their bracket.
+ * `align` is read only to be refused by name: it now means where along a side,
+ * and lining the children up is `align-children`.
+ */
+export declare const LAYOUT_KEYS: readonly ["gap", "widths", "align-children", "align", "centers", "heights"];
+/**
+ * Where `gather-children:` puts a container's children in its spare room: a
+ * side, a corner, or the middle.
+ */
+export declare const GATHER_PLACES: readonly ["center", "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"];
 /**
  * What `widths:` may say. `natural` is the default and is today's behavior.
  * `match` is what `align: widths` did — every child as wide as the widest.
@@ -189,12 +278,14 @@ export declare const CONTENTS_KEYS: readonly ["widths", "align"];
  */
 export declare const CONTENT_WIDTHS: readonly ["natural", "match", "fill"];
 /**
- * Where the block of contents sits when it is narrower than the band. `right`
- * is accepted although no diagram has yet wanted it: refusing it would give
- * `align:` a different value set depending on which bracket it is in, which is
- * the divergence this scheme exists to remove.
+ * How `align-children:` lines laid-out children up with each other: in a
+ * column their left edges, middles or right edges; in a row their tops,
+ * middles or bottoms.
  */
-export declare const CONTENT_ALIGNMENTS: readonly ["left", "center", "right"];
+export declare const CHILD_ALIGNMENTS: {
+    readonly column: readonly ["left", "center", "right"];
+    readonly row: readonly ["top", "center", "bottom"];
+};
 /** How a placement reads back in the author's own words, for error messages. */
 export declare function describePlacement(placement: Placement): string;
 /** "borg", "hub text", "borg and bare" — as the author would write them. */
@@ -247,13 +338,15 @@ export declare const TEXT_KEYS: readonly ["color", "size", "wrap", "align", "at"
  * it goes in one bracket, as the text's do. `line: red` stays as the short form
  * of `line: (color: red)`, and both are stored under the bare `line` key.
  */
-export declare const LINE_KEYS: readonly ["color", "path", "corners", "crossing", "pattern", "thickness"];
+export declare const LINE_KEYS: readonly ["color", "path", "corners", "crossing", "pattern", "thickness", "curve", "turn", "step-out"];
 /**
  * The words each of the line's properties takes, the default first. Thickness
- * takes a plain number of pixels as well.
+ * takes a multiple of normal (`2`) or pixels (`3px`) as well. `turn:` takes a fraction and
+ * `step-out:` a distance, so neither has a list.
  */
 export declare const LINE_VALUES: {
-    readonly path: readonly ["curved", "square", "straight"];
+    readonly path: readonly ["straight", "square", "curved"];
+    readonly curve: readonly ["normal", "strong", "subtle"];
     readonly corners: readonly ["sharp", "rounded"];
     readonly crossing: readonly ["gap", "none", "arc", "square"];
     readonly pattern: readonly ["solid", "dashed", "dotted", "dash-dot"];
@@ -271,9 +364,13 @@ export interface NodeStmt {
     statedText: boolean;
     /** The text's bracketed modifiers, as written. Usually empty. */
     textAttrs: Attrs;
+    /** Placements in the text's bracket, against the box's own children (design.org 7.2). */
+    titlePlacements?: Placement[];
     /** Everything the author said about where this goes. Empty for the anchor. */
     placements: Placement[];
     attrs: Attrs;
+    /** `guide node frame ""`: does everything a node does except draw (design.org 8.1). */
+    guide?: boolean;
     line: number;
 }
 /**
@@ -290,6 +387,61 @@ export type Mark = (typeof MARKS)[number];
  * have none: nothing would explain itself, and `<>` is two arrows.
  */
 export declare const MARK_GLYPHS: Record<'from' | 'to', Record<string, Mark>>;
+/** A side of something, as a text's bracket names it: `above s1`, `right of edge`. */
+export type TextSide = 'above' | 'below' | 'left of' | 'right of';
+/**
+ * Where one text on a line sits, as its bracket says (design.org 7.3). Every
+ * field is optional: with nothing said the text shares the line with the
+ * other unplaced texts, spread evenly.
+ */
+export interface EdgeTextPlace {
+    /** `at: 1/4`, `at: 0.25`, `at: start`, `at: end`: a spot along the line, or along the leg `on` names. */
+    at?: number | 'start' | 'end';
+    /** `on: rise`: the named leg the text sits on. */
+    on?: string;
+    /** `on: longest level`: the line's longest piece running left to right, the first of two the same length. */
+    longestLevel?: boolean;
+    /** `straight right from c`: where a line that way from c's middle first meets this one. */
+    straight?: {
+        way: Way;
+        target: PlacementTarget;
+        written: string;
+    };
+    /**
+     * `above s1`, `2 above s1`: a gap from the box, centered on it the other way, as a box
+     * placed so would be; with `onLine`, where the line first reaches that height or position across.
+     */
+    by?: {
+        side: TextSide;
+        target: PlacementTarget;
+        written: string;
+    };
+    /** `on the line`: a text placed by a box stays on its line (design.org 7.3). */
+    onLine?: boolean;
+    /** `right of edge`: moved clear of the part of the line it landed on. */
+    beside?: TextSide;
+    /**
+     * `left even with x right`: one axis set by a box, at most one per axis; the
+     * other stays where the text would otherwise sit (design.org 7.3).
+     */
+    even?: {
+        placement: AlignPlacement;
+        written: string;
+    }[];
+    /** `gap:` — from the node, for `at: start`/`end` and a text placed by a box. */
+    gap?: string;
+    /** `edge-gap:` — off the line, for a text beside it. */
+    edgeGap?: string;
+    /** `reads: up`, `down` or `along`. */
+    reads?: 'up' | 'down' | 'along';
+}
+/** One text on a line: what it says, how it looks, where it sits. */
+export interface EdgeTextStmt {
+    text: string;
+    /** `color:`, `size:`, `wrap:` from its bracket. */
+    textAttrs: Attrs;
+    place: EdgeTextPlace;
+}
 /** The marks written in an edge's arrow, by end. An end with none written is absent. */
 export interface EdgeMarks {
     from?: Mark;
@@ -304,9 +456,8 @@ export interface EdgeStmt {
     arrow: string;
     /** The marks the arrow writes at each end: `->` is an arrow at `to`, `<-` one at `from`. */
     marks: EdgeMarks;
-    text?: string;
-    /** The text's bracketed modifiers, as written. Usually empty. */
-    textAttrs: Attrs;
+    /** `"1" (at: start) "places" "many" (at: end)`: each text in written order, with its own bracket (design.org 7.3). */
+    texts: EdgeTextStmt[];
     /** `between desktop1 and laptop1` — the gap the line passes through. */
     between?: Passage;
     /**
@@ -316,9 +467,162 @@ export interface EdgeStmt {
      * line is passing, as `between` does. Always `kind: 'offset'` with no gap.
      */
     passes?: OffsetPlacement[];
+    /** `edge req client -> api`: the line's own name. */
+    name?: string;
+    /** `straight down`: the line leaves its start that way and stops at what it meets (design.org 6.2). */
+    straight?: Way;
+    /** `to: left, even with cat1`: what each end is even with, on the side its `from:`/`to:` names (6.2). */
+    evenWith?: {
+        from?: PlacementTarget[];
+        to?: PlacementTarget[];
+    };
+    /** `via: b top, between c and d, leg climb`: the places the line passes, in order (design.org 6.4). */
+    via?: ViaEntry[];
+    /** `edge each child of a -> b`: the end whose name is a container, one line per direct child of it (design.org 6.6). */
+    each?: 'from' | 'to';
+    /** `edge a -> b, c, d`: the end written as a list, and every name in it, one line to each (design.org 6.6). */
+    several?: {
+        side: 'from' | 'to';
+        names: string[];
+    };
     attrs: Attrs;
+    /** `guide edge a -> b`: shapes nothing differently, and is drawn only when guides are shown. */
+    guide?: boolean;
     line: number;
 }
+/** One place a line passes (design.org 6.4). */
+export type ViaStop = {
+    /**
+     * `b top`, `server right 3/4 down`, `proxy`, `between c and d`, a named
+     * point or region: anything section 4 names. A part of a box is just
+     * outside it unless `on` or `inside` says otherwise.
+     */
+    kind: 'place';
+    target: PlacementTarget;
+    mode: 'outside' | 'on' | 'inside';
+    gap?: string;
+    /** `via: trunk (after: z)`: this line's place in a bundle's order, which only a bundle has. */
+    order?: {
+        way: 'after' | 'before';
+        name: string;
+    };
+    written: string;
+} | {
+    /** `via: trunk`: the whole length of a bundle, in this line's lane (6.6). Read from a place naming a bundle. */
+    kind: 'bundle';
+    bundle: string;
+    order?: {
+        way: 'after' | 'before';
+        name: string;
+    };
+    written: string;
+} | {
+    kind: 'through';
+    region: string;
+    axis: 'horizontal' | 'vertical';
+    written: string;
+} | {
+    kind: 'alongside';
+    way: 'above' | 'below' | 'left of' | 'right of';
+    leg: string;
+    gap?: string;
+    written: string;
+} | {
+    /** `req at 1/3`, `req start`, `req end`, or a bare `req`, its middle: a point on a named line or leg. */
+    kind: 'online';
+    line: string;
+    at: number | 'start' | 'end';
+    /** `req b top`: the middle of where req runs along one of its own stops, written as that stop. */
+    along?: string;
+    written: string;
+};
+/** An entry in a `via:` list: a stop, a leg's name, or a leg's name and the run it names. */
+export interface ViaEntry {
+    leg?: {
+        name: string;
+        attrs: Attrs;
+    };
+    stop?: ViaStop;
+}
+/** A stop written as the author would write it. */
+export declare function describeStop(stop: ViaStop): string;
+/**
+ * `point funnel  between c2 and api at 2/3` — a point with a name, so several
+ * things can use it and moving it is one edit (design.org 4.5). Drawn as a dot.
+ */
+/**
+ * A point's or a region's text and its bracket (design.org 7.4). `place` holds
+ * the position words: a direction from the dot (`above-right`), or a side as a
+ * title says it (`outside top`).
+ */
+export interface MarkText {
+    text: string;
+    textAttrs: Record<string, string>;
+}
+export interface PointStmt {
+    kind: 'point';
+    name: string;
+    point: PlacementTarget;
+    text?: MarkText;
+    attrs: Attrs;
+    guide?: boolean;
+    line: number;
+}
+/**
+ * `region r  c bottom-left to d top-right`, or `region r  between a and b` —
+ * a rectangle with a name and every part a box has (design.org 4.5). It
+ * bounds things without owning them, and is drawn as a tint (8.3).
+ */
+export interface RegionStmt {
+    kind: 'region';
+    name: string;
+    /** The two corners, in either order; or one `between`, which is a region of its own. */
+    corners: [PlacementTarget, PlacementTarget] | [PlacementTarget];
+    text?: MarkText;
+    attrs: Attrs;
+    guide?: boolean;
+    line: number;
+}
+/**
+ * `bundle trunk  via: through slot horizontal`: a shared path several lines
+ * travel together, built like a line with no ends (design.org 6.6). A line
+ * joins it with `via: trunk` and runs its whole length.
+ */
+export interface BundleStmt {
+    kind: 'bundle';
+    name: string;
+    /** A path out in space. A bundle has this or `between`, never both. */
+    via?: ViaEntry[];
+    /**
+     * `bundle calls  a -> b`: between two boxes, the direct way unless its
+     * `from:`, `to:` or `line: (path: …)` route it as one line would go.
+     */
+    between?: [string, string];
+    /**
+     * `layout: parallel (gap: tight)`, the default; `layout: collapsed`, a bus;
+     * or, between two boxes only, `layout: fan`, lanes widest apart at the middle.
+     */
+    arrangement: 'parallel' | 'collapsed' | 'fan';
+    /** The gap between neighboring members of a parallel bundle, as written. */
+    gap?: string;
+    /** `order: y, z, x`: every member, in reading order across where the bundle starts. */
+    order?: string[];
+    /**
+     * `line:`, `from-mark:`, `to-mark:`: how a collapsed bundle's shared stretch
+     * is drawn; between two boxes, `from:`, `to:` and `line: (path: …)` route it.
+     */
+    attrs: Attrs;
+    line: number;
+}
+/** What a bundle may say besides `via:`, `layout:` and `order:`. */
+export declare const BUNDLE_KEYS: readonly ["via", "layout", "order", "line", "from-mark", "to-mark", "from", "to"];
+/** What a point and a region may say. A region's padding pushes every edge out. */
+export declare const POINT_KEYS: readonly ["style", "fill", "depth"];
+/** Which way from its dot a point's text sits (design.org 7.4); the first is the default. */
+export declare const POINT_TEXT_SIDES: readonly ["above", "below", "left", "right", "above-right", "above-left", "below-right", "below-left"];
+/** What a point's or a region's text takes in its bracket besides its position words. */
+export declare const MARK_TEXT_KEYS: readonly ["color", "size", "wrap", "align", "reads", "gap"];
+export declare const REGION_KEYS: readonly ["style", "fill", "opacity", "border", "padding", "padding-top", "padding-right", "padding-bottom", "padding-left", "depth"];
 /**
  * `diagram background: #111111` — settings that belong to the drawing as a
  * whole rather than to anything in it. It has no name because there is only
@@ -333,8 +637,10 @@ export interface DiagramStmt {
  * The attributes a `diagram` statement understands. `text` takes a bracket,
  * `text: (color: …)`, and sets the text color of everything at once — the
  * theme has one text color, shared by nodes and edges, and this is that.
+ * `checks` takes a bracket too, `checks: (edge-crossings: on)`, turning kinds
+ * of finding on or off by name.
  */
-export declare const DIAGRAM_KEYS: readonly ["theme", "background", "text"];
+export declare const DIAGRAM_KEYS: readonly ["theme", "background", "text", "checks", "guides"];
 /**
  * `default leaf  fill: #2e5d3a` — a style that applies to every thing of one
  * kind without being named. The more specific wins: `node` covers every node,
@@ -347,7 +653,7 @@ export interface DefaultStmt {
     attrs: Attrs;
     line: number;
 }
-export declare const DEFAULT_TARGETS: readonly ["node", "leaf", "container", "edge"];
+export declare const DEFAULT_TARGETS: readonly ["node", "leaf", "container", "edge", "guide node", "guide edge", "guide point", "guide region"];
 export type DefaultTarget = (typeof DEFAULT_TARGETS)[number];
 /**
  * What each default may say. A default carries a style's vocabulary, less the
@@ -355,10 +661,12 @@ export type DefaultTarget = (typeof DEFAULT_TARGETS)[number];
  *
  * - A default names its kind, so it is strict where a style is permissive —
  *   `default edge  fill:` can only be a mistake.
- * - `badge:` gives a box a child, which makes it a container, so every leaf
- *   given one by `default leaf` or `default node` would stop being a leaf.
  * - `icon:` draws a picture, and a picture cannot hold children, so it is a
  *   leaf's word and not a container's or every node's.
+ * - `heading:` names one node's own child, so it belongs to that node alone.
+ *
+ * `badge:` is every kind's: it makes the picture part of the label, a heading,
+ * and a heading doesn't make a leaf a container.
  */
 export declare const DEFAULT_KEYS: Record<DefaultTarget, readonly string[]>;
 /**
@@ -414,8 +722,8 @@ export type Kind = 'shape' | 'icon' | 'none' | 'edge';
  * The exclusions are the whole of what this table decides, and each is a place
  * the old silence hid something:
  *
- * - A node drawn as a picture, or with no body at all, takes no `fill:` or
- *   `border:`. There is no outline for either to reach.
+ * - A node drawn as a picture, or with no body at all, takes no `fill:`,
+ *   `border:` or `corners:`. There is no outline for any of them to reach.
  * - Neither of those takes `contents:` either, which says how a node's children
  *   sit, and neither may have any.
  * - `shape:` and `icon:` each name the body, so each appears only on the kind it
@@ -424,7 +732,23 @@ export type Kind = 'shape' | 'icon' | 'none' | 'edge';
  * - An edge takes no `gap:` or `overlap:`. Those are about where a box sits, and
  *   an edge is not placed — it joins two things that are.
  */
+/** The keys that state a size; `size.ts` reads their values. */
+export declare const SIZE_KEY_NAMES: readonly ["width", "height", "min-width", "max-width", "min-height", "max-height"];
+/** `padding-right: 4`: one side's padding, over `padding:` on that side. */
+export declare const PADDING_SIDES: readonly ["top", "right", "bottom", "left"];
+export declare const PADDING_SIDE_KEYS: string[];
+/** `right-edge-order: ae, ad, ac`: the lines on one side of a box, in reading order. */
+export declare const EDGE_ORDER_KEYS: readonly ["top-edge-order", "bottom-edge-order", "left-edge-order", "right-edge-order"];
 export declare const ATTR_KEYS: Record<Kind, readonly string[]>;
+/**
+ * What a node's `corners:` takes, the default first: a box is drawn rounded
+ * unless it says otherwise. The same word and values as a line's `corners:`,
+ * whose default is the other one. It applies to every outline with corners — a
+ * rectangle and a document, whose fold stays as it is — and changes only the
+ * drawing, never where anything sits.
+ */
+export declare const NODE_CORNERS: readonly ["rounded", "sharp"];
+export type NodeCorners = (typeof NODE_CORNERS)[number];
 /**
  * Every word that is an attribute *somewhere*, which is what separates a
  * misspelling from a key written on the wrong kind of thing. The two deserve
@@ -458,7 +782,7 @@ export interface IconStmt {
     pasted: boolean;
     line: number;
 }
-export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt | IconStmt;
+export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt | IconStmt | PointStmt | RegionStmt | BundleStmt;
 export interface Document {
     statements: Stmt[];
 }