@restless-dreams/orbit 0.1.0 → 0.2.0

package/dist/core/other-apps/zip.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reads files out of a zip archive, such as an XMind map: its directory,
+ * then each entry on request, stored or deflated, checked against its
+ * CRC-32. Archives that span disks, need ZIP64 or are encrypted are refused,
+ * and so is an entry that would unpack past the archive's limits.
+ */
+/** An archive that can't be read, or an entry that can't be unpacked. */
+export declare class ZipError extends Error {
+    constructor(message: string);
+}
+export interface ZipLimits {
+    /** The most entries an archive may list. */
+    entries: number;
+    /** The most bytes one entry may unpack to. */
+    entrySize: number;
+    /** The most bytes all the entries read may unpack to, together. */
+    totalSize: number;
+}
+export declare const DEFAULT_ZIP_LIMITS: ZipLimits;
+/** Whether bytes start the way every zip archive does. */
+export declare const isZip: (bytes: Uint8Array) => boolean;
+export declare class ZipArchive {
+    private readonly bytes;
+    private readonly view;
+    private readonly limits;
+    private readonly entries;
+    private unpacked;
+    constructor(bytes: Uint8Array, limits?: Partial<ZipLimits>);
+    /** The names of the files in the archive, folders left out. */
+    get names(): string[];
+    has(name: string): boolean;
+    /** An entry's bytes, or null when the archive has no such file. */
+    read(name: string): Uint8Array | null;
+    /** An entry as UTF-8 text, or null when the archive has no such file. */
+    text(name: string): string | null;
+    private readDirectory;
+}

package/dist/core/print-layout.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A map laid out for paper: its title, the map as a picture that fits the
+ * page, then every idea in reading order with its details, link, note and
+ * media. Orbit's web pages print with it, and so can any page that shows a
+ * map: lay it out in an element that only shows in print.
+ */
+import { type OrbitNodeType, type OrbitStatusStyle } from './extensions.js';
+import { type OrbitStrings } from './languages.js';
+import { type OrbitThemeName } from './themes.js';
+import type { OrbitDocument, OrbitNode, OrbitRendererTheme, OrbitThemePreset, ViewMode } from './types.js';
+export interface OrbitPrintOptions {
+    /** The heading at the top. Default: the map's `title`, or its root's text. */
+    title?: string;
+    /** Whether the map's picture comes before the outline. Default: true. */
+    picture?: boolean;
+    /** What the picture shows: `focus`, a node with its orbit, or `all`, the whole map. Default: the map's `view`, or `focus`. */
+    viewMode?: ViewMode;
+    /** The node in the middle of the picture in focus mode, by id. Default: the root. */
+    focus?: string;
+    /**
+     * The map's theme: a theme name or `{ preset, tokens }`. Default: the
+     * document's. Paper is light, so a dark theme prints as its light
+     * counterpart (see `printTheme`), and nothing prints a background.
+     */
+    theme?: OrbitThemePreset | (string & {}) | OrbitRendererTheme;
+    /** The map's colors: the root's, then one per top-level branch. Default: the document's, or the theme's. */
+    palette?: string[];
+    /** The language of the few words the layout has: a BCP 47 tag. Default: English. */
+    language?: string;
+    /** Words to change, over the language's. */
+    strings?: Partial<OrbitStrings>;
+    /** Resolves relative picture, video and link URLs. Default: the document's `baseUrl`. */
+    baseUrl?: string;
+    /** Node types by name, before the registered ones: their icons, colors, labels and details. */
+    nodeTypes?: Record<string, OrbitNodeType>;
+    /** Status words and how they look, before the registered ones. */
+    statuses?: Record<string, OrbitStatusStyle>;
+    /** The type a node that names none is laid out as (see `RendererOptions.nodeTypeFor`). */
+    nodeTypeFor?: (node: OrbitNode) => string | undefined;
+    /** Prefix for the picture's SVG ids; give each layout in one page its own. Default: `orbit-print`. */
+    idPrefix?: string;
+}
+/** The light theme each dark built-in theme prints as. Light themes print as themselves. */
+export declare const PRINT_THEMES: Readonly<Partial<Record<OrbitThemePreset, OrbitThemeName>>>;
+/**
+ * The theme a map prints in: the map's own when it's light, otherwise its
+ * light counterpart (`PRINT_THEMES`), always without a background. A dark
+ * theme of your own keeps only its colors (`color-root` to `color-7`).
+ */
+export declare const printTheme: (theme: string | OrbitRendererTheme | undefined) => OrbitRendererTheme;
+/**
+ * Lays a map out for print in `container`, replacing what it held, and
+ * returns the layout: the title, the map as a picture that fits the page,
+ * then every idea in reading order, nested by depth, with its icon, status,
+ * priority, tags, link (its address printed), note, picture and video. An
+ * idea stays whole across page breaks, and a heading stays with what
+ * follows it.
+ *
+ * It's laid out on screen like any element: hide it there and show it in
+ * print, as Orbit's web pages do.
+ *
+ * @example
+ * ```ts
+ * import { renderPrintLayout } from '@restless-dreams/orbit';
+ *
+ * renderPrintLayout(document.querySelector('#print'), markdown, { viewMode: 'all' });
+ * // #print { display: none } @media print { #print { display: block } #app { display: none } }
+ * ```
+ */
+export declare const renderPrintLayout: (container: HTMLElement, input: string | OrbitDocument, options?: OrbitPrintOptions) => HTMLElement;

