@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/engine/text-measure.d.ts

@@ -0,0 +1,116 @@
+/**
+ * How wide label text is, in ems of the font it's drawn with. In a browser,
+ * names are measured with the fonts the page gives the map's labels (each
+ * theme's, a node type's own, a page's brand font), so a name fills its
+ * node as far as it really reaches and never spills out of it. Where there's
+ * no canvas to measure with (a server, tests), widths are estimated from the
+ * kind of each character.
+ */
+import type { OrbitNode } from '../types.js';
+import type { MapExtensions } from '../extensions.js';
+import type { NodeRole } from './scene.js';
+/** Text widths in one font. */
+export interface TextMeasure {
+    /** Equal keys measure alike: caches of fitted labels are kept by it. */
+    readonly key: string;
+    /** Whether widths in ems differ by font size (fonts with optical sizes); estimates don't. */
+    readonly bySize: boolean;
+    /** The width of `text` on one line at `fontSize` px, in ems. */
+    ems(text: string, fontSize: number): number;
+    /** The space between two words, in ems. */
+    space(fontSize: number): number;
+    /** The ellipsis a cut name ends with, in ems. */
+    ellipsis(fontSize: number): number;
+    /** How wide the font draws, as `font-stretch` (a percentage of its normal width). */
+    readonly stretch: number;
+    /**
+     * The same font drawn narrower, for names that don't fit at its width,
+     * or null when it has no narrower width (most fonts don't: only those
+     * with a width axis or condensed faces do).
+     */
+    narrower(): TextMeasure | null;
+}
+/** The measures a map's labels are fitted with: names inside nodes, pills beside them, and the "+N" names keep clear of. */
+export interface LabelMeasures {
+    /** Equal keys measure alike. */
+    readonly key: string;
+    /** For a node's name inside it. */
+    inside(role: NodeRole, node?: OrbitNode): TextMeasure;
+    /** For a node's name on its pill. */
+    pill(role: NodeRole, node?: OrbitNode): TextMeasure;
+    /** For the "+N" a node shows for children that aren't drawn. */
+    count(): TextMeasure;
+}
+/** A name inside its node: semibold UI fonts average a little under 0.58 em a character. */
+export declare const INSIDE_ESTIMATE: TextMeasure;
+/** A name on a pill: 6.4 px a character in its 11.5 px text. */
+export declare const PILL_ESTIMATE: TextMeasure;
+/** A "+N": its plus sign and figures, in semibold text, take a little over two thirds of an em each. */
+export declare const COUNT_ESTIMATE: TextMeasure;
+/** Estimates for every label, where nothing can be measured. */
+export declare const ESTIMATED_LABELS: LabelMeasures;
+/** What a label's font is, as the page computes it. */
+export interface LabelFont {
+    family: string;
+    weight: string;
+    style: string;
+    /** `font-stretch`, as a percentage of the normal width. */
+    stretch: number;
+    /** Space after each character, in ems. */
+    letterSpacing: number;
+}
+/** The measure for a font, or null when nothing can measure it. */
+export declare const measureFor: (font: LabelFont) => TextMeasure | null;
+/**
+ * Calls `listener` whenever measurements start over: a font finished loading,
+ * so text measured while the page drew it with a fallback measures anew.
+ * Returns a function that stops listening.
+ */
+export declare const onMeasurementsReset: (listener: () => void) => () => void;
+/** Forgets every measurement, and tells whoever keeps fits made from them. */
+export declare const resetMeasurements: () => void;
+/**
+ * The fonts a map's labels are drawn with, read from the page: a hidden
+ * label of each kind in the map's label layer, so the theme, the page's
+ * own CSS and a node type's tokens all count. Read again when `refresh` is
+ * called (the theme or the page may have changed), not on every frame.
+ */
+export declare class LabelFonts implements LabelMeasures {
+    private readonly layer;
+    private readonly extensions;
+    /** A hidden box in the label layer holding a label of each kind, to read its font from. */
+    private shelf;
+    private probes;
+    /** By kind of label (and node type with a font of its own); null where nothing measures. */
+    private measures;
+    /** The sun's and other nodes' measures, for nodes without a type: looked up for every label on every frame. */
+    private sunMeasure;
+    private nameMeasure;
+    /** The "+N"'s measure: looked up for every label on every frame. */
+    private countMeasure;
+    private stale;
+    private currentKey;
+    /** A recheck waiting for the page to be idle (see `recheckWhenIdle`). */
+    private recheck;
+    constructor(layer: HTMLElement, extensions: () => MapExtensions | undefined);
+    /** Equal keys measure alike: a change of font changes the key. */
+    get key(): string;
+    /** The theme, the page or the fonts may have changed: read the fonts again before the next fit. */
+    refresh(): void;
+    inside(role: NodeRole, node?: OrbitNode): TextMeasure;
+    pill(role: NodeRole, node?: OrbitNode): TextMeasure;
+    count(): TextMeasure;
+    /**
+     * Once the page is idle, reads the fonts again and calls `changed` if they
+     * differ: a page may switch its fonts at any time (a class, a brand font).
+     * Off the frames that draw, so reading doesn't make one late.
+     */
+    recheckWhenIdle(changed: () => void): void;
+    /** Takes the hidden labels out of the page. */
+    destroy(): void;
+    private read;
+    private measure;
+    private measureOf;
+    /** The font of a hidden element of `className` (a label, or a "+N") in the label layer, with a node type's `tokens`. */
+    private computedFont;
+}

