Core

Classes#

OrbitParseError#

Extends#

• Error

Constructors#

Constructor#

new OrbitParseError(
   message, 
   line, 
   code?
): OrbitParseError;

Parameters#

Returns#

OrbitParseError

Overrides#

Error.constructor

Properties#

code#

readonly code: 
  | "empty-document"
  | "no-structure"
  | "synthetic-root"
  | "invalid-frontmatter"
  | "unknown-frontmatter-key"
  | "unsupported-schema-version"
  | "invalid-attributes"
  | "unknown-attribute"
  | "invalid-option-value"
  | "media-missing-source"
  | "unknown-content-type"
  | "caption-without-media"
  | "unknown-link-target"
  | "invalid-yaml"
  | "unknown-yaml-key"
  | "ignored-node-entry";

line#

readonly line: number;

OrbitSVGRenderer#

Constructors#

Constructor#

new OrbitSVGRenderer(container, options?): OrbitSVGRenderer;

Parameters#

Returns#

OrbitSVGRenderer

Methods#

addNode()#

addNode(
   parentId, 
   input, 
   index?
): OrbitNode | null;

Adds a node under parentId, at index among its children (default: last); it flies out of its parent into place. Its id comes from its text, as when the map is read from markdown. Fires edit. Returns the new node, or null when there’s no such parent.

Parameters#

Returns#

OrbitNode | null

destroy()#

destroy(): void;

Returns#

void

editNewNode()#

editNewNode(parentId?, index?): boolean;

Adds an idea by typing it on the map: a field opens in the orbit of parentId (default: the node in focus), at index among its children (default: after the last), flying there first. Enter adds the idea where it was typed and opens the next one after it; Escape, or Enter with nothing typed, stops. Fires editor-open, edit for each idea, then editor-close. Returns false when there’s no such node.

Parameters#

Returns#

boolean

editNode()#

editNode(id): boolean;

Opens a field over a node to type its text where it is: Enter saves, Escape cancels, and leaving the field saves. A moon, or a node out of view, flies into view first. Fires editor-open, then editor-close. Returns false when there’s no such node.

Parameters#

Returns#

boolean

fit()#

fit(): void;

Returns the camera to the fitted view.

Returns#

void

flyTo()#

flyTo(id): boolean;

Flies to a node by id, switching to focus mode if needed (fires onFocusChange and onViewModeChange). Returns false when there’s no such node.

Parameters#

Returns#

boolean

focusNode()#

focusNode(id): boolean;

Focuses a node by id and flies to it (fires onFocusChange). In the overview, the camera moves to the node instead. Returns false when the id isn’t in the map.

Parameters#

Returns#

boolean

getDocument()#

getDocument(): OrbitDocument | null;

The map as a document: its tree, and the options its source set in frontmatter. Edits change this tree in place.

Returns#

OrbitDocument | null

getFocusedNode()#

getFocusedNode(): OrbitNode | null;

The node focused in focus mode (the sun).

Returns#

OrbitNode | null

getFocusPath()#

getFocusPath(): string[];

Ids from the root to the focused node.

Returns#

string[]

getNodeColor()#

getNodeColor(id): string | null;

The color a node is drawn with: its own, its type’s, or its branch’s from the palette and theme. For lists and legends next to the map. A hex color, or the CSS color as written when Orbit can’t read it; null when the id isn’t in the map.

Parameters#

Returns#

string | null

getSVGElement()#

getSVGElement(): SVGSVGElement;

Returns#

SVGSVGElement

getViewMode()#

getViewMode(): ViewMode;

Returns#

ViewMode

moveNode()#

moveNode(
   id, 
   parentId, 
   index?
): OrbitNode | null;

Moves a node, with everything under it, under parentId at index among its children (default: last). Fires edit. Returns the node, or null when either node is missing, the node is the root, or parentId is inside the node.

Parameters#

Returns#

OrbitNode | null

on()#

on<Name>(name, listener): () => void;

Listens for a map event; returns a function that stops listening. The same events are dispatched on the container as orbit-<name> DOM events.

Type Parameters#

Parameters#

Returns#

() => void

overview()#

overview(): void;

Flies out to the overview of the whole map (fires onViewModeChange).

Returns#

void

removeNode()#

removeNode(id): OrbitNode | null;

Removes a node and everything under it. When the node in focus goes, the nearest node left takes the focus. The root stays. Fires edit. Returns the removed node, or null.

Parameters#

Returns#

OrbitNode | null

render()#

render(input): void;

Draws a map: markdown or YAML source (parsed forgivingly), a parsed document, or a node tree. A document’s frontmatter options apply, though options given to the renderer win. Drawing a new version of the same map keeps the reader’s place: the focused node, or its closest ancestor that still exists.

Parameters#

Returns#

void

setOptions()#

setOptions(options): void;

Parameters#

Returns#

void

setViewMode()#

setViewMode(mode): void;

Switches between focus mode and the overview (fires onViewModeChange).

Parameters#

Returns#

void

spin()#

spin(speed): void;

Flicks the orbit at speed degrees per second; negative speeds turn it counterclockwise. Only in focus mode.

Parameters#

Returns#

void

stopEditing()#

stopEditing(save?): void;

Closes the field for typing on the map, keeping what was typed unless save is false.

Parameters#

Returns#

void

toMarkdown()#

toMarkdown(): string;

The map as orbit-md, frontmatter included: what to save after an edit.

Returns#

string

toSVGString()#

toSVGString(): string;

The current view as a standalone SVG document: colors resolved, labels as SVG text, nothing that depends on the page’s stylesheet.

Returns#

string

unmount()#

static unmount(target): boolean;

Destroys the renderer drawing into target, if there is one. Returns whether there was.

Parameters#

Returns#

boolean

updateNode()#

updateNode(id, changes): OrbitNode | null;

Changes a node’s text or attributes: { text: 'Budget' }, { status: 'done' }, or { color: undefined } to remove one. New text gives the node a new id when its id came from its text and no link points at it, so the saved map needs no id attribute. Fires edit. Returns the node, or null when there’s no such node.

Parameters#

Returns#

OrbitNode | null

zoomBy()#

zoomBy(factor): void;

Zooms by factor around the middle of the map (above 1 zooms in).

Parameters#

Returns#

void

Interfaces#

AutoRenderOptions#

How a map looks and behaves. Every option is optional; options passed to the renderer win over the document’s frontmatter.

Extends#

• RendererOptions

Properties#

CreateOrbitMapOptions#

How a map looks and behaves. Every option is optional; options passed to the renderer win over the document’s frontmatter.

Extends#

• RendererOptions

Properties#

OrbitAction#

A button under the focused node and in its detail sheet.

Properties#

OrbitActionDetail#

The action event: call preventDefault() to skip what the button does (the detail sheet, the link, or your action’s run).

Extends#

• OrbitActionEvent

Properties#

Methods#

preventDefault()#

preventDefault(): void;

Returns#

void

OrbitActionEvent#

A button pressed under the focused node or in its detail sheet.

Extended by#

• OrbitActionDetail

Properties#

OrbitDiagnostic#

Properties#

OrbitDocument#

A parsed map: its tree, its options and the problems the parser worked around.

Properties#

OrbitDocumentOptions#

Options a document sets in its frontmatter (markdown) or top-level keys (YAML).

Properties#

OrbitEdit#

An edit to the map, as the edit event and onEdit report it.

Properties#

OrbitEditorEvent#

The field for typing a node’s text on the map (see editable, editNode and editNewNode).

Properties#

OrbitEventMap#

What a map reports, by event name. Listen with renderer.on(name, listener), or for orbit-<name> DOM events, which bubble from the map’s container (and out of <orbit-map>).

Properties#

OrbitMapElement#

The <orbit-map> element’s API, for code that holds a reference to one. It also dispatches the map’s events (orbit-focus-change, orbit-view-mode-change, orbit-node-click, orbit-action, orbit-spin-settle) and orbit-error.

Extends#

• HTMLElement

Properties#

Methods#

flyTo()#

flyTo(nodeId): boolean;

Flies to a node by id, in focus mode. Returns false when the map has no such node.

Parameters#

Returns#

boolean

overview()#

overview(): void;

Flies out to the overview of the whole map.

Returns#

void

refresh()#

refresh(): void;

Re-reads the source and redraws the map, keeping the reader’s place when it can.

Returns#

void

OrbitNode#

One node of a map, as the parsers produce it.

Properties#

OrbitNodeContextEvent#

A long press, right click or context menu key on a node.

Properties#

OrbitNodeType#

How nodes of one type look and behave. Nodes pick a type with type: name.

Properties#

OrbitRenderErrorDetail#

Detail of the orbit-error event dispatched on an element whose map couldn’t be drawn.

Properties#

OrbitRendererTheme#

A theme with your own values: { preset: 'night', tokens: { surface: '#0b1020', 'ring-dash': 'none' } }. Each token sets the matching --orbit-* CSS custom property on the map, so a value the page sets in its own CSS still wins.

Properties#

OrbitSpinOptions#

How a flicked orbit spins in focus mode.

Properties#

OrbitZoomOptions#

How the map responds to the wheel, trackpads and pinches.

Properties#

ParseOptions#

Properties#

ParseYamlOptions#

Properties#

RendererOptions#

How a map looks and behaves. Every option is optional; options passed to the renderer win over the document’s frontmatter.

Extended by#

• OrbitMindMapProps
• CreateOrbitMapOptions
• AutoRenderOptions

Properties#

RenderToSVGOptions#

Properties#

Type Aliases#

OrbitContentAction#

type OrbitContentAction = "image" | "video" | "embed" | "note" | "link" | "details";

Orbit’s own buttons for a node: its picture, video, embed, note, link, and its type’s details.

OrbitDiagnosticCode#

type OrbitDiagnosticCode = typeof DIAGNOSTIC_CODES[number];

OrbitDiagnosticSeverity#

type OrbitDiagnosticSeverity = "error" | "warning";

OrbitEventName#

type OrbitEventName = keyof OrbitEventMap;

OrbitNodeInput#

type OrbitNodeInput = Partial<Pick<OrbitNode, 
  | "text"
  | "icon"
  | "color"
  | "status"
  | "priority"
  | "tags"
  | "collapsed"
  | "link"
  | "note"
  | "noteFormat"
  | "image"
  | "video"
  | "embed"
  | "type"
| "attrs">>;

What addNode and updateNode take: a node’s text and attributes.

OrbitStatusStyle#

type OrbitStatusStyle = OrbitStatusTone | string & object;

How a status word looks: one of the dot tones, or any CSS color.

OrbitStatusTone#

type OrbitStatusTone = "active" | "done" | "blocked" | "todo" | "neutral";

The colored dots statuses get.

OrbitThemeName#

type OrbitThemeName = 
  | "paper"
  | "night"
  | "glass"
  | "glass-night"
  | "cosmos"
  | "blueprint"
  | "ink"
  | "contrast";

OrbitThemePreset#

type OrbitThemePreset = OrbitThemeName | "auto";

A built-in theme, or auto for paper or night following the reader’s light or dark preference.

OrbitThemeToken#

type OrbitThemeToken = typeof THEME_TOKENS[number];

OrbitThemeTokens#

type OrbitThemeTokens = Record<OrbitThemeToken, string>;

ViewMode#

type ViewMode = "focus" | "all";

focus: one node at the center with its children around it. all: the overview of the whole tree.

Variables#

DIAGNOSTIC_CODES#

const DIAGNOSTIC_CODES: readonly ["empty-document", "no-structure", "synthetic-root", "invalid-frontmatter", "unknown-frontmatter-key", "unsupported-schema-version", "invalid-attributes", "unknown-attribute", "invalid-option-value", "media-missing-source", "unknown-content-type", "caption-without-media", "unknown-link-target", "invalid-yaml", "unknown-yaml-key", "ignored-node-entry"];

Every kind of problem the parsers report.

ORBIT_THEME_PRESETS#

const ORBIT_THEME_PRESETS: Readonly<Record<OrbitThemeName, Readonly<OrbitThemeTokens>>>;

SUPPORTED_SCHEMA_VERSION#

const SUPPORTED_SCHEMA_VERSION: 1 = 1;

The newest schemaVersion a document may declare. A newer one gets a warning, or an error in strict mode.

THEME_TOKENS#

const THEME_TOKENS: readonly ["font-family", "label-font", "display-font", "label-weight", "display-weight", "label-letter-spacing", "label-shadow", "surface", "surface-pattern", "text", "muted-text", "root-text", "node-text", "node-text-inverse", "color-root", "color-1", "color-2", "color-3", "color-4", "color-5", "color-6", "color-7", "shade-light", "shade-dark", "node-fill-opacity", "moon-opacity", "node-highlight", "node-terminator", "node-shading", "node-stroke", "node-stroke-tint", "node-stroke-width", "badge-stroke", "node-shadow", "node-shadow-tint", "node-shadow-opacity", "node-shadow-offset", "node-shadow-size", "sun-shadow-opacity", "sun-shadow-size", "sun-halo", "sun-halo-tint", "sun-halo-opacity", "sun-halo-width", "sun-halo-dash", "sun-halo-size", "ring-stroke", "ring-tint", "ring-opacity", "ring-width", "ring-dash", "link-stroke", "link-tint", "link-opacity", "link-width", "link-dash", "focus-ring", "note-indicator", "control-background", "control-border", "control-text", "control-muted-text", "control-active-background", "control-active-text", "control-shadow", "control-blur", "tooltip-background", "tooltip-text", "action-background", "action-border", "action-text", "action-shadow", "sheet-background", "sheet-text", "sheet-muted-text", "sheet-border", "sheet-backdrop", "sheet-shadow", "sheet-blur", "chip-background", "chip-text", "link-text", "status-active", "status-done", "status-blocked", "status-todo", "status-neutral", "error-background", "error-border", "error-text"];

Theme tokens. Each token is a CSS custom property: set --orbit-<token> on the map or any ancestor to override it. Presets only provide defaults: internally every token resolves as var(--orbit-<token>, <preset value>).

Functions#

createOrbitMap()#

function createOrbitMap(
   target, 
   source, 
   options?
): OrbitSVGRenderer;

Draws a map into target in one call: markdown or YAML source, a parsed document or a node tree. Returns the renderer, to listen for events (renderer.on('focus-change', …)), draw new versions (renderer.render(source)) and clean up (renderer.destroy()).

The map fills target, so give it a height.

Parameters#

Returns#

OrbitSVGRenderer

Example#

import { createOrbitMap } from '@restless-dreams/orbit';

const map = createOrbitMap(document.querySelector('#map')!, '# Launch\n## Research\n## Build', { theme: 'auto' });
map.on('focus-change', ({ node }) => console.log(node.text));

defineOrbitMapElement()#

function defineOrbitMapElement(tagName?): void;

Registers the <orbit-map> element. Write the map as the element’s content (indent it however you like, <!-- orbit … --> comments included), inside a <script type="text/orbit"> child, or in a source attribute. The map renders in a shadow root, so the raw markdown is never displayed, and it redraws when the content or an attribute changes.

Parameters#

Returns#

void

Example#

<script type="module">
  import { defineOrbitMapElement } from '@restless-dreams/orbit';
  defineOrbitMapElement();
</script>

<orbit-map height="420" theme="night">
  # Launch
  ## Research <!-- orbit status: active -->
  ## Build
</orbit-map>

documentToRendererOptions()#

function documentToRendererOptions(options): RendererOptions;

The renderer options a document asks for in its frontmatter (or YAML top-level keys). title becomes the map’s accessible label. Container concerns (height, className) are left to the caller.

Parameters#

Returns#

RendererOptions

findNodeById()#

function findNodeById(root, id): OrbitNode | null;

Parameters#

Returns#

OrbitNode | null

formatDiagnostic()#

function formatDiagnostic(diagnostic): string;

Parameters#

Returns#

string

getNodePath()#

function getNodePath(root, id): OrbitNode[];

Parameters#

Returns#

OrbitNode[]

isOrbitThemePreset()#