package/dist/core/renderer/content-painter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What node types draw inside their nodes (`render`), in an HTML layer over
+ * the map: a 100 × 100 px box per node, moved and scaled with it each frame,
+ * created when the node comes on the map and cleaned up when it leaves.
+ */
+import type { Display } from '../engine/display.js';
+import type { Viewport } from '../engine/camera.js';
+import type { MapExtensions } from '../extensions.js';
+/** What node contents need from the map around them. */
+export interface ContentHost {
+    extensions(): MapExtensions;
+    viewport(): Viewport;
+    /** Nodes changed since the last frame. */
+    changedIds(): ReadonlySet<string>;
+}
+export declare class ContentPainter {
+    private readonly layer;
+    private readonly host;
+    private readonly contents;
+    constructor(layer: HTMLDivElement, host: ContentHost);
+    /** Cleans up every node's content. */
+    clear(): void;
+    /**
+     * Draws what node types render inside their nodes: a 100 × 100 px box per
+     * node, moved and scaled with it each frame, created when the node comes
+     * on the map and cleaned up when it leaves.
+     */
+    paint(display: Display): void;
+    private remove;
+}

package/dist/core/renderer/dom.d.ts

@@ -0,0 +1,15 @@
+/** The page around a map: its elements, events, focus and scrolling, as the renderer reads them. */
+import { OrbitWords } from '../languages.js';
+export declare const reportListenerError: (error: unknown) => void;
+export declare const createEmptyState: (words: OrbitWords) => HTMLDivElement;
+/** The empty map's message and hint, in `words`' language. */
+export declare const fillEmptyState: (empty: HTMLDivElement, words: OrbitWords) => void;
+/** The + in arrow-key order around the orbit. */
+export declare const SLOT_STOP = "\0slot";
+export declare const isAddSlot: (target: EventTarget | null) => boolean;
+export declare const nodeIdFrom: (target: EventTarget | null) => string | null;
+export declare const isFocusVisible: (target: EventTarget | null) => boolean;
+export declare const isApplePlatform: () => boolean;
+/** Whether the document, or any element around `element`, can scroll. */
+export declare const scrollsAround: (element: Element) => boolean;
+export declare const parentAcrossShadow: (element: Element) => Element | null;

