reladraw 0.19.1 → 0.21.0

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { BUNDLE_KEYS, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
+import { BUNDLE_KEYS, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, BORDER_KEYS, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { CHECK_DEFAULTS, CHECK_KINDS, setCheck } from './checks.js';
 import { SourceError } from './errors.js';
 import { STATEMENT_KEYWORDS } from './grammar.js';
@@ -309,6 +309,7 @@ const BRACKET_KEYS = {
     text: TEXT_KEYS,
     contents: CONTENTS_KEYS,
     line: LINE_KEYS,
+    border: BORDER_KEYS,
     checks: CHECK_KINDS,
 };
 /** How each bracketed key's error quotes itself back, and what it is about. */
@@ -316,6 +317,7 @@ const BRACKET_ABOUT = {
     text: { kind: 'a text', example: 'color: theme-muted' },
     contents: { kind: 'a `contents:` bracket', example: 'widths: match' },
     line: { kind: 'a line', example: 'path: square' },
+    border: { kind: 'a border', example: 'thickness: thick' },
     checks: { kind: 'a `checks:` bracket', example: 'edge-crossings: on' },
 };
 /**
@@ -702,7 +704,8 @@ function readAttr(tokens, at, attrs, line, subject) {
             // A line's color is stored where `line: red` puts it, so the short form
             // and the bracket are one key: a style's `line: red` merges under an
             // edge's `line: (color: blue)`, and writing both on one line is a repeat.
-            const stored = key === 'line' && inner === 'color' ? 'line' : `${key}.${inner}`;
+            // A border's color the same.
+            const stored = (key === 'line' || key === 'border') && inner === 'color' ? key : `${key}.${inner}`;
             setOnce(attrs, stored, value, subject, line, { key: `${key}: (${inner}: …)`, value: (v) => v });
         }
         return read.next;
@@ -720,6 +723,16 @@ function readAttr(tokens, at, attrs, line, subject) {
         setOnce(attrs, key, value.text, subject, line, { key, value: quoteOf });
         return at + 2;
     }
+    if (key === 'title') {
+        // A title is a text, and every text is quoted. Unquoted, its first word
+        // would be the title and the rest read as stray words.
+        const value = tokens[at + 1];
+        if (!value || !value.quoted) {
+            throw new SourceError(`${subject}: a title is written in quotes — \`title: "How a login reaches the database"\``, line);
+        }
+        setOnce(attrs, key, value.text, subject, line, { key, value: quoteOf });
+        return at + 2;
+    }
     if (key === 'style') {
         // `style: base, critical and alarm` — several bundles, applied in the order
         // written, a later one winning where two set the same key. The list reads
@@ -768,7 +781,7 @@ function readAttr(tokens, at, attrs, line, subject) {
         });
         return next;
     }
-    if (bracketKeys !== undefined && key !== 'text' && key !== 'line') {
+    if (bracketKeys !== undefined && key !== 'text' && key !== 'line' && key !== 'border') {
         // `contents: match` names the part and then says one of its two properties
         // without saying which. The brackets are what make the level shift visible,
         // so there is no unbracketed spelling to fall back to.
@@ -821,6 +834,11 @@ function readAttr(tokens, at, attrs, line, subject) {
                 `\`line: (${property}: ${valueToken.text})\``, line);
         }
     }
+    if (key === 'border' && !valueToken.quoted && /^(thin|normal|thick|\d*\.?\d+(px)?)$/.test(valueToken.text)) {
+        // `border: red` is the short form of the color, as `line: red` is.
+        throw new SourceError(`\`border: ${valueToken.text}\` — \`border:\` on its own takes a color. Its thickness goes in its bracket: ` +
+            `\`border: (thickness: ${valueToken.text})\``, line);
+    }
     if (key === 'align' && valueToken.text === 'widths') {
         // Removed in 0.3.0. It was a size operation wearing an alignment's name,
         // and its value set had one member — a flag in a property's clothes. Its
@@ -1238,7 +1256,15 @@ function parseNode(head, line) {
         listed: NODE_TEXT_LISTED,
     });
     refuseNodeReads(bracket.values['reads'], subject, line);
-    const tail = parseTail(head, bracket.next, line, subject);
+    const limits = [];
+    const tail = parseTail(head, bracket.next, line, subject, (tokens, index) => {
+        const word = tokens[index];
+        if (word.quoted || word.text !== 'stays')
+            return undefined;
+        const read = readLimit(tokens, index, line, subject);
+        limits.push(read.limit);
+        return read.next;
+    });
     refuseTextKey(tail.attrs, subject, 'after the name', line);
     return {
         kind: 'node',
@@ -1248,10 +1274,43 @@ function parseNode(head, line) {
         textAttrs: place === undefined ? bracket.values : { ...bracket.values, place },
         ...(titlePlacements.length > 0 ? { titlePlacements } : {}),
         placements: tail.placements,
+        ...(limits.length > 0 ? { limits } : {}),
         attrs: tail.attrs,
         line,
     };
 }
+/**
+ * `stays above laptop.photos (gap: wide)`: a limit (design.org 5.6). The words
+ * after `stays` are read as a placement would be, then held to one straight
+ * way and one target, since a limit says which side of one thing to keep to.
+ */
+function readLimit(tokens, at, line, subject) {
+    const way = tokens[at + 1];
+    const straight = ['above', 'below', 'left', 'right'];
+    if (!way || way.quoted || !straight.includes(way.text)) {
+        const diagonal = way !== undefined && !way.quoted && isDirection(way.text);
+        throw new SourceError(diagonal
+            ? `${subject}: "stays ${way.text}" keeps to two sides at once — write one limit for each, such as \`stays above a  stays right of a\``
+            : `${subject}: "stays" is followed by the way it keeps to — stays above, stays below, stays left of or stays right of`, line);
+    }
+    const read = readPlacement(tokens, at + 1, line, subject, true);
+    const placement = read.placement;
+    if (placement.kind !== 'offset' || placement.own !== undefined || placement.gaps !== undefined) {
+        throw new SourceError(`${subject}: "stays" names a way and one thing, such as \`stays above laptop.photos\``, line);
+    }
+    if (placement.targets.length !== 1) {
+        throw new SourceError(`${subject}: "${describePlacement(placement)}" after "stays" names ${placement.targets.length} things — a limit keeps clear of one; write one for each`, line);
+    }
+    return {
+        limit: {
+            way: way.text,
+            target: placement.targets[0],
+            ...(placement.gap !== undefined ? { gap: placement.gap } : {}),
+            line,
+        },
+        next: read.next,
+    };
+}
 /**
  * A node's text takes the look keys and `reads:` (design.org 7.2). `at` is
  * read only to be refused with the side form, so it isn't listed as one it takes.
@@ -2394,6 +2453,12 @@ function checkColorWord(value, subject, line) {
     if (value.startsWith('theme-') && !THEME_COLORS.includes(value)) {
         throw new SourceError(`${subject}: there is no theme color "${value}" — the theme colors are ${THEME_COLORS.join(', ')}`, line);
     }
+    // Hex digits without their `#` are no CSS color, so the viewer would draw nothing.
+    if (/^([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
+        // `bad` and `face` are spelled in hex digits too, so without a digit it is only a guess.
+        const fix = /\d/.test(value) ? 'a hex color is written' : 'if it is a hex color, write';
+        throw new SourceError(`${subject}: \`${value}\` is not a color — ${fix} \`#${value}\``, line);
+    }
 }
 function follows(tokens, at, word) {
     const token = tokens[at];

package/dist/place.d.ts

@@ -130,6 +130,8 @@ export declare class Placer {
     private readonly sizes;
     private readonly frames;
     private readonly outlines;
+    /** A container's box while a limit tries it out (`roomFor`), in place of its final one. */
+    private readonly trials;
     private readonly working;
     /** What is being worked out, innermost last, for reporting a circle. */
     private readonly trail;
@@ -151,6 +153,8 @@ export declare class Placer {
     private readonly origins;
     /** Containers whose anchor is being placed on the page, so a box outside them is measured on the page rather than in their frame. */
     private readonly onPage;
+    /** Boxes that anchor their frame on one axis only, when no box in it says nothing at all (`splitAnchors`). */
+    private readonly axisAnchors;
     /** Named points and regions being worked out, innermost last, to refuse one defined through itself. */
     private readonly expanding;
     constructor(roots: LayoutNode[], byName: Map<string, LayoutNode>, facts: Map<LayoutNode, NodeFacts>, 
@@ -181,6 +185,20 @@ export declare class Placer {
     };
     /** Work out everything, and write it onto the nodes. */
     run(): void;
+    /**
+     * What a limit may relate (design.org 5.6): two things in one box that
+     * nothing else ties together, since the box's own spacing between them is
+     * the only distance it may lengthen.
+     */
+    private checkLimitTargets;
+    /**
+     * Which of the things a box holds that nothing ties to each other a member
+     * belongs to, on one axis: its title, what is placed against the box's
+     * sides, or the rest, placed against each other.
+     */
+    private groupOf;
+    /** A limit the box couldn't make room for: no side helps, or a stated size holds it in. */
+    private checkLimitsMet;
     /** Where a node starts on the page. */
     page(node: LayoutNode, axis: Axis): number;
     /**
@@ -226,6 +244,26 @@ export declare class Placer {
     private frame;
     /** A container's outline around what it holds, before anything states its size. */
     private outline;
+    /**
+     * A container's outline with room made for its children's limits
+     * (design.org 5.6). The only distance a limit may lengthen is between what
+     * the box holds and its sides, which every placement inside leaves unstated.
+     * Each side's room moves a limit's two ends apart at a fixed rate (all of
+     * it for a corner, half for the middle of a side), so one trial of each
+     * side gives the rate, and the room is the shortfall over the rate. A side
+     * that doesn't help is never used; with both helping, as for two corner
+     * children, the box grows evenly. A limit no side helps is left unmet, and
+     * `checkLimits` refuses it.
+     */
+    private roomFor;
+    /** The limits a container's children state on one axis. */
+    private limitsIn;
+    /** How much nearer than its gap a limit's two ends are, in a trial frame of their container. */
+    private shortfall;
+    /** The distance a limit keeps: its gap, or the usual one; beside a text, as beside any text. */
+    private limitGap;
+    /** Where a child of `node` is on one axis, in a trial frame of `node`. */
+    private memberAt;
     private remember;
     /**
      * Work something out, refusing a circle. The trail holds what was being
@@ -238,6 +276,14 @@ export declare class Placer {
     private unitStart;
     /** A box's start from its own placements. */
     private placed;
+    /**
+     * Opposite placements center a box between two others, but not when one of
+     * them is its own container's box: `inside c top-right  right of c.k` would
+     * be neither in the corner nor a gap from `c.k` (design.org 5.3). Refused,
+     * naming the two ways out: the corner's other half beside the sibling, or
+     * the corner kept and the sibling held off with `stays`.
+     */
+    private refuseBoxAndSibling;
     private edgeOf;
     /** A box's start from one statement. */
     private apply;
@@ -314,6 +360,15 @@ export declare class Placer {
     private textOf;
     /** A child placed against its own container's box, which it does not grow. */
     framed(node: LayoutNode): boolean;
+    /**
+     * Framed on one axis: what says where it goes on that axis is against its
+     * container's box. `right of c.k  inside c top` is framed down, so its height
+     * is measured from the finished box, and is content across, so the box holds
+     * it there (design.org 5.6).
+     */
+    framedOn(node: LayoutNode, axis: Axis): boolean;
+    /** Whether a placement names its container's box, any part but the text. */
+    private againstBox;
     /**
      * A child placed against its container's text, or against its heading,
      * which makes the title its frame's anchor.
@@ -334,7 +389,8 @@ export declare class Placer {
     /**
      * The children a container's box is the outline of, besides its title: not
      * its heading, not what is joined to its text, and not those placed against
-     * the box.
+     * the box. Given an axis, a child placed against the box only on the other
+     * axis is content on this one.
      */
     private contentOf;
     /** Whether a node has a title: its text, what is joined to it, or a heading. */
@@ -480,6 +536,23 @@ export declare class Placer {
      * title something is placed against anchors the frame instead.
      */
     private checkAnchors;
+    /**
+     * Every box in a frame says something about where it goes, so the frame is
+     * anchored one axis at a time (design.org 5.3): across by the one box that
+     * says nothing across, up and down by the one that says nothing up and
+     * down. A lone direction's centering counts as saying nothing when its
+     * target's place on that axis is worked out from the box itself, as with
+     * `b right of a` and `a even with b.1`: the centering gives way to what was
+     * written. An axis nobody leaves free is a circle, reported when placing,
+     * and an axis a container is placed on by what it holds needs no anchor.
+     */
+    private splitAnchors;
+    /** Whether a box with nothing stated on this axis is left free there: no lone direction centers it, or the one that would is placed from the box itself. */
+    private loneGivesWay;
+    /** The boxes a placement names, through points and regions. */
+    private namedFrom;
+    /** Whether a box's place on one axis is worked out, however indirectly, from `from` or something inside it. */
+    private placedFrom;
     /**
      * A box in a venn's part may be placed against a box in another part, and
      * then it says where its whole part goes up and down: so it must be the