reladraw 0.1.0 → 0.3.0

package/dist/ast.js

@@ -16,41 +16,182 @@ export function isDirection(word) {
     return DIRECTIONS.includes(word);
 }
 /**
- * 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 const EDGES = ['centre', 'top', 'bottom', 'left', 'right'];
-/** An edge belongs to one axis, so an alignment never has to say which. */
-export const EDGE_AXIS = {
-    centre: 'y',
+export const SIDES = ['center', 'top', 'bottom', 'left', 'right'];
+/** A side belongs to one axis, so an alignment never has to say which. */
+export const SIDE_AXIS = {
+    center: 'y',
     top: 'y',
     bottom: 'y',
     left: 'x',
     right: 'x',
 };
+/**
+ * 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 const POSITIONS = [
+    'top-left',
+    'top-center',
+    'top-right',
+    'left-center',
+    'center',
+    'right-center',
+    'bottom-left',
+    'bottom-center',
+    'bottom-right',
+];
+export function isPosition(word) {
+    return POSITIONS.includes(word);
+}
+/**
+ * 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 const PART_SIDES = ['top', 'bottom', 'left', 'right'];
+export const PARTS = ['text', ...PART_SIDES, ...POSITIONS];
+export function isPart(word) {
+    return PARTS.includes(word);
+}
+/**
+ * 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 const INWARD = {
+    top: 'below',
+    bottom: 'above',
+    left: 'right',
+    right: 'left',
+    'top-left': 'below-right',
+    'top-center': 'below',
+    'top-right': 'below-left',
+    'left-center': 'right',
+    'right-center': 'left',
+    'bottom-left': 'above-right',
+    'bottom-center': 'above',
+    'bottom-right': 'above-left',
+};
+/** The other way round, for `outside`. */
+export const OPPOSITE = {
+    above: 'below',
+    below: 'above',
+    left: 'right',
+    right: 'left',
+    'above-left': 'below-right',
+    'above-right': 'below-left',
+    'below-left': 'above-right',
+    'below-right': 'above-left',
+};
+/** The parts `inside` and `outside` can be read from — everything on the boundary. */
+export const BOUNDARY_PARTS = Object.keys(INWARD);
 /**
  * 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 const PLACEMENT_KEYS = ['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 const CONTENTS_KEYS = ['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 const CONTENT_WIDTHS = ['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 const CONTENT_ALIGNMENTS = ['left', 'center', 'right'];
 /** How a placement reads back in the author's own words, for error messages. */
 export function describePlacement(placement) {
     const targets = listTargets(placement.targets);
+    if (placement.kind === 'on') {
+        return `on ${targets}`;
+    }
     if (placement.kind === 'align') {
-        const edge = placement.edge === 'centre' ? '' : `${placement.edge} `;
-        return `${edge}level with ${targets}`;
+        const side = placement.side === 'center' ? '' : `${placement.side} `;
+        return `${side}level with ${targets}`;
     }
+    const gap = placement.gap === undefined ? '' : ` (gap: ${placement.gap})`;
+    // `inside` and `outside` take no `of`, and are quoted back as the author
+    // wrote them — the derived direction is what they *mean*, not what they say.
+    if (placement.written)
+        return `${placement.written} ${targets}${gap}`;
     // "left of X" and "above X" are both good English; "above of X" is not.
     const joiner = placement.direction === 'above' || placement.direction === 'below' ? '' : 'of ';
-    const gap = placement.gap === undefined ? '' : ` (gap: ${placement.gap})`;
     return `${placement.direction} ${joiner}${targets}${gap}`;
 }
-/** "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 function listTargets(targets) {
-    if (targets.length <= 1)
-        return targets[0] ?? '';
-    return `${targets.slice(0, -1).join(', ')} and ${targets[targets.length - 1]}`;
+    const written = targets.map(nameTarget);
+    if (written.length <= 1)
+        return written[0] ?? '';
+    return `${written.slice(0, -1).join(', ')} and ${written[written.length - 1]}`;
+}
+/** One target in the author's words: the node's name, and its part if it named one. */
+export function nameTarget(target) {
+    return target.part === undefined ? target.name : `${target.name} ${target.part}`;
 }
 /** How the axis of a passage is written, and what it means. */
 export const PASSAGE_AXES = {
@@ -65,14 +206,105 @@ export function describeAxis(axis) {
     return axis === 'y' ? 'vertically' : 'horizontally';
 }
 /**
- * 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 const LABEL_KEYS = ['at', 'align'];
+export const TEXT_KEYS = ['color', 'size', 'wrap', 'align', 'at'];
 /** The attributes a `diagram` statement understands. */
 export const DIAGRAM_KEYS = ['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 const COLOR_KEYS = [
+    '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 const COLOR_PARTS = {
+    shape: ['fill:', 'border:', 'text: (color: …)'],
+    icon: ['text: (color: …)'],
+    none: ['text: (color: …)'],
+    edge: ['line:', 'text: (color: …)'],
+};
+/**
+ * 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 const ATTR_KEYS = {
+    shape: ['style', 'gap', 'overlap', 'contents', 'badge', 'shape', 'fill', 'border', 'text', 'url'],
+    icon: ['style', 'gap', 'overlap', 'icon', 'text', 'url'],
+    none: ['style', 'gap', 'overlap', 'shape', 'text', 'url'],
+    edge: ['style', 'from', 'to', 'line', 'text', 'url'],
+};
+/**
+ * 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 const ALL_ATTR_KEYS = [
+    ...new Set([...Object.values(ATTR_KEYS).flat(), ...DIAGRAM_KEYS]),
+];

package/dist/constants.d.ts

@@ -1,15 +1,16 @@
 /** Spacing and text sizes shared by the resolver and the renderer, so the two cannot drift. */
-import type { Attrs } from './ast.js';
+import type { Attrs, Position } from './ast.js';
 import type { Measurer } from './measure.js';
+import { type Line } from './text.js';
 /** Inside a box, between its border and its contents. */
 export declare const PAD = 14;
 /** Between stacked children of one container. */
 export declare const CHILD_GAP = 10;
-/** Between a container's own label and its first child. */
+/** Between a container's own text and its first child. */
 export declare const HEADER_GAP = 10;
 /**
  * How far each deck copy is offset behind the front face. It has to clear a
- * whole line of text plus the padding above it, or a copy's label is drawn and
+ * whole line of text plus the padding above it, or a copy's text is drawn and
  * then immediately covered by the copy in front of it.
  */
 export declare const DECK_STEP = 34;
@@ -28,7 +29,7 @@ export declare const GAPS: Record<string, number>;
  */
 export declare const SEPARATION_GAP: number;
 /**
- * Between two links meeting the same side of the same box. An author names a
+ * Between two edges meeting the same side of the same box. An author names a
  * side, never a point on it, so this is the tool keeping two attachments apart
  * rather than a distance anyone asked for — small, like `SEPARATION_GAP`, and
  * squeezed further if the side is too short to hold the whole group.
@@ -36,7 +37,7 @@ export declare const SEPARATION_GAP: number;
 export declare const ATTACH_STEP = 16;
 /** Kept clear at each end of a side, so an attachment never sits on a corner. */
 export declare const ATTACH_MARGIN = 10;
-/** How wide a link's line is drawn. */
+/** How wide an edge's line is drawn. */
 export declare const LINE_WIDTH = 1.6;
 /**
  * The arrowhead's length, in the `markerUnits="strokeWidth"` the marker is
@@ -50,44 +51,50 @@ export declare const ARROW_MARKER_WIDTH = 7;
  */
 export declare const ARROW_LENGTH: number;
 /**
- * Line left showing between a link's label and the box at that end of the
+ * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.
  *
  * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
  * Those two keep two things from touching, and the least distance that reads as
- * "not touching" is the right one. This one has something to show: a label sits
+ * "not touching" is the right one. This one has something to show: a text sits
  * in a knockout that erases the line behind it, so whatever is left either side
- * is the entire evidence that the label belongs to a link at all. At ten pixels
+ * is the entire evidence that the text belongs to an edge at all. At ten pixels
  * it did not read as a line — the seed diagram in the playground drew as a word
  * with a dash beside it — so it is the length of a run of line, not a margin.
  *
  * Say `gap:` if you want the corridor wider than its contents.
  */
-export declare const LABEL_CLEARANCE = 20;
+export declare const TEXT_CLEARANCE = 20;
 /**
- * How much room a link's label takes along one axis.
+ * How much room an edge's text takes along one axis.
  *
- * The knockout rectangle drawn behind a label is the text plus five either side,
+ * The knockout rectangle drawn behind a text is the text plus five either side,
  * so that rectangle, not the glyphs, is what must not overlap anything.
  *
- * Shared by the resolver, which widens a corridor to hold a label, and the
+ * Shared by the resolver, which widens a corridor to hold a text, and the
  * renderer, which spaces the lanes of a channel by it, so the two cannot
- * disagree about how much room a label needs. The two ask different questions of
- * it and both are right: the resolver measures *along* the run, so a link
- * travelling horizontally needs the label's width; the renderer measures *across*
- * the channel, so a link travelling horizontally down one needs its height.
+ * disagree about how much room a text needs. The two ask different questions of
+ * it and both are right: the resolver measures *along* the run, so an edge
+ * traveling horizontally needs the text's width; the renderer measures *across*
+ * the channel, so an edge traveling horizontally down one needs its height.
  */
-export declare function labelExtent(label: string, appearance: Attrs, axis: 'x' | 'y', measurer: Measurer, fontSize: number, line: number): number;
+export declare function textExtent(lines: Line[], textAttrs: Attrs, axis: 'x' | 'y', measurer: Measurer, fontSize: number, line: number): number;
 /**
- * An icon is two lines of the label tall, and that ratio is what makes it a
- * *label-sized* ornament rather than a picture with a size of its own. It is
+ * The widest of these lines, which is how wide the block of them is. Shared by
+ * the resolver, which sizes a node to hold its text, and the renderer, which
+ * places that block in the room the node gave it.
+ */
+export declare function widestLine(lines: Line[], measurer: Measurer, fontSize: number): number;
+/**
+ * An icon is two lines of the text tall, and that ratio is what makes it a
+ * *text-sized* ornament rather than a picture with a size of its own. It is
  * read off the reference, where the title lines run 25 pixels baseline to
  * baseline and the drive and machine glyphs are close to 50 tall. Deriving it
  * from the text also means an icon on a `size: small` node shrinks with it,
  * which is what anyone would expect and what a fixed pixel count would not do.
  */
 export declare const ICON_LINES = 2;
-/** Between the label column and the icon column beside it. */
+/** Between the text column and the icon column beside it. */
 export declare const ICON_GAP = 10;
 export declare const DEFAULT_FONT_SIZE = 14;
 /**
@@ -97,7 +104,7 @@ export declare const DEFAULT_FONT_SIZE = 14;
  * it says nothing about why one piece of text is smaller than another.
  *
  * `small` is sampled rather than chosen. In
- * `examples/reference/arch.png` the box and container labels run 25
+ * `examples/reference/arch.png` the box and container texts run 25
  * pixels baseline to baseline and every annotation runs 21, which is this
  * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
  * taken the other way, so the scale is symmetric about the document size.
@@ -108,35 +115,46 @@ export declare const TEXT_SIZES: Record<string, number>;
  * the room, and the renderer, which fills it, so the two cannot disagree about
  * how much room there is.
  */
-export declare function fontSizeFor(kind: string, appearance: Attrs, fontSize: number, line: number): number;
+export declare function fontSizeFor(kind: string, textAttrs: Attrs, fontSize: number, line: number): number;
 export declare const DEFAULT_MARGIN = 40;
 /**
- * Where a container's own label sits. Every container reserves a band for its
- * label and its icon; `at` says which end of the box that band is, and the
- * contents take what is left. `align` says how the text sits across it.
+ * Where a node's own text sits, and how its lines range once it is there.
+ *
+ * `at` names one of the nine positions of the box — the same closed set the
+ * overlay placement uses, and for the same reason: a box has nine points anyone
+ * can name without measuring, and a diagram written in them still moves
+ * correctly when a box moves. It replaced `top | bottom`, which was a slot: two
+ * of the nine handed out because those were the two somebody needed.
  *
- * The two are independent and neither implies the other. A label at the bottom
- * is an ordinary label that happens to be at the bottom — there is no kind of
- * label being named here and no second thing quietly coming along with the
- * first. An earlier version bundled them as `label: heading | caption`, which
- * read a position as though it were a meaning; a folded corner means "artifact
- * rather than process" and a reader decodes it, while "lower down" means only
- * lower down.
+ * The two halves are read independently, exactly as `overlaidAt` reads an
+ * overlay's. The vertical half says which end of the box the text's band sits
+ * at, and the contents of a container take the other end. The horizontal half
+ * says where the block of text sits across the room it is given.
  *
- * A leaf has no band — its label is centred in the box — so neither says
- * anything about one.
+ * `align` is a different question and stays one: a text of more than one line
+ * has lines of unequal length wherever the block sits, and how those range
+ * against each other is not where the block is. A container's lines default to
+ * ranged left and a leaf's to centered, which is why the fallback is a
+ * parameter.
  */
-export declare const LABEL_ENDS: readonly ["top", "bottom"];
-export type LabelEnd = (typeof LABEL_ENDS)[number];
-export interface LabelStyle {
-    /** Which end of the box the band sits at. */
-    at: LabelEnd;
-    /** How the text sits in the band, in the renderer's own vocabulary. */
+export interface TextStyle {
+    at: Position;
+    /** Which end of the box the text's band sits at, from `at`'s vertical half. */
+    end: 'top' | 'center' | 'bottom';
+    /** Where the block sits across the room, from `at`'s horizontal half. */
+    side: 'left' | 'center' | 'right';
+    /** How the lines range against each other, in the renderer's own vocabulary. */
     align: 'start' | 'middle' | 'end';
 }
 /**
- * Read a label's bracketed modifiers. Shared by the resolver, which offsets the
+ * Read a text's bracketed modifiers. Shared by the resolver, which offsets the
  * contents away from the band, and the renderer, which draws into it, so the two
  * cannot disagree about which end the band is at.
  */
-export declare function labelStyleFor(label: Attrs, line: number): LabelStyle;
+export declare function textStyleFor(attrs: Attrs, line: number, fallbackAlign?: 'start' | 'middle', fallbackAt?: Position): TextStyle;
+/**
+ * Where a leaf's text or badge starts vertically, given which end it sits at.
+ * Shared, because the resolver works out the text's box and the renderer draws
+ * it, and the two must not be able to disagree.
+ */
+export declare function leafTop(end: 'top' | 'center' | 'bottom', y: number, height: number, own: number): number;