reladraw 0.15.1 → 0.17.0

package/dist/size.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A stated size: `height: 0.5 group height`, `width: a + b + 2`,
+ * `height: a top to c bottom`, `width: larger of a and b`, `height: 3 lines`.
+ *
+ * Read here once, by the parser, which checks it and stores it back as text
+ * with every word spaced out; the placing pass reads that text again and works
+ * the number out. A size ends at the first word that cannot continue it, so a
+ * placement can follow it on the same line: `height: a right of b`.
+ */
+import type { Token } from './lexer.js';
+export type Dimension = 'width' | 'height';
+export type SpanSide = 'top' | 'bottom' | 'left' | 'right' | 'center';
+export type SizeExpr = {
+    kind: 'number';
+    value: number;
+    unit: 'unit' | 'px' | 'lines' | 'chars';
+}
+/** Another box's measurement; no dimension means the one being stated. */
+ | {
+    kind: 'measure';
+    name: string;
+    dimension?: Dimension;
+}
+/** The box's own other measurement: `height: 0.75 width`. */
+ | {
+    kind: 'own';
+    dimension: Dimension;
+} | {
+    kind: 'span';
+    from: {
+        name: string;
+        side: SpanSide;
+    };
+    to: {
+        name: string;
+        side: SpanSide;
+    };
+} | {
+    kind: 'scale';
+    by: number;
+    of: SizeExpr;
+} | {
+    kind: 'sum';
+    terms: SizeExpr[];
+} | {
+    kind: 'pick';
+    which: 'larger' | 'smaller';
+    first: SizeExpr;
+    second: SizeExpr;
+};
+/** The keys that state a size, and the dimension each measures. */
+export declare const SIZE_KEYS: Record<string, Dimension>;
+/**
+ * Read a size starting at `at`. Returns it and the index of the first token
+ * after it.
+ */
+export declare function readSize(tokens: Token[], at: number, key: string, subject: string, line: number, stops: (token: Token) => boolean): {
+    size: SizeExpr;
+    next: number;
+};
+/** A size as text, every word spaced, which `readSize` reads back the same. */
+export declare function writeSize(size: SizeExpr): string;
+/** Read a stored size back. */
+export declare function storedSize(text: string, key: string, subject: string, line: number): SizeExpr;

package/dist/size.js

