reladraw 0.16.0 → 0.17.1

package/dist/ast.js

@@ -65,6 +65,23 @@ export const POSITIONS = [
 export function isPosition(word) {
     return POSITIONS.includes(word);
 }
+/**
+ * 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 function partWordHint(name, names) {
+    const dot = name.lastIndexOf('.');
+    if (dot < 0)
+        return '';
+    const part = name.slice(dot + 1);
+    if (!isPosition(part) && !PART_SIDES.includes(part) && part !== 'text')
+        return '';
+    const base = name.slice(0, dot);
+    const all = [...names];
+    const found = all.includes(base) ? [base] : all.filter((each) => each.endsWith(`.${base}`));
+    return found.length === 1 ? ` — a side or point is a separate word after the box's full name: ${found[0]} ${part}` : '';
+}
 /**
  * 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
@@ -124,6 +141,25 @@ export const OPPOSITE = {
 };
 /** The parts `inside` and `outside` can be read from — everything on the boundary. */
 export const BOUNDARY_PARTS = Object.keys(INWARD);
+/** The axis a fraction measures along. */
+export function fractionAxis(fraction) {
+    return fraction.along === 'across' ? 'x' : 'y';
+}
+/** The words that start a line from a thing, in `down from a and left from b`. */
+export const WAYS = ['up', 'down', 'left', 'right'];
+/** A point written out, as the author would write it. */
+export function describePoint(point) {
+    if (point.kind === 'between') {
+        const at = point.atWritten === undefined ? '' : ` at ${point.atWritten}`;
+        const span = point.span ? ' (span: both)' : '';
+        return `between ${nameTarget(point.a)} and ${nameTarget(point.b)}${at}${span}`;
+    }
+    if (point.kind === 'from') {
+        return point.lines.map((line) => `${line.way === 'even' ? 'even with' : `${line.way} from`} ${nameTarget(line.target)}`).join(' and ');
+    }
+    const of = /left|right/.test(point.direction) ? ' of' : '';
+    return `${point.distance} ${point.direction}${of} ${nameTarget(point.from)}`;
+}
 /**
  * The modifiers a placement understands, in brackets after its targets. Refused
  * by name when unrecognized, for the reason `DIAGRAM_KEYS` are: a modifier that
@@ -149,6 +185,17 @@ export const PLACEMENT_KEYS = ['gap'];
  * range against each other.
  */
 export const CONTENTS_KEYS = ['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 const LAYOUT_KEYS = ['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 const GATHER_PLACES = ['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.
@@ -157,12 +204,11 @@ export const CONTENTS_KEYS = ['widths', 'align'];
  */
 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.
+ * 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 const CONTENT_ALIGNMENTS = ['left', 'center', 'right'];
+export const CHILD_ALIGNMENTS = { column: ['left', 'center', 'right'], row: ['top', 'center', 'bottom'] };
 /** How a placement reads back in the author's own words, for error messages. */
 export function describePlacement(placement) {
     const targets = listTargets(placement.targets);
@@ -170,16 +216,28 @@ export function describePlacement(placement) {
         return `on ${targets}`;
     }
     if (placement.kind === 'align') {
-        const side = placement.side === 'center' ? '' : `${placement.side} `;
-        return `${side}level with ${targets}`;
+        const side = placement.side !== 'center' ? `${placement.side} ` : placement.axis === 'x' ? 'x ' : '';
+        return `${side}even 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)
+    if (placement.written) {
+        const gap = placement.gap === undefined ? '' : ` (gap: ${placement.gap})`;
         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 own = placement.own === undefined ? '' : `${placement.own} `;
+    if (placement.gaps) {
+        const y = placement.direction.startsWith('above') ? 'above' : 'below';
+        const x = placement.direction.endsWith('left') ? 'left' : 'right';
+        return `${own}${placement.gaps.y} ${y} and ${placement.gaps.x} ${x} of ${targets}`;
+    }
+    // A distance in front, and one in brackets, are the same thing; quoted in front when the part form needs it.
+    if (placement.own !== undefined && placement.gap !== undefined) {
+        return `${own}${placement.gap} ${placement.direction} ${joiner}${targets}`;
+    }
+    const gap = placement.gap === undefined ? '' : ` (gap: ${placement.gap})`;
     return `${placement.direction} ${joiner}${targets}${gap}`;
 }
 /** "borg", "hub text", "borg and bare" — as the author would write them. */
@@ -191,7 +249,12 @@ export function listTargets(targets) {
 }
 /** 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}`;
+    if (target.point)
+        return describePoint(target.point);
+    if (target.fraction?.first)
+        return `${target.fraction.written} ${target.name}`;
+    const named = target.part === undefined ? target.name : `${target.name} ${target.part}`;
+    return target.fraction ? `${named} ${target.fraction.written}` : named;
 }
 /** How the axis of a passage is written, and what it means. */
 export const PASSAGE_AXES = {
@@ -228,13 +291,15 @@ export const TEXT_KEYS = ['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 const LINE_KEYS = ['color', 'path', 'corners', 'crossing', 'pattern', 'thickness'];
+export const LINE_KEYS = ['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 const LINE_VALUES = {
-    path: ['curved', 'square', 'straight'],
+    path: ['straight', 'square', 'curved'],
+    curve: ['normal', 'strong', 'subtle'],
     corners: ['sharp', 'rounded'],
     crossing: ['gap', 'none', 'arc', 'square'],
     pattern: ['solid', 'dashed', 'dotted', 'dash-dot'],
@@ -256,29 +321,60 @@ export const MARK_GLYPHS = {
     from: { '<': 'arrow', '<|': 'oarrow', '*': 'dot', o: 'odot', '|': 'bar' },
     to: { '>': 'arrow', '|>': 'oarrow', '*': 'dot', o: 'odot', '|': 'bar' },
 };
+/** A stop written as the author would write it. */
+export function describeStop(stop) {
+    return stop.written;
+}
+/** What a bundle may say besides `via:`, `layout:` and `order:`. */
+export const BUNDLE_KEYS = ['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 const POINT_KEYS = ['style', 'fill', 'depth'];
+/** Which way from its dot a point's text sits (design.org 7.4); the first is the default. */
+export const POINT_TEXT_SIDES = ['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 const MARK_TEXT_KEYS = ['color', 'size', 'wrap', 'align', 'reads', 'gap'];
+export const REGION_KEYS = ['style', 'fill', 'opacity', 'border', 'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'depth'];
 /**
  * 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 const DIAGRAM_KEYS = ['theme', 'background', 'text'];
-export const DEFAULT_TARGETS = ['node', 'leaf', 'container', 'edge'];
+export const DIAGRAM_KEYS = ['theme', 'background', 'text', 'checks', 'guides'];
+export const DEFAULT_TARGETS = [
+    'node',
+    'leaf',
+    'container',
+    'edge',
+    'guide node',
+    'guide edge',
+    'guide point',
+    'guide region',
+];
 /**
  * What each default may say. A default carries a style's vocabulary, less the
  * words that would contradict the kind it is written for:
  *
  * - 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 const DEFAULT_KEYS = {
-    node: ['style', 'shape', 'fill', 'border', 'text'],
-    leaf: ['style', 'shape', 'icon', 'fill', 'border', 'text'],
-    container: ['style', 'shape', 'badge', 'fill', 'border', 'text'],
+    node: ['style', 'shape', 'badge', 'fill', 'border', 'corners', 'text'],
+    leaf: ['style', 'shape', 'icon', 'badge', 'fill', 'border', 'corners', 'text'],
+    container: ['style', 'shape', 'badge', 'fill', 'border', 'corners', 'text'],
     edge: ['style', 'line', 'text'],
+    // A shown guide's look, one line per kind (design.org 8.2).
+    'guide node': ['style', 'fill', 'border', 'corners', 'text'],
+    'guide edge': ['style', 'line', 'text'],
+    'guide point': ['style', 'fill'],
+    'guide region': ['style', 'fill', 'border'],
 };
 /**
  * The attributes whose value is a color rather than text. A color is written
@@ -335,8 +431,8 @@ export const COLOR_PARTS = {
  * 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
@@ -345,12 +441,27 @@ export const COLOR_PARTS = {
  * - 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 const SIZE_KEY_NAMES = ['width', 'height', 'min-width', 'max-width', 'min-height', 'max-height'];
+/** `padding-right: 4`: one side's padding, over `padding:` on that side. */
+export const PADDING_SIDES = ['top', 'right', 'bottom', 'left'];
+export const PADDING_SIDE_KEYS = PADDING_SIDES.map((side) => `padding-${side}`);
+/** `right-edge-order: ae, ad, ac`: the lines on one side of a box, in reading order. */
+export const EDGE_ORDER_KEYS = ['top-edge-order', 'bottom-edge-order', 'left-edge-order', 'right-edge-order'];
 export const ATTR_KEYS = {
-    shape: ['style', 'gap', 'overlap', 'contents', 'badge', 'deck', 'shape', 'fill', 'border', 'text', 'url'],
-    icon: ['style', 'gap', 'overlap', 'icon', 'text', 'url'],
-    none: ['style', 'gap', 'overlap', 'shape', 'text', 'url'],
-    edge: ['style', 'from', 'to', 'from-mark', 'to-mark', 'line', 'text', 'url'],
+    shape: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...PADDING_SIDE_KEYS, ...SIZE_KEY_NAMES, 'heading', 'join-with', 'badge', 'cards', 'shape', 'fill', 'border', 'corners', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
+    icon: ['style', 'overlap', 'icon', 'join-with', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
+    none: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...SIZE_KEY_NAMES, 'heading', 'join-with', 'shape', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
+    edge: ['style', 'from', 'to', 'via', 'from-mark', 'to-mark', 'line', 'text', 'url', 'depth'],
 };
+/**
+ * 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 const NODE_CORNERS = ['rounded', 'sharp'];
 /**
  * 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
@@ -362,5 +473,5 @@ export const ATTR_KEYS = {
  * not told the word does not exist.
  */
 export const ALL_ATTR_KEYS = [
-    ...new Set([...Object.values(ATTR_KEYS).flat(), ...DIAGRAM_KEYS]),
+    ...new Set([...Object.values(ATTR_KEYS).flat(), ...DIAGRAM_KEYS, ...REGION_KEYS]),
 ];

package/dist/checks.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Findings: things about a drawn picture that may look wrong. An error means
+ * the file can't be drawn; a finding means "look at this". A render with
+ * findings succeeds.
+ *
+ * Every finding is measured off the solved layout, never fixed by moving
+ * anything: the picture is drawn as written, and this says where it may not
+ * read as the writer meant.
+ */
+import { type Layout } from './model.js';
+/**
+ * The kinds of finding, each with whether it is on when nothing says. Named in
+ * the language's own nouns, since the name is what a writer types to turn one
+ * off. Crossings are often fine, so they are off; the rest are almost always a
+ * fault, so an agent that never thinks to ask still hears about them.
+ */
+export declare const CHECK_DEFAULTS: {
+    readonly 'text-overlap': true;
+    readonly 'text-overflow': true;
+    readonly 'edge-node-overlap': true;
+    readonly 'edge-overlap': true;
+    readonly 'crowded-edge-ends': true;
+    readonly 'node-overlap': true;
+    readonly 'edge-no-length': true;
+    readonly 'edge-crossings': false;
+};
+export type CheckKind = keyof typeof CHECK_DEFAULTS;
+export declare const CHECK_KINDS: CheckKind[];
+/** Which kinds run. */
+export type Checks = Record<CheckKind, boolean>;
+export declare function isCheckKind(word: string): word is CheckKind;
+/** One finding: the statement at fault, the kind, and what happened. */
+export declare class Finding {
+    readonly kind: CheckKind;
+    readonly message: string;
+    readonly line: number;
+    constructor(kind: CheckKind, message: string, line: number);
+    /** `diagram.reladraw:12: warning(node-overlap): …` — the form compilers and editors already read. */
+    format(file?: string): string;
+}
+/**
+ * `edge-crossings: on, crowded-edge-ends: off` — the inside of a `checks:`
+ * bracket, as `--checks` takes it, laid over `base`. A kind not mentioned
+ * keeps what `base` says.
+ */
+export declare function readChecks(text: string, base: Checks): Checks;
+/**
+ * The checks a layout asks for: the defaults, then the file's
+ * `diagram checks: (…)`, which arrives flattened as `checks.<kind>` and was
+ * refused by the parser if it named no kind.
+ */
+export declare function fileChecks(layout: Layout): Checks;
+/** One `kind: on|off`, refused by name if either word is wrong. */
+export declare function setCheck(checks: Checks, kind: string, value: string, fail: (message: string) => Error): void;
+/** Every finding the layout has, for the kinds that are on, in line order. */
+export declare function findings(layout: Layout, checks: Checks): Finding[];
+/** The one word in `words` a slip of a letter or two away from `word`, if there is one. */
+export declare function nearMatch(word: string, words: readonly string[]): string | undefined;