reladraw 0.15.1 → 0.17.0

package/dist/place.d.ts

@@ -0,0 +1,501 @@
+/**
+ * Where every box goes, and how big each container is.
+ *
+ * Nothing here is solved and nothing is pushed. A placement gives a box an
+ * exact distance from its target, each axis of each box comes from exactly one
+ * statement, and a box is worked out from things already worked out, in
+ * whatever order its targets allow. A container is the outline of its children
+ * plus its padding. Two boxes the file puts on one spot are drawn there, and
+ * the findings report it.
+ *
+ * Every quantity is worked out on demand and remembered: a box's start on an
+ * axis, its size, and a container's frame. A box asked for while it is still
+ * being worked out is a circle in the file, reported with the placements that
+ * make it.
+ *
+ * Coordinates are per frame. The top level's frame is the page. A container's
+ * children are placed in its own frame, whose origin is wherever its anchor
+ * landed, and the container's box is found around them; a child's place on the
+ * page is its container's plus its offset in that frame.
+ */
+import type { Axis, PlacementTarget, PointStmt, RegionStmt } from './ast.js';
+import { type LayoutNode } from './model.js';
+/** A stretch of one axis. */
+interface Extent {
+    start: number;
+    size: number;
+}
+/** Where a container's title sits: against which side, and how. */
+export interface TitlePlace {
+    /** `inside`, `on` or `outside` a side, or `center` for the middle of the box. */
+    how: 'inside' | 'on' | 'outside' | 'center';
+    side: 'top' | 'bottom' | 'left' | 'right' | 'center';
+    /** Along the side: the start (left or top), the middle, or the end. */
+    along: 'start' | 'center' | 'end';
+}
+/** A region's text as the placer needs it: its turned size, its gap, and where it sits. */
+export interface RegionTextFacts {
+    width: number;
+    height: number;
+    gap: number;
+    how: 'inside' | 'on' | 'outside';
+    side: 'top' | 'bottom' | 'left' | 'right';
+    along: 'start' | 'center' | 'end';
+}
+/**
+ * How a region grows to hold its text, on one axis (design.org 7.4). Inside,
+ * it gains a band on that side as tall as the text and its gap, as a container
+ * makes room for its title; inside or on the border, it widens to hold the
+ * text along the side, from the end the text is aligned to. Outside, nothing.
+ */
+export declare function regionGrown(extent: Extent, text: RegionTextFacts, axis: Axis): Extent;
+/**
+ * Where a region's text sits on one axis, against the region as drawn (already
+ * grown): a gap inside or outside the side, or across the border; along the
+ * side, at its start, middle or end, held off the corner by the gap except
+ * outside, where its end is even with the region's edge, as a title's is.
+ */
+export declare function regionTextAt(region: Extent, text: RegionTextFacts, axis: Axis): Extent;
+/** What `layout:` said, read and checked. */
+export interface Layout {
+    /** A deck stacks its children, the first in front and each next one up and to the left behind it. */
+    kind: 'column' | 'row' | 'deck';
+    /** Between facing sides of neighbors, in pixels. Absent when `centers` is given. */
+    gap?: number;
+    /** Between neighbors' centers, in pixels. */
+    centers?: number;
+    widths: 'natural' | 'match' | 'fill';
+    /** `align-children:`: the children's starts, middles or ends even with each other. */
+    align: 'start' | 'center' | 'end';
+}
+/** What `layout: venn` said: its three parts in order, whether the two sets share a height, and the gap outside each crossing border. */
+export interface Venn {
+    heights: 'natural' | 'equal';
+    gap: number;
+    /** `align-children:`: the two sets lined up by their tops, middles or bottoms. */
+    align: 'start' | 'center' | 'end';
+    /** The left set, the overlap, the right set. */
+    parts: [LayoutNode, LayoutNode, LayoutNode];
+}
+/** What the tree pass settled about each node before anything is placed. */
+export interface NodeFacts {
+    /** The size the node's own contents give it: a leaf's text and padding, a picture. Zero for a container. */
+    natural: {
+        width: number;
+        height: number;
+    };
+    /** The text's ink box from the node's top-left, as a leaf is sized. */
+    textBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Whether the node has any text. An empty text takes no room. */
+    hasText: boolean;
+    /** `padding:`, which a title keeps its inset by. */
+    padding: number;
+    /** Each side's padding: `padding:`, or `padding-right:` and the rest over it. */
+    pad: Record<'top' | 'right' | 'bottom' | 'left', number>;
+    /** One line of the node's text, and one character, for sizes in `lines` and `chars`. */
+    lineHeight: number;
+    charWidth: number;
+    title: TitlePlace;
+    layout?: Layout;
+    venn?: Venn;
+    circle: boolean;
+    /** Where `gather-children:` puts the children in the box's spare room, on each axis. */
+    gather: Record<Axis, 'start' | 'center' | 'end'>;
+}
+/**
+ * A gap as written: a gap word, a number in the file's unit, or a number of
+ * pixels with `px`. A distance is never negative; the words for an overlap are
+ * `inside` and `on`.
+ */
+export declare function gapPixels(written: string, subject: string, line: number): number;
+/**
+ * A region's `opacity:`, an amount from none to full: `0` to `1.0`. The one
+ * look whose bare number is not a multiple of its normal (design.org 8.3).
+ */
+export declare function checkOpacity(value: string, subject: string, line: number): void;
+export declare class Placer {
+    private readonly roots;
+    private readonly byName;
+    private readonly facts;
+    /** Named points and regions (design.org 4.5), worked out wherever they are used. */
+    private readonly named;
+    /** A region's text, which may grow the region to hold it (design.org 7.4). */
+    private readonly regionTexts;
+    private readonly starts;
+    private readonly sizes;
+    private readonly frames;
+    private readonly outlines;
+    private readonly working;
+    /** What is being worked out, innermost last, for reporting a circle. */
+    private readonly trail;
+    /** A node's size on its own, from what it states or holds, within its limits. */
+    private readonly owns;
+    /** A layout's child's position and size on each axis, worked out for the whole layout at once. */
+    private readonly laid;
+    /** Where each of a venn's parts' frames sits in the venn's, on each axis. */
+    private readonly vennPlans;
+    /** Where one venn part's frame sits in the venn's, up and down. */
+    private readonly vennShifts;
+    /** The band a laid-out container's children are aligned in, across its layout. */
+    private readonly bands;
+    /** Where a node joined to its container's text starts, measured from the text's start. */
+    private readonly unitStarts;
+    /** The stretch a container's text and what is joined to it cover, measured from the text's start. */
+    private readonly units;
+    /** Where a container's frame's origin is on the page. */
+    private readonly origins;
+    /** Containers whose anchor is being placed on the page, so a box outside them is measured on the page rather than in their frame. */
+    private readonly onPage;
+    /** Named points and regions being worked out, innermost last, to refuse one defined through itself. */
+    private readonly expanding;
+    constructor(roots: LayoutNode[], byName: Map<string, LayoutNode>, facts: Map<LayoutNode, NodeFacts>, 
+    /** Named points and regions (design.org 4.5), worked out wherever they are used. */
+    named?: Map<string, PointStmt | RegionStmt>, 
+    /** A region's text, which may grow the region to hold it (design.org 7.4). */
+    regionTexts?: Map<string, RegionTextFacts>);
+    /**
+     * Where each named point and region is on the page. A point names one spot,
+     * so one that works out to a stretch (a side, a whole box) is refused.
+     */
+    placeNamed(): Map<string, {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Where a target is on the page once everything is placed: a box, a side (a
+     * stretch on one axis), a point, a named point or region. For a line's
+     * `via:` stops (design.org 6.4).
+     */
+    locate(target: PlacementTarget, subject: string, line: number): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Work out everything, and write it onto the nodes. */
+    run(): void;
+    /** Where a node starts on the page. */
+    page(node: LayoutNode, axis: Axis): number;
+    /**
+     * Where a container's frame's origin is on the page. A container that says
+     * nothing about where it goes shares its own container's origin, so it is
+     * known without its outline; one placed by what it holds is where its
+     * anchor goes; any other is found from where its box went.
+     */
+    private origin;
+    /**
+     * A container that says where it goes on one axis cannot also hold a child
+     * placed against a box outside it on that axis: both would say where the
+     * container goes, and it is refused even when the two agree.
+     */
+    private refusePlacedTwice;
+    /** The origin a box outside `parent` is measured from: the page while `parent`'s anchor is being placed on it. */
+    private originFor;
+    /** Where the anchor of a container placed by what it holds goes on the page, which is its frame's origin. */
+    private anchorOnPage;
+    /**
+     * A container that is its frame's anchor: it says nothing about where it
+     * goes, and nothing inside it is placed against a box outside it in its
+     * stead. Its frame's origin is its own container's.
+     */
+    private floats;
+    /**
+     * A container placed by what it holds, on one axis (design.org 5.5): it
+     * says nothing about where it goes, nothing inside it is its anchor, and a
+     * child is placed against boxes outside it. The first such child is the
+     * frame's anchor, and where it goes says where the container goes.
+     */
+    private frameAnchor;
+    /** A box that says nothing about where it goes, and so anchors its frame. */
+    private unplaced;
+    /** Whether everything a box is placed against on one axis is outside `of`. */
+    private fromOutside;
+    /** The boxes a target is worked out from: the box it names, or those a point or region it names is worked out from. */
+    private boxesNamed;
+    /** Where a node starts in its container's frame, or on the page for the top level. */
+    start(node: LayoutNode, axis: Axis): number;
+    size(node: LayoutNode, axis: Axis): number;
+    /** A container's box and title in its own frame, at the size it ends up. */
+    private frame;
+    /** A container's outline around what it holds, before anything states its size. */
+    private outline;
+    private remember;
+    /**
+     * Work something out, refusing a circle. The trail holds what was being
+     * worked out on the way here, and the placements that asked for each.
+     */
+    private guard;
+    private circle;
+    private workOutStart;
+    /** Where a node joined to its container's text starts, from the text's start. */
+    private unitStart;
+    /** A box's start from its own placements. */
+    private placed;
+    private edgeOf;
+    /** A box's start from one statement. */
+    private apply;
+    /**
+     * Nothing states this axis. A lone direction on the other axis centers the
+     * box on its target here, since walking right from something keeps you on
+     * its center line. Two of them leave it open which target to center on, and
+     * that is refused rather than decided.
+     */
+    private lone;
+    /**
+     * The stretch of this box a placement measures from, from the box's start:
+     * the part it names, or the whole box.
+     */
+    private ownPart;
+    private overStated;
+    /** Every statement a node's placements make about one axis. */
+    private statements;
+    /** A direction with nothing said about its distance, which a pin on its axis may refine. */
+    private yields;
+    /**
+     * The sides that gave up their distance to a pin still have to hold: a box
+     * said to be below another, and pinned beside it, is refused.
+     */
+    private checkYielded;
+    /**
+     * Two alignments pinning opposite edges: `top even with a  bottom even with
+     * c` positions the box and sizes it, and counts as one statement.
+     */
+    private pins;
+    /** The gap a placement leaves, in pixels. */
+    private gapOf;
+    /** The extent on one axis of what a placement names: one target, or the region bounding several. */
+    private region;
+    /**
+     * One target's extent on one axis, in the frame `node` is placed in: a
+     * point written out, a named point or region, a fraction of the way across
+     * a box, or a box and its part.
+     */
+    private extentOf;
+    /**
+     * A fraction of the way across `whole` on its own axis (`3/4 down`, `1/3
+     * across from right`). On the other axis it is the side it runs along, or
+     * the whole box when it was written first.
+     */
+    private alongFraction;
+    /** A named point or region, worked out in the frame `node` is placed in, with a region's padding. */
+    private namedExtent;
+    /** A point written out, on one axis. */
+    private pointExtent;
+    /**
+     * `between a and b`: the space between two things. On an axis where they are
+     * apart it is the gap, from `a`'s facing side to `b`'s; where they overlap,
+     * the stretch they share. As a point it is the middle of that, or `at` the
+     * fraction of the gap from `a`. As a region (`region` given) it is the whole
+     * of it, and `(span: both)` stretches it over both boxes where they overlap
+     * (design.org 4.2).
+     */
+    private betweenOf;
+    /**
+     * `down from a and left from b`: where a line straight down from `a` meets
+     * one straight left from `b`. The words also say which way the point lies
+     * from each, and that is checked (design.org 4.3).
+     */
+    private crossingOf;
+    /** A box, or a part of one, on one axis, in the frame `node` is placed in. */
+    private nodeExtent;
+    /** A node's text on one axis, given where the node starts. */
+    private textOf;
+    /** A child placed against its own container's box, which it does not grow. */
+    framed(node: LayoutNode): boolean;
+    /**
+     * A child placed against its container's text, or against its heading,
+     * which makes the title its frame's anchor.
+     */
+    private onTitle;
+    /** The stretch a container's text and what is joined to it cover, measured from the text's start. */
+    private unit;
+    /** Whether anything is joined to a container's text. */
+    private hasUnit;
+    /** How big a container's own text is on one axis, without what is joined to it. */
+    private textSize;
+    /**
+     * Whether a container's title anchors its frame, because a child is placed
+     * against it. A title placed against the children is a link between them
+     * instead, and the child it is placed against anchors the frame.
+     */
+    private anchoredOnTitle;
+    /**
+     * 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.
+     */
+    private contentOf;
+    /** Whether a node has a title: its text, what is joined to it, or a heading. */
+    private hasTitle;
+    /** How big a container's title is on one axis: its heading, or its text with what is joined to it. */
+    private titleSize;
+    /**
+     * Where a container's title sits. A heading, or a text with something joined
+     * to it, over nothing else is centered, as a leaf's text is, unless its
+     * bracket says where.
+     */
+    private titleOf;
+    /**
+     * A node's size: from two pinned edges, from its layout's stretching, or from
+     * what it states or holds. Each axis's size is stated once, so a size key
+     * beside pins or a stretching layout is refused.
+     */
+    private workOutSize;
+    /** Whether a laid-out container sets its children's size on this axis. */
+    private stretches;
+    /** A node's size from what it states, or else what it holds, within its limits. */
+    private ownSize;
+    /** What a node's own contents make it, before anything stretches it. */
+    private naturalSize;
+    /** Work out one size key's value, in pixels. */
+    private measure;
+    private evaluate;
+    /** The box a size names. */
+    private sized;
+    /**
+     * `a top to c bottom`: the distance between two edges. Both are found in the
+     * frame of the innermost container holding them both, so a span between two
+     * children never waits on their container's box.
+     */
+    private span;
+    /**
+     * Whether `named` sits inside a sibling within `frame`'s frame, with every
+     * container between them placed in that frame rather than by what it holds.
+     */
+    private nestedInFrame;
+    /** Where a node starts in the frame of `frame`, one of its containers, or on the page when that is undefined. */
+    private within;
+    /**
+     * A container on one axis: its box in its own frame, and where its title
+     * sits. The box is the outline of what it holds, plus padding: the children
+     * not placed against the box itself, and the title when it sits inside the
+     * border or on it.
+     */
+    private workOutFrame;
+    /**
+     * A container's box at the size it ends up, when something states one: its
+     * outline grown or shrunk so what it holds sits where gather-children: says,
+     * the middle unless it says, and its title moved with the side it keeps to. A title something
+     * is placed against is part of what it holds, and stays.
+     */
+    private fit;
+    /** The title's placements that state one axis. */
+    private titleStatementsOn;
+    /** Whether the title's bracket places it on this axis with a placement. */
+    private titleStates;
+    /**
+     * Where a title placed against the box's own children starts on one axis,
+     * in the box's frame, or undefined when no placement states the axis and
+     * its side words place it (design.org 7.2). Each axis is stated once.
+     */
+    private titlePlaced;
+    /** Where one placement of a title against the box's own children puts the title's start. */
+    private titleStart;
+    /** The padded-in block of a circle on the other axis, which its diameter depends on as well. */
+    private innerOther;
+    /**
+     * A child of a laid-out container: placed by the layout, in written order,
+     * and never by itself.
+     */
+    private inLayout;
+    /** Which part of a venn a node is: 0 the left set, 1 the overlap, 2 the right set. */
+    private vennPart;
+    /** The outline of what a venn's part holds, in its own frame. The overlap's includes its title's width. */
+    private partContent;
+    /**
+     * Where each part's own frame sits in the venn's: what to add to a part's
+     * coordinates. Across, the left set's contents, the overlap's and the right
+     * set's in that order. The border between a pair is the crossing set's
+     * padding from what is inside it, and the venn's gap from what is outside it,
+     * as a box beside a container would be. Up and down, see `vennShift`.
+     */
+    private vennPlan;
+    /**
+     * Where a part's frame sits in the venn's up and down. A part whose anchor
+     * is placed against a box in another part goes where that puts the anchor;
+     * the set that moves to line the two sets' tops or bottoms up goes there
+     * (`vennAlign`); otherwise its contents are centered on the line every
+     * unplaced part shares.
+     */
+    private vennShift;
+    /**
+     * Which set moves to line up the two sets' tops or bottoms, and by which edge.
+     * `top even with` between the sets is a relation between them, not an order
+     * to move the one it's written on: only where they sit against each other
+     * shows, since the venn wraps them both. So the set it's written on moves,
+     * unless what it would move to meet moves with it (the overlap or the other
+     * set placed against it); then the other set moves, if nothing holds it.
+     * A stagger on a set whose contents are held in place says where its box
+     * goes, not its contents (`boxOnly`): the box starts there and still holds
+     * what it wraps.
+     */
+    private vennAlign;
+    /** Whether a venn part moves with `part`: its anchor is placed against a box in `part`, directly or through the third part. */
+    private leansOn;
+    /** The part of the same venn that this part's anchor is placed against, if it has one. */
+    private anchorPart;
+    /** Whether `named` is a child of a different part of the venn `node`'s part belongs to. */
+    private inOtherPart;
+    /** A child of a venn's part placed against a box in another part, which `checkAnchors` lets only the part's anchor be. */
+    private acrossParts;
+    /** The overlap's contents in a set's own frame, which the set's box wraps as well as its own. */
+    private vennPhantom;
+    /** Where a venn's part starts in the venn's frame. */
+    private vennStart;
+    /** A venn's part's size: a set wraps what it holds, or takes the box `vennBox` gives it; the overlap is where they cross. */
+    private vennSize;
+    /**
+     * A set's box up and down in the venn's frame, where it is not just the
+     * outline round what it holds. With `heights: equal`, the span from the
+     * higher set's top to the lower one's bottom, which both boxes then cover,
+     * so they start and end together however their contents are lined up; a set
+     * staggered by `top even with 2 below …` keeps its stagger, its box the span
+     * moved by that much. A stagger that places only the box (`vennAlign`'s
+     * `boxOnly`) moves the side it names, and the box must still hold its contents.
+     */
+    private vennBox;
+    /** Where a venn's two sets cross, in the venn's frame. */
+    private strip;
+    /**
+     * The overlap's frame: the strip where the sets cross, with no border of its
+     * own. Its title is centered across the strip, on the row of the title of
+     * the set whose top is lower, so the strip's contents start below it.
+     */
+    private stripFrame;
+    /**
+     * Exactly one box in each frame says nothing about where it goes, and every
+     * other is placed against it, directly or through others. In a container a
+     * title something is placed against anchors the frame instead.
+     */
+    private checkAnchors;
+    /**
+     * 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
+     * part's anchor, say nothing else, and say nothing across, which is the venn's.
+     */
+    private checkAcrossParts;
+    /** The text box, how far the node reaches past its own box, and the flags the renderer reads. */
+    private finish;
+    /**
+     * Where a leaf's text sits, from the leaf's top-left. Centered unless its
+     * bracket says a side, and then where a container's title would be: inside,
+     * on or outside that side, at the start, middle or end along it. A picture
+     * and a circle keep their text where their shape puts it.
+     */
+    private leafText;
+    /**
+     * How far a node reaches past its own box on one axis: its title outside the
+     * border, and its children, with whatever they reach in turn. A container's
+     * outline holds what its children reach, so it is worked out as soon as a
+     * container asks, not after everything is placed.
+     */
+    private reachOf;
+}
+export {};