package/dist/core/renderer/families.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Families: the renderer draws nodes in groups of siblings, and a group whose
+ * members come or go together in a flight (one `Cluster`) moves as one, with
+ * one transform per frame instead of one per node.
+ */
+import type { Cluster, DisplayNode } from '../engine/display.js';
+import { NodeView } from '../engine/views.js';
+/**
+ * Children of one parent, drawn in one group in the layer of their role. In
+ * a flight, the members of a family often come or go together, growing out
+ * of their parent or shrinking into it, and then the group moves instead of
+ * each of them: one transform per frame instead of hundreds.
+ */
+export interface Family {
+    group: SVGGElement;
+    layer: 'sun' | 'moon' | 'node';
+    parentId: string;
+    transform: string;
+    opacity: string;
+    hidden: boolean;
+    /** This frame's members, and the motion they all share (null if they don't), once worked out. */
+    members: FamilyMember[];
+    motion?: Cluster | null;
+}
+export interface FamilyMember {
+    entry: DisplayNode;
+    view: NodeView;
+    family: Family;
+}
+export declare const sameMotion: (first: Cluster, second: Cluster) => boolean;
+/** The motion all of a family's members share this frame, or null when they move each on their own. */
+export declare const familyMotion: (family: Family) => Cluster | null;
+/** A cluster too faint or too small to draw. */
+export declare const clusterHidden: (cluster: Cluster) => boolean;
+export declare const moveFamily: (family: Family, motion: Cluster | null) => void;

package/dist/core/renderer/label-painter.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Names and "+N" counts, in the HTML layer over the map. Each frame's names
+ * are planned for its display (see `planLabels`), shown a share at a time on
+ * an animated map, and ride along as one layer while only the camera moves.
+ */
+import type { LabelFonts } from '../engine/text-measure.js';
+import type { Viewport } from '../engine/camera.js';
+import type { Display, DisplayNode } from '../engine/display.js';
+import type { Scene } from '../engine/scene.js';
+import type { MapExtensions } from '../extensions.js';
+import { type LabelPlacement, type NodeView } from '../engine/views.js';
+/** What the names need from the map around them. */
+export interface LabelHost {
+    extensions(): MapExtensions;
+    viewport(): Viewport;
+    /** The scene on screen, or null during a flight: names keep their order for a scene. */
+    restingScene(): Scene | null;
+    inFlight(): boolean;
+    /** Whether only the camera moves: a camera flight, a wheel zoom, a glide or a drag. */
+    cameraMoving(): boolean;
+    /** Nodes changed since the last frame. */
+    changedIds(): ReadonlySet<string>;
+    /** The node whose text is being typed, which shows the field instead of its name. */
+    editedId(): string | null;
+    animationsEnabled(): boolean;
+    requestPaint(): void;
+    nodeView(id: string): NodeView | undefined;
+    themeTokens(): Record<string, string>;
+}
+export declare class LabelPainter {
+    private readonly layer;
+    private readonly fonts;
+    private readonly host;
+    private readonly labels;
+    private readonly counts;
+    /**
+     * Nodes in the order their labels are placed, for one display, and their
+     * ids for a scene at rest: the order holds while the orbit spins, only the
+     * entries are new each frame.
+     */
+    private labelOrder;
+    /** The camera labels and counts were last placed for, and the nodes they were placed for. */
+    private placed;
+    /** Names planned to show that wait for a later frame (see `LABELS_SHOWN_PER_FRAME`), placed for `placed`'s camera, and whether the map moved then. */
+    private waiting;
+    private layerTransform;
+    private readonly lightText;
+    /** The theme's label colors, resolved when first needed after each theme change. */
+    private textColors;
+    constructor(layer: HTMLDivElement, fonts: LabelFonts, host: LabelHost);
+    /** Places the names and counts for this frame's display, or lets them ride along with the camera. */
+    paint(display: Display): void;
+    /** Where the node's name is drawn now. */
+    placementOf(id: string): LabelPlacement | undefined;
+    /** Forgets which nodes' names are light (their colors may have changed). */
+    forgetLightText(): void;
+    /** Forgets the theme's text colors and which names are light (the theme changed). */
+    forgetTextColors(): void;
+    /** Forgets a node that left the map. */
+    forgetNode(id: string): void;
+    /** Takes every name and count off the map. */
+    clear(): void;
+    /**
+     * While only the camera moves (a pan, a pinch, a zoom, a glide), labels and counts ride along
+     * as one layer instead of being placed again on every frame, which for a big view means
+     * restyling hundreds of them. They're placed again once the camera rests, or has gone far
+     * enough that they'd be too big or too small, or missing for nodes coming into view. Returns
+     * the layer's transform from where they were placed, or null to place them now.
+     */
+    private ride;
+    /** Fits and places every label again, where it is (the fonts changed). */
+    refit(): void;
+    /** Whether the labels were placed for this very view: the same nodes, the camera where it was, nothing changed. */
+    private still;
+    private setLayerTransform;
+    private paintLabels;
+    /** Shows a planned label: its view (made when it has none yet) placed and fitted as planned. */
+    private showLabel;
+    /**
+     * While the labels ride along with the camera, shows the next names
+     * waiting to: placed as planned, for the camera the labels were placed
+     * at, so they ride along with the rest.
+     */
+    private showWaiting;
+    /** Whether the node shows a picture or its type's own content, so its label goes outside. */
+    private showsImage;
+    /** Whether the theme's light text has more contrast on this node's color than its dark text. Measured once per node and color. */
+    usesLightText(entry: DisplayNode): boolean;
+    /** The theme's label colors as plain values. */
+    private resolveTextColors;
+    /** The "+N" of nodes with children that aren't drawn, at their lower right. In the label layer, so they ride along with the labels. */
+    private paintCounts;
+}