@@ -0,0 +1,222 @@
+import { isAttrKey } from './lexer.js';
+import { SourceError } from './errors.js';
+/** The keys that state a size, and the dimension each measures. */
+export const SIZE_KEYS = {
+    width: 'width',
+    height: 'height',
+    'min-width': 'width',
+    'max-width': 'width',
+    'min-height': 'height',
+    'max-height': 'height',
+};
+const SPAN_SIDES = ['top', 'bottom', 'left', 'right', 'center'];
+const RESERVED = new Set(['and', 'of', 'to', '+', '(', ')', 'larger', 'smaller']);
+const NUMBER = /^(\d*\.?\d+)(?:\/(\d*\.?\d+))?(px)?$/;
+/**
+ * Read a size starting at `at`. Returns it and the index of the first token
+ * after it.
+ */
+export function readSize(tokens, at, key, subject, line, stops) {
+    // `a+b` is `a + b`: how much whitespace there is never matters.
+    const spaced = [];
+    for (const [index, token] of tokens.entries()) {
+        if (index < at || token.quoted || token.text === '+' || !token.text.includes('+')) {
+            spaced.push(token);
+            continue;
+        }
+        token.text.split(/(\+)/).filter((part) => part.length > 0).forEach((part) => spaced.push({ text: part, quoted: false }));
+    }
+    const reading = { tokens: spaced, at, key, subject, line, stops };
+    if (!startsOperand(reading)) {
+        throw new SourceError(`${subject}: ${key}: takes a size, such as ${key}: 4, ${key}: 120px or ${key}: group ${SIZE_KEYS[key]}`, line);
+    }
+    const size = sum(reading);
+    refuseBracket(reading);
+    // Count back to the caller's tokens, which had `a+b` as one.
+    let next = at;
+    let consumed = 0;
+    for (let index = at; index < tokens.length && consumed < reading.at - at; index += 1) {
+        const token = tokens[index];
+        consumed += token.quoted || token.text === '+' || !token.text.includes('+')
+            ? 1
+            : token.text.split(/(\+)/).filter((part) => part.length > 0).length;
+        next = index + 1;
+    }
+    return { size, next };
+}
+/** A size as text, every word spaced, which `readSize` reads back the same. */
+export function writeSize(size) {
+    switch (size.kind) {
+        case 'number':
+            return size.unit === 'px' ? `${size.value}px` : size.unit === 'unit' ? `${size.value}` : `${size.value} ${size.unit}`;
+        case 'measure':
+            return size.dimension ? `${size.name} ${size.dimension}` : size.name;
+        case 'own':
+            return size.dimension;
+        case 'span':
+            return `${size.from.name} ${size.from.side} to ${size.to.name} ${size.to.side}`;
+        case 'scale': {
+            const inner = writeSize(size.of);
+            return `${size.by} ${size.of.kind === 'sum' ? `( ${inner} )` : inner}`;
+        }
+        case 'sum':
+            return size.terms.map(writeSize).join(' + ');
+        case 'pick':
+            return `${size.which} of ( ${writeSize(size.first)} ) and ( ${writeSize(size.second)} )`;
+    }
+}
+/** Read a stored size back. */
+export function storedSize(text, key, subject, line) {
+    const tokens = text.split(' ').map((word) => ({ text: word, quoted: false }));
+    return readSize(tokens, 0, key, subject, line, () => false).size;
+}
+function peek(reading, ahead = 0) {
+    return reading.tokens[reading.at + ahead];
+}
+function isWord(reading, word, ahead = 0) {
+    const token = peek(reading, ahead);
+    return token !== undefined && !token.quoted && token.text === word;
+}
+/** A word that could be a box's name here. */
+function isName(reading, token) {
+    if (!token || token.quoted || isAttrKey(token))
+        return false;
+    if (RESERVED.has(token.text) || reading.stops(token))
+        return false;
+    return /^[A-Za-z_][\w.-]*$/.test(token.text);
+}
+function startsOperand(reading) {
+    const token = peek(reading);
+    if (!token || token.quoted || isAttrKey(token))
+        return false;
+    return (NUMBER.test(token.text) ||
+        token.text === '(' ||
+        token.text === 'larger' ||
+        token.text === 'smaller' ||
+        token.text === 'width' ||
+        token.text === 'height' ||
+        isName(reading, token) ||
+        token.text.startsWith('-'));
+}
+function sum(reading) {
+    const terms = [scaled(reading)];
+    while (isWord(reading, '+')) {
+        reading.at += 1;
+        if (!startsOperand(reading)) {
+            throw new SourceError(`${reading.subject}: ${reading.key}: ends with a +, which has nothing to add`, reading.line);
+        }
+        terms.push(scaled(reading));
+    }
+    refuseStar(reading);
+    return terms.length === 1 ? terms[0] : { kind: 'sum', terms };
+}
+function refuseStar(reading) {
+    const token = peek(reading);
+    if (token && !token.quoted && token.text.includes('*')) {
+        throw new SourceError(`${reading.subject}: ${reading.key}: scales by writing the number in front — ${reading.key}: 0.5 group, not 0.5 * group`, reading.line);
+    }
+}
+/** `height: group (at most: 30)`: a bracket of settings, which a size never takes. */
+function refuseBracket(reading) {
+    if (!isWord(reading, '('))
+        return;
+    let settings = false;
+    for (let ahead = 1; peek(reading, ahead) && !isWord(reading, ')', ahead); ahead += 1) {
+        if (isAttrKey(peek(reading, ahead)))
+            settings = true;
+    }
+    if (!settings)
+        return;
+    const dimension = SIZE_KEYS[reading.key];
+    throw new SourceError(`${reading.subject}: ${reading.key}: takes no bracket — a limit is its own key, min-${dimension}: or max-${dimension}:, ` +
+        'since a bracket reads as belonging to whatever it sits beside', reading.line);
+}
+function scaled(reading) {
+    const token = peek(reading);
+    if (token.text.startsWith('-')) {
+        throw new SourceError(`${reading.subject}: ${reading.key}: a size is never negative, so ${token.text} is not one`, reading.line);
+    }
+    const number = NUMBER.exec(token.text);
+    if (!number)
+        return atom(reading);
+    reading.at += 1;
+    const value = number[2] === undefined ? Number(number[1]) : Number(number[1]) / Number(number[2]);
+    if (number[3])
+        return { kind: 'number', value, unit: 'px' };
+    if (isWord(reading, 'lines') || isWord(reading, 'chars')) {
+        const unit = peek(reading).text;
+        reading.at += 1;
+        return { kind: 'number', value, unit };
+    }
+    refuseStar(reading);
+    const next = peek(reading);
+    const scales = next !== undefined &&
+        !next.quoted &&
+        (next.text === '(' || next.text === 'larger' || next.text === 'smaller' || next.text === 'width' ||
+            next.text === 'height' || isName(reading, next));
+    if (!scales)
+        return { kind: 'number', value, unit: 'unit' };
+    return { kind: 'scale', by: value, of: atom(reading) };
+}
+function atom(reading) {
+    const token = peek(reading);
+    const { subject, key, line } = reading;
+    if (token.text === '(') {
+        refuseBracket(reading);
+        reading.at += 1;
+        const inner = sum(reading);
+        if (!isWord(reading, ')'))
+            throw new SourceError(`${subject}: ${key}: opens a bracket it never closes`, line);
+        reading.at += 1;
+        return inner;
+    }
+    if (token.text === 'larger' || token.text === 'smaller') {
+        const which = token.text;
+        if (!isWord(reading, 'of', 1)) {
+            throw new SourceError(`${subject}: ${key}: ${which} chooses between two — ${which} of a and b`, line);
+        }
+        reading.at += 2;
+        const first = sum(reading);
+        if (!isWord(reading, 'and')) {
+            throw new SourceError(`${subject}: ${key}: ${which} of names two sizes, joined by and — ${which} of a and b`, line);
+        }
+        reading.at += 1;
+        if (!startsOperand(reading)) {
+            throw new SourceError(`${subject}: ${key}: ${which} of a and … names nothing after and`, line);
+        }
+        const second = sum(reading);
+        return { kind: 'pick', which, first, second };
+    }
+    if (token.text === 'width' || token.text === 'height') {
+        reading.at += 1;
+        return { kind: 'own', dimension: token.text };
+    }
+    if (!isName(reading, token)) {
+        throw new SourceError(`${subject}: ${key}: "${token.text}" is not a size or the name of a box`, line);
+    }
+    reading.at += 1;
+    const name = token.text;
+    const after = peek(reading);
+    if (after && !after.quoted && SPAN_SIDES.includes(after.text) && isWord(reading, 'to', 1)) {
+        reading.at += 2;
+        const far = peek(reading);
+        const side = peek(reading, 1);
+        // `a top to c right of b`: the far side is missing, and a placement follows.
+        const placed = isWord(reading, 'of', 2);
+        if (!isName(reading, far) || !side || side.quoted || !SPAN_SIDES.includes(side.text) || placed) {
+            throw new SourceError(`${subject}: ${key}: a span names a side at each end — ${name} ${after.text} to c ${after.text === 'top' ? 'bottom' : after.text}`, line);
+        }
+        reading.at += 2;
+        return {
+            kind: 'span',
+            from: { name, side: after.text },
+            to: { name: far.text, side: side.text },
+        };
+    }
+    if (isWord(reading, 'width') || isWord(reading, 'height')) {
+        const dimension = peek(reading).text;
+        reading.at += 1;
+        return { kind: 'measure', name, dimension };
+    }
+    return { kind: 'measure', name };
+}

