reladraw 0.19.1 → 0.21.0

package/dist/place.js

@@ -1,4 +1,4 @@
-import { describePlacement, describePoint, fractionAxis, nameTarget, PART_SIDES, partWordHint } from './ast.js';
+import { describeLimit, describePlacement, describePoint, fractionAxis, nameTarget, PART_SIDES, partWordHint } from './ast.js';
 import { DECK_STEP, GAPS, HEADER_GAP, UNIT } from './constants.js';
 import { SourceError } from './errors.js';
 import { isWithin, joinedToText } from './model.js';
@@ -107,6 +107,8 @@ export class Placer {
     sizes = new Map();
     frames = new Map();
     outlines = new Map();
+    /** A container's box while a limit tries it out (`roomFor`), in place of its final one. */
+    trials = new Map();
     working = new Set();
     /** What is being worked out, innermost last, for reporting a circle. */
     trail = [];
@@ -128,6 +130,8 @@ export class Placer {
     origins = new Map();
     /** Containers whose anchor is being placed on the page, so a box outside them is measured on the page rather than in their frame. */
     onPage = new Set();
+    /** Boxes that anchor their frame on one axis only, when no box in it says nothing at all (`splitAnchors`). */
+    axisAnchors = new Set();
     /** Named points and regions being worked out, innermost last, to refuse one defined through itself. */
     expanding = [];
     constructor(roots, byName, facts, 
@@ -175,6 +179,8 @@ export class Placer {
     /** Work out everything, and write it onto the nodes. */
     run() {
         this.checkAnchors(this.roots, undefined);
+        for (const node of this.byName.values())
+            this.checkLimitTargets(node);
         for (const node of this.byName.values()) {
             for (const axis of BOTH_AXES) {
                 this.size(node, axis);
@@ -189,9 +195,76 @@ export class Placer {
         }
         for (const node of this.byName.values())
             this.checkYielded(node);
+        for (const node of this.byName.values())
+            this.checkLimitsMet(node);
         for (const node of this.byName.values())
             this.finish(node);
     }
+    /**
+     * 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.
+     */
+    checkLimitTargets(node) {
+        for (const limit of node.limits ?? []) {
+            const parent = node.parent;
+            const said = `"${node.name} ${describeLimit(limit)}"`;
+            const named = this.byName.get(limit.target.name);
+            if (!named) {
+                throw new SourceError(`${said}: "${limit.target.name}" does not exist${partWordHint(limit.target.name, this.byName.keys())}`, limit.line);
+            }
+            const ownText = parent !== undefined && named === parent && limit.target.part === 'text';
+            const sibling = parent !== undefined && named.parent === parent && named !== node && limit.target.part === undefined;
+            if (!parent || !(ownText || sibling)) {
+                throw new SourceError(`${said}: a limit keeps clear of something in the same box, a sibling or ` +
+                    `${parent ? `"${parent.name} text"` : 'the box\'s own text'}, since that box is what makes room`, limit.line);
+            }
+            if (ownText && !this.hasTitle(parent)) {
+                throw new SourceError(`${said}: "${parent.name}" has no text`, limit.line);
+            }
+            const axis = limitAxis(limit);
+            const own = this.groupOf(node, parent, axis);
+            if (own !== 'frame' && own === this.groupOf(ownText ? 'text' : named, parent, axis)) {
+                const how = own === 'title' ? `with "${parent.name}"'s text` : 'against each other';
+                throw new SourceError(`${said} could never change anything: "${node.name}" and "${nameTarget(limit.target)}" are placed ${how}, ` +
+                    'so the distance between them is already stated — a limit relates two things in one box that nothing else ties together, ' +
+                    `such as a child placed against "${parent.name}"'s side and one of its other children`, limit.line);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    groupOf(member, parent, axis) {
+        const titleTied = this.anchoredOnTitle(parent) || (parent.titlePlacements?.length ?? 0) > 0;
+        if (member === 'text' || member === parent.heading || joinedToText(member))
+            return titleTied ? 'content' : 'title';
+        return this.framedOn(member, axis) ? 'frame' : 'content';
+    }
+    /** A limit the box couldn't make room for: no side helps, or a stated size holds it in. */
+    checkLimitsMet(node) {
+        for (const limit of node.limits ?? []) {
+            const parent = node.parent;
+            const axis = limitAxis(limit);
+            const frame = this.frame(parent, axis);
+            if (this.shortfall(parent, axis, { subject: node, limit }, frame) <= LIMIT_EPSILON)
+                continue;
+            const said = `"${describeLimit(limit)}"`;
+            if (frame.boxSize !== this.outline(parent, axis).boxSize) {
+                throw new SourceError(`"${node.name} ${describeLimit(limit)}", but "${parent.name}"'s stated ${axis === 'x' ? 'width' : 'height'} leaves no room for it — ` +
+                    'make it bigger, or leave the size unstated so the box can make room', limit.line);
+            }
+            const named = this.byName.get(limit.target.name);
+            const framed = [node, named].find((member) => member !== parent && this.framedOn(member, axis));
+            const where = framed
+                ? this.statements(framed, axis).map((statement) => `"${framed.name} ${describePlacement(statement.placement)}"`).join(' and ')
+                : undefined;
+            throw new SourceError(`"${node.name}" can't keep to ${said}${where ? ` with ${where}` : ''}: "${parent.name}" holds both, and growing it ` +
+                'never moves them apart — keep one of the two', limit.line);
+        }
+    }
     // --- the quantities ------------------------------------------------------
     /** Where a node starts on the page. */
     page(node, axis) {
@@ -215,7 +288,7 @@ export class Placer {
             if (this.frameAnchor(node, axis))
                 return this.anchorOnPage(node, axis);
             const above = node.parent ? this.origin(node.parent, axis) : 0;
-            if (this.floats(node))
+            if (this.floats(node, axis))
                 return above;
             this.refusePlacedTwice(node, axis);
             return above + this.start(node, axis) - this.frame(node, axis).boxStart;
@@ -275,9 +348,11 @@ export class Placer {
      * goes, and nothing inside it is placed against a box outside it in its
      * stead. Its frame's origin is its own container's.
      */
-    floats(node) {
+    floats(node, axis) {
         const parent = node.parent;
-        if (node.placements.length > 0 || node.children.length === 0)
+        if (node.children.length === 0)
+            return false;
+        if (node.placements.length > 0 && !this.axisAnchors.has(`${node.name}\n${axis}`))
             return false;
         if (parent && (parent.heading === node || joinedToText(node) || this.facts.get(parent).layout || this.vennPart(node) !== undefined)) {
             return false;
@@ -363,6 +438,9 @@ export class Placer {
     /** A container's box and title in its own frame, at the size it ends up. */
     frame(node, axis) {
         const key = `${node.name}\n${axis}`;
+        const trial = this.trials.get(key);
+        if (trial)
+            return trial;
         const known = this.frames.get(key);
         if (known)
             return known;
@@ -376,10 +454,91 @@ export class Placer {
         const known = this.outlines.get(key);
         if (known)
             return known;
-        const worked = this.guard(`outline\n${key}`, node, axis, undefined, () => this.workOutFrame(node, axis));
+        const worked = this.guard(`outline\n${key}`, node, axis, undefined, () => this.roomFor(node, axis));
         this.outlines.set(key, worked);
         return worked;
     }
+    /**
+     * 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.
+     */
+    roomFor(node, axis) {
+        const limits = this.limitsIn(node, axis);
+        let room = NO_ROOM;
+        let frame = this.workOutFrame(node, axis);
+        for (let round = 0; round < limits.length * 2; round++) {
+            const short = (at) => Math.max(...limits.map((each) => this.shortfall(node, axis, each, at)));
+            const owed = short(frame);
+            if (owed <= LIMIT_EPSILON)
+                break;
+            const rate = (more) => (owed - short(this.workOutFrame(node, axis, more))) / owed;
+            const low = rate({ low: room.low + owed, high: room.high });
+            const high = rate({ low: room.low, high: room.high + owed });
+            if (low > LIMIT_EPSILON && high > LIMIT_EPSILON) {
+                const both = rate({ low: room.low + owed, high: room.high + owed });
+                room = { low: room.low + owed / both, high: room.high + owed / both };
+            }
+            else if (low > LIMIT_EPSILON) {
+                room = { ...room, low: room.low + owed / low };
+            }
+            else if (high > LIMIT_EPSILON) {
+                room = { ...room, high: room.high + owed / high };
+            }
+            else {
+                break;
+            }
+            frame = this.workOutFrame(node, axis, room);
+        }
+        return frame;
+    }
+    /** The limits a container's children state on one axis. */
+    limitsIn(node, axis) {
+        return node.children.flatMap((subject) => (subject.limits ?? []).filter((limit) => limitAxis(limit) === axis).map((limit) => ({ subject, limit })));
+    }
+    /** How much nearer than its gap a limit's two ends are, in a trial frame of their container. */
+    shortfall(node, axis, { subject, limit }, at) {
+        const own = this.memberAt(subject, node, axis, at);
+        const other = limit.target.name === node.name ? { start: at.textStart, size: at.textSize } : this.memberAt(this.byName.get(limit.target.name), node, axis, at);
+        const gap = this.limitGap(subject, limit);
+        const toward = limit.way === 'above' || limit.way === 'left';
+        return toward ? own.start + own.size + gap - other.start : other.start + other.size + gap - own.start;
+    }
+    /** The distance a limit keeps: its gap, or the usual one; beside a text, as beside any text. */
+    limitGap(subject, limit) {
+        if (limit.gap !== undefined)
+            return gapPixels(limit.gap, `"${subject.name}"`, limit.line);
+        const parent = subject.parent;
+        if (limit.target.name === parent.name)
+            return this.hasTitle(parent) ? UNIT : 0;
+        return GAPS['normal'];
+    }
+    /** Where a child of `node` is on one axis, in a trial frame of `node`. */
+    memberAt(member, node, axis, at) {
+        const size = this.size(member, axis);
+        if (member === node.heading)
+            return { start: at.titleStart, size };
+        if (joinedToText(member))
+            return { start: at.textStart + this.unitStart(member, axis), size };
+        if (!this.framedOn(member, axis))
+            return { start: this.start(member, axis), size };
+        // Placed against the box: where the trial box puts it, worked out
+        // without remembering, since the box isn't final.
+        const key = `${node.name}\n${axis}`;
+        this.trials.set(key, at);
+        try {
+            return { start: this.placed(member, axis), size };
+        }
+        finally {
+            this.trials.delete(key);
+        }
+    }
     remember(memo, node, axis, work) {
         const key = `${node.name}\n${axis}`;
         const known = memo.get(key);
@@ -454,7 +613,7 @@ export class Placer {
         }
         // A container that anchors its frame shares its container's origin, so
         // its box starts where its outline does.
-        if (this.floats(node))
+        if (this.floats(node, axis))
             return this.frame(node, axis).boxStart;
         if (node.placements.length === 0 || this.acrossParts(node)) {
             // The anchor of its frame. One placed against a box in another part of
@@ -473,13 +632,14 @@ export class Placer {
     placed(node, axis) {
         const statements = this.statements(node, axis);
         if (statements.length === 0)
-            return this.lone(node, axis);
+            return this.axisAnchors.has(`${node.name}\n${axis}`) ? 0 : this.lone(node, axis);
         if (statements.length === 1) {
             const [only] = statements;
             return this.apply(node, axis, only);
         }
         const [first, second] = statements;
         if (first.kind !== 'align' && second.kind !== 'align' && first.kind !== second.kind) {
+            this.refuseBoxAndSibling(node, axis, first.placement, second.placement);
             // Opposite placements: centered between the two at its own size. Each
             // target stays where its own statement put it.
             const after = first.kind === 'after' ? first : second;
@@ -494,6 +654,36 @@ export class Placer {
             return pins.start;
         throw this.overStated(node, axis, statements);
     }
+    /**
+     * 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`.
+     */
+    refuseBoxAndSibling(node, axis, first, second) {
+        const parent = node.parent;
+        if (!parent || this.againstBox(first, parent) === this.againstBox(second, parent))
+            return;
+        const [box, other] = this.againstBox(first, parent) ? [first, second] : [second, first];
+        if (other.kind !== 'offset')
+            return;
+        const ways = [];
+        const corner = box.targets[0]?.part;
+        if (box.kind === 'offset' && box.written !== undefined && corner !== undefined && corner.includes('-')) {
+            const [down, across] = corner.split('-');
+            const kept = axis === 'x' ? down : across;
+            ways.push(`to sit ${describePlacement(other)} at the ${kept} of ${parent.name}, write "${describePlacement(other)}  ${box.written} ${parent.name} ${kept}"`);
+        }
+        const way = component(other.direction, axis);
+        const straight = axis === 'x' ? (way === 'after' ? 'right' : 'left') : way === 'after' ? 'below' : 'above';
+        const of = axis === 'x' ? ' of' : '';
+        if (other.targets.length === 1) {
+            ways.push(`to stay ${describePlacement(box)} and clear of ${nameTarget(other.targets[0])}, write "stays ${straight}${of} ${nameTarget(other.targets[0])}"`);
+        }
+        throw new SourceError(`"${node.name}" says twice where it goes ${AXIS_SAID[axis]}, with "${describePlacement(box)}" and "${describePlacement(other)}"` +
+            (ways.length > 0 ? `; ${ways.join('; ')}` : ' — keep one'), other.line);
+    }
     edgeOf(node, axis, statement) {
         return this.guard(`edge\n${node.name}\n${axis}\n${statement.placement.line}`, node, axis, statement.placement, () => statement.kind === 'align' ? 0 : statement.edge());
     }
@@ -991,7 +1181,7 @@ export class Placer {
                 text = { start: frame.textStart, size: frame.textSize };
         }
         else if (named.parent === parent) {
-            if (this.framed(named) && !this.framed(node)) {
+            if (this.framedOn(named, axis) && !this.framedOn(node, axis)) {
                 throw new SourceError(`"${node.name}" is placed against "${named.name}", which is placed against "${parent.name}" itself. ` +
                     `Nothing may be placed against a thing placed against its container's side or corner — place ` +
                     `"${node.name}" against another child`, placement.line);
@@ -1049,7 +1239,27 @@ export class Placer {
         const parent = node.parent;
         if (!parent || this.facts.get(parent).layout || this.facts.get(parent).venn)
             return false;
-        return node.placements.some((placement) => placement.targets.some((target) => target.name === parent.name && target.part !== 'text'));
+        return node.placements.some((placement) => this.againstBox(placement, parent));
+    }
+    /**
+     * 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, axis) {
+        if (!this.framed(node))
+            return false;
+        const parent = node.parent;
+        const statements = this.statements(node, axis);
+        if (statements.length > 0)
+            return statements.some((statement) => this.againstBox(statement.placement, parent));
+        // Nothing states this axis, so a lone direction on the other one centers it on its target.
+        return node.placements.some((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined && this.againstBox(placement, parent));
+    }
+    /** Whether a placement names its container's box, any part but the text. */
+    againstBox(placement, parent) {
+        return placement.targets.some((target) => target.name === parent.name && target.part !== 'text');
     }
     /**
      * A child placed against its container's text, or against its heading,
@@ -1111,10 +1321,13 @@ export 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.
      */
-    contentOf(node) {
-        return node.children.filter((child) => child !== node.heading && !joinedToText(child) && !this.framed(child));
+    contentOf(node, axis) {
+        return node.children.filter((child) => child !== node.heading &&
+            !joinedToText(child) &&
+            !(axis === undefined ? this.framed(child) : this.framedOn(child, axis)));
     }
     /** Whether a node has a title: its text, what is joined to it, or a heading. */
     hasTitle(node) {
@@ -1307,12 +1520,12 @@ export class Placer {
      * not placed against the box itself, and the title when it sits inside the
      * border or on it.
      */
-    workOutFrame(node, axis) {
+    workOutFrame(node, axis, room = NO_ROOM) {
         const facts = this.facts.get(node);
         const title = this.titleOf(node);
         const hasTitle = this.hasTitle(node);
         const titleSize = this.titleSize(node, axis);
-        const content = this.contentOf(node);
+        const content = this.contentOf(node, axis);
         const anchoredOnTitle = this.anchoredOnTitle(node);
         let low = Infinity;
         let high = -Infinity;
@@ -1343,6 +1556,12 @@ export class Placer {
                 high = Math.max(high, band);
             }
         }
+        // Room a child's limit asks for (design.org 5.6), between what the box
+        // holds and its sides, so a title against a side moves out with it.
+        if (!empty) {
+            low -= room.low;
+            high += room.high;
+        }
         // Where the title sits in the frame. When something is placed against it,
         // it is the frame's anchor and sits at the origin; otherwise it is placed
         // against the children by its side.
@@ -1358,6 +1577,10 @@ export class Placer {
                 low = titleStart;
                 high = titleStart + titleSize;
             }
+            if (empty) {
+                low -= room.low;
+                high += room.high;
+            }
         }
         else if (title.how === 'center' || title.side === 'center') {
             titleStart = (low + high) / 2 - titleSize / 2;
@@ -1590,7 +1813,7 @@ export class Placer {
     innerOther(node, axis) {
         const key = `inner\n${node.name}\n${axis}`;
         return this.guard(key, node, axis, undefined, () => {
-            const content = this.contentOf(node);
+            const content = this.contentOf(node, axis);
             let low = Infinity;
             let high = -Infinity;
             for (const child of content) {
@@ -2015,9 +2238,8 @@ export class Placer {
             const content = members.filter((member) => !this.framed(member));
             const unplaced = content.filter((member) => this.unplaced(member));
             const onTitle = content.find((member) => this.onTitle(member));
-            if (!parent && unplaced.length === 0) {
-                throw new SourceError('every node is placed relative to another, so nothing anchors the diagram', 1);
-            }
+            if (unplaced.length === 0 && !(parent && this.anchoredOnTitle(parent)))
+                this.splitAnchors(content, parent);
             if (unplaced.length > 1) {
                 const names = unplaced.map((node) => `"${node.name}"`).join(', ');
                 throw new SourceError(parent
@@ -2034,6 +2256,62 @@ export class Placer {
         for (const member of all)
             this.checkAnchors(member.children, member);
     }
+    /**
+     * 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.
+     */
+    splitAnchors(members, parent) {
+        const free = BOTH_AXES.map((axis) => parent && this.frameAnchor(parent, axis)
+            ? []
+            : members.filter((member) => this.statements(member, axis).length === 0 && this.loneGivesWay(member, axis)));
+        if (!parent && free.every((on) => on.length === 0)) {
+            throw new SourceError('every node is placed relative to another, so nothing anchors the diagram', 1);
+        }
+        BOTH_AXES.forEach((axis, index) => {
+            const on = free[index];
+            // With the other axis bound all round there is a circle, which placing reports better.
+            if (on.length > 1 && free.every((other) => other.length > 0)) {
+                const names = on.map((node) => `"${node.name}"`).join(', ');
+                throw new SourceError(`exactly one node may say nothing about where it goes ${AXIS_SAID[axis]}, but ${on.length} do: ${names}`, on[1].line);
+            }
+            if (on.length === 1)
+                this.axisAnchors.add(`${on[0].name}\n${axis}`);
+        });
+    }
+    /** 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. */
+    loneGivesWay(node, axis) {
+        const offsets = node.placements.filter((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined);
+        if (offsets.length === 0)
+            return true;
+        if (offsets.length > 1)
+            return false;
+        return this.namedFrom(offsets[0]).some((named) => this.placedFrom(named, axis, node, new Set()));
+    }
+    /** The boxes a placement names, through points and regions. */
+    namedFrom(placement) {
+        return placement.targets
+            .flatMap((target) => this.boxesNamed(target, []))
+            .flatMap((name) => this.byName.get(name) ?? []);
+    }
+    /** Whether a box's place on one axis is worked out, however indirectly, from `from` or something inside it. */
+    placedFrom(node, axis, from, seen) {
+        if (node === from || isWithin(node, from))
+            return true;
+        if (seen.has(node))
+            return false;
+        seen.add(node);
+        const stated = this.statements(node, axis).map((statement) => statement.placement);
+        const placements = stated.length > 0
+            ? stated
+            : node.placements.filter((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined);
+        return placements.some((placement) => this.namedFrom(placement).some((named) => this.placedFrom(named, axis, from, seen)));
+    }
     /**
      * 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
@@ -2173,6 +2451,13 @@ export class Placer {
         return { low, high };
     }
 }
+const NO_ROOM = { low: 0, high: 0 };
+/** Less than this is no distance at all, for a limit worked out in floating point. */
+const LIMIT_EPSILON = 0.01;
+/** The axis a limit keeps to: up and down for above and below. */
+function limitAxis(limit) {
+    return limit.way === 'above' || limit.way === 'below' ? 'y' : 'x';
+}
 /**
  * `top even with 2 below design top` on a venn's set: the other set's same
  * side, moved up or down. Anything else, such as its bottom or a sideways

package/dist/render.d.ts

@@ -10,3 +10,20 @@ export interface RenderOptions {
 }
 /** Turn solved geometry into a standalone SVG document. */
 export declare function render(layout: Layout, options?: RenderOptions): string;
+/**
+ * The SVG as `render` gives it, and the same drawing with each thing wrapped in
+ * a group naming it and its statement's line, for a page that points at things
+ * (`--page`). Drawn once, so the two can't disagree.
+ */
+export declare function renderTagged(layout: Layout, options?: RenderOptions): {
+    svg: string;
+    tagged: string;
+};
+/**
+ * The colors a drawing is made in. A theme passed in — the command line's
+ * `--theme` — beats the one the file names, so one source renders in either.
+ * `diagram background:` and `text:` are the author overruling a color of
+ * whichever theme that is, and a color written by hand wins over any theme, so
+ * they are folded in afterwards and everything downstream sees one theme.
+ */
+export declare function themeOf(layout: Layout, options?: RenderOptions): Theme;