package/dist/core/renderer/node-painter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The nodes on the map: a view per node, drawn in groups of siblings (see
+ * `families.ts`), kept in step with each frame's display. Small flat bodies
+ * become specks, an orbit spinning turns the layers its planets and moons are
+ * in, and while only the camera moves the nodes hold still.
+ */
+import type { Display } from '../engine/display.js';
+import type { Scene } from '../engine/scene.js';
+import type { MapExtensions } from '../extensions.js';
+import type { OrbitWords } from '../languages.js';
+import { NodeView, type ViewIds } from '../engine/views.js';
+/** What the nodes need from the map around them. */
+export interface NodeHost {
+    extensions(): MapExtensions;
+    words(): OrbitWords;
+    baseUrl(): string | undefined;
+    /** The scene on screen (the one a flight leaves, until it lands). */
+    scene(): Scene | null;
+    inFlight(): boolean;
+    /** Whether the orbit is at rest: not dragged, coasting or settling. */
+    spinResting(): boolean;
+    /** Whether the slow drift is running. */
+    driftRunning(): boolean;
+    /** The node whose text is being typed, if any. */
+    editedId(): string | null;
+    /** The node lifted to be dragged, the bodies carried under the press (null when nothing is), and the node it would drop into. */
+    drag(): {
+        liftedId: string | null;
+        carried: Set<string> | null;
+        targetId: string | null;
+    };
+    /** Nodes changed since the last frame. */
+    changedIds(): ReadonlySet<string>;
+    requestPaint(): void;
+    /** A node's view came on the map: the map's tab stops need placing again. */
+    tabStopsChanged(): void;
+    /** A node's view left the map. */
+    viewRemoved(id: string): void;
+}
+/** The layers nodes are drawn in. */
+export interface NodeLayers {
+    moons: SVGGElement;
+    nodes: SVGGElement;
+    suns: SVGGElement;
+    carried: SVGGElement;
+}
+export declare class NodePainter {
+    private readonly root;
+    private readonly definitions;
+    private readonly ids;
+    private readonly layers;
+    private readonly host;
+    /** The orbit's turn as last written to the layers of its planets and moons (see `paintTurn`). */
+    private turnTransform;
+    /** The turn the shading of specks is turned back by (see `turnShading`). */
+    private speckLighting;
+    /** The on-screen radius (px) below which bodies were last drawn as specks (see `speckRadius`). */
+    private specksBelow;
+    /**
+     * The nodes as last painted at rest, with what they were drawn for: while
+     * only the camera or the orbit's turn changes, they hold still, all but
+     * the bodies turned back upright (see `paintNodes`).
+     */
+    private stillNodes;
+    private readonly nodeViews;
+    /** The family group each node's element is in (see `Family`). */
+    private readonly nodeGroups;
+    private readonly families;
+    /** Counts flights, so each one's arrivals get groups of their own. */
+    private flightCount;
+    private familyCount;
+    /** The lifted node and the drop target last drawn, so a change draws every node again. */
+    private dragMarks;
+    constructor(root: HTMLDivElement, definitions: SVGDefsElement, ids: ViewIds, layers: NodeLayers, host: NodeHost);
+    /** The view drawing a node, if it's on the map. */
+    view(id: string): NodeView | undefined;
+    /** Every node's view, by id. */
+    entries(): IterableIterator<[string, NodeView]>;
+    /** A new flight starts: the ideas it brings in get families of their own. */
+    startFlight(): void;
+    /** Takes a node's view off the map. */
+    removeView(id: string): void;
+    /** Takes every node off the map. */
+    clear(): void;
+    /**
+     * Turns the layers of the planets and moons with the orbit (see
+     * `OrbitTurn`). Returns the turn (degrees) its bodies are drawn in, or
+     * undefined when each is drawn where it is.
+     */
+    paintTurn(display: Display): number | undefined;
+    paintNodes(display: Display, turn: number | undefined): void;
+    /**
+     * The on-screen radius (px) below which flat bodies are specks, for this
+     * screen's pixels; the stylesheet sizes specks' rims from it.
+     */
+    private speckRadius;
+    /**
+     * A family whose members don't all move alike in this flight (some travel
+     * on, the rest leave) splits in two, the fewer of them moving to a group of
+     * their own, so each part moves as one.
+     */
+    private splitIfMixed;
+    /**
+     * The group a node is drawn in: its family's, in the layer of its role. A
+     * node stays in its group while its parent and role do, so nothing moves
+     * between groups when a flight lands; the ideas a flight brings in get a
+     * group of their own, so they can move as one while their siblings travel.
+     */
+    private placeInFamily;
+    /** A new family's group; one that starts hidden (newcomers yet to appear) is hidden before it joins the map, so its members aren't styled until they show. */
+    private createFamily;
+    private moveIntoFamily;
+}