package/dist/themes.d.ts

@@ -45,6 +45,23 @@ export interface Accent {
     /** Text on a solid fill of `color`: `theme-on-primary`. */
     on: string;
 }
+/**
+ * A venn's overlap when it states no fill: the theme's secondary at its subtle
+ * strength laid over the left set's fill, so the shared part reads as both
+ * sets at once. A left fill that can't be measured is taken as the theme's
+ * primary-subtle, the left set's default.
+ */
+export declare function overlapFill(under: string, theme: Theme): string;
+/**
+ * A region's fill when it states none (design.org 8.3): the theme's primary
+ * mixed toward the page, so that drawn at a region's half opacity it reads as
+ * the primary at 12% did, the tint regions have always had. A page color that
+ * can't be measured keeps the primary itself, at a quarter of the opacity.
+ */
+export declare function regionTint(theme: Theme, opacity: number): {
+    color: string;
+    opacity: number;
+};
 export declare const THEME_COLORS: readonly string[];
 /** A color as written, with a `theme-` word replaced by the theme's value. */
 export declare function themeColor(value: string, theme: Theme): string;

package/dist/themes.js

@@ -3,6 +3,30 @@ const SUBTLE = 0.25;
 function accent(color, page, on, subtle = mix(color, page, SUBTLE)) {
     return { color, subtle, on };
 }
