reladraw 0.26.1 → 0.28.0

package/examples/shapes.reladraw

@@ -0,0 +1,38 @@
+// What a node is drawn as. `shape:` is the outline it is drawn with; `icon:` is
+// a picture it is drawn as, with no box at all.
+
+style artifact  fill: theme-secondary-subtle  border: theme-border  shape: document
+
+// The fold is a fixed size rather than a fraction of the box, so it looks the
+// same on all three of these.
+node narrow "Report"  style: artifact
+node medium "Nightly database dump"        right of narrow (gap: tight)  style: artifact
+node wide   "A very much longer file name than either of the other two"  right of medium (gap: tight)  style: artifact
+
+// A picture has no outline, no fill and no padding. The text goes underneath.
+node services ""  below narrow  shape: none
+node services.web    "web"                          icon: cube
+node services.api    "api"     right of services.web (gap: tight)  icon: cube
+node services.worker "worker"  right of services.api (gap: tight)  icon: cube
+
+// No text at all: a picture usually is the statement, so it gets no caption.
+node bare1  below services  icon: cube
+node bare2  below bare1 (gap: tight)  icon: cube
+
+// A picture body is an ordinary node, so it takes edges and sides like any
+// other. That is what it buys over a badge, which cannot be the end of an arrow.
+node sink "collector"  right of bare1 and bare2 (gap: wide)
+edge bare1 -> sink  from: right  to: left
+edge bare2 -> sink  from: right  to: left
+
+// Any icon works as a body, not just the cube.
+node store  below bare2  icon: database
+node drive  right of store (gap: tight)  icon: disk
+
+// `(inside bottom)` puts the title under the contents, centered along that side.
+// The lower cube is centered under the upper pair by naming both of them and
+// nothing else.
+node pool "Worker pool" (inside bottom)  right of store and drive (gap: wide)
+node pool.one  icon: cube
+node pool.two  right of pool.one (gap: tight)  icon: cube
+node pool.three  below pool.one and pool.two (gap: tight)  icon: cube

package/examples/snug.reladraw

@@ -0,0 +1,8 @@
+// A node sits exactly where its placements say: a gap is the distance asked
+// for, not a minimum.
+
+node anchor "anchor"
+node far    "far"   right of anchor
+node near   "near"  right of far
+
+node trailing "one tight gap from near"  left of near (gap: tight)  below anchor (gap: tight)  overlap: allow  shape: none

package/examples/text.reladraw

@@ -0,0 +1,69 @@
+// An edge's text takes no room of its own: the gap it sits in is the one the
+// placements say, so a text that needs room is given it by stating the gap.
+
+style plain  fill: theme-fill  border: theme-border
+
+// A `normal` gap is sized for two nodes to breathe, not to hold a word, so a
+// word that needs more is given it by stating the gap, here in units.
+node parser   "Parser"                           style: plain
+node resolver "Resolver"  right of parser (gap: 10)  style: plain
+edge parser -> resolver  "statements"  from: right  to: left
+
+// Going downward the text is only a line deep, and it hangs out either side.
+//
+// Written with `<-`, which draws the same picture as `writer -> disk`. It just
+// puts the node the line is about first. `from:` is still the first name
+// written, so it names Disk's side.
+node writer "Writer"  right of resolver (gap: wide)  style: plain
+node disk   "Disk"    below writer (gap: wide)      style: plain
+edge disk <- writer  "flushed to disk"  from: top  to: bottom
+
+// Corner to corner, the text sits at the middle of the line, so the gap is
+// stated on both axes.
+node high "High"  right of writer (gap: wide)  style: plain
+node low  "Low"   below high (gap: wide)  right of high (gap: wide)  style: plain
+edge high -> low  "diagonal"
+
+
+// --- What the brackets after a text say ------------------------------------
+// A container's title says which side it sits against, and `align` where along
+// that side, which also ranges its lines against each other.
+
+style dim  text: (color: theme-muted)
+
+node shelf "Shelf" (inside bottom, align: right)  below disk (gap: wide)  left even with parser  style: plain
+node shelf.one "first"   style: plain
+node shelf.two "second"  below shelf.one (gap: tight)  style: plain
+
+// A box is usually the size of its own text. A picture beside the text is two
+// lines tall, and lining the picture's top or bottom up with the text's puts
+// the text at the top or bottom of the box. Joined to the text, the picture and
+// the text are centered in the box together.
+node tall "Top"     right of shelf (gap: wide)  style: plain
+node tall.disk  icon: disk  1 right of tall text  top even with tall text  join-with: tall text
+node deep "Bottom"  below tall (gap: tight)  style: plain
+node deep.disk  icon: disk  1 right of deep text  bottom even with deep text  join-with: deep text
+
+// Marked words take their style's size as well as its color. A line that is
+// all small is spaced as a small line, and a small word mid-line sits on the
+// same baseline as its neighbors.
+style note  text: (size: small, color: theme-muted)
+node synced "Shared folder / [note]synced 2 min ago[/note] / 3 [note]files[/note] waiting"  below deep (gap: tight)  style: plain
+
+// `size` and `wrap` are properties of the text too. The wrap is a count of
+// characters, not a distance: it says how much fits on a line and nothing
+// about where anything sits.
+node aside "A quiet remark that folds itself, with [dim]one word[/dim] quieter than the rest." (size: small, wrap: 28)  right of tall (gap: wide)  shape: none
+
+// A literal bracket is written \[, since [ opens markup.
+node literal "sizes \[small, normal, large]"  below aside (gap: tight)  shape: none
+
+// An edge's text takes the same brackets. A size may be a multiple of normal,
+// such as 1.2, or pixels, such as 12px, as well as a name.
+edge tall -> aside  "carried" (color: theme-muted, size: 12px)  from: right  to: left
+
+// `reads: up` or `down` turns a text a quarter turn, so a title on a left or
+// right side takes a column one line wide rather than one word wide.
+node rack "Rack" (inside left, reads: up)  right of aside (gap: wide)  top even with tall  layout: column (gap: tight)  style: plain
+node rack.web "web"  style: plain
+node rack.db  "db"   style: plain