package/dist/core/engine/views.d.ts

@@ -0,0 +1,361 @@
+/**
+ * DOM views for the map content. Nodes are SVG groups drawn at unit radius
+ * and positioned with a single `translate() scale()`, so moving or resizing
+ * a node is one attribute write per frame; spinning an orbit turns the group
+ * its bodies are in instead (see `OrbitTurn`). Labels are HTML in screen
+ * space, so text never scales with the camera and keeps a readable size.
+ */
+import type { OrbitNode } from '../types.js';
+import type { DisplayNode, DisplayRing, DisplaySlot } from './display.js';
+import type { NodeRole } from './scene.js';
+import type { MapExtensions, OrbitNodeType } from '../extensions.js';
+import { type TextMeasure } from './text-measure.js';
+import { OrbitWords } from '../languages.js';
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+export interface ViewIds {
+    /** Unit-circle clip path shared by every node image. */
+    clip: string;
+    /** Sphere shading gradient. */
+    shade: string;
+    /**
+     * The shading of specks: the same, turned back by the turn they're drawn in
+     * once their orbit rests, so it comes from the top left (see `turnShading`).
+     */
+    speckShade: string;
+    /** Blur for the shadow (or glow) of planets and moons. */
+    shadow: string;
+    /** A wider blur for the sun's. */
+    sunShadow: string;
+}
+export declare const svgElement: <Name extends keyof SVGElementTagNameMap>(name: Name, attributes?: Record<string, string>) => SVGElementTagNameMap[Name];
+/**
+ * Where the sphere shading changes, from the lit side (top left) to the far
+ * edge. The theme colors each stop (`node-highlight`, `node-terminator`,
+ * `node-shading`); the stylesheet and the SVG export share these offsets.
+ */
+export declare const SHADE_STOPS: readonly [{
+    readonly offset: 0;
+    readonly part: "highlight";
+}, {
+    readonly offset: 0.45;
+    readonly part: "highlight-fade";
+}, {
+    readonly offset: 0.55;
+    readonly part: "terminator-start";
+}, {
+    readonly offset: 0.78;
+    readonly part: "terminator";
+}, {
+    readonly offset: 1;
+    readonly part: "shading";
+}];
+/**
+ * The circle the shading spreads over, in fractions of a node's box: its
+ * center, then its radius. The default lights spheres from the top left; a
+ * theme moves it with the `node-shade-circle` token, such as to the bottom
+ * right so the far stops catch light along the top left rim, as glass does.
+ */
+export interface ShadeCircle {
+    x: number;
+    y: number;
+    radius: number;
+}
+export declare const DEFAULT_SHADE_CIRCLE: ShadeCircle;
+/** A `node-shade-circle` value (`0.34 0.3 0.78`) read, or the default when it isn't three numbers with a radius above 0. */
+export declare const readShadeCircle: (value: string | undefined) => ShadeCircle;
+/** Moves the shading of every node (specks follow it) to the theme's circle. */
+export declare const placeShading: (defs: SVGDefsElement, ids: ViewIds, circle: ShadeCircle) => void;
+/** Blur radius of a shadow, in node radii: planets and moons, then the sun. */
+export declare const SHADOW_BLUR: {
+    readonly planet: 0.16;
+    readonly sun: 0.3;
+};
+/** Shared definitions: the image clip, sphere shading and shadow blurs, with instance-scoped ids. */
+export declare const createDefinitions: (ids: ViewIds) => SVGDefsElement;
+/**
+ * Turns the shading of specks back by `turn` degrees, the turn they're drawn
+ * in, so their light comes from the top left. One write for every speck, but
+ * the browser draws each of them again: not on every frame of a spin.
+ */
+export declare const turnShading: (defs: SVGDefsElement, ids: ViewIds, turn: number) => void;
+/** Labels and the assistive name of a node, in the map's language (English without one). */
+export declare const describeNode: (node: OrbitNode, hiddenChildren: number, visibleChildren: number, extensions?: MapExtensions, words?: OrbitWords) => string;
+/**
+ * The on-screen radius (px) below which flat bodies are specks, at
+ * `pixelRatio` device pixels per px: bigger for a `plainCrowded` planet, one
+ * of a crowded orbit without badges (a status, a note's marker, a play button).
+ */
+export declare const speckRadius: (pixelRatio: number, plainCrowded?: boolean) => number;
+/** What every node is drawn with this frame, besides its own place (see `NodeView.update`). */
+export interface NodeDrawing {
+    /** In an orbit turned as one, the degrees it's turned (see `OrbitTurn`). */
+    turn?: number;
+    /** The on-screen radius (px) below which flat bodies are specks (see `speckRadius`). */
+    speckRadius: number;
+    /** The same for a crowded orbit's planets without badges. */
+    crowdedSpeckRadius: number;
+    /**
+     * How many more nodes may become specks, or stop being them, this frame.
+     * The rest wait for the next: a zoom across the size where a whole orbit
+     * becomes specks doesn't redraw all of it at once.
+     */
+    switches: number;
+    /** Set when a node is waiting for its turn to switch. */
+    waiting: boolean;
+    /**
+     * During a flight bodies don't become specks: one shrinking as the camera
+     * pulls away costs less to leave as it is until the flight lands.
+     */
+    flight: boolean;
+}
+/**
+ * Whether a body leaves out its blurred shadow (and hidden halo): when it's
+ * too small on screen for a shadow to show, a planet of a crowded orbit,
+ * where shadows overlap into a haze, or one coming or going in a flight,
+ * fading in or out while the camera sweeps past it (and may draw it huge).
+ * Blurring hundreds of shadows on every frame is also what makes a crowded
+ * orbit or a flight slow.
+ */
+export declare const drawsFlat: (display: DisplayNode, screenRadius: number) => boolean;
+export declare class NodeView {
+    readonly element: SVGGElement;
+    readonly id: string;
+    readonly node: OrbitNode;
+    /** The type the node was drawn as. One given for display can change with the map around it, and the view is drawn again then. */
+    readonly typeName: string | undefined;
+    /** Shows a picture (an image, or a video's thumbnail) rather than a plain color. */
+    hasImage: boolean;
+    /** Shows a status, a note's marker or a play button: a crowded orbit's planet with one stays a body down to the usual size (see `speckRadius`). */
+    private readonly hasBadges;
+    private readonly body;
+    private readonly disc;
+    private readonly shade;
+    private readonly shadeFills;
+    private readonly shadowFilters;
+    /**
+     * Created once a node shows them: a shadow when it's drawn with one (not
+     * the hundreds of flat planets of a crowded orbit, or overview nodes), the
+     * halo when it becomes the sun, the focus ring when it's focused.
+     */
+    private shadow;
+    private halo;
+    private focusRing;
+    private status;
+    private role;
+    private color;
+    private visible;
+    /** Where the node was last drawn, and how: what its transform (or a speck's circles) is worked out from. */
+    private drawn;
+    private transform;
+    private opacity;
+    private editing;
+    private lifted;
+    private dropTarget;
+    private flat;
+    private crowded;
+    private speck;
+    private turnedBack;
+    constructor(display: DisplayNode, screenRadius: number, ids: ViewIds, baseUrl: string | undefined, extensions: MapExtensions, drawing?: NodeDrawing, onImageError?: () => void);
+    /**
+     * Draws the node as `display` places it, `screenRadius` px across on screen.
+     *
+     * A speck (see `speckRadius`) is drawn with its circles' own coordinates
+     * instead of a transform, its badges left out: the browser handles a
+     * thousand of them far faster that way, as long as they hold still. A node
+     * `moving` on its own (one travelling in a flight) is drawn as a body:
+     * moving it is one write instead of one per circle.
+     *
+     * In an orbit turned as one (see `OrbitTurn`), a body that turns with it is
+     * drawn where it is in the unturned orbit: a speck turns with the orbit,
+     * shading and all, and anything bigger is turned back upright.
+     */
+    update(display: DisplayNode, screenRadius?: number, drawing?: NodeDrawing, moving?: boolean): void;
+    /** Whether it was last drawn turned back upright in an orbit turned as one: it moves as the orbit turns. */
+    get isTurnedBack(): boolean;
+    /** Draws the node as a speck from now on, or as a body again. */
+    private setSpeck;
+    /** Puts a speck's circles at (`x`, `y`), `radius` in size, in the map's own units. */
+    private placeSpeck;
+    /** The circles a body draws at unit radius around its center, and a speck at its own place. */
+    private unitCircles;
+    /** The fill as the browser resolved it (theme tokens and color mixes included). */
+    resolvedFill(): string;
+    /** Marks the node whose text is being edited on the map. */
+    setEditing(editing: boolean): void;
+    /** Held up by a press, to be dragged somewhere else: it grows, its shadow deepens. */
+    setLifted(lifted: boolean): void;
+    /** Where a node being dragged would go if let go now: it grows to take it, ringed. */
+    setDropTarget(target: boolean): void;
+    /** Adds the ring that shows while the node has keyboard focus or is being edited. */
+    showFocusRing(): void;
+}
+/**
+ * The free place in the orbit for a new idea: a dashed circle with a plus,
+ * drawn at unit radius like a node. While a new idea is typed there, it
+ * fills in around the field.
+ */
+export declare class AddSlotView {
+    readonly element: SVGGElement;
+    private shown;
+    private pending;
+    private drop;
+    private label;
+    private transform;
+    private opacity;
+    get isShown(): boolean;
+    /** `held`: the place held for a node being dragged, which only shows, rather than the + to press. */
+    constructor(held?: boolean);
+    /**
+     * Draws the slot where `slot` says, or hides it. `label` names it for
+     * assistive technology. `drop` shows it as the place held open for a node
+     * being dragged, without its plus: the `target`, or `waiting` while the
+     * node is over another one. In an orbit turned `turn` degrees, it's drawn
+     * where it is in the unturned orbit, turned back upright.
+     */
+    update(slot: DisplaySlot | undefined, label: string, pending: boolean, turn?: number, drop?: 'target' | 'waiting' | false): void;
+}
+/** CSS hooks for a node's element and label: `data-orbit-type`, `data-orbit-status` and `data-orbit-tags`. */
+export declare const markNode: (element: HTMLElement | SVGElement, node: OrbitNode, type?: string | undefined) => void;
+/** A node type's theme tokens, set on its node's elements so they win over the map's theme there. */
+export declare const applyTypeTokens: (element: HTMLElement | SVGElement, type: OrbitNodeType | undefined) => void;
+/** The picture a node shows: its image, or its video's thumbnail. */
+export declare const nodeThumbnail: (node: OrbitNode) => string | undefined;
+/** Inside the node, as a pill outside it, or not shown. */
+export type LabelPlacement = 'inside' | 'outside' | 'hidden';
+/** The width (px) of a label typed into a node of this on-screen radius. Snapped to 6 px steps so zooming doesn't re-wrap text every frame. */
+export declare const insideLabelWidth: (role: NodeRole, screenRadius: number) => number;
+/**
+ * The font size (px) of text typed into a node: the role's size, reduced
+ * (down to its minimum) until the longest word fits on one line.
+ */
+export declare const insideFontSize: (role: NodeRole, width: number, text: string, measure?: TextMeasure) => number;
+export interface InsideLabelLayout {
+    /** Width of the text block (px): its widest line's room. */
+    width: number;
+    fontSize: number;
+    /** The name as it shows, line by line; the last ends with an ellipsis when the name is cut short. */
+    lines: string[];
+    /** Whether the node's icon shows above its name. */
+    icon: boolean;
+    /** The name doesn't fit whole. */
+    truncated: boolean;
+    /** A narrower width of the font the name is drawn in, as `font-stretch` (a percentage), when it needs one to fit. */
+    stretch?: number;
+    /** How far above the node's center (px) the lines and icon are centered: they rise to clear the node's "+N". */
+    lift: number;
+}
+/**
+ * The "+N" of a node with children that aren't drawn (the renderer's
+ * `paintCounts`) is centered this share of the node's radius right of and
+ * below the node's center.
+ */
+export declare const COUNT_POSITION = 0.74;
+/** A "+N" is this tall (px): its line and padding, as the stylesheet sets them. */
+export declare const COUNT_HEIGHT = 15;
+/** Whether a node of this role and on-screen radius shows a "+N" for children that aren't drawn (flights and faded nodes hide it for a while). */
+export declare const showsCount: (role: NodeRole, screenRadius: number, hiddenChildren: number) => boolean;
+/** How wide (px) a node's "+N" is for `hiddenChildren` children, in `measure` (the font it's drawn in). */
+export declare const measureCount: (hiddenChildren: number, measure?: TextMeasure) => number;
+/** How far below its node's center (px) a name laid out inside it reaches: its lines and icon are centered `lift` above it. */
+export declare const insideLabelReach: (layout: InsideLabelLayout) => number;
+/**
+ * How a node's name fits inside it at this on-screen radius, or null when it
+ * doesn't. The name shrinks (down to the role's minimum) and wraps (at
+ * spaces, and inside long words where they read), its lines balanced and
+ * each as wide as the circle is where it sits. The icon above it stays while
+ * the name only shrinks a little. A name too long to fit whole even then
+ * shows as much as fits, ending with an ellipsis, as long as that's enough
+ * to read. `measure` measures the text in the font it's drawn with (by
+ * default, widths are estimated).
+ *
+ * A name that doesn't fit at its font's width tries narrower ones (see
+ * `fitInside`) only when `narrower` allows, as it does while the map is
+ * still: while the map moves, trying hundreds of names in each width would
+ * make frames late. A fit already made with them is kept, though.
+ *
+ * A node showing a "+N" `countWidth` px wide (see `measureCount`) keeps its
+ * name clear of it: the name rises above it, or gets smaller.
+ */
+export declare const insideLabelLayout: (role: NodeRole, screenRadius: number, text: string, hasIcon?: boolean, measure?: TextMeasure, narrower?: boolean, countWidth?: number) => InsideLabelLayout | null;
+/**
+ * Where a node's label goes at this on-screen size. A name goes inside its
+ * node whenever it fits there (see `insideLabelLayout`). A pill beside the
+ * node is for the nodes that need one: nodes showing a picture, the focused
+ * node when its name doesn't fit inside, and overview nodes too small for
+ * their names. Any other node too small for its name shows none until you
+ * zoom in. A name inside a node keeps clear of its "+N", `countWidth` px wide.
+ */
+export declare const labelPlacement: (role: NodeRole, screenRadius: number, text: string, hasImage: boolean, hasIcon?: boolean, measure?: TextMeasure, narrower?: boolean, countWidth?: number) => LabelPlacement;
+/** How a node's label is drawn on a frame (see `NodeLabel.update`). */
+export interface LabelDrawing {
+    /** The node's center on screen (px). */
+    x: number;
+    y: number;
+    /** The node's radius on screen (px). */
+    screenRadius: number;
+    role: NodeRole;
+    placement: LabelPlacement;
+    opacity: number;
+    /** Whether a name inside its node takes the theme's light text. */
+    light?: boolean;
+    /** The font a name inside its node is fitted in, as its placement was (default: estimated widths). */
+    measure?: TextMeasure;
+    /** Whether a name inside its node may try narrower widths of its font, as it does while the map is still (default: true). */
+    narrower?: boolean;
+    /** The width (px) of the node's "+N", which a name inside it keeps clear of (default: 0, when it shows none). */
+    countWidth?: number;
+    /** The side of its node a pill touches, a unit vector (default: below). */
+    direction?: {
+        x: number;
+        y: number;
+    };
+    /** How far from the node's center a pill sits (px; see `pillDistance` in `labels.ts`; default: 5 px past its edge). */
+    distance?: number;
+    /** Pixels a pill above or below its node slid sideways to stay on the map. */
+    offset?: number;
+    /** A pill's lines, and the width (px) it wraps at on two. */
+    lines?: 1 | 2;
+    width?: number;
+    /** What a pill says (default: the node's name). */
+    pillText?: string;
+}
+export declare class NodeLabel {
+    readonly element: HTMLDivElement;
+    readonly node: OrbitNode;
+    /** The type the node was drawn as, as for its view. */
+    readonly typeName: string | undefined;
+    private readonly text;
+    /** Whether the node has an icon, shown above its name when there's room. */
+    private readonly hasIcon;
+    /** The side an outside label sat on last (a unit vector), or null. */
+    direction: {
+        x: number;
+        y: number;
+    } | null;
+    private placement;
+    private role;
+    private fontSize;
+    /** The `font-stretch` written for a name drawn narrower to fit (0: the font's own width). */
+    private stretch;
+    /** The lines written into the label inside its node, or null while it holds the whole name (pills wrap it themselves). */
+    private shownLines;
+    /** What the label's pill says, while it's a pill. */
+    private pillText;
+    private iconHidden;
+    private light;
+    /** An outside pill on two lines, and the width it wraps at. */
+    private wrapped;
+    private pillWidth;
+    /** What was last written, so a label that didn't move isn't touched: the map repaints every frame while it moves. */
+    private shown;
+    private transform;
+    private opacity;
+    constructor(node: OrbitNode, extensions: MapExtensions);
+    get currentPlacement(): LabelPlacement;
+    /** Whether the label shows: placed somewhere and not hidden. */
+    get isShown(): boolean;
+    /** Draws the label as `drawing` says: inside its node, fitted as its placement was, or as a pill beside it. */
+    update(drawing: LabelDrawing): void;
+}
+/** Dashed ring arcs between the bodies on a ring (centered on the origin). */
+export declare const ringPath: (radius: number, gaps: DisplayRing["gaps"]) => string;

