reladraw 0.1.0 → 0.3.0

package/dist/ast.d.ts

@@ -7,13 +7,88 @@ export type Direction = (typeof DIRECTIONS)[number];
 export declare function isDirection(word: string): word is Direction;
 export type Axis = 'x' | 'y';
 /**
- * Which edge of the target a `level with` shares. `centre` is the plain form;
+ * Which side of the target a `level with` shares. `center` is the plain form;
  * the rest are written in front of it, as in `top level with media`.
  */
-export declare const EDGES: readonly ["centre", "top", "bottom", "left", "right"];
-export type Edge = (typeof EDGES)[number];
-/** An edge belongs to one axis, so an alignment never has to say which. */
-export declare const EDGE_AXIS: Record<Edge, Axis>;
+export declare const SIDES: readonly ["center", "top", "bottom", "left", "right"];
+export type Side = (typeof SIDES)[number];
+/** A side belongs to one axis, so an alignment never has to say which. */
+export declare const SIDE_AXIS: Record<Side, Axis>;
+/**
+ * The nine points of a box anybody can name without measuring: the four
+ * corners, the four side midpoints, and the center. One closed set, accepted
+ * everywhere the language has a position — which is the rule that replaced a
+ * scatter of one-position slots, each decided on its own and each a little
+ * piece of the same expressiveness loss.
+ *
+ * Closed-and-meaningful is allowed where open-and-ordinal is not: these are
+ * words a reader decodes, and a diagram written in them still moves correctly
+ * when a box moves, which is the property the refusal of `x: 140` protects.
+ *
+ * A compound position is hyphenated and is one token, matching the diagonal
+ * directions above. A *phrase* of separate keywords stays spaced (`level
+ * with`); a compound *word* does not.
+ *
+ * Every midpoint carries `-center` rather than standing alone as `top` or
+ * `left`. Two reasons, and the second is the binding one. A side midpoint reads
+ * as "the bottom edge, centered along it", which is what the word says. And
+ * `top`, `bottom`, `left` and `right` already name a *side* in this language —
+ * an edge's `from:` and an alignment's `top level with` — so a bare `bottom`
+ * would mean a side in one place and a point in another. `from: bottom` spreads
+ * attachments along the side; `from: bottom-center` will pin one to the point.
+ */
+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;
+/**
+ * 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
+ * — `hub text`, `server right`, `board top-right`.
+ *
+ * No noun is carried. `board right side` was considered and dropped, because
+ * the language already tells a segment from a point by *spelling*: a bare
+ * `top` names a side everywhere (`from: bottom`, `top level with`) and a
+ * hyphenated `top-right` names a point, which is exactly why every midpoint
+ * carries `-center` rather than standing alone. A noun would mark with a word
+ * a distinction the hyphen already marks.
+ *
+ * The spaced form needs no reservation against a child called `text`: a
+ * sibling is always written dotted (`right of server.mirror`), so `hub text`
+ * spaced can never be `hub.text`. The dotted spelling was rejected because it
+ * interferes with the dot's one meaning.
+ */
+export declare const PART_SIDES: readonly ["top", "bottom", "left", "right"];
+export type PartSide = (typeof PART_SIDES)[number];
+export declare const PARTS: readonly ["text", "top", "bottom", "left", "right", "top-left", "top-center", "top-right", "left-center", "center", "right-center", "bottom-left", "bottom-center", "bottom-right"];
+export type Part = (typeof PARTS)[number];
+export declare function isPart(word: string): word is Part;
+/**
+ * Which way "toward the box's center" points from a part. This is the whole of
+ * what `inside` and `outside` mean, which is why neither needs a table of its
+ * own: `inside` is this direction, `outside` is its opposite, and one rule
+ * covers every part.
+ *
+ * `center` and `text` are absent on purpose. Neither is on the boundary, so
+ * there is no direction toward the interior from them, and both are refused by
+ * name where the shorthand is read.
+ */
+export declare const INWARD: Partial<Record<Part, Direction>>;
+/** The other way round, for `outside`. */
+export declare const OPPOSITE: Record<Direction, Direction>;
+/** The parts `inside` and `outside` can be read from — everything on the boundary. */
+export declare const BOUNDARY_PARTS: readonly string[];
+/**
+ * One thing a placement is placed against: a node, or a part of a node.
+ *
+ * A part target is the one target that is an *extent* rather than a node, which
+ * is what it buys over naming a sibling — a column of children against a
+ * container's right edge is flush by that edge and commits to no row, and
+ * nothing anchored to a single node can say that.
+ */
+export interface PlacementTarget {
+    name: string;
+    part?: Part;
+}
 /**
  * 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
@@ -21,15 +96,23 @@ export declare const EDGE_AXIS: Record<Edge, Axis>;
  * several placements: two separate `level with` statements are two demands that
  * fight, while one naming two targets is a single demand about one region.
  */