package/dist/core/renderer/numbers.d.ts

@@ -0,0 +1,2 @@
+/** Numbers as the renderer writes them into the DOM: rounded, so unchanged values compare equal and attributes stay short. */
+export declare const round: (value: number, decimals?: number) => number;

package/dist/core/renderer/options.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The renderer's options: the caller's merged over the document's over the
+ * defaults, and the values Orbit works out from them (insets, spin settings).
+ */
+import type { Insets } from '../engine/camera.js';
+import { type SpinSettings } from '../engine/spin.js';
+import type { OrbitInsets, OrbitSpinOptions, RendererOptions } from '../types.js';
+export type ResolvedRendererOptions = RendererOptions & Required<Pick<RendererOptions, 'viewMode' | 'showRings' | 'interactive' | 'orbitAnimation' | 'orbitSpeed' | 'showControls'>>;
+export declare const spinSettings: (options: OrbitSpinOptions | undefined) => SpinSettings;
+export declare const mergeRendererOptions: (base: RendererOptions, overrides: RendererOptions) => ResolvedRendererOptions;
+/** The room the page's controls take at the map's edges, as numbers of px (none for anything else). */
+export declare const resolveInsets: (insets: OrbitInsets | undefined) => Insets;

package/dist/core/renderer/rings-and-links.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The rings around orbits and the lines between nodes in the overview, kept
+ * in step with each frame's display: one view each, written only when what it
+ * shows changed.
+ */
+import type { Display } from '../engine/display.js';
+/** The layers rings and links are drawn in, below the nodes. */
+export interface RingAndLinkLayers {
+    rings: SVGGElement;
+    links: SVGGElement;
+}
+export declare class RingsAndLinks {
+    private readonly layers;
+    private readonly rings;
+    private readonly links;
+    constructor(layers: RingAndLinkLayers);
+    /** Draws the display's rings (unless `showRings` is off) and links. */
+    paint(display: Display, showRings: boolean): void;
+    /** Takes every ring and link off the map. */
+    clear(): void;
+    private paintRings;
+    private paintLinks;
+}