package/examples/themes.reladraw

@@ -0,0 +1,16 @@
+// A diagram that states no color of its own, so every color in it is the
+// theme's. Render it in each theme to compare them.
+
+style quiet  text: (color: theme-muted, size: small)
+
+node web     "Web app"  badge: laptop
+node api     "API server"                          10 right of web
+node cluster "Workers" (inside top, align: left)  6 below api
+node cluster.a "worker a"
+node cluster.b "worker b"                          right of cluster.a (gap: tight)
+node db      "Records"  icon: database             10 right of api
+node note    "Backed up nightly / to cold storage"  below db  shape: none  style: quiet
+
+edge web -> api "HTTPS"
+edge api -> cluster "jobs"
+edge api -> db "queries"

package/examples/urls.reladraw

@@ -0,0 +1,35 @@
+// `url:` makes a node or an edge clickable. The whole thing is the target — the
+// box and everything drawn in it, or an edge's text — and nothing about it
+// looks any different, because a destination is content rather than appearance
+// and nothing else in the language lets content reach the ink.
+//
+// The value is quoted. Without the quotes everything from the `//` onwards is a
+// comment, which is why the error for the bare form talks about punctuation.
+
+style plain  fill: theme-fill  border: theme-border
+
+node docs "Documentation"  style: plain  url: "https://example.com/docs"
+
+// A container's destination reaches its children: `intro` has none of its own
+// and follows the container, while `deep` overrules it inside its own box.
+node site "Handbook" (inside top, align: left)  right of docs (gap: wide)  layout: column (align-children: left)  url: "https://example.com/"
+node site.intro  "Introduction"  style: plain
+node site.deep   "Deep dive"  style: plain  url: "https://example.com/deep"
+
+// A picture and a bodiless node take one too. There is no kind that cannot.
+node store  icon: database  below docs (gap: wide)  url: "https://example.com/store"
+node aside  "and this line is a link as well"  shape: none  right of store  url: "https://example.com/aside"
+
+// An edge's text is what carries the destination. An edge with no text may
+// have one too: an unseen wider copy of the line takes the click.
+edge docs -> store "read first"  from: bottom  to: top  url: "https://example.com/order"
+
+// A long address is declared once under a name, with its name and badge, and
+// used by that name. A declaration may also list several links, a bundle, and
+// a `url:` mixes names and quoted addresses in the order written.
+url orders-docs   "https://docs.example.com/orders/v2/reference/endpoints" (name: "Docs", icon: "D" (fill: #3a6ea5, text: white))
+url orders-code   "https://github.com/example/orders/tree/main/services/api" (name: "Code", icon: "C")
+url orders-links  orders-docs  orders-code  "https://wiki.example.com/teams/orders" (name: "Wiki")
+
+node api     "Orders API"  style: plain  below store (gap: wide)  url: orders-links
+node worker  "Worker"  style: plain  right of api  url: orders-docs  "https://example.com/runbooks/worker" (name: "Runbook")

package/examples/venn.reladraw

@@ -0,0 +1,15 @@
+// A PDF template is made at design time and used at runtime, so it sits where the two overlap.
+
+node phases ""  layout: venn (gap: 12)
+node phases.design  "Design time" (inside top, align: left)
+node phases.both    ""
+node phases.runtime "Runtime" (inside top, align: right)
+
+node phases.design.editor    "Editor"
+node phases.both.template    "PDF template"
+node phases.runtime.python   "Python Lib"  even with phases.both.template
+node phases.runtime.report   "Report PDF"  below phases.runtime.python (gap: wide)
+
+edge phases.design.editor -> phases.both.template      "generate"
+edge phases.both.template -> phases.runtime.python     "import"
+edge phases.runtime.python -> phases.runtime.report    "generate"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   "files": [
     ".claude/skills",
     "dist",
+    "examples/*.reladraw",
     "NOTICE",
     "SYNTAX.md"
   ],

package/dist/search.d.ts

@@ -1,104 +0,0 @@
-/**
- * Finding a line's way through the open space between boxes.
- *
- * Every box is a wall. A line may turn only where two tracks cross, and the
- * tracks are few: a line a little way out from each side of each wall, one
- * down the middle of each gap between walls, and the lines through the two
- * ends. That is the whole of the open space a right-angled line ever needs,
- * reduced to a grid of a few hundred points for a diagram of ordinary size.
- *
- * The line leaves its start heading straight out and arrives at its end heading
- * straight in, with a straight stretch at each end at least `stub` long, so an
- * arrowhead always lands on a straight piece. Between those two stretches it
- * takes the cheapest way through the grid, where cost is length plus a charge
- * for every turn and for every line already placed that it crosses. On a
- * right-angled grid many ways tie on length — a staircase is exactly as long as
- * one bend — and the turn charge breaks those ties toward the fewest bends,
- * which is the line a person would draw. What still ties after that goes over
- * the top rather than under, and round the right rather than the left.
- *
- * A way through a box is not a losing option here. It is not a way at all.
- */
-export interface SearchPoint {
-    x: number;
-    y: number;
-}
-/** A box the line may not enter, as its extent. Touching its border is allowed. */
-export interface SearchWall {
-    minX: number;
-    minY: number;
-    maxX: number;
-    maxY: number;
-}
-/** One end of the line: a point on a box's side, and the unit direction out of it. */
-export interface SearchEnd {
-    x: number;
-    y: number;
-    dx: number;
-    dy: number;
-}
-export interface SearchOptions {
-    /** How far the line runs straight out of each end before it may turn. */
-    stub: number;
-    /** How far outside a wall a track runs beside it, where there is room. */
-    clear: number;
-    /** What a turn costs, in the same units as length. */
-    turn: number;
-    /**
-     * Walls the stretches at the two ends may pass through: the line's own boxes,
-     * which it has to cross the margin of to leave, and any box holding an end.
-     */
-    ownStart: SearchWall[];
-    ownEnd: SearchWall[];
-    /**
-     * Lines already placed. A line may cross one but not run along it within
-     * `lane` of it; tracks are added a lane either side of each, so a later line
-     * sharing a stretch takes the next lane out.
-     */
-    taken: SearchPoint[][];
-    lane: number;
-    /**
-     * For each line in `taken`, for each of its stretches, half the depth across
-     * it of a text riding there, and 0 where none does. A line running beside a
-     * stretch carrying a text keeps clear of the text, not just of the line.
-     */
-    takenHalves?: number[][];
-    /**
-     * A gap the line must pass through: somewhere it crosses the line at `at`
-     * on the `run` axis, travelling along `run`, at a level between `lo` and `hi`.
-     */
-    gate?: SearchGate;
-    /**
-     * Half the depth of this line's own text, which rides in the gate: inside it,
-     * the line keeps that much further from the lines beside it.
-     */
-    ownHalf?: number;
-    /**
-     * How far the line may go at all: the diagram with room round it. A wall
-     * reaching past this — a clause's fence, which runs to the edge of the page —
-     * cannot be gone round at its far end.
-     */
-    bounds?: SearchWall;
-    /**
-     * A cost the line is no use at unless it comes in under: the cheapest way
-     * already found between another pair of sides. The search gives up as soon
-     * as it cannot.
-     */
-    limit?: number;
-}
-/** A gap a line must pass through. See `SearchOptions.gate`. */
-export interface SearchGate {
-    run: 'x' | 'y';
-    at: number;
-    lo: number;
-    hi: number;
-}
-export interface SearchResult {
-    points: SearchPoint[];
-    cost: number;
-}
-/**
- * The cheapest right-angled line from `start` to `end` that enters no wall, or
- * undefined when there is none.
- */
-export declare function searchRoute(start: SearchEnd, end: SearchEnd, walls: SearchWall[], options: SearchOptions): SearchResult | undefined;