-export type Targets = string[];
+export type Targets = PlacementTarget[];
 /**
- * `right of docker` — the node sits a gap beyond one of the target's edges.
+ * `right of docker` — the node sits a gap beyond one of the target's sides.
  * A direction rules out part of an axis rather than fixing a point, which is
  * what lets two of them bracket a node between two targets.
  */
 export interface OffsetPlacement {
     kind: 'offset';
     direction: Direction;
+    /**
+     * `inside` or `outside`, where the author wrote one of those instead of a
+     * direction. Both are shorthands whose expansion is *derived* rather than
+     * listed — inside is the direction from the named part toward the box's
+     * center, outside is away from it — so the direction above is the whole of
+     * their meaning and this only remembers the word, to quote back.
+     */
+    written?: 'inside' | 'outside';
     targets: Targets;
     /**
      * The gap this one placement asks for, from `(gap: wide)` written after the
@@ -40,11 +123,31 @@ export interface OffsetPlacement {
     gap?: string;
     line: number;
 }
-/** `level with docker` — share an edge or a centre line, with no gap in between. */
+/** `level with docker` — share a side or a center line, with no gap in between. */
 export interface AlignPlacement {
     kind: 'align';
     axis: Axis;
-    edge: Edge;
+    side: Side;
+    targets: Targets;
+    line: number;
+}
+/**
+ * `on hub top-right` — the node's center sits at the part's center, so a node
+ * on a corner straddles it.
+ *
+ * This is the one genuine addition beside `inside` and `outside`, and it is a
+ * both-axes center alignment the language did not have: `level with` gives the
+ * vertical and the edge alignments give whichever axis their edge belongs to,
+ * and there is no horizontal center alignment at all — so the only long form
+ * would need two new words rather than one. `centered on` was proposed and
+ * rejected: beside `inside` and `outside` the three read as a series and `on`
+ * is unmistakable.
+ *
+ * One target only, unlike the other two. It names an exact point of one box,
+ * and the box that bounds two things is not a box anybody drew.
+ */
+export interface OnPlacement {
+    kind: 'on';
     targets: Targets;
     line: number;
 }
@@ -52,19 +155,54 @@ export interface AlignPlacement {
  * One thing the author said about where a node goes. A node carries as many as
  * it needs; the resolver intersects them.
  */
-export type Placement = OffsetPlacement | AlignPlacement;
+export type Placement = OffsetPlacement | AlignPlacement | OnPlacement;
 /**
  * The modifiers a placement understands, in brackets after its targets. Refused
- * by name when unrecognised, for the reason `DIAGRAM_KEYS` are: a modifier that
+ * by name when unrecognized, for the reason `DIAGRAM_KEYS` are: a modifier that
  * silently does nothing looks like a bug in the tool rather than a typo.
  */
 export declare const PLACEMENT_KEYS: readonly ["gap"];
+/**
+ * `contents: (widths: match, align: center)` — how a container's children sit
+ * inside it. A container has a fill, a border, a title and its contents, and
+ * this is the one key that points at the last of them.
+ *
+ * Two properties, independent, which is why they are bracketed modifiers of one
+ * key rather than two keys side by side. The cross product has a live cell in
+ * every corner — *equal widths, ranged left, under a long title* is the case
+ * that proves it — so one token could never carry both. And they sit at
+ * different levels: `contents:` is a property of the node, `widths:` a property
+ * of the contents, which written as peers would read as two facts about the box
+ * when they are one about the box and one about its children.
+ *
+ * It replaced `align: widths`, which was a size operation wearing an
+ * alignment's name and had a one-element value set — a flag in a property's
+ * clothes. With it gone, `align` means one thing everywhere: how a text's lines
+ * range against each other.
+ */
+export declare const CONTENTS_KEYS: readonly ["widths", "align"];
+/**
+ * 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.
+ * `fill` is the whole content band, which is `match` wherever the contents set
+ * the container's width and the better answer wherever the title wins.
+ */
+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.
+ */
+export declare const CONTENT_ALIGNMENTS: readonly ["left", "center", "right"];
 /** How a placement reads back in the author's own words, for error messages. */
 export declare function describePlacement(placement: Placement): string;
-/** "borg", "borg and bare", "borg, bare and media" — as the author would write them. */
+/** "borg", "hub text", "borg and bare" — as the author would write them. */
 export declare function listTargets(targets: Targets): string;
+/** One target in the author's words: the node's name, and its part if it named one. */
+export declare function nameTarget(target: PlacementTarget): string;
 /**
- * `between computer1 and computer2` on a link — the gap it passes through.
+ * `between desktop1 and laptop1` on an edge — the gap it passes through.
  *
  * This is not a claim about the whole line. It binds only the stretch where the
  * line is actually passing the pair, and says nothing about where it goes
@@ -87,53 +225,59 @@ export declare function describeAxis(axis: Axis): string;
 /** `key: value` pairs trailing a statement. Values are always strings here. */
 export type Attrs = Record<string, string>;
 /**
- * What a label's brackets may say: `"Docker" (at: bottom, align: centre)`.
+ * What a text's brackets may say: `"Docker" (at: bottom-center, color: muted)`.
  *
- * They are bracketed onto the label rather than written among the node's
+ * They are bracketed onto the text rather than written among the node's
  * attributes for the same reason a gap is bracketed onto its placement — they
  * modify that one thing, and the brackets make the scope visible instead of
- * positional. `at` and `align` are independent: neither implies the other, and a
- * label at the bottom is an ordinary label that happens to be at the bottom.
+ * positional. What is left at the top level is then about the node itself:
+ * `shape`, `icon`, `fill`, `border`, `gap`, `overlap`, `style`.
+ *
+ * In a style, which has no string for a bracket to hang off, the bracket hangs
+ * off the key instead: `style synced  text: (color: muted)`.
+ *
+ * `at` and `align` are independent and neither implies the other. `at` is where
+ * the block of text sits in the node — one of the nine named positions — and
+ * `align` is how its lines range against each other once it is there.
  */
-export declare const LABEL_KEYS: readonly ["at", "align"];
-export interface BoxStmt {
-    kind: 'box';
+export declare const TEXT_KEYS: readonly ["color", "size", "wrap", "align", "at"];
+export interface NodeStmt {
+    kind: 'node';
     name: string;
     text: string;
-    /** The label's bracketed modifiers, as written. Usually empty. */
-    label: Attrs;
+    /**
+     * Whether that text was written, or is the name standing in for it. A node
+     * drawn as a picture takes no such default — see `buildTree` — and only this
+     * flag can tell `node cube_a` from `node cube_a "cube_a"`.
+     */
+    statedText: boolean;
+    /** The text's bracketed modifiers, as written. Usually empty. */
+    textAttrs: Attrs;
     /** Everything the author said about where this goes. Empty for the anchor. */
     placements: Placement[];
     attrs: Attrs;
     line: number;
 }
-export interface LinkStmt {
-    kind: 'link';
+export interface EdgeStmt {
+    kind: 'edge';
     from: string;
     to: string;
     /** `<->` rather than `->`. */
     both: boolean;
-    label?: string;
-    /** `between computer1 and computer2` — the gap the line passes through. */
+    text?: string;
+    /** The text's bracketed modifiers, as written. Usually empty. */
+    textAttrs: Attrs;
+    /** `between desktop1 and laptop1` — the gap the line passes through. */
     between?: Passage;
     attrs: Attrs;
     line: number;
 }
-export interface NoteStmt {
-    kind: 'note';
-    name: string;
-    text: string;
-    /** Everything the author said about where this goes. Empty for the anchor. */
-    placements: Placement[];
-    attrs: Attrs;
-    line: number;
-}
 export interface DeckStmt {
     kind: 'deck';
     /** The container to draw with offset copies behind it. */
     name: string;
-    /** One label per copy, back to front as written. */
-    labels: string[];
+    /** One text per copy, back to front as written. */
+    texts: string[];
     line: number;
 }
 /**
@@ -148,13 +292,88 @@ export interface DiagramStmt {
 }
 /** The attributes a `diagram` statement understands. */
 export declare const DIAGRAM_KEYS: readonly ["background"];
+/**
+ * The attributes whose value is a color rather than text. A color is written
+ * as the viewer will receive it and the renderer keeps no list of color words
+ * of its own, so there is nothing to check a value *against* — but quoting is
+ * the author saying "this is text", and an unquoted value cannot hold a space,
+ * so prose has to be quoted to get in at all. Refusing a quoted color is
+ * therefore the whole of what can be checked here, and it happens to be the
+ * mistake people actually make: `subtext: "medium-fine"` reads as the text
+ * that goes underneath, and was accepted and dropped in silence.
+ */
+export declare const COLOR_KEYS: readonly ["fill", "border", "line", "background"];
+/**
+ * A color attribute names the *part* it colors, and a part exists only on the
+ * kinds that have one. A node has a border and text; a note and a glyph body are
+ * text and nothing else; an edge is a line and its text.
+ *
+ * This table is what makes the words checkable. `border:` on a note is refused
+ * by name rather than ignored — the same rule as an unknown `diagram` key, and
+ * for the same reason: an attribute that silently does nothing looks like the
+ * tool being broken.
+ *
+ * Each entry is written the way the author would write it, since the text's is
+ * a bracket rather than a bare key, and this list is only ever quoted back.
+ *
+ * A style spanning kinds writes one key per kind — `border: #d2904e  line:
+ * #d2904e` — since a style contributes a part only to the kinds that have it.
+ * That is what replaced `stroke:`, which named no part and so could never be
+ * wrong, and which is why a node's text had no word of its own until now.
+ */
+export declare const COLOR_PARTS: Record<Kind, readonly string[]>;
+/**
+ * The four things an attribute can be written on. Three of them are nodes, and
+ * which one a node is, is what its body says: `shape:` draws an outline,
+ * `icon:` draws a picture, and `shape: none` draws neither. None of the three
+ * is a statement keyword — a node is a node — but each takes a different set of
+ * attributes, which is what makes it a kind here.
+ */
+export type Kind = 'shape' | 'icon' | 'none' | 'edge';
+/**
+ * Every attribute each kind understands. An attribute a kind has no use for is
+ * refused by name rather than dropped, the same rule as an unknown `diagram`
+ * key, a `PLACEMENT_KEYS` modifier or a color part — and for the same reason,
+ * which the color parts only closed one level down: a key that silently does
+ * nothing looks like the tool being broken rather than like a typo.
+ *
+ * The color entries repeat `COLOR_PARTS` and must agree with it. They are
+ * written out rather than spliced in because this table is the answer to "what
+ * may I write here", and a reader of it should not have to assemble the list
+ * from two places.
+ *
+ * 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.
+ * - 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
+ *   makes. `shape:` is on `none` as well, because `shape: none` is how that kind
+ *   is written in the first place.
+ * - 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.
+ */
+export declare const ATTR_KEYS: Record<Kind, readonly string[]>;
+/**
+ * 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
+ * different errors: one has no remedy but the spelling, the other has a real
+ * meaning somewhere else in the file.
+ *
+ * `DIAGRAM_KEYS` is in here so that `background:` on a node is understood to be
+ * a real word in the wrong place — that mistake wants to be pointed at `fill:`,
+ * not told the word does not exist.
+ */
+export declare const ALL_ATTR_KEYS: readonly string[];
 export interface StyleStmt {
     kind: 'style';
     name: string;
     attrs: Attrs;
     line: number;
 }
-export type Stmt = BoxStmt | LinkStmt | NoteStmt | DeckStmt | StyleStmt | DiagramStmt;
+export type Stmt = NodeStmt | EdgeStmt | DeckStmt | StyleStmt | DiagramStmt;
 export interface Document {
     statements: Stmt[];
 }