package/dist/core/renderer/scene-helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Views of a scene the renderer works out: where its orbit starts, its planets
+ * in order, what of a display shows, where a view lands inside another, and a
+ * flight's display with a new or renamed node in it.
+ */
+import type { Camera, Similarity, Viewport } from '../engine/camera.js';
+import { type Display } from '../engine/display.js';
+import type { Scene, SceneNode } from '../engine/scene.js';
+/** Resizes within this share of the size a view was laid out for keep its layout: no one sees 2% in a node's size. */
+export declare const RELAYOUT_THRESHOLD = 0.02;
+/** A node an edit just added, and where it was typed: its first frame is there. */
+export interface Arrival {
+    id: string;
+    x: number;
+    y: number;
+    radius: number;
+}
+/** Whether `size` is within `RELAYOUT_THRESHOLD` of `laidOut` in both directions. */
+export declare const closeInSize: (size: Viewport, laidOut: Viewport) => boolean;
+/** How far the nearest planet's edge (or the +'s) is from the sun, in world units: the room around the sun. */
+export declare const innerEdges: WeakMap<Scene, number>;
+export declare const innerOrbitEdge: (scene: Scene) => number;
+/** Planets clockwise from the top. */
+export declare const orderedPlanets: (scene: Scene) => SceneNode[];
+export declare const clockwiseFromTop: (angle: number) => number;
+/** Places `target` so its fitted view matches `camera`: the views cross-fade without the camera moving. */
+export declare const overlayPlacement: (target: Scene, camera: Camera) => Similarity;
+/** Drops what has already faded out, so it isn't carried into the next flight. */
+export declare const visiblePart: (display: Display) => Display;
+/** `display` with a node an edit just added already where it was typed, so it stays there as the others make room. */
+export declare const withArrival: (display: Display, arrival: Arrival | null, target: Scene) => Display;
+/** `display` with the nodes an edit gave new ids under the new ones, so they move rather than leave and arrive. */
+export declare const renameNodes: (display: Display, renamed: ReadonlyMap<string, string>) => Display;

package/dist/core/renderer/trees.d.ts

@@ -0,0 +1,22 @@
+/** Maps as the renderer takes them: documents or trees, compared, checked and carried over between renders. */
+import { OrbitWords } from '../languages.js';
+import type { OrbitDocument, OrbitNode } from '../types.js';
+import type { EditorText } from '../ui/inline-editor.js';
+/** The field's text for a new idea under `parent`. */
+export declare const newIdeaText: (parent: OrbitNode, words: OrbitWords) => EditorText;
+export declare const sameValues: (first: unknown, second: unknown) => boolean;
+/** Says how to call an editing method that got something other than an object. */
+export declare const expectObject: (method: string, value: unknown, example: string) => void;
+/** Whether two trees hold the same map: the same nodes, ids and attributes, wherever their source wrote them. */
+export declare const sameTree: (first: OrbitNode, second: OrbitNode) => boolean;
+/**
+ * Moves where a fresh parse of the same map came from onto the tree as drawn:
+ * each node's own place, and the source itself (keyed by node, see
+ * `documentSource`), so saving writes the new text against the nodes the map
+ * already shows.
+ */
+export declare const transplantSource: (kept: OrbitNode, fresh: OrbitNode) => void;
+/** An object's entries that have a value. */
+export declare const definedEntries: (value: object) => Record<string, unknown>;
+export declare const isOrbitDocument: (input: OrbitNode | OrbitDocument) => input is OrbitDocument;
+export declare const isEmptyTree: (tree: OrbitNode) => boolean;