reladraw 0.7.1 → 0.8.0

package/SYNTAX.md

@@ -171,6 +171,7 @@ Every node has a *body*: the thing that is drawn where the node is. Two keys nam
 | --- | --- |
 | `rectangle` | The plain rounded box. The default, so nothing has to say it. |
 | `document` | The same box with its top-right corner folded — the flowchart symbol saying *this is an artifact, not a process*. |
+| `circle` | A circle just big enough to hold the text, and always round — a longer text makes a bigger circle, never an oval. |
 | `none` | No outline, no fill, no padding. The node is its text and nothing else. |
 
 `icon: <name>` is a picture the node is drawn **as**, with no box at all.
@@ -193,7 +194,11 @@ node svc  icon: cube
 
 A node has one body, so writing both keys is an error naming both.
 
-The `document` fold is worth having because a shape is a second channel alongside color, and a stronger one. A fill means whatever you assigned it and a reader has to learn it from the diagram; a folded corner has meant "a document" for as long as there have been flowcharts, and reads with no legend. Most diagrams lose the difference between a thing that runs and a thing that is produced, because every node is a rectangle. `circle` and `diamond` will join these when a diagram asks for them.
+The `document` fold is worth having because a shape is a second channel alongside color, and a stronger one. A fill means whatever you assigned it and a reader has to learn it from the diagram; a folded corner has meant "a document" for as long as there have been flowcharts, and reads with no legend. Most diagrams lose the difference between a thing that runs and a thing that is produced, because every node is a rectangle. `diamond` will join these when a diagram asks for one.
+
+A circle is an ordinary node in every other way, and the file means the same thing whichever shape its nodes are. `from: right` on a circle leaves from its rightmost point, and several edges on one side spread round the quarter of the circle about that point, each meeting it square on. A corner such as `top-right` is the point on the circle halfway between those two sides, not the corner of the square around it. A circle can hold other nodes; they sit in the middle of it. A circle cannot yet take a `badge:`, a `deck:`, or a node placed against its own edge or text, and each is refused with an error saying so.
+
+`circle` is the one name that describes the picture rather than the meaning, because a circle has no single meaning to name it after: it is a state in one diagram, a step in another, a person in a third.
 
 A name says what the thing *is*, never what the picture looks like: naming the meaning is what lets the drawing be improved later without every diagram that uses it changing sense. `document`, not `folded-corner`. The one place that rule stops is a picture with no single meaning — the cube stands for a container in one diagram, a VM in another, a service in a third — which is why it is called `cube` and not `instance`. An unrecognized name is an error listing the whole set, rather than a node that quietly draws nothing.
 
@@ -1012,6 +1017,10 @@ That one was found by testing the lexer, not by rendering — and it could not h
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal below is refused by name with the replacement quoted, rather than dropped in silence — an older file stops with an error saying what to write instead.
 
+**Unreleased**
+
+- `shape: circle`. A circle is sized to hold its text and is always round. Edges on one of its sides spread round that quarter of the circle, and a corner of it is the point on the circle halfway round. It does not yet take a badge, a deck or a node placed against its own edge. Nothing that already renders changes.
+
 **0.7.1**
 
 - A fix, no syntax change. An edge with `line: (path: straight)` and a clause such as `below m` could draw its text on top of `m`. The line now bends through the room left for the text, so the text sits clear of the node. Existing diagrams with such an edge will look different, and correct.

package/dist/icons.d.ts

@@ -50,13 +50,16 @@ export declare const ICON_NAMES: string[];
  * diagram, while a folded corner has meant "an artifact, not a process" in
  * flowcharts for decades and reads with no legend at all.
  *
- * `circle` and `diamond` join these when a diagram asks. The set being short is
- * a fact about what has been drawn, not about the key.
+ * `circle` is the one geometric name, because a circle carries no single
+ * meaning to name it after — it is a state, a step, a person, whatever the
+ * diagram's own convention makes it. `diamond` joins these when a diagram
+ * asks. The set being short is a fact about what has been drawn, not about the
+ * key.
  */
-export declare const OUTLINES: readonly ["rectangle", "document"];
+export declare const OUTLINES: readonly ["rectangle", "document", "circle"];
 export type Outline = (typeof OUTLINES)[number];
 /** Every value `shape:` accepts, `none` included. */
