@restless-dreams/orbit 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,125 @@
+/**
+ * What is on screen this frame. Pure functions: a scene plus the orbit's
+ * rotation gives the resting display; during a flight, the current display
+ * morphs into the target scene placed in today's world coordinates.
+ */
+import type { OrbitNode } from '../types.js';
+import { type Camera, type CameraPath, type Similarity } from './camera.js';
+import { type NodeRole, type Scene, type SceneRing } from './scene.js';
+export interface DisplayNode {
+    id: string;
+    node: OrbitNode;
+    role: NodeRole;
+    x: number;
+    y: number;
+    radius: number;
+    opacity: number;
+    /** Multiplies the label's own visibility rules (level of detail, role). */
+    labelOpacity: number;
+    color: string;
+    depth: number;
+    hiddenChildren: number;
+    parentId?: string;
+    hostId?: string;
+    /** A planet of a crowded orbit, drawn flat (see `drawsFlat`). */
+    crowded?: boolean;
+    /** During a flight, how the node comes or goes with its siblings (see `Cluster`). */
+    cluster?: Cluster;
+    /** A body that turns with its orbit: where it is in the unturned orbit (see `OrbitTurn`). */
+    unturned?: Point;
+}
+/**
+ * A focused orbit at rest, turned `rotation` degrees about its sun at
+ * (`cx`, `cy`). Each body that turns with it (those with `unturned`) is drawn
+ * where it is in the unturned orbit, in a group that turns, so spinning the
+ * orbit moves the group instead of every body in it.
+ */
+export interface OrbitTurn {
+    cx: number;
+    cy: number;
+    rotation: number;
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * During a flight, nodes that come or go together: the children of one
+ * parent growing out of it, shrinking into it, or fading where they are.
+ * Each is drawn at its own `x`, `y`, `radius` and `nodeOpacity`, which hold
+ * still, scaled by `scale` about the pivot with `opacity` on top, which are
+ * the same for all of them, so a family can be moved as one.
+ */
+export interface Cluster {
+    pivotX: number;
+    pivotY: number;
+    scale: number;
+    opacity: number;
+    x: number;
+    y: number;
+    radius: number;
+    nodeOpacity: number;
+}
+export interface DisplayRing {
+    id: string;
+    centerId: string;
+    cx: number;
+    cy: number;
+    radius: number;
+    color: string;
+    gaps: SceneRing['gaps'];
+    /** Degrees added to every gap angle (the orbit's spin). */
+    rotation: number;
+    opacity: number;
+}
+export interface DisplayLink {
+    id: string;
+    fromId: string;
+    toId: string;
+    color: string;
+    opacity: number;
+}
+/** The free place in the orbit for a new idea (see `SceneSlot`), where it is this frame. */
+export interface DisplaySlot {
+    parentId: string;
+    index: number;
+    x: number;
+    y: number;
+    radius: number;
+    opacity: number;
+    /** Where the slot is in the unturned orbit (see `OrbitTurn`). */
+    unturned?: Point;
+}
+export interface Display {
+    nodes: Map<string, DisplayNode>;
+    rings: DisplayRing[];
+    links: DisplayLink[];
+    camera: Camera;
+    addSlot?: DisplaySlot;
+    /** A focused orbit at rest. */
+    turn?: OrbitTurn;
+}
+/** A scene at rest, with its orbit turned by `rotation` degrees. */
+export declare const sceneDisplay: (scene: Scene, rotation: number, camera: Camera) => Display;
+export interface Transition {
+    /** The display when the flight started, in the current world. */
+    from: Display;
+    /** Fade out and in without moving anything, for readers who prefer reduced motion. */
+    fade?: boolean;
+    /** The destination scene in its own coordinates. */
+    target: Scene;
+    /** Places `target` in the current world. */
+    placement: Similarity;
+    cameraPath: CameraPath;
+    startedAt: number;
+    duration: number;
+}
+/** The camera that frames `scene` once it is placed by `placement`. */
+export declare const placedFrame: (scene: Scene, placement: Similarity) => Camera;
+export declare const transitionDisplay: (transition: Transition, progress: number) => Display;
+/**
+ * A view change without movement: the old view fades out, then the new one
+ * fades in already in place (in its own coordinates, with its own camera).
+ */
+export declare const fadeDisplay: (transition: Transition, progress: number) => Display;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * Standalone SVG for a display. Every color is resolved to a plain value,
+ * labels are SVG text and nothing depends on the page's stylesheet, so the
+ * file looks the same in any viewer or editor.
+ */
+import type { Display, DisplayNode } from './display.js';
+import { type Viewport } from './camera.js';
+import type { MapExtensions } from '../extensions.js';
+import type { OrbitWords } from '../languages.js';
+import { type LabelMeasures } from './text-measure.js';
+export interface ExportOptions {
+    viewport: Viewport;
+    /** Concrete theme values, keyed by token name (`surface`, `color-1`, …). */
+    tokens: Record<string, string>;
+    showRings: boolean;
+    title: string;
+    /** The fill the page resolved for a node, when it is on screen. */
+    fills?: (node: DisplayNode) => string;
+    baseUrl?: string;
+    /** Size the SVG to its container (100% wide and tall) instead of in pixels. */
+    responsive?: boolean;
+    /** Prefix for the SVG's ids; give each SVG inlined in one page its own. */
+    idPrefix?: string;
+    /** The map's node types and status words, for icons, status colors and type tokens. */
+    extensions?: MapExtensions;
+    /** Measures names in the fonts the map draws them with, so labels break as on the live map; by default, widths are estimated. */
+    measures?: LabelMeasures;
+    /** The map's words, for the name of an idea without text. Default: English. */
+    words?: OrbitWords;
+}
+export declare const exportDisplay: (display: Display | null, options: ExportOptions) => string;
+export declare const escapeXml: (value: string) => string;

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

@@ -0,0 +1,34 @@
+/**
+ * Pan momentum for the overview. Like the orbit spin, the release velocity
+ * is the least-squares slope of the last 80 ms of pointer movement, and the
+ * glide slows down exponentially using the exact solution for each step.
+ */
+export interface Velocity {
+    /** Pixels per millisecond. */
+    x: number;
+    y: number;
+}
+/** Tracks a dragged position over time and reports the release velocity. */
+export declare class PointVelocityTracker {
+    private samples;
+    private x;
+    private y;
+    reset(time: number): void;
+    /** Records a movement of (`deltaX`, `deltaY`) pixels at `time` (milliseconds). */
+    add(time: number, deltaX: number, deltaY: number): void;
+    velocityAt(releaseTime: number): Velocity;
+}
+export declare class Glide {
+    velocity: Velocity;
+    private readonly timeConstant;
+    /** `timeConstant` in milliseconds: how long the glide takes to lose about two thirds of its speed. */
+    constructor(timeConstant?: number);
+    get isMoving(): boolean;
+    start(velocity: Velocity): void;
+    stop(): void;
+    /** Advances by `elapsed` milliseconds and returns the distance travelled, in pixels. */
+    step(elapsed: number): {
+        x: number;
+        y: number;
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Where every label goes, frame by frame: inside its node, on a chip, as a
+ * pill beside the node, or nowhere. Pills try the sides of their node in
+ * order of preference and take the first one that covers no other label,
+ * no other node and doesn't run off the map. The browser renderer and the
+ * SVG export both use this, so an export looks like the live map.
+ */
+import type { Viewport } from './camera.js';
+import type { Display, DisplayNode } from './display.js';
+import { type LabelPlacement } from './views.js';
+import { type LabelMeasures, type TextMeasure } from './text-measure.js';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Box {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface PlannedLabel {
+    entry: DisplayNode;
+    /** The node's center on screen. */
+    x: number;
+    y: number;
+    screenRadius: number;
+    placement: Exclude<LabelPlacement, 'hidden'>;
+    /** Which side of the node an outside label sits on (a unit vector). */
+    direction: Point;
+    /** How far from the node's center a pill sits (px; see `pillDistance`). */
+    distance: number;
+    /** Pixels a pill above or below its node slid sideways to stay on the map. */
+    offset: number;
+    /** A pill's lines: two when one line fits nowhere. */
+    lines: 1 | 2;
+    /** A pill's estimated width. */
+    width: number;
+    opacity: number;
+    /** What a pill says: the node's name, after its icon when `pillIcon` gives one. */
+    text: string;
+    /** The width (px) of the node's "+N", which a name inside it keeps clear of; 0 when it shows none. */
+    countWidth: number;
+}
+export interface LabelPlanOptions {
+    viewport: Viewport;
+    /** Whether the node shows a picture, which pushes its label outside. */
+    hasImage(entry: DisplayNode): boolean;
+    /** Whether the node has an icon to show above its name (the fit is the label's own, cached). */
+    hasIcon?(entry: DisplayNode): boolean;
+    /**
+     * An icon to show on the node's pill, before its name: for a node whose
+     * picture or content fills it, so the icon has no place inside.
+     */
+    pillIcon?(entry: DisplayNode): string | undefined;
+    /** The side a label sat on last frame, so labels don't hop around while the map moves. */
+    previousSide?(id: string): Point | null;
+    /** While nodes fly between views, pills stay hidden; they'd flicker as nodes grow and shrink. */
+    inFlight?: boolean;
+    /** Measures names in the fonts the map draws them with; by default, widths are estimated. */
+    measures?: LabelMeasures;
+    /**
+     * While the map moves, names that don't fit at their font's width don't
+     * try narrower ones, and names not yet showing only start to when they'd
+     * fit by the estimate too (`isShown` says which show): measured names fit
+     * more often, and hundreds starting to show mid-zoom would make frames
+     * late. Once the map is still (and by default), every name that fits shows.
+     */
+    moving?: boolean;
+    /** Whether a node's label shows now. */
+    isShown?(id: string): boolean;
+    /** Whether nodes show a "+N" for children that aren't drawn, which names inside them keep clear of: the map does, an export doesn't. */
+    counts?: boolean;
+}
+/** The order labels are placed in, so the important ones win when they would overlap. */
+export declare const labelOrder: (nodes: Iterable<DisplayNode>) => DisplayNode[];
+/** The labels to show this frame, in `order`. Nodes missing from the result show no label. */
+export declare const planLabels: (display: Display, order: DisplayNode[], options: LabelPlanOptions) => PlannedLabel[];
+/**
+ * The sides a node's pill may go, best first. Toward the parent is usually
+ * free (a planet's moons and a branch's children sit on the far side); a
+ * leaf in the overview has its far side free too. Moons look away from
+ * their planet. Below and above are the fallbacks.
+ */
+export declare const labelSides: (entry: DisplayNode, display: Display) => Point[];
+/**
+ * Where an outside label will be, from its text's width in `measure` (by
+ * default, an estimate), slid `offset` pixels sideways, on `lines` lines.
+ * The pill is drawn no bigger than this box: its width holds the text, the
+ * pill's padding (16 px) and 2 px to spare, and the stylesheet counts the
+ * padding in a pill's width, capped at the same 160 px (280 px for the
+ * focused node).
+ */
+export declare const outsideLabelBox: (text: string, point: Point, screenRadius: number, direction: Point, maximumWidth: number, offset?: number, lines?: 1 | 2, measure?: TextMeasure) => Box;
+/**
+ * How far from its node's center a pill toward `direction` sits. A pill is
+ * placed by its point that matches its side: the middle of its top when it's
+ * below the node, the middle of its left end when it's to the right, and on a
+ * slant a point between them, inside the pill. That point sits past the node's
+ * edge by the gap, which keeps a pill on a side clear of its node, but on a
+ * slant the pill's nearest end would reach back over it: there the pill sits
+ * farther out, as far as that end keeps the same gap.
+ */
+export declare const pillDistance: (screenRadius: number, direction: Point, width: number, lines: 1 | 2) => number;
+/** A pill's text width (px): on two lines, its longer line when it breaks where the two balance best. Estimated, unless `measure` measures it. */
+export declare const pillTextWidth: (text: string, lines: 1 | 2, measure?: TextMeasure) => number;

package/dist/core/engine/node-drag.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a node being dragged would go if it were let go now: into another
+ * node, at a place in the focused orbit, or nowhere. Pure functions over what
+ * is on screen, so the renderer only tracks the finger.
+ */
+import type { OrbitNode } from '../types.js';
+import type { Display, DisplayNode } from './display.js';
+import { type Scene } from './scene.js';
+/** Where a dragged node would go: under `parentId`, at `index` among its children (null: after the last). */
+export interface DropPlace {
+    parentId: string;
+    index: number | null;
+    /** Dropped on a node rather than on a place in the orbit. */
+    into: boolean;
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * The ids a node can't be dropped into: itself and everything under it
+ * (a node can't go inside itself), and its parent, which it is already in.
+ */
+export declare const unreachableIds: (node: OrbitNode, parentId: string | undefined) => Set<string>;
+/**
+ * The node under `point` (world coordinates) to drop into, or null. Each
+ * node catches the point within `catchRadius` of its center (world units),
+ * given whether it's the target so far, so a target can hold on a little
+ * further than it caught; the most central catch wins.
+ */
+export declare const nodeUnder: (display: Display, point: Point, unreachable: ReadonlySet<string>, catchRadius: (node: DisplayNode, current: boolean) => number, current: string | null) => DisplayNode | null;
+/**
+ * The place in a focused orbit for node `draggedId` dropped at `point`
+ * (relative to the sun, in an orbit turned `rotation` degrees), counted among
+ * the sun's children without it, or null when the point is off the orbit.
+ * `layout` is the orbit as it's drawn, with the place it's held at (it, laid
+ * out there, or the slot), so the place under the press is the one on
+ * screen: it stays put while the press stays near it, and moves past a
+ * planet the press crosses. `ringRadius` is used when the orbit is empty.
+ * Orbits of more than one ring take drops on their planets only.
+ *
+ * The first place and the last are the same gap, between the last planet
+ * and the first: there, the place held now (`current`) stays, rather than
+ * turning the whole orbit a step.
+ */
+export declare const orbitPlaceAt: (layout: Scene, point: Point, rotation: number, ringRadius: number, band: number, draggedId: string, current?: number | null) => number | null;
+/** Whether two places are the same. */
+export declare const samePlace: (first: DropPlace | null, second: DropPlace | null) => boolean;
+export {};

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

@@ -0,0 +1,160 @@
+/**
+ * Scenes: what each view of a map contains, in world coordinates.
+ *
+ * A focus scene puts the focused node (the sun) at the origin with its
+ * children (planets) on rings and its grandchildren as small moons around
+ * them. An overview scene lays out the whole tree around the root. Every
+ * node keeps one color in every scene, and nodes are keyed by id so a
+ * transition can morph the same node from one scene into the next: the
+ * moons of a planet grow into the planets of the next view.
+ */
+import type { OrbitNode } from '../types.js';
+import { MOON_LIMIT } from '../layout.js';
+import { type Camera, type Insets, type Similarity, type Viewport } from './camera.js';
+export type NodeRole = 'sun' | 'planet' | 'moon' | 'node';
+export interface SceneNode {
+    id: string;
+    node: OrbitNode;
+    role: NodeRole;
+    /** World position of the center, before any orbit spin. */
+    x: number;
+    y: number;
+    radius: number;
+    color: string;
+    depth: number;
+    parentId?: string;
+    /** Planets: angle around the sun (degrees, −90 = top) and distance from it. */
+    orbitAngle?: number;
+    orbitRadius?: number;
+    /** Moons: the planet they circle, their angle relative to the direction from the sun to the planet, and their distance. */
+    hostId?: string;
+    hostOffset?: number;
+    hostDistance?: number;
+    /** Children that exist but aren't drawn: beyond the moon limit, or under a collapsed node. */
+    hiddenChildren: number;
+    /** Turns with the orbit when it spins. */
+    spins: boolean;
+    /** A planet of an orbit too crowded for each planet's shadow to read: drawn flat. */
+    crowded?: boolean;
+}
+export interface SceneRing {
+    id: string;
+    centerId: string;
+    cx: number;
+    cy: number;
+    radius: number;
+    color: string;
+    /** Openings around each body on the ring, so the line never runs through a node. */
+    gaps: {
+        angle: number;
+        halfWidth: number;
+    }[];
+    spins: boolean;
+}
+export interface SceneLink {
+    id: string;
+    fromId: string;
+    toId: string;
+    color: string;
+}
+export interface Scene {
+    kind: 'focus' | 'overview';
+    focusId: string;
+    nodes: Map<string, SceneNode>;
+    rings: SceneRing[];
+    links: SceneLink[];
+    /** The camera that fits the scene into the viewport. */
+    frame: Camera;
+    /**
+     * How far the scene reaches from its focus node on each axis, in world
+     * units: what `frame` fits. A focus scene reaches as far on both, the edge
+     * of its orbit at every turn.
+     */
+    extent: {
+        x: number;
+        y: number;
+    };
+    /** Focus scenes of editable maps: the free place in the orbit where a new idea goes. */
+    addSlot?: SceneSlot;
+}
+/** A free place in the sun's orbit, laid out like a planet, for the next child. */
+export interface SceneSlot {
+    /** The node a new idea there becomes a child of: the sun. */
+    parentId: string;
+    /** Its position among the sun's children. */
+    index: number;
+    x: number;
+    y: number;
+    radius: number;
+    orbitAngle: number;
+    orbitRadius: number;
+}
+export interface SceneOptions {
+    viewport: Viewport;
+    /** The parts of the viewport the page's own controls cover: views are fitted into the rest. */
+    insets?: Insets;
+    colors: Map<string, string>;
+    maxDepth?: number;
+    /** Keep a place in the orbit for a new idea, after the sun's children (or at `index`). Focus scenes only. */
+    addSlot?: {
+        index?: number;
+    };
+    /**
+     * One of the sun's children being dragged to another place among them: it's
+     * laid out at `index` among the others, so they make room for it there.
+     * Focus scenes only.
+     */
+    reorder?: {
+        id: string;
+        index: number;
+    };
+    /**
+     * While a node is carried along the orbit of `focusId`: the radii its rings
+     * had when the drag began. They keep them until the drop, so the orbit
+     * doesn't grow or shrink as the places in it move. Focus scenes only.
+     */
+    keptRings?: {
+        focusId: string;
+        radii: number[];
+    };
+}
+export { MOON_LIMIT };
+/** More planets than this in one view, and their shadows overlap into a haze: they're drawn flat. */
+export declare const CROWDED_ORBIT = 48;
+/**
+ * The camera that fits `scene` into `viewport` as its `frame` does, inside
+ * what `insets` leave of it, and with at least `below` px under it: room for
+ * something drawn there, such as the focused node's buttons.
+ */
+export declare const fitScene: (scene: Scene, viewport: Viewport, insets?: Insets, below?: number) => Camera;
+/**
+ * One color per node, the same in every view. The root uses the first
+ * palette entry; top-level branches take the others in turn (see
+ * `branchNumbers`); deeper nodes use their branch's color, mixed toward the
+ * theme's `shade-light` or `shade-dark` by position so siblings stay
+ * distinguishable. A node's own color always wins: its `color`, or its
+ * type's (see `ownColor`); then its `paletteColor`.
+ */
+export declare const assignNodeColors: (tree: OrbitNode, palette: string[], ownColor?: (node: OrbitNode) => string | undefined) => Map<string, string>;
+/** How much of the branch color each sibling keeps, and what the rest is mixed with. */
+export declare const SHADES: [number, 'light' | 'dark'][];
+export declare const buildFocusScene: (tree: OrbitNode, focusId: string, options: SceneOptions) => Scene;
+export declare const buildOverviewScene: (tree: OrbitNode, options: SceneOptions) => Scene;
+/**
+ * The transform that places `target` so the node `anchorId` lands exactly
+ * where it is displayed now (`current`): used to fly from one view to the
+ * next without any jump.
+ */
+export declare const alignScene: (target: Scene, anchorId: string, current: {
+    x: number;
+    y: number;
+    radius: number;
+}) => Similarity;
+/** Applies a placement to a scene node's position and size. */
+export declare const placeNode: (node: SceneNode, transform: Similarity) => {
+    x: number;
+    y: number;
+    radius: number;
+};
+export declare const toRadians: (degrees: number) => number;
+export declare const toDegrees: (radians: number) => number;

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

@@ -0,0 +1,62 @@
+/**
+ * Spinner physics for the focus-mode orbit.
+ *
+ * Release speed comes from where the pointer actually was over the last
+ * 80 ms, not from the last pointer event, so a lazy drag barely coasts and a
+ * hard flick spins for several turns on any device. Coasting decays
+ * exponentially using the exact solution for each step, so the result is the
+ * same at 60 Hz, 120 Hz or any other frame rate.
+ */
+/** Degrees. `-180 < result <= 180`. */
+export declare const normalizeDelta: (delta: number) => number;
+/** Tracks a dragged angle over time and reports the release velocity. */
+export declare class AngularVelocityTracker {
+    private samples;
+    private lastRawAngle;
+    private unwrappedAngle;
+    reset(time: number, rawAngle: number): void;
+    /** Records the pointer's angle (degrees) at `time` (milliseconds). Returns the change since the last sample. */
+    add(time: number, rawAngle: number): number;
+    /** Degrees per millisecond at `releaseTime`: the least-squares slope of the last 80 ms. */
+    velocityAt(releaseTime: number): number;
+}
+export interface SpinSettings {
+    /** Time constant of the exponential slow-down, in seconds. */
+    decay: number;
+    /** Fastest coast, in degrees per second. */
+    maxSpeed: number;
+    /** Below this speed (degrees per second) a coast hands over to settling. */
+    settleSpeed: number;
+    /** Snap a planet to the top when settling. */
+    snap: boolean;
+}
+export declare const DEFAULT_SPIN_SETTINGS: SpinSettings;
+export type SpinMode = 'idle' | 'dragging' | 'coasting' | 'settling';
+export declare class SpinPhysics {
+    /** Rotation of the orbit, in degrees. */
+    angle: number;
+    /** Degrees per millisecond. */
+    velocity: number;
+    mode: SpinMode;
+    settings: SpinSettings;
+    private settleTarget;
+    /** Angles (degrees) that put a planet at the top; used for snapping. */
+    private slots;
+    constructor(settings?: Partial<SpinSettings>);
+    /** The finger is on the orbit: stops any coast. */
+    grab(): void;
+    /** Rotates directly while dragging. */
+    drag(delta: number): void;
+    /** Lets go with a velocity in degrees per millisecond. */
+    release(velocity: number, slots?: number[]): void;
+    /** Eases the orbit to the turn equivalent to `angle` (degrees) that is nearest to where it is now. */
+    settleTo(angle: number): void;
+    /** Stops immediately, wherever the orbit is. */
+    stop(): void;
+    get isMoving(): boolean;
+    /** Advances by `elapsed` milliseconds. Returns whether the orbit is still moving. */
+    step(elapsed: number): boolean;
+    private beginSettling;
+    private nearestSlot;
+    private stepSettling;
+}

package/dist/core/engine/surface-pattern.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A theme's `surface-pattern` (CSS backgrounds) drawn as SVG, so exported
+ * pictures keep the wallpaper glass shows through, a starfield or a grid.
+ * Reads the kinds of layers Orbit's own themes use: radial gradients of one
+ * color fading out, `linear-gradient` lines tiled by a size, and tiled
+ * images. A layer of any other kind is left out of the picture.
+ */
+export interface PatternLayers {
+    /** `<defs>` entries the layers use. */
+    definitions: string[];
+    /** One full-size rectangle per layer, bottom layer first. */
+    layers: string[];
+}
+/**
+ * The layers of `pattern` for a picture `width` × `height`, with ids made
+ * from `prefix`. `color` resolves a theme color to a plain value.
+ */
+export declare const patternLayers: (pattern: string, width: number, height: number, prefix: string, color: (value: string) => string) => PatternLayers;
+/** The layers of a CSS background list, split at the commas between them. */
+export declare const splitLayers: (value: string) => string[];