package/dist/core/extensions.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Ways to extend Orbit: node types, actions and status words. Each works for
+ * one map, through its options, or for every map once registered, which also
+ * covers `<orbit-map>` elements and maps in markdown pages. A map's own
+ * options win over registered ones.
+ */
+import type { OrbitNode } from './types.js';
+import type { OrbitThemeToken } from './themes.js';
+/** The colored dots statuses get. */
+export type OrbitStatusTone = 'active' | 'done' | 'blocked' | 'todo' | 'neutral';
+/** How a status word looks: one of the dot tones, or any CSS color. */
+export type OrbitStatusStyle = OrbitStatusTone | (string & {});
+/** A button under the focused node and in its detail sheet. */
+export interface OrbitAction {
+    /** Names the action in the `action` event: `event.action === 'assign'`. */
+    id: string;
+    /** The button's name, read by screen readers, shown as its tooltip and in the detail sheet. */
+    label: string | ((node: OrbitNode) => string);
+    /**
+     * The icon: an emoji or short symbol (`'✏️'`), SVG path data on a 24-unit
+     * grid (`'M4 20h4L20 8l-4-4L4 16z'`), or one of Orbit's icons (`'note'`,
+     * `'link'`, `'goto'`, `'image'`, `'video'`, `'list'`). Default: the
+     * label's first letter.
+     */
+    icon?: string;
+    /** Which nodes offer the action. Default: every node. */
+    when?: (node: OrbitNode) => boolean;
+    /** Runs when the button is pressed, unless an `action` listener prevents it. */
+    run: (node: OrbitNode, event: MouseEvent | KeyboardEvent) => void;
+}
+/** How nodes of one type look and behave. Nodes pick a type with `type: name`. */
+export interface OrbitNodeType {
+    /** The type's name for people, shown in the detail sheet and the tooltip: `'Milestone'`. */
+    label?: string;
+    /** The icon these nodes get unless they set their own. */
+    icon?: string;
+    /** The color these nodes get unless they set their own; their children take shades of it. */
+    color?: string;
+    /**
+     * Theme tokens for these nodes only, without `--orbit-`: their rim,
+     * shadow, glow, label and status colors, such as
+     * `{ 'node-stroke': '#B45309', 'node-stroke-width': '3' }`.
+     */
+    tokens?: Partial<Record<OrbitThemeToken, string>>;
+    /**
+     * Draws inside the node, the way a picture does: `element` is a 100 × 100 px
+     * box clipped to the node's circle and scaled with it, and the label moves
+     * outside. Return a function to clean up when the node leaves the map.
+     */
+    render?: (node: OrbitNode, element: HTMLElement) => void | (() => void);
+    /** Adds a section to the detail sheet, above the note; the node gets a "Details" button. */
+    details?: (node: OrbitNode, element: HTMLElement) => void;
+    /** Actions only nodes of this type offer, after the map's own. */
+    actions?: OrbitAction[];
+    /**
+     * The version of the fields these nodes keep in their attributes, once
+     * the type changes them: 1 at first. Nodes say which version they were
+     * written for (`type: task@2`; none means 1), and older ones are brought
+     * up to date with `upgrade` when a map is drawn.
+     */
+    version?: number;
+    /**
+     * Brings a node written for an older version of the type up to date:
+     * renames or reshapes its attributes, in place. `from` is the version it
+     * was written for. Runs once per node when a map is drawn (or with
+     * `upgradeNodeTypes`), and the next save writes the node as upgraded.
+     * Nodes written for a newer version than this one are left as they are.
+     */
+    upgrade?: (node: OrbitNode, from: number) => void;
+}
+/** The extensions a map is created with, before the registered ones. */
+export interface OrbitExtensionOptions {
+    /** Node types by name. */
+    nodeTypes?: Record<string, OrbitNodeType>;
+    /** Actions every node offers (or the ones `when` picks). */
+    actions?: OrbitAction[];
+    /** Status words and how they look: `{ review: 'active', 'on hold': '#A855F7' }`. */
+    statuses?: Record<string, OrbitStatusStyle>;
+    /**
+     * The type a node is drawn as when it names none: its look, content and
+     * actions, as if it said `type: name`, for display only. Orbit never writes
+     * it to the map, never upgrades a node for it, and asks again whenever it
+     * draws, so return undefined to draw the node as it is. Called often: keep
+     * it quick.
+     */
+    nodeTypeFor?: (node: OrbitNode) => string | undefined;
+}
+/**
+ * Defines a node type for every map: nodes with `type: name` (any case) take
+ * it. Returns a function that removes it again.
+ */
+export declare const registerNodeType: (name: string, definition: OrbitNodeType) => () => void;
+/** Adds an action to every map. Returns a function that removes it again. */
+export declare const registerAction: (action: OrbitAction) => () => void;
+/**
+ * Gives a status word its look on every map: one of the tones (`active`,
+ * `done`, `blocked`, `todo`, `neutral`) or any CSS color. Returns a function
+ * that removes it again.
+ */
+export declare const registerStatus: (word: string, style: OrbitStatusStyle) => () => void;
+/** How a status looks on a map: its tone, and its own color when it has one. */
+export interface StatusLook {
+    tone: OrbitStatusTone;
+    color?: string;
+}
+/**
+ * One map's view of the extensions: its own node types, actions and status
+ * words first, then the registered ones. Lookups read the registries each
+ * time, so a type registered after the map was created applies on its next
+ * redraw.
+ */
+export declare class MapExtensions {
+    private readonly types;
+    private readonly statuses;
+    private readonly actionList;
+    private readonly typeFor;
+    /** `nodeTypeFor` threw: it's asked on every frame, so the console hears of it once. */
+    private typeForFailed;
+    constructor(options?: OrbitExtensionOptions);
+    /**
+     * The name of the type the node is drawn as: its own `type`, or for a node
+     * that names none, the one `nodeTypeFor` gives it for display.
+     */
+    typeName(node: OrbitNode): string | undefined;
+    /** The type the node is drawn as, if this map knows it: its own, or one given for display (see `typeName`). */
+    nodeType(node: OrbitNode): OrbitNodeType | undefined;
+    /** The node's own type (`type`), never one given for display: what upgrades go by. */
+    ownType(node: OrbitNode): OrbitNodeType | undefined;
+    private typeNamed;
+    /** The node's icon: its own, or its type's. */
+    icon(node: OrbitNode): string | undefined;
+    /** The node's own color, or its type's. */
+    color(node: OrbitNode): string | undefined;
+    /** The actions a node offers: the map's, the registered ones, then its type's, each id once. */
+    actions(node: OrbitNode): OrbitAction[];
+    /** How a status looks: a word this map or a registration names, or one of the built-in words. */
+    status(word: string): StatusLook;
+}
+/**
+ * Brings nodes written for older versions of their types up to date (see
+ * `OrbitNodeType.version`), with the types `nodeTypes` defines or the
+ * registered ones. Maps do this when they're drawn; this is for documents
+ * read without one, on a server or in a script. Returns how many nodes
+ * were upgraded.
+ */
+export declare const upgradeNodeTypes: (root: OrbitNode, nodeTypes?: Record<string, OrbitNodeType>) => number;
+/** Upgrades the nodes under `root` with the types `extensions` knows. */
+export declare const upgradeTypes: (root: OrbitNode, extensions: MapExtensions) => number;
+/** An action's label for a node. */
+export declare const actionLabel: (action: OrbitAction, node: OrbitNode) => string;
+/**
+ * Runs code a map was extended with. If it throws, the map carries on and
+ * the console says which extension failed.
+ */
+export declare const guarded: <Result>(what: string, fallback: Result, run: () => Result) => Result;

package/dist/core/format-upgrades.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The format's versions. A document says which version it's written for
+ * with `schemaVersion` (none means 1). When the format changes, the change
+ * goes here with a step that brings older documents up to date, and
+ * `SUPPORTED_SCHEMA_VERSION` goes up: documents are upgraded as they're
+ * read, and the next save writes them in the new format, changing only
+ * what the upgrade changed.
+ *
+ * A document written for a newer version than this one is read as well as
+ * it can be, and reported (`unsupported-schema-version`, an error), so apps
+ * can open it without editing it: everything it says is kept on save, but
+ * what this version doesn't know of it isn't understood.
+ */
+import type { OrbitDocument } from './types.js';
+import type { DiagnosticCollector } from './diagnostics.js';
+/** A change to the format: how a document written for version `from` becomes one for `from + 1`. */
+export interface FormatUpgrade {
+    from: number;
+    /** Changes the document in place: its options, and its nodes' fields. */
+    upgrade: (document: OrbitDocument) => void;
+}
+/**
+ * The format's changes, oldest first. Empty while the format is at its
+ * first version; tests check it ends at `SUPPORTED_SCHEMA_VERSION`.
+ */
+export declare const FORMAT_UPGRADES: FormatUpgrade[];
+/** The newest `schemaVersion` this version of Orbit reads and writes. */
+export declare const SUPPORTED_SCHEMA_VERSION = 1;
+/**
+ * Upgrades a document written for an older version of the format, one step
+ * at a time, and says so. A document for a newer version is reported.
+ */
+export declare const upgradeFormat: (document: OrbitDocument, diagnostics: DiagnosticCollector, line: number | undefined, upgrades?: readonly FormatUpgrade[]) => void;