-export declare const SHAPE_WORDS: readonly ["rectangle", "document", "none"];
+export declare const SHAPE_WORDS: readonly ["rectangle", "document", "circle", "none"];
 /**
  * What a node is drawn as: an outline, a picture, or nothing at all.
  *

package/dist/icons.js

@@ -126,10 +126,13 @@ export const ICON_NAMES = Object.keys(ICONS);
  * diagram, while a folded corner has meant "an artifact, not a process" in
  * flowcharts for decades and reads with no legend at all.
  *
- * `circle` and `diamond` join these when a diagram asks. The set being short is
- * a fact about what has been drawn, not about the key.
+ * `circle` is the one geometric name, because a circle carries no single
+ * meaning to name it after — it is a state, a step, a person, whatever the
+ * diagram's own convention makes it. `diamond` joins these when a diagram
+ * asks. The set being short is a fact about what has been drawn, not about the
+ * key.
  */
-export const OUTLINES = ['rectangle', 'document'];
+export const OUTLINES = ['rectangle', 'document', 'circle'];
 /** Every value `shape:` accepts, `none` included. */
 export const SHAPE_WORDS = [...OUTLINES, 'none'];
 const PLAIN = { kind: 'shape', outline: 'rectangle' };

package/dist/render.js

@@ -230,6 +230,16 @@ const FOLD = CORNER * 2;
 /** The node's outline, as path data. */
 function outlinePath(shape, x, y, w, h) {
     const r = CORNER;
+    if (shape === 'circle') {
+        // Two half-turns from the leftmost point, since one arc cannot close.
+        const radius = w / 2;
+        return [
+            `M${round(x)} ${round(y + h / 2)}`,
+            `a${round(radius)} ${round(radius)} 0 1 0 ${round(w)} 0`,
+            `a${round(radius)} ${round(radius)} 0 1 0 ${round(-w)} 0`,
+            'Z',
+        ].join(' ');
+    }
     if (shape === 'document') {
         // Every corner rounded but the top-right one, which is cut away and folded.
         return [
@@ -897,6 +907,10 @@ function sidePoint(box, toward) {
     const dy = toward.y - center.y;
     if (dx === 0 && dy === 0)
         return center;
+    if (box.round) {
+        const scale = box.width / 2 / Math.hypot(dx, dy);
+        return { x: center.x + dx * scale, y: center.y + dy * scale };
+    }
     const scaleX = dx === 0 ? Infinity : box.width / 2 / Math.abs(dx);
     const scaleY = dy === 0 ? Infinity : box.height / 2 / Math.abs(dy);
     const scale = Math.min(scaleX, scaleY);
@@ -1291,6 +1305,8 @@ function claim(claims, node, side, entry) {
 }
 /** The point `at` along one side of a box, with the outward normal for that side. */
 function anchorOn(face, side, at) {
+    if (face.round)
+        return anchorOnCircle(face, side, at);
     switch (side) {
         case 'top':
             return { x: at, y: face.y, tx: 0, ty: -1, side };
@@ -1302,6 +1318,28 @@ function anchorOn(face, side, at) {
             return { x: face.x + face.width, y: at, tx: 1, ty: 0, side };
     }
 }
+/**
+ * The same, on a circle: a side is the quarter of the circle around its
+ * compass point, and `at` is walked round the arc rather than along a
+ * straight edge, so points spaced a step apart on a side are a step apart on
+ * the circle too. The line meets the circle square on, heading from its center.
+ */
+function anchorOnCircle(face, side, at) {
+    const radius = face.width / 2;
+    const center = centerOf(face);
+    const across = side === 'top' || side === 'bottom' ? at - center.x : at - center.y;
+    const turn = Math.max(-Math.PI / 4, Math.min(Math.PI / 4, across / radius));
+    // SVG's y runs down, so the bottom is a quarter-turn clockwise from the right.
+    const angle = {
+        right: turn,
+        bottom: Math.PI / 2 - turn,
+        left: Math.PI - turn,
+        top: -Math.PI / 2 + turn,
+    }[side];
+    const tx = Math.cos(angle);
+    const ty = Math.sin(angle);
+    return { x: center.x + radius * tx, y: center.y + radius * ty, tx, ty, side };
+}
 /** An end with no side named: leave from the border, pointing at the far end. */
 function free(face, toward) {
     const point = sidePoint(face, toward);
@@ -1324,6 +1362,20 @@ function exitAlong(box, from, dir) {
     // is the graceful answer, and the crowding it signals is a diagnostic.
     const x = Math.min(Math.max(from.x, box.x), box.x + box.width);
     const y = Math.min(Math.max(from.y, box.y), box.y + box.height);
+    if (box.round) {
+        // Where the ray leaves the circle: the larger root of |p + t·dir − c| = r.
+        const center = centerOf(box);
+        const px = x - center.x;
+        const py = y - center.y;
+        const a = dir.x * dir.x + dir.y * dir.y;
+        const b = px * dir.x + py * dir.y;
+        const c = px * px + py * py - (box.width / 2) ** 2;
+        const reach = b * b - a * c;
+        if (a === 0 || reach < 0)
+            return { x, y };
+        const t = Math.max(0, (-b + Math.sqrt(reach)) / a);
+        return { x: x + dir.x * t, y: y + dir.y * t };
+    }
     const tx = dir.x === 0 ? Infinity : ((dir.x > 0 ? box.x + box.width : box.x) - x) / dir.x;
     const ty = dir.y === 0 ? Infinity : ((dir.y > 0 ? box.y + box.height : box.y) - y) / dir.y;
     const t = Math.min(tx, ty);
@@ -2421,6 +2473,7 @@ function faceOf(node) {
         y: node.y + node.inset,
         width: node.width - node.inset,
         height: node.height - node.inset,
+        round: node.body.kind === 'shape' && node.body.outline === 'circle',
     };
 }
 function centerOf(box) {

package/dist/resolve.js

@@ -598,6 +598,9 @@ function sizeNode(node, edges, measurer, fontSize, local) {
     // too. The *absence* of children makes the setting inert, which stays silent;
     // a value the language does not have is wrong wherever it is written.
     const contents = contentsStyleFor(node);
+    const circle = isCircle(node);
+    if (circle)
+        refuseOnCircle(node);
     if (node.children.length === 0) {
         // `at` is read on a leaf too, and is inert wherever the box is exactly the
         // size of what it holds — which is every leaf, since a leaf is sized from
@@ -629,7 +632,7 @@ function sizeNode(node, edges, measurer, fontSize, local) {
     }
     else {
         if (contents.widths === 'match')
-            matchWidths(node.children);
+            matchWidths(node.children, local);
         let content = layoutChildren(node.children, edges, measurer, fontSize, local);
         if (contents.widths === 'fill') {
             // The band is the wider of the title and the contents, so filling it
@@ -638,7 +641,7 @@ function sizeNode(node, edges, measurer, fontSize, local) {
             // could not give.
             const band = Math.max(textWidth, content.width);
             for (const child of node.children)
-                widenTo(child, band);
+                widenTo(child, band, local);
             content = layoutChildren(node.children, edges, measurer, fontSize, local);
             checkOneColumn(node, node.children, local);
         }
@@ -671,8 +674,62 @@ function sizeNode(node, edges, measurer, fontSize, local) {
         }
         node.banded = true;
     }
+    if (circle)
+        circumscribe(node, local);
     applyDeck(node, local);
 }
+function isCircle(node) {
+    return node.body.kind === 'shape' && node.body.outline === 'circle';
+}
+/**
+ * Grow a node sized as a rectangle into the circle around what it holds.
+ *
+ * The circle passes a padding outside the corners of the padded-in block —
+ * the text of a leaf, or the band and contents of a container — so whatever
+ * fits in the rectangle fits in the circle, clear of its edge by the same
+ * padding at the corners where it comes closest. Everything inside moves to
+ * keep the block centered.
+ */
+function circumscribe(node, local) {
+    const side = Math.hypot(node.width - PAD * 2, node.height - PAD * 2) + PAD * 2;
+    moveInside(node, (side - node.width) / 2, (side - node.height) / 2, local);
+    node.width = side;
+    node.height = side;
+}
+function moveInside(node, dx, dy, local) {
+    node.textBox.x += dx;
+    node.textBox.y += dy;
+    for (const child of node.children) {
+        const offset = local.get(child);
+        offset.x += dx;
+        offset.y += dy;
+    }
+}
+/**
+ * What a circle does not take yet, refused by name rather than drawn as an
+ * ellipse or with a copy's text outside the outline.
+ *
+ * Something placed against the circle's own edge or text — a badge included —
+ * sizes the frame in the same solve as the thing placed, and a circle's corner
+ * points are a fraction of a radius that solve does not know yet. A deck's
+ * copies write their text at the top-left of the face, which on a circle is
+ * outside it.
+ */
+function refuseOnCircle(node) {
+    const [framed] = framedChildren(node);
+    if (node.attrs['badge'] !== undefined || node.appearance['badge'] !== undefined) {
+        throw new SourceError(`"${node.name}" is a circle with a badge:, and a badge is not built for circles yet — ` +
+            'make it a rectangle, or place the badge as a node of its own against the circle', node.line);
+    }
+    if (framed !== undefined) {
+        throw new SourceError(`"${framed.name}" is placed against "${node.name}" itself, and "${node.name}" is a circle. ` +
+            'Something placed against a circle\'s own edge or text is not built yet — place it against ' +
+            `another node, or make "${node.name}" a rectangle`, framed.line);
+    }
+    if (node.deckTexts.length > 0) {
+        throw new SourceError(`"${node.name}" is a circle with a deck:, and a deck is not built for circles yet`, node.line);
+    }
+}
 /**
  * Make room for a deck's copies, once the node's own face has been sized.
  *
@@ -726,10 +783,10 @@ function contentsStyleFor(node) {
  * before layoutChildren sizes and positions anything from those widths. A
  * container's own children are already sized by this point.
  */
-function matchWidths(children) {
+function matchWidths(children, local) {
     const maxWidth = Math.max(...children.map((child) => child.width));
     for (const child of children)
-        widenTo(child, maxWidth);
+        widenTo(child, maxWidth, local);
 }
 /**
  * `widths: fill` makes every child as wide as the band, which only holds for
@@ -757,8 +814,18 @@ function checkOneColumn(node, children, local) {
  * was sized from its own contents, and the text's box was worked out against
  * the old one. A left-ranged text stays where it is; a centered or right-ranged
  * one moves by its share of the difference.
+ *
+ * A circle grows both ways, since a wider circle is a bigger one, and what is
+ * inside it stays centered.
  */
-function widenTo(node, width) {
+function widenTo(node, width, local) {
+    if (isCircle(node)) {
+        const grew = width - node.width;
+        moveInside(node, grew / 2, grew / 2, local);
+        node.width = width;
+        node.height = width;
+        return;
+    }
     // A node with something placed against its own frame is laid out by a
     // solve, and a wider frame is one more thing that solve has to hold: the
     // things against its right edge move, and a centered text re-centers.
@@ -1013,7 +1080,7 @@ function layoutFramed(node, own, edges, measurer, fontSize, local, minWidth) {
     let block = { width: 0, height: 0 };
     if (banded) {
         if (contents.widths === 'match')
-            matchWidths(stacked);
+            matchWidths(stacked, local);
         block = layoutChildren(stacked, edges, measurer, fontSize, local);
         if (contents.widths === 'fill') {
             // The row is the text and whatever stands beside it, each at its gap.
@@ -1025,7 +1092,7 @@ function layoutFramed(node, own, edges, measurer, fontSize, local, minWidth) {
             }
             const across = Math.max(row, block.width);
             for (const child of stacked)
-                widenTo(child, across);
+                widenTo(child, across, local);
             block = layoutChildren(stacked, edges, measurer, fontSize, local);
             checkOneColumn(node, stacked, local);
         }
@@ -1720,6 +1787,15 @@ function partOf(target, part, owner, line) {
     };
     narrow('x', 'left', 'right');
     narrow('y', 'top', 'bottom');
+    // A circle has no corners, so a corner of one is the point on it halfway
+    // between the two sides named: on the outline, as a rectangle's corner is.
+    const across = words.includes('left') || words.includes('right');
+    const down = words.includes('top') || words.includes('bottom');
+    if (isCircle(target.node) && across && down) {
+        const pull = (target.width / 2) * (1 - Math.SQRT1_2);
+        box.offset.x += words.includes('left') ? pull : -pull;
+        box.offset.y += words.includes('top') ? pull : -pull;
+    }
     return box;
 }
 /** Where a node of this size sits so that the named side of it meets the span's. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {