@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/ui/controls.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Map controls: real, themable buttons in an HTML layer over the map.
+ * Wide containers show breadcrumbs; narrow ones a back chip with the
+ * parent's name (switched by a container query in the stylesheet).
+ */
+import type { OrbitNode, ViewMode } from '../types.js';
+import type { OrbitWords } from '../languages.js';
+export interface ControlsCallbacks {
+    onNavigate(nodeId: string): void;
+    onViewMode(mode: ViewMode): void;
+    onZoom(direction: 1 | -1): void;
+    onFit(): void;
+    onToggleOutline(): void;
+}
+export interface ControlsState {
+    viewMode: ViewMode;
+    /** From the root to the focused node. */
+    path: OrbitNode[];
+    outlineOpen: boolean;
+}
+/** A rectangle on the map, in px from its top left corner. */
+export interface ScreenBox {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export declare class Controls {
+    readonly element: HTMLDivElement;
+    private readonly callbacks;
+    private readonly back;
+    private readonly backLabel;
+    private readonly breadcrumbs;
+    private readonly breadcrumbPanel;
+    private readonly viewGroup;
+    private readonly focusButton;
+    private readonly overviewButton;
+    private readonly outlineButton;
+    private readonly zoomPanel;
+    private readonly zoomInButton;
+    private readonly fitButton;
+    private readonly zoomOutButton;
+    private readonly hint;
+    private hintTimer;
+    private parentId;
+    private words;
+    private state;
+    constructor(callbacks: ControlsCallbacks, words: OrbitWords);
+    /** Writes every label in `words`' language. */
+    relabel(words: OrbitWords): void;
+    update(state: ControlsState): void;
+    /**
+     * Where the zoom buttons are on a map `width` by `height` px, known
+     * without laying them out, or null while the controls are hidden.
+     */
+    zoomBox(width: number, height: number): ScreenBox | null;
+    /** Shows a short message at the bottom of the map. */
+    showHint(text: string, duration?: number): void;
+    destroy(): void;
+    private crumbs;
+}

package/dist/core/ui/detail-sheet.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The detail sheet: a node's media, note, status, tags and link. A native
+ * `<dialog>` opened as a modal, so it sits in the top layer, traps focus,
+ * closes with Esc and makes the page behind it inert. Phones get a bottom
+ * sheet that can be swiped down to close.
+ */
+import type { OrbitNode } from '../types.js';
+import { OrbitWords } from '../languages.js';
+export type DetailSection = 'details' | 'image' | 'video' | 'embed' | 'note';
+/** What the map tells the sheet about the node it shows, beyond its content: its type, actions and status look. */
+export interface SheetExtensions {
+    icon(node: OrbitNode): string | undefined;
+    typeLabel(node: OrbitNode): string | undefined;
+    /** Draws the node type's section, if it has one. */
+    details(node: OrbitNode): ((element: HTMLElement) => void) | undefined;
+    actions(node: OrbitNode): {
+        id: string;
+        label: string;
+        icon?: string;
+    }[];
+    runAction(node: OrbitNode, action: string, event: MouseEvent): void;
+    status(word: string): {
+        tone: string;
+        color?: string;
+    };
+}
+export interface DetailRequest {
+    node: OrbitNode;
+    /** Ancestors from the root, for the path above the title. */
+    path: OrbitNode[];
+    /** Siblings to step through with the previous / next buttons and arrow keys. */
+    siblings: OrbitNode[];
+    section?: DetailSection;
+    baseUrl?: string;
+    noteRenderer?: (note: string, context: {
+        node: OrbitNode;
+        format: 'markdown' | 'plain';
+    }) => string;
+    /** Called when the reader steps to a sibling. */
+    onNavigate?: (node: OrbitNode) => void;
+    /** The node a `#id` link points at, if the map has it. */
+    resolveLink?: (href: string) => OrbitNode | null;
+    /** Called, after the sheet closes, when the reader follows a link to another node. */
+    onFollowLink?: (node: OrbitNode) => void;
+    /** The map's node types, actions and status words. */
+    extensions?: SheetExtensions;
+    /**
+     * Opens the media viewer on the node's picture or video: with it, the
+     * picture is a button and the video gets one. `startAt` is where the
+     * sheet's own player of a video file was.
+     */
+    onViewMedia?: (node: OrbitNode, kind: 'image' | 'video', event: MouseEvent, startAt?: number) => void;
+    /** The map's words, in its language. Default: English. */
+    words?: OrbitWords;
+}
+export declare class DetailSheet {
+    private readonly host;
+    private dialog;
+    private request;
+    private returnFocus;
+    constructor(host: HTMLElement);
+    get isOpen(): boolean;
+    /** The words of the map that opened the sheet. */
+    private get words();
+    /** The node being shown, if the sheet is open. */
+    get node(): OrbitNode | null;
+    open(request: DetailRequest): void;
+    close(): void;
+    /** Closes the sheet, then hands the linked node to the map to fly to. */
+    private followLink;
+    destroy(): void;
+    private restoreFocus;
+    private ensureDialog;
+    private step;
+    private enableSwipeToClose;
+    private buildContent;
+    private stepButton;
+    private buildChips;
+    private buildMedia;
+    /**
+     * The button that moves a video to the media viewer. The sheet's own
+     * player stops first; a video file goes on from where it was.
+     */
+    private expandButton;
+    private figure;
+}
+/** Maps a free-text status onto a theme color: active, done, blocked, todo or neutral. */
+export declare const statusTone: (status: string) => "active" | "done" | "blocked" | "todo" | "neutral";

package/dist/core/ui/frames.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Frames for the detail sheet and the media viewer: another site's page
+ * (an embed), and YouTube's and Vimeo's players.
+ */
+/** A page shown in a frame, or null when its URL isn't allowed in one. */
+export declare const embedFrame: (url: string, baseUrl: string | undefined, title: string) => HTMLIFrameElement | null;
+/**
+ * YouTube's or Vimeo's player in a frame, from an embed URL made by
+ * `toVideoEmbedUrl`, or null when its URL isn't allowed in one.
+ */
+export declare const playerFrame: (src: string, title: string) => HTMLIFrameElement | null;

package/dist/core/ui/icons.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One icon set for every control: a 24 px grid, 1.75 px strokes with round
+ * caps and joins. Each icon is a list of SVG path commands.
+ */
+export type IconName = 'back' | 'home' | 'chevron' | 'focus' | 'overview' | 'zoom-in' | 'zoom-out' | 'fit' | 'image' | 'video' | 'embed' | 'note' | 'link' | 'goto' | 'info' | 'close' | 'previous' | 'next' | 'list' | 'expand';
+/** An inline, decorative icon element for HTML controls. */
+export declare const createIcon: (name: IconName) => SVGSVGElement;
+export declare const iconPaths: (name: IconName) => readonly string[];
+/**
+ * The icon for one of your actions: one of these icons by name, SVG path
+ * data on the same 24-unit grid (`'M4 20h4L20 8l-4-4L4 16z'`), or an emoji
+ * or short symbol. Without one, the label's first letter.
+ */
+export declare const createActionIcon: (icon: string | undefined, label: string) => Element;

package/dist/core/ui/inline-editor.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The field for typing a node's text on the map: a textarea laid over the
+ * node each frame, in the label's font, size and color. Enter saves, Escape
+ * cancels, and leaving the field saves.
+ */
+import type { NodeRole } from '../engine/scene.js';
+export interface InlineEditorCallbacks {
+    /** Enter, or the field losing focus: keep `text`. */
+    onSave(text: string, how: 'enter' | 'blur'): void;
+    /** Escape. */
+    onCancel(): void;
+    /** Tab (`back` for Shift+Tab), with `text` typed. Returns whether it was used; if not, Tab moves keyboard focus as usual. */
+    onTab(text: string, back: boolean): boolean;
+}
+/** Where the field goes this frame: centered on a node, in screen pixels. */
+export interface EditorPlacement {
+    x: number;
+    y: number;
+    /** The width text gets inside the node. */
+    width: number;
+    /** The label's font size, which the text takes on. */
+    fontSize: number;
+    /** The tallest the field grows before it scrolls. */
+    maxHeight: number;
+    role: NodeRole;
+    /** Light text, on a dark node. */
+    light: boolean;
+    /** A new idea, in the + rather than a node. */
+    slot: boolean;
+    /** Over a node too small to hold it, on a card of its own. */
+    floating: boolean;
+    /** How far below its center (px) the field may reach: the top of the node's "+N", which the field rises to keep clear of as it grows. */
+    lowest?: number;
+}
+export interface EditorText {
+    /** What the field is for, for assistive technology. */
+    label: string;
+    placeholder: string;
+    /** The label of a phone keyboard's Enter key: `next` while ideas keep coming, `done` otherwise. */
+    enterKey: 'next' | 'done';
+}
+export declare class InlineEditor {
+    readonly element: HTMLTextAreaElement;
+    private readonly callbacks;
+    private open;
+    /** Closing blurs the field: that blur is no save. */
+    private closing;
+    /** One Enter can arrive as a key and as a line break: a second one straight after, with nothing typed between, is ignored. */
+    private savedAt;
+    private typedSinceSave;
+    /** The size and style last applied, and the position, so frames that change nothing touch no styles. */
+    private look;
+    private position;
+    /** Where the field was last placed (null while it's out of sight), to move it again when it grows. */
+    private placement;
+    /** The field's height (px, unscaled) as it last grew to fit its text. */
+    private height;
+    constructor(callbacks: InlineEditorCallbacks);
+    get isOpen(): boolean;
+    get value(): string;
+    get hasFocus(): boolean;
+    /** Shows the field holding `value`, all selected, with the cursor in it. */
+    show(value: string, text: EditorText): void;
+    /** Empties the field for the next idea. The cursor stays, and with it a phone's keyboard. */
+    clear(text: EditorText): void;
+    hide(): void;
+    /** Lays the field over its node, or keeps it out of sight (and focused) while the node isn't shown. */
+    place(placement: EditorPlacement | null): void;
+    private describe;
+    /** Centers the field over its node, risen as far as it must to keep clear of the node's "+N". */
+    private move;
+    /** Grows the field with its text. */
+    private fit;
+    private save;
+    private readonly handleKeyDown;
+    private readonly handleBeforeInput;
+    private readonly handleInput;
+    private readonly handleBlur;
+}

package/dist/core/ui/media-players.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Videos in the media viewer, behind one interface: a file plays in a
+ * `<video>` element, and YouTube and Vimeo in their own players, framed and
+ * driven through the messages those players take (the same ones their
+ * JavaScript APIs send). A video on any other site is framed as the detail
+ * sheet frames it, with nothing to drive.
+ */
+import type { OrbitNode } from '../types.js';
+/** A video as it plays. */
+export interface PlaybackState {
+    /** Playing, rather than paused, not started yet, or ended. */
+    playing: boolean;
+    /** Seconds from the start. */
+    time: number;
+    /** Seconds, once known. */
+    duration: number | null;
+    /** It played to the end. */
+    ended: boolean;
+    /** Its sound is off. */
+    muted: boolean;
+}
+export interface MediaPlayer {
+    /** What shows the video: a `<video>` element or a frame. */
+    readonly element: HTMLVideoElement | HTMLIFrameElement;
+    /** Width over height, as far as it's known yet. */
+    readonly ratio: number;
+    /** Whether `play`, `pause` and `seek` reach the video, and it reports its state. */
+    readonly controllable: boolean;
+    readonly state: PlaybackState;
+    play(): void;
+    pause(): void;
+    /** Moves to `seconds` from the start. */
+    seek(seconds: number): void;
+    /** Turns its sound on. */
+    unmute(): void;
+    /** Shows or hides the player's own controls, where that can change while it plays. */
+    setControls(controls: boolean): void;
+    /** Stops the video and lets go of it. */
+    destroy(): void;
+}
+export interface PlayerOptions {
+    /** Start playing as soon as it can. */
+    autoplay: boolean;
+    /** Show the player's own controls. */
+    controls: boolean;
+    /** Seconds into the video to start at. */
+    startAt?: number;
+    /** The frame's or video's accessible name. */
+    title: string;
+    /** A picture to show before a video file plays. */
+    poster?: string;
+    baseUrl?: string;
+    /** It played, paused, moved on, ended or was muted. */
+    onState(state: PlaybackState): void;
+    /** It learned its width over height. */
+    onRatio(ratio: number): void;
+    /** A video file couldn't be played. */
+    onError(): void;
+}
+/**
+ * The player for a node's video, or null when its URL isn't allowed. Files
+ * (`.mp4`, `.webm`, `.mov`, `blob:` URLs, or `provider: native`) play in a
+ * `<video>` element; YouTube and Vimeo in their players.
+ */
+export declare const createPlayer: (video: NonNullable<OrbitNode["video"]>, options: PlayerOptions) => MediaPlayer | null;

package/dist/core/ui/media-viewer.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The media viewer: a node's picture or video over the whole window, to see
+ * the one up close and to play the other. A native `<dialog>` opened as a
+ * modal, so it sits in the top layer above a map of any size, keeps focus
+ * inside and makes the page behind it inert.
+ *
+ * Pictures fit the window. The wheel, a pinch, a double click or tap, the
+ * +, − and 0 keys and the zoom buttons zoom them around the point under the
+ * pointer, and a zoomed picture pans with a drag. Previous and next step
+ * through the map's pictures and videos in reading order; so do the arrow
+ * keys and, on touch screens, a swipe, while the picture isn't zoomed. Esc,
+ * a click around the media or a swipe down closes it.
+ *
+ * On a map that isn't interactive, the viewer is the page's to drive: no
+ * buttons, no input of its own and no controls on videos.
+ */
+import type { OrbitNode } from '../types.js';
+import type { OrbitWords } from '../languages.js';
+import { type MediaPlayer, type PlaybackState } from './media-players.js';
+export type MediaKind = 'image' | 'video';
+/** A node's picture or its video. */
+export interface MediaItem {
+    node: OrbitNode;
+    kind: MediaKind;
+}
+/** What the viewer asks the map, and tells it. */
+export interface MediaViewerContext {
+    /** The map's pictures and videos, in reading order. */
+    items(): MediaItem[];
+    /** The map's node with this id, while it has one. */
+    node(id: string): OrbitNode | null;
+    baseUrl(): string | undefined;
+    /** Whether the map takes input; without it, neither does the viewer. */
+    interactive(): boolean;
+    /** The icon before a node's title: its own, or its type's. */
+    icon(node: OrbitNode): string | undefined;
+    /** It shows `item`, `index` of `total`: as it opens, and at every step. */
+    onShow(item: MediaItem, index: number, total: number): void;
+    /** It closed while showing `item`. */
+    onClose(item: MediaItem, index: number, total: number): void;
+    /** The video it shows started, paused, moved on, ended or was muted. */
+    onState(node: OrbitNode, state: PlaybackState): void;
+    /** The map's words, in its language. */
+    words(): OrbitWords;
+}
+export interface MediaShowOptions {
+    /** Start a video playing. Default true. */
+    autoplay?: boolean;
+    /** Start a video this many seconds in: where the detail sheet's player was, or where the page says. */
+    startAt?: number;
+}
+/** Whether a node's picture or video can be shown: it has one, at a URL allowed there. */
+export declare const showsMedia: (node: OrbitNode, kind: MediaKind) => boolean;
+/**
+ * The map's pictures and videos in reading order: depth first, as the
+ * outline lists the map, a node's picture before its video. Nodes below
+ * `maxDepth` are left out, as they are from the map.
+ */
+export declare const galleryItems: (tree: OrbitNode, maxDepth?: number) => MediaItem[];
+export declare class MediaViewer {
+    private static count;
+    private readonly host;
+    private readonly context;
+    private readonly id;
+    private dialog;
+    private parts;
+    private shown;
+    private items;
+    private index;
+    private picture;
+    private player;
+    /** The player's frame or video, in the box fitted to its width over height. */
+    private playerBox;
+    private returnFocus;
+    private resizeObserver;
+    private readonly pointers;
+    private press;
+    /** A pinch, from where it started: the picture's view, and the fingers' distance and middle (from the stage's center). */
+    private pinch;
+    private suppressClick;
+    private lastTap;
+    private settleTimer;
+    constructor(host: HTMLElement, context: MediaViewerContext);
+    get isOpen(): boolean;
+    /** What it shows, while it's open. */
+    get item(): MediaItem | null;
+    /** The video it shows, while it shows one that can be driven. */
+    get video(): MediaPlayer | null;
+    /**
+     * Shows a node's picture or video, opening the viewer if it's closed.
+     * Returns false when the node has no such media to show.
+     */
+    open(item: MediaItem, options?: MediaShowOptions): boolean;
+    close(): void;
+    /** Steps to the previous (-1) or next (1) picture or video. Returns false at either end. */
+    step(direction: 1 | -1): boolean;
+    /**
+     * The map changed: what the viewer shows takes the node's new title and
+     * media, or the viewer closes if the node or its media went away.
+     */
+    refresh(): void;
+    play(): boolean;
+    pause(): boolean;
+    seek(seconds: number): boolean;
+    unmute(): boolean;
+    destroy(): void;
+    /** Writes the viewer's buttons in the map's language, and what it shows, if it's open. */
+    relabel(): void;
+    private go;
+    private show;
+    private showPicture;
+    private pictureLoaded;
+    private showVideo;
+    /** Lets go of the media shown: a video stops. */
+    private clearMedia;
+    /** The title, caption, description, counter, link and buttons, for what's shown. */
+    private describe;
+    /** Where to see the picture on its own, or the video on its site; none for pictures in the map itself (`data:` and `blob:` URLs). */
+    private mediaLink;
+    /** Shows `text` over the stage, with a spinner while it's `loading`; null shows nothing. */
+    private setStatus;
+    /** Fits the picture or the player to the stage. */
+    private layout;
+    /**
+     * Where the media fits: the stage, less a margin, and the room the
+     * previous and next buttons take beside it on wide stages, or under a
+     * video on narrow ones.
+     */
+    private mediaRoom;
+    /** The stage's place in the window: happy-dom has no layout, so tests replace this. */
+    private readStageBox;
+    /** A point in the window, from the stage's center. */
+    private stagePoint;
+    private setView;
+    /** Zooms the picture by `factor` around `anchor` (from the stage's center). */
+    private zoomAt;
+    private fitPicture;
+    private panBy;
+    private get zoomed();
+    private updateZoomButtons;
+    /** A button that had focus and can't be pressed any more (the last step, the furthest zoom) hands focus to the viewer, which keeps its keys. */
+    private keepFocus;
+    private ensureDialog;
+    /** After the dialog closed, by `close()` or by the browser. */
+    private finish;
+    private observeStage;
+    private readonly handleKeyDown;
+    /** Plays the video if it's paused, and pauses it if it plays. */
+    private togglePlayback;
+    /** Esc, as the browser reports it: the viewer closes itself, so focus goes back and the map hears of it. */
+    private readonly handleCancel;
+    private readonly handleClick;
+    private readonly handleWheel;
+    /** A drag on the viewer never scrolls the page behind it. */
+    private readonly handleTouchMove;
+    private readonly handleDoubleClick;
+    private toggleZoomAt;
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    /** What a drag that starts this way does: pans a zoomed picture, or swipes across or down on a touch screen. */
+    private dragMode;
+    /** Brings media a swipe moved back to its place. */
+    private settleLayer;
+    private resetGestures;
+    private capture;
+    private pinchDistance;
+    private pinchCenter;
+}

package/dist/core/ui/media-zoom.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Geometry for pictures in the media viewer: fitting a picture to the
+ * window, zooming around a point that stays where it is, and keeping a
+ * zoomed picture over the stage while it is panned.
+ *
+ * Points are in px from the stage's center. A view is the picture's zoom
+ * relative to its fitted size, and where its center is.
+ */
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A picture shown `scale` times its fitted size, its center `x`, `y` px from the stage's center. */
+export interface PictureView {
+    scale: number;
+    x: number;
+    y: number;
+}
+export declare const FITTED: PictureView;
+/**
+ * The size a picture is drawn at to fit `room`: as large as fits, but no
+ * more than twice its own size, unless it's `scalable` (a vector picture).
+ */
+export declare const fittedSize: (natural: Size, room: Size, scalable?: boolean) => Size;
+/** The furthest a picture zooms in, relative to its fitted size. */
+export declare const maximumZoom: (natural: Size, fitted: Size) => number;
+/**
+ * `view` within its limits: zoomed between the fitted size and `maximum`,
+ * and placed so a picture bigger than the stage leaves no gap at its edges,
+ * while one smaller than the stage (in either direction) stays centered.
+ */
+export declare const clampView: (view: PictureView, fitted: Size, stage: Size, maximum: number) => PictureView;
+/**
+ * Zooms by `factor`, keeping the point of the picture under `anchor` where
+ * it is, as far as the limits allow.
+ */
+export declare const zoomAround: (view: PictureView, factor: number, anchor: Point, fitted: Size, stage: Size, maximum: number) => PictureView;
+/** Moves the picture by `deltaX`, `deltaY`, as far as its edges allow. */
+export declare const panView: (view: PictureView, deltaX: number, deltaY: number, fitted: Size, stage: Size, maximum: number) => PictureView;
+/**
+ * A double click or tap: back to the fitted view when zoomed in; otherwise
+ * in at `anchor`, to the picture's own size, or to twice the fitted size
+ * when that is further.
+ */
+export declare const toggleZoom: (view: PictureView, anchor: Point, natural: Size, fitted: Size, stage: Size, maximum: number) => PictureView;
+/** Whether the picture is zoomed in past its fitted size. */
+export declare const isZoomed: (view: PictureView) => boolean;

package/dist/core/ui/note-markdown.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A small, safe markdown renderer for notes. It builds DOM nodes directly
+ * (never `innerHTML`), so note text can't inject markup, and links and
+ * images go through the same URL guard as the rest of the map.
+ *
+ * Supported: paragraphs, headings, bullet and numbered lists (nested by
+ * indentation), blockquotes, fenced code, **bold**, *italic*, ~~strike~~,
+ * `code`, [links](https://…), <https://autolinks> and ![images](…).
+ */
+export interface NoteRenderContext {
+    /** Where relative links and pictures resolve from: the map's `baseUrl`. */
+    baseUrl?: string;
+    /** Whether a `#id` link points at a node of the map; links to missing nodes show as text. */
+    resolveLink?: (href: string) => unknown;
+}
+/** A note as DOM nodes, the way the detail sheet shows it: for pages that show notes in their own UI. */
+export declare const renderNoteMarkdown: (markdown: string, context?: NoteRenderContext) => DocumentFragment;
+/** The note as plain text, for tooltips: markdown syntax removed, whitespace collapsed. */
+export declare const noteToPlainText: (markdown: string) => string;

package/dist/core/ui/outline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The map as a nested list. Screen readers can always browse it (it is
+ * visually hidden but present), the list button shows it to everyone, and
+ * a polite live region announces where navigation landed.
+ */
+import type { OrbitNode } from '../types.js';
+import type { OrbitWords } from '../languages.js';
+export declare class AccessibleOutline {
+    readonly element: HTMLElement;
+    readonly live: HTMLDivElement;
+    private readonly onSelect;
+    private visible;
+    private icon;
+    /** Each node's entry, so moving between nodes only moves the current marker. */
+    private readonly entries;
+    private currentId;
+    private words;
+    constructor(onSelect: (nodeId: string) => void, words: OrbitWords);
+    /** Names the list in `words`' language; the next `update` writes its entries in it. */
+    relabel(words: OrbitWords): void;
+    get isVisible(): boolean;
+    /**
+     * Rebuilds the list. Without `interactive`, entries are plain text instead
+     * of buttons. `icon` gives a node's icon, its type's when it has none.
+     */
+    update(tree: OrbitNode, focusId: string | null, maxDepth: number | undefined, interactive: boolean, icon?: (node: OrbitNode) => string | undefined): void;
+    /** Marks the focused node's entry, without rebuilding the list: a big map's outline has thousands. */
+    setCurrent(focusId: string | null): void;
+    setVisible(visible: boolean): void;
+    announce(text: string): void;
+    private item;
+}
+/** A hover and keyboard-focus tooltip for nodes. */
+export declare class Tooltip {
+    readonly element: HTMLDivElement;
+    private readonly title;
+    private readonly detail;
+    constructor();
+    get isVisible(): boolean;
+    show(title: string, detail: string, x: number, y: number): void;
+    /** Puts the tooltip's tip at `x`, `y`, the tooltip centered above it. */
+    place(x: number, y: number): void;
+    hide(): void;
+}

package/dist/core/url-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * URL guard for Orbit. Validates the scheme per render surface, lets
+ * relative URLs through unchanged, and resolves them against an optional
+ * baseUrl.
+ */
+export type UrlSurface = 'image' | 'video' | 'embed' | 'link';
+/**
+ * A URL as browsers read it: without the control characters and spaces at
+ * its ends, and without tabs and line breaks anywhere. The URL standard drops
+ * them before it reads the scheme, so " javascript:" and "java\tscript:"
+ * are both "javascript:" to a browser.
+ */
+export declare const normalizeUrl: (url: string) => string;
+/**
+ * The URL to use on `surface`, or null when its scheme isn't allowed there.
+ * Checks the URL the way a browser will read it, and returns it in that form.
+ * A blocked URL is reported on the console, unless `report` is false: for
+ * checking one before it goes into a map.
+ */
+export declare const guardUrl: (input: string, surface: UrlSurface, report?: boolean) => string | null;
+/**
+ * Resolve a baseUrl string to its canonical absolute href.
+ *
+ * - Absolute baseUrls (`https://example.com/assets/`) are returned as `URL().href`.
+ * - Relative baseUrls (`/assets/`, `./foo/`) are resolved against `document.baseURI` in browsers.
+ * - Throws if baseUrl is relative and no `document.baseURI` is available (Node/SSR).
+ */
+export declare const resolveBaseUrl: (baseUrl: string) => string;
+/**
+ * Resolve `url` against `baseUrl` if relative; pass through if absolute or no baseUrl.
+ *
+ * - Absolute URLs (https://, http://, etc.) pass through unchanged.
+ * - Protocol-relative URLs (//host/path) are treated as already-absolute (resolved by the browser at fetch time).
+ * - Relative URLs (foo.jpg, ./x, /assets/y) are resolved against `baseUrl`.
+ *
+ * For directory-relative resolution, `baseUrl` should end with `/`.
+ * Per WHATWG URL spec, `new URL('foo.jpg', 'https://x/dir')` yields `https://x/foo.jpg`
+ * (the trailing path segment is consumed); `new URL('foo.jpg', 'https://x/dir/')` yields `https://x/dir/foo.jpg`.
+ */
+export declare const resolveUrl: (url: string, baseUrl: string | undefined) => string;

package/dist/core/utils.d.ts

@@ -0,0 +1,23 @@
+import type { OrbitNode } from './types.js';
+export declare const slugify: (value: string) => string;
+/**
+ * Slug used for auto-generated node ids in both parsers and for detecting
+ * explicit ids in both serializers (`nodesWithExplicitIds`), which is why
+ * it lives here.
+ */
+export declare const nodeSlug: (text: string) => string;
+/**
+ * Links a node to its parent. The link is non-enumerable so a parsed tree
+ * stays a plain tree for `JSON.stringify`, spreads and structured clones.
+ */
+export declare const setParent: (node: OrbitNode, parent: OrbitNode | undefined) => void;
+export declare const ensureUniqueNodeIds: (root: OrbitNode) => void;
+/**
+ * The nodes whose ids a serializer has to write: those the parsers wouldn't
+ * give them from their text. A second "Research" reads back as
+ * `research-2` on its own, so it needs no id attribute.
+ */
+export declare const nodesWithExplicitIds: (root: OrbitNode) => Set<OrbitNode>;
+export declare const findNodeById: (root: OrbitNode, id: string) => OrbitNode | null;
+export declare const getNodePath: (root: OrbitNode, id: string) => OrbitNode[];
+export declare const clamp: (value: number, min: number, max: number) => number;