reladraw 0.0.1 → 0.2.0

package/dist/constants.js

@@ -0,0 +1,189 @@
+import { SourceError } from './errors.js';
+/** Inside a box, between its border and its contents. */
+export const PAD = 14;
+/** Between stacked children of one container. */
+export const CHILD_GAP = 10;
+/** Between a container's own label and its first child. */
+export const HEADER_GAP = 10;
+/**
+ * How far each deck copy is offset behind the front face. It has to clear a
+ * whole line of text plus the padding above it, or a copy's label is drawn and
+ * then immediately covered by the copy in front of it.
+ */
+export const DECK_STEP = 34;
+/**
+ * The named gaps a placement may ask for, each a *minimum* distance rather than a
+ * fixed one. Anything the author puts between two things widens the space
+ * between them on its own, so no gap here ever has to be chosen large enough
+ * to leave room for something else.
+ */
+export const GAPS = {
+    // A zero gap turns an offset into edge-to-edge contact, so "my top edge
+    // against Docker's bottom edge" needs no vocabulary of its own.
+    none: 0,
+    tight: 24,
+    normal: 56,
+    wide: 110,
+};
+/**
+ * How far apart two boxes are pushed when they would otherwise overlap. Small
+ * on purpose: this is the tool enforcing something the author did not write, so
+ * the space it leaves should read as "these are not the same box" and never as
+ * a relationship someone stated. Say `gap:` if you want breathing room.
+ */
+export const SEPARATION_GAP = GAPS['tight'];
+/**
+ * Between two links meeting the same side of the same box. An author names a
+ * side, never a point on it, so this is the tool keeping two attachments apart
+ * rather than a distance anyone asked for — small, like `SEPARATION_GAP`, and
+ * squeezed further if the side is too short to hold the whole group.
+ */
+export const ATTACH_STEP = 16;
+/** Kept clear at each end of a side, so an attachment never sits on a corner. */
+export const ATTACH_MARGIN = 10;
+/** How wide a link's line is drawn. */
+export const LINE_WIDTH = 1.6;
+/**
+ * The arrowhead's length, in the `markerUnits="strokeWidth"` the marker is
+ * declared in, so its drawn length is this times `LINE_WIDTH`.
+ */
+export const ARROW_MARKER_WIDTH = 7;
+/**
+ * How much of the line an arrowhead covers. Derived rather than written down,
+ * because the resolver reserves it and the renderer draws it, and a number
+ * agreed by coincidence is a number that drifts.
+ */
+export const ARROW_LENGTH = ARROW_MARKER_WIDTH * LINE_WIDTH;
+/**
+ * Line left showing between a link's label and the box at that end of the
+ * corridor it crosses.
+ *
+ * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
+ * Those two keep two things from touching, and the least distance that reads as
+ * "not touching" is the right one. This one has something to show: a label sits
+ * in a knockout that erases the line behind it, so whatever is left either side
+ * is the entire evidence that the label belongs to a link at all. At ten pixels
+ * it did not read as a line — the seed diagram in the playground drew as a word
+ * with a dash beside it — so it is the length of a run of line, not a margin.
+ *
+ * Say `gap:` if you want the corridor wider than its contents.
+ */
+export const LABEL_CLEARANCE = 20;
+/**
+ * How much room a link's label takes along one axis.
+ *
+ * The knockout rectangle drawn behind a label is the text plus five either side,
+ * so that rectangle, not the glyphs, is what must not overlap anything.
+ *
+ * Shared by the resolver, which widens a corridor to hold a label, and the
+ * renderer, which spaces the lanes of a channel by it, so the two cannot
+ * disagree about how much room a label needs. The two ask different questions of
+ * it and both are right: the resolver measures *along* the run, so a link
+ * traveling horizontally needs the label's width; the renderer measures *across*
+ * the channel, so a link traveling horizontally down one needs its height.
+ */
+export function labelExtent(label, appearance, axis, measurer, fontSize, line) {
+    const size = fontSizeFor('link', appearance, fontSize, line);
+    const { width, lines } = measurer.measure(label, size);
+    return axis === 'x' ? width + 10 : lines.length * measurer.lineHeight(size);
+}
+/**
+ * An icon is two lines of the label tall, and that ratio is what makes it a
+ * *label-sized* ornament rather than a picture with a size of its own. It is
+ * read off the reference, where the title lines run 25 pixels baseline to
+ * baseline and the drive and machine glyphs are close to 50 tall. Deriving it
+ * from the text also means an icon on a `size: small` node shrinks with it,
+ * which is what anyone would expect and what a fixed pixel count would not do.
+ */
+export const ICON_LINES = 2;
+/** Between the label column and the icon column beside it. */
+export const ICON_GAP = 10;
+export const DEFAULT_FONT_SIZE = 14;
+/**
+ * The named text sizes, each a multiple of the document's own size. Named
+ * rather than numeric for the reason gaps are: a number here is typography by
+ * coordinate. It goes stale the moment the document is set at another size, and
+ * it says nothing about why one piece of text is smaller than another.
+ *
+ * `small` is sampled rather than chosen. In
+ * `examples/reference/arch.png` the box and container labels run 25
+ * pixels baseline to baseline and every annotation runs 21, which is this
+ * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
+ * taken the other way, so the scale is symmetric about the document size.
+ */
+export const TEXT_SIZES = {
+    small: 21 / 25,
+    normal: 1,
+    large: 25 / 21,
+};
+/**
+ * What each kind of text is set at when the file says nothing. A note annotates
+ * the diagram rather than being part of it, and at the size of a box label an
+ * aside reads as a statement — so `note` starts small and says so by being a
+ * note. This is a default and not a ceiling: `size:` overrides it, the same way
+ * `fill:` overrides the theme's color.
+ */
+const DEFAULT_TEXT_SIZE = { note: 'small' };
+/**
+ * The size a piece of text is set at. Shared by the resolver, which reserves
+ * the room, and the renderer, which fills it, so the two cannot disagree about
+ * how much room there is.
+ */
+export function fontSizeFor(kind, appearance, fontSize, line) {
+    const named = appearance['size'] ?? DEFAULT_TEXT_SIZE[kind] ?? 'normal';
+    const scale = TEXT_SIZES[named];
+    if (scale === undefined) {
+        throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')}, not "${named}"`, line);
+    }
+    return Math.round(fontSize * scale);
+}
+export const DEFAULT_MARGIN = 40;
+/**
+ * Where a container's own label sits. Every container reserves a band for its
+ * label and its icon; `at` says which end of the box that band is, and the
+ * contents take what is left. `align` says how the text sits across it.
+ *
+ * The two are independent and neither implies the other. A label at the bottom
+ * is an ordinary label that happens to be at the bottom — there is no kind of
+ * label being named here and no second thing quietly coming along with the
+ * first. An earlier version bundled them as `label: heading | caption`, which
+ * read a position as though it were a meaning; a folded corner means "artifact
+ * rather than process" and a reader decodes it, while "lower down" means only
+ * lower down.
+ *
+ * A leaf has no band, so `at` says nothing about one and is refused there. But
+ * `align` is not about the band: a label of more than one line has lines of
+ * unequal length whatever kind of box it is in, and how those sit across each
+ * other is a real question anywhere. A leaf's default is centered rather than
+ * ranged left, which is why the fallback is a parameter.
+ */
+export const LABEL_ENDS = ['top', 'bottom'];
+/**
+ * Author's word to the SVG's. One spelling of each, per the rule that refuses
+ * synonyms for `box` and `link`: an alias is a variant a reader has to learn,
+ * and every document and example has to pick one of them anyway.
+ */
+const LABEL_ALIGNMENTS = {
+    left: 'start',
+    center: 'middle',
+    right: 'end',
+};
+/**
+ * Read a label's bracketed modifiers. Shared by the resolver, which offsets the
+ * contents away from the band, and the renderer, which draws into it, so the two
+ * cannot disagree about which end the band is at.
+ */
+export function labelStyleFor(label, line, fallbackAlign = 'start') {
+    const at = label['at'];
+    if (at !== undefined && !LABEL_ENDS.includes(at)) {
+        throw new SourceError(`a label's at takes ${LABEL_ENDS.join(' or ')}, not "${at}"`, line);
+    }
+    const align = label['align'];
+    if (align !== undefined && LABEL_ALIGNMENTS[align] === undefined) {
+        throw new SourceError(`a label's align takes left, center or right, not "${align}"`, line);
+    }
+    return {
+        at: at ?? 'top',
+        align: align === undefined ? fallbackAlign : LABEL_ALIGNMENTS[align],
+    };
+}

package/dist/constrain.d.ts

@@ -0,0 +1,56 @@
+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

@@ -0,0 +1,95 @@
+/** 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();
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/** A problem in the source, reported in the vocabulary of the source. */
+export declare class SourceError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+    /** `12: two placements for "server"` — the form the command-line tool prints. */
+    format(file?: string): string;
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+/** A problem in the source, reported in the vocabulary of the source. */
+export class SourceError extends Error {
+    line;
+    constructor(message, line) {
+        super(message);
+        this.line = line;
+        this.name = 'SourceError';
+    }
+    /** `12: two placements for "server"` — the form the command-line tool prints. */
+    format(file) {
+        const where = file ? `${file}:${this.line}` : `line ${this.line}`;
+        return `${where}: ${this.message}`;
+    }
+}

package/dist/grammar.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The language's *lexical* vocabulary, and a scanner that classifies one line of
+ * source into colored spans.
+ *
+ * This is deliberately separate from `parser.ts`, and it is not a second parser.
+ * The parser answers "what does this file mean" and refuses anything it cannot
+ * answer for; a highlighter has to color a half-typed line without complaint,
+ * so it answers only "what kind of word is this" and never fails. Every rule
+ * below is a regex applied to a single line, in priority order, with one bit of
+ * carried state (whether anything has been seen on the line yet, and whether the
+ * previous token was an attribute key).
+ *
+ * **That restriction is the point, and it is what makes this reusable.** An
+ * Emacs `font-lock-keywords` list, a Vim `syntax match` file and a TextMate
+ * grammar are all exactly this: an ordered list of single-line regexes with a
+ * face attached. So the vocabulary here — which is the half that goes stale, and
+ * which is imported from `ast.ts`, `constants.ts` and `icons.ts` rather than
+ * retyped — can be emitted into any of those without this file being ported.
+ * The scanner is the JavaScript consumer of the same spec, and the playground is
+ * its only caller.
+ *
+ * Nothing in the language spans lines: `//` runs to the end of one, a string
+ * closes on one, and there are no blocks. That is the property those editor
+ * formats need and the reason a `.reladraw` grammar is small in all of them.
+ */
+/** What a span of source is, for coloring. */
+export type TokenKind = 
+/** `// to the end of the line` */
+'comment'
+/** A quoted string, quotes included. Unterminated ones count, so typing is quiet. */
+ | 'string'
+/** The word a statement opens with: `box`, `link`, … */
+ | 'keyword'
+/** The name a statement declares, right after its keyword. */
+ | 'name'
+/** `->` and `<->`. */
+ | 'arrow'
+/** Placement and link vocabulary: `right`, `of`, `level`, `with`, `and`, `between`, … */
+ | 'relation'
+/** A `key:` opening an attribute or a bracketed modifier. */
+ | 'attribute'
+/** The single word an attribute takes. */
+ | 'value'
+/** `#14532d`, wherever it appears. */
+ | 'color'
+/** `(` and `)` around a placement's or a label's modifiers. */
+ | 'bracket'
+/** Everything else: node names being referred to, and whitespace. */
+ | 'plain';
+export interface Span {
+    kind: TokenKind;
+    /** Half-open, in characters, into the line it came from. */
+    start: number;
+    end: number;
+}
+/**
+ * The words a statement may open with. `parseStatement` in `parser.ts` is the
+ * authority — its switch is what actually accepts them — and this list mirrors
+ * it. A word missing here is a word that draws in the plain color, which is a
+ * dull page rather than a wrong one.
+ */
+export declare const STATEMENT_KEYWORDS: readonly ["box", "note", "link", "deck", "style", "diagram"];
+/**
+ * Every word that says something about where a thing goes. Assembled from the
+ * lists the parser itself reads, so a direction or a passage axis added there
+ * colors here without anybody remembering to come back.
+ */
+export declare const RELATION_WORDS: string[];
+/**
+ * The patterns, as source strings, so a generator can emit them into another
+ * editor's grammar without reaching into a compiled RegExp. Each is written to
+ * match at the point the scanner has reached; the scanner adds the sticky flag.
+ *
+ * A name may contain dots (containment) and hyphens, which is why the word
+ * pattern is what it is rather than `\w+`.
+ */
+export declare const PATTERNS: {
+    readonly comment: "\\/\\/.*";
+    readonly string: "\"(?:\\\\.|[^\"\\\\])*\"?";
+    readonly keyword: `(?:${string})\\b`;
+    readonly arrow: "<->|->|<-";
+    readonly attribute: "[A-Za-z][A-Za-z0-9_-]*:";
+    readonly color: "#[0-9A-Fa-f]{3,8}\\b";
+    readonly relation: `(?:${string})\\b`;
+    readonly bracket: "[()]";
+    readonly word: "(?:[^\\s()\"\\/]|\\/(?!\\/))(?:[^\\s\"\\/]|\\/(?!\\/))*";
+    /**
+     * The same, inside an open bracket, where `)` closes the group instead of
+     * being an ordinary character. An editor grammar that cannot count brackets
+     * should use this one throughout: mistaking `rgb(20,20,20)` for three tokens
+     * is a smaller wrong than swallowing the `)` that ends `(gap: tight)`.
+     */
+    readonly wordInGroup: "(?:[^\\s()\"\\/]|\\/(?!\\/))(?:[^\\s)\"\\/]|\\/(?!\\/))*";
+};
+/**
+ * Classify one line. Always returns spans covering it end to end, in order, so a
+ * caller can rebuild the text by concatenation and can trust that nothing was
+ * dropped — which is what a highlighter drawn *behind* a textarea needs, since
+ * a lost character would slide every following one out of register.
+ */
+export declare function highlightLine(line: string): Span[];
+/** Every line of a source file, classified. Line endings are not included. */
+export declare function highlight(source: string): Span[][];