+/**
+ * A venn's overlap when it states no fill: the theme's secondary at its subtle
+ * strength laid over the left set's fill, so the shared part reads as both
+ * sets at once. A left fill that can't be measured is taken as the theme's
+ * primary-subtle, the left set's default.
+ */
+export function overlapFill(under, theme) {
+    const base = /^#[0-9a-f]{6}$/i.test(under) ? under : theme.primary.subtle;
+    return mix(theme.secondary.color, base, SUBTLE);
+}
+/**
+ * A region's fill when it states none (design.org 8.3): the theme's primary
+ * mixed toward the page, so that drawn at a region's half opacity it reads as
+ * the primary at 12% did, the tint regions have always had. A page color that
+ * can't be measured keeps the primary itself, at a quarter of the opacity.
+ */
+export function regionTint(theme, opacity) {
+    const hex = /^#[0-9a-f]{6}$/i;
+    if (!hex.test(theme.primary.color) || !hex.test(theme.background))
+        return { color: theme.primary.color, opacity: opacity * REGION_TINT };
+    return { color: mix(theme.primary.color, theme.background, REGION_TINT), opacity };
+}
+/** How much of the primary a region's own tint keeps, so that at half opacity it is 12% of it. */
+const REGION_TINT = 0.24;
 /** `amount` of `color` over `page`, both `#rrggbb`. */
 function mix(color, page, amount) {
     const channel = (hex, at) => parseInt(hex.slice(at, at + 2), 16);
@@ -92,10 +116,11 @@ export const DARK_THEME = {
     iconInk: '#8d8d8e',
     iconShade: '#3e3d58',
     // The reference's two colored boxes: `synced` is the green, `dump` the red.
-    // Their fills are sampled rather than mixed, so the benchmark written in
-    // theme colors renders exactly as it did in hex.
+    // The green's fill is sampled rather than mixed, so the benchmark written in
+    // theme colors renders as it did in hex. The red's is mixed, as every other
+    // theme's is: the sampled #460000 glared across a venn's whole set.
     primary: accent('#486544', '#111111', '#d9d9d9', '#142814'),
-    secondary: accent('#8f3a3a', '#111111', '#d9d9d9', '#460000'),
+    secondary: accent('#8f3a3a', '#111111', '#d9d9d9'),
 };
 /** The dark theme's counterpart: the same roles, on a white page. */
 const LIGHT_THEME = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "prepublishOnly": "npm run build",
     "preversion": "./dev.sh check-version \"$npm_new_version\"",
     "dev": "tsc --watch",
-    "example": "npm run build && node dist/cli.js examples/arch.reladraw -o examples/out/arch.svg"
+    "example": "npm run build && node dist/cli.js render examples/arch.reladraw -o examples/out/arch.svg"
   },
   "engines": {
     "node": ">=18"

package/dist/constrain.d.ts

@@ -1,56 +0,0 @@
-import type { Placement } from './ast.js';
-/**
- * The tightest arrangement satisfying a set of relative distances.
- *
- * Every placement in the language turns into the same shape of fact: one thing sits
- * at least so far along an axis from another. Written as `pos[to] >= pos[from]
- * + weight`, a whole diagram is a system of those, and the arrangement the
- * author meant is the one where nothing is further apart than it has to be.
- *
- * That arrangement is unique and is found by longest paths, so no search
- * happens and no alternative is ever weighed. Distances come out of the
- * arithmetic; which side of what a thing sits on came from the author.
- */
-export interface Constraint {
-    from: number;
-    to: number;
-    weight: number;
-    /** The placement this came from, so a failure can be reported in the author's words. */
-    placement?: Placement;
-}
-/** An exact distance, which is two inequalities pointing opposite ways. */
-export declare function fix(from: number, to: number, distance: number, placement?: Placement): Constraint[];
-export interface Contradiction {
-    /** The placements that cannot all hold. Empty if the loop is entirely implicit. */
-    placements: Placement[];
-}
-/**
- * Solve, or report the placements that fight.
- *
- * Longest path from a virtual source joined to everything at zero, which is
- * Bellman-Ford with the comparison flipped. A distance that keeps growing after
- * one pass per node means the constraints run in a circle that demands ever
- * more room, and that circle is exactly the set of placements to quote back.
- */
-export declare function tightest(count: number, constraints: Constraint[]): {
-    positions: number[];
-} | {
-    contradiction: Contradiction;
-};
-/**
- * Which members can be driven apart from which, along one axis.
- *
- * A constraint says `pos[to] >= pos[from] + weight`, so it bounds `to` from
- * below and leaves it free to move further away. Follow those edges and the
- * question "may this one end up beyond that one?" becomes plain reachability:
- * if `j` is reachable from `i` and `i` is not reachable from `j`, then the file
- * lets the distance from `i` to `j` grow without limit and never lets it be
- * closed from the other side. Pushing `j` past `i` is then the one separation
- * the file allows, and no choice was made.
- *
- * Reachable both ways means the two are pinned at a fixed distance, so they
- * cannot be separated along this axis at all. Reachable neither way means the
- * file said nothing that orders them, which is the case the caller must refuse
- * rather than guess at.
- */
-export declare function reachability(count: number, constraints: Constraint[]): boolean[][];

package/dist/constrain.js

@@ -1,95 +0,0 @@
-/** An exact distance, which is two inequalities pointing opposite ways. */
-export function fix(from, to, distance, placement) {
-    return [
-        { from, to, weight: distance, ...(placement ? { placement } : {}) },
-        { from: to, to: from, weight: -distance, ...(placement ? { placement } : {}) },
-    ];
-}
-/**
- * Solve, or report the placements that fight.
- *
- * Longest path from a virtual source joined to everything at zero, which is
- * Bellman-Ford with the comparison flipped. A distance that keeps growing after
- * one pass per node means the constraints run in a circle that demands ever
- * more room, and that circle is exactly the set of placements to quote back.
- */
-export function tightest(count, constraints) {
-    const positions = new Array(count).fill(0);
-    const cameFrom = new Array(count).fill(undefined);
-    for (let pass = 0; pass < count; pass += 1) {
-        let moved = false;
-        for (const constraint of constraints) {
-            const candidate = positions[constraint.from] + constraint.weight;
-            if (candidate > positions[constraint.to] + 1e-9) {
-                positions[constraint.to] = candidate;
-                cameFrom[constraint.to] = constraint;
-                moved = true;
-            }
-        }
-        if (!moved)
-            return { positions };
-    }
-    // Still moving after a full pass per node, so some loop demands more room
-    // every time round it. Walk backwards to find it.
-    for (const constraint of constraints) {
-        if (positions[constraint.from] + constraint.weight > positions[constraint.to] + 1e-9) {
-            return { contradiction: { placements: loopFrom(constraint.to, cameFrom, count) } };
-        }
-    }
-    return { contradiction: { placements: [] } };
-}
-/**
- * Which members can be driven apart from which, along one axis.
- *
- * A constraint says `pos[to] >= pos[from] + weight`, so it bounds `to` from
- * below and leaves it free to move further away. Follow those edges and the
- * question "may this one end up beyond that one?" becomes plain reachability:
- * if `j` is reachable from `i` and `i` is not reachable from `j`, then the file
- * lets the distance from `i` to `j` grow without limit and never lets it be
- * closed from the other side. Pushing `j` past `i` is then the one separation
- * the file allows, and no choice was made.
- *
- * Reachable both ways means the two are pinned at a fixed distance, so they
- * cannot be separated along this axis at all. Reachable neither way means the
- * file said nothing that orders them, which is the case the caller must refuse
- * rather than guess at.
- */
-export function reachability(count, constraints) {
-    const reach = Array.from({ length: count }, () => new Array(count).fill(false));
-    for (const constraint of constraints)
-        reach[constraint.from][constraint.to] = true;
-    for (let via = 0; via < count; via += 1) {
-        for (let from = 0; from < count; from += 1) {
-            if (!reach[from][via])
-                continue;
-            for (let to = 0; to < count; to += 1) {
-                if (reach[via][to])
-                    reach[from][to] = true;
-            }
-        }
-    }
-    return reach;
-}
-/** The placements on the loop reached by following each position back to what set it. */
-function loopFrom(start, cameFrom, count) {
-    let at = start;
-    for (let step = 0; step < count; step += 1) {
-        const previous = cameFrom[at];
-        if (previous === undefined)
-            break;
-        at = previous.from;
-    }
-    const placements = [];
-    const seen = new Set();
-    let cursor = at;
-    while (!seen.has(cursor)) {
-        seen.add(cursor);
-        const previous = cameFrom[cursor];
-        if (previous === undefined)
-            break;
-        if (previous.placement)
-            placements.push(previous.placement);
-        cursor = previous.from;
-    }
-    return placements.reverse();
-}