function isOrbitThemePreset(value): value is OrbitThemePreset;

Whether value names a built-in theme: one of the presets or auto.

Parameters#

Returns#

value is OrbitThemePreset

isThemeName()#

function isThemeName(value): value is string;

Whether value names a theme: a built-in one, auto, or a registered one.

Parameters#

Returns#

value is string

parseOrbit()#

function parseOrbit(input, options?): OrbitDocument;

Parses an orbit document in either flavor. Markdown is the default; a document is read as YAML when its first line is a top-level YAML key (nodes:, title:, view:, …), it has a top-level nodes: list, or its frontmatter says flavor: yaml. A fenced “`orbit block is unwrapped first.

Problems the parser can work around are listed in diagnostics (each with a code, line, severity and a message that says how to fix it); pass { strict: true } to throw an OrbitParseError on the first one instead.

Parameters#

Returns#

OrbitDocument

Example#

import { parseOrbit } from '@restless-dreams/orbit';

const { root, diagnostics } = parseOrbit('# Launch\n## Research <!-- orbit status: active -->');
for (const problem of diagnostics ?? []) console.warn(`line ${problem.line}: ${problem.message}`);

parseOrbitMarkdown()#

function parseOrbitMarkdown(input, options?): OrbitDocument;

Parameters#

Returns#

OrbitDocument

parseOrbitYAML()#

function parseOrbitYAML(input, options?): OrbitDocument;

Parameters#

Returns#

OrbitDocument

registerAction()#

function registerAction(action): () => void;

Adds an action to every map. Returns a function that removes it again.

Parameters#

Returns#

() => void

registerNodeType()#

function registerNodeType(name, definition): () => void;

Defines a node type for every map: nodes with type: name (any case) take it. Returns a function that removes it again.

Parameters#

Returns#

() => void

registerStatus()#

function registerStatus(word, style): () => 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.

Parameters#

Returns#

() => void

registerTheme()#

function registerTheme(name, theme): () => void;

Names a theme for every map, so theme: 'brand' works in options, in a document’s frontmatter and on <orbit-map theme="brand">. It starts from preset (a built-in theme or another registered one) and sets its own tokens. Returns a function that removes it again.

Parameters#

Returns#

() => void

renderOrbitElement()#

function renderOrbitElement(element, options?): OrbitSVGRenderer | null;

Renders an orbit map into the given element. Problems in the document never throw: parse warnings go to the console, and a map that can’t be drawn is replaced by an error card and an orbit-error event on the element.

Callers who later detach the element should invoke OrbitSVGRenderer.unmount(element) to release RAF loops and the ResizeObserver. The <orbit-map> web component does this automatically.

Parameters#

Returns#

OrbitSVGRenderer | null

renderOrbitMarkdownBlocks()#

function renderOrbitMarkdownBlocks(root?, options?): OrbitSVGRenderer[];

Renders every orbit block under root (default: the whole document). Each block is independent: one that fails shows its error card and the rest still render.

Parameters#

Returns#

OrbitSVGRenderer[]

renderToSVGString()#

function renderToSVGString(input, options?): string;

Renders a map to a standalone SVG string, without a browser: for files, the command line, static sites and server rendering. It draws what the renderer shows at rest, with the theme’s colors resolved to plain values and the labels as SVG text.

Parameters#

Returns#

string

Example#

import { renderToSVGString } from '@restless-dreams/orbit';

const svg = renderToSVGString('# Launch\n## Research\n## Build', { width: 1200, height: 800, theme: 'cosmos' });

serializeOrbitMarkdown()#

function serializeOrbitMarkdown(doc): string;

Parameters#

Returns#

string

serializeOrbitYAML()#

function serializeOrbitYAML(doc): string;

Parameters#

Returns#

string

themeNames()#

function themeNames(): string[];

Every theme name: the built-in ones, auto, then the registered ones.

Returns#

string[]

themeTokens()#

function themeTokens(name): OrbitThemeTokens;

Concrete token values for a theme name, built in or registered, e.g. for exports outside a page. auto resolves to paper.

Parameters#

Returns#

OrbitThemeTokens