@restless-dreams/orbit 0.0.0-stage → 0.1.0

package/dist/core/markdown-writing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * How Orbit writes a map as markdown: its own form, the way people write
+ * maps. `serializeOrbitMarkdown` writes a whole map this way, and saving an
+ * edited map writes its changed ideas this way (see source-patch.ts).
+ */
+import type { OrbitDocument, OrbitNode } from './types.js';
+/** A whole map in Orbit's own form. */
+export declare const writeMarkdown: (doc: OrbitDocument) => string;
+export declare const collectFrontmatter: (doc: Pick<OrbitDocument, "options" | "extra">) => Record<string, unknown>;
+/**
+ * The root and its children are headings; everything under them is a
+ * list, the way people write maps. Below two levels, headings would only
+ * make a map harder to read.
+ */
+export declare const HEADING_LEVELS = 2;
+/** The statuses a list item writes as a checkbox. */
+export declare const CHECKBOXES: Record<string, string>;
+/** What writing a node needs besides the node: which ids to write. */
+export interface Writing {
+    /** The nodes whose ids the parsers wouldn't make from their text, so they are written. */
+    explicitIds: ReadonlySet<OrbitNode>;
+}
+export declare const emitHeading: (node: OrbitNode, level: number, writing: Writing) => string;
+export declare const emitList: (children: OrbitNode[], indent: string, writing: Writing) => string;
+/**
+ * A node as written: its line after the heading's `#`s or the item's
+ * marker (title, then the attributes that fit on it), and what follows the
+ * line, indented by `indent`.
+ */
+export declare const nodeParts: (node: OrbitNode, listItem: boolean, writing: Writing, indent: string) => {
+    line: string;
+    title: string;
+    inline: string;
+    body: string;
+};
+/** The pieces of a node as written, each ending with a line break (or empty): see `nodeParts`. */
+export interface NodePieces {
+    title: string;
+    /** The attributes on the title line, with the space before them; empty when they don't fit there. */
+    inline: string;
+    /** The attributes that didn't fit on the line, as a block of their own. */
+    attributes: string;
+    media: string;
+    note: string;
+}
+export declare const nodePieces: (node: OrbitNode, listItem: boolean, writing: Writing, indent: string) => NodePieces;
+export declare const titleLine: (node: OrbitNode, listItem: boolean, writing: Writing) => {
+    title: string;
+    attributes: Record<string, unknown>;
+};
+/**
+ * Attributes on the node's own line, `<!-- orbit status: done, priority: 2 -->`,
+ * when they are short, plain values: up to three of them, or more while the
+ * comment stays short, as a goal's numbers are (`type: goal, target: 5,
+ * current: 2, unit: apples`). Keys that wouldn't survive the comma-separated
+ * form (with a quote, a comma, a colon or a space of their own) go to the
+ * block form instead.
+ */
+export declare const inlineAttributes: (attributes: Record<string, unknown>) => string;
+export declare const inlineValue: (value: unknown) => string | null;
+/** What follows a node's line, indented under a list item: attributes that didn't fit on the line, media, then the note. */
+export declare const body: (node: OrbitNode, blockAttributes: Record<string, unknown>, indent: string) => string;
+/** Attributes as a `<!-- orbit … -->` block of their own, indented by `indent`; nothing when there are none. */
+export declare const attributeBlock: (attributes: Record<string, unknown>, indent: string) => string;
+/** A node's note as written under it, indented by `indent`. */
+export declare const noteLines: (node: OrbitNode, indent: string) => string;
+/**
+ * A note as paragraphs when they read back as the same note, otherwise
+ * quoted: quoted lines never turn into nodes, so a note can hold lines that
+ * look like headings, lists or media.
+ */
+export declare const noteText: (note: string, listItem: boolean) => string;
+export declare const indentLines: (text: string, indent: string) => string;
+/**
+ * A node's text as a heading or list item title: as is when it reads back
+ * unchanged, otherwise with its markup characters escaped.
+ */
+export declare const escapeTitle: (text: string) => string;
+export declare const renderMedia: (node: OrbitNode) => string;
+/**
+ * YAML to write inside an HTML comment. A "-->" in a value would end the
+ * comment early, so its ">" is written as an escape; strings holding one are
+ * always double-quoted, where the escape reads back as ">".
+ */
+export declare const commentYaml: (value: Record<string, unknown>) => string;
+/** Attributes carried in `<!-- orbit ... -->` comments: the ones a node's title and lines don't show. */
+export declare const collectAttrs: (node: OrbitNode, explicitIds: ReadonlySet<OrbitNode>) => Record<string, unknown>;

package/dist/core/material.d.ts

@@ -0,0 +1,25 @@
+import type { OrbitRendererTheme } from './types.js';
+/**
+ * Material 3 themes from one color, the way Material You colors an app from
+ * its wallpaper: tonal palettes in the color's hue, surfaces and containers
+ * picked by tone, and branches in hues spread evenly around the color wheel
+ * from it. Picking colors by tone is what keeps text readable: two tones 50
+ * apart always have at least 4.5:1 contrast.
+ */
+/** Material's baseline color: the `material` and `material-night` themes are built from it. */
+export declare const MATERIAL_SEED = "#6750A4";
+export interface MaterialThemeOptions {
+    /** Dark surfaces with light text, like `material-night`, instead of light ones. */
+    dark?: boolean;
+}
+/** The tokens a Material theme takes from its color: everything else comes from `material` or `material-night`. */
+export declare const MATERIAL_COLOR_TOKENS: readonly ["surface", "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-stroke", "badge-stroke", "sun-halo", "ring-stroke", "link-stroke", "focus-ring", "note-indicator", "control-background", "control-text", "control-muted-text", "control-active-background", "control-active-text", "tooltip-background", "tooltip-text", "action-background", "action-text", "sheet-background", "sheet-text", "sheet-muted-text", "sheet-border", "chip-background", "chip-text", "link-text", "status-active", "status-done", "status-blocked", "status-todo", "status-neutral", "error-background", "error-border", "error-text"];
+export type MaterialColorToken = (typeof MATERIAL_COLOR_TOKENS)[number];
+/**
+ * A Material 3 theme built from `seed`, any CSS color Orbit reads (hex,
+ * `rgb()`, `oklch()`…). Use it as the `theme` option, or name it for every
+ * map: `registerTheme('brand', materialTheme('#0B57D0'))`.
+ */
+export declare const materialTheme: (seed: string, options?: MaterialThemeOptions) => OrbitRendererTheme;
+/** Every color token of a Material theme built from `seed`. */
+export declare const materialColors: (seed: string, dark: boolean) => Record<MaterialColorToken, string>;

package/dist/core/media.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Video provider helpers shared by the parser (provider detection), the
+ * renderer (thumbnail derivation), and the detail sheet and media viewer
+ * (embed URL conversion, and links to a video's page on its site).
+ *
+ * YouTube and Vimeo forbid framing their watch pages (X-Frame-Options /
+ * frame-ancestors); only the dedicated embed endpoints may be iframed, so
+ * anything that puts a video URL into an <iframe> must go through
+ * `toVideoEmbedUrl` first.
+ */
+export type VideoProvider = 'youtube' | 'vimeo' | 'native';
+/** Which player a video URL needs, by the site it is on; null when it isn't a video. */
+export declare const detectVideoProvider: (url: string) => VideoProvider | null;
+export declare const isNativeVideoUrl: (url: string) => boolean;
+/** The video id in any of YouTube's URL shapes: watch pages, youtu.be, embeds, Shorts and lives. */
+export declare const youtubeVideoId: (url: string) => string | null;
+/**
+ * A Vimeo video's id, and the hash an unlisted video needs, from its page
+ * (`vimeo.com/123`, `/123/abc`, channels, groups, showcases) or its player.
+ */
+export declare const vimeoVideo: (url: string) => {
+    id: string;
+    hash?: string;
+} | null;
+/** The numeric id of a Vimeo video. */
+export declare const vimeoVideoId: (url: string) => string | null;
+/**
+ * Convert a video URL to a frameable embed URL. Returns null when no
+ * conversion is known (callers fall back to the original URL).
+ */
+export declare const toVideoEmbedUrl: (url: string, provider?: string) => string | null;
+/** Whether a YouTube URL is a Short, a video that plays upright. */
+export declare const isYouTubeShort: (url: string) => boolean;
+/** Where a video is watched on its site: its YouTube or Vimeo page, or the URL itself. */
+export declare const videoPageUrl: (url: string, provider?: string) => string;
+export declare const youtubeThumbnailUrl: (url: string) => string | null;
+/** True when an image, video or embed value has a usable `src`. */
+export declare const hasMediaSource: (media: {
+    src?: unknown;
+} | undefined | null) => media is {
+    src: string;
+};

package/dist/core/node-attributes.d.ts

@@ -0,0 +1,31 @@
+import type { DiagnosticCollector } from './diagnostics.js';
+import type { OrbitNode } from './types.js';
+type ImageMedia = NonNullable<OrbitNode['image']>;
+type VideoMedia = NonNullable<OrbitNode['video']>;
+type EmbedMedia = NonNullable<OrbitNode['embed']>;
+/**
+ * The fields a picture, video or embed was written with that Orbit doesn't
+ * read (a `width`, a provider it doesn't know): kept so saving writes them
+ * back, for a newer version or another app that reads them.
+ */
+export declare const mediaExtras: (media: object | undefined) => Record<string, unknown> | undefined;
+/** A copy of a picture, video or embed, with the fields Orbit doesn't read. */
+export declare const copyMedia: <Media extends object>(media: Media) => Media;
+export declare const readImage: (value: unknown) => ImageMedia | undefined;
+export declare const readVideo: (value: unknown) => VideoMedia | undefined;
+export declare const readEmbed: (value: unknown) => EmbedMedia | undefined;
+/** The attributes every node takes, in `<!-- orbit … -->` blocks and in YAML. */
+export declare const NODE_ATTRIBUTE_KEYS: readonly ["color", "icon", "status", "priority", "tags", "collapsed", "link", "note", "noteFormat", "image", "video", "embed", "caption", "id", "type"];
+/** Keys a flavor accepts besides the node attributes, and the words that stand in for them. */
+export interface AttributeVocabulary {
+    keys: readonly string[];
+    synonyms?: Readonly<Record<string, string>>;
+}
+/**
+ * Applies one typed attribute (from a `<!-- orbit ... -->` block or a YAML
+ * node map) to a node. Unknown keys are kept in `node.attrs`, with a note
+ * when they look like a misspelled attribute. Values Orbit can't read are
+ * reported and kept in `node.attrs` too, so they're written back.
+ */
+export declare const assignNodeAttribute: (node: OrbitNode, key: string, value: unknown, diagnostics: DiagnosticCollector, line?: number, vocabulary?: AttributeVocabulary) => void;
+export {};

package/dist/core/node-links.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Links between nodes. A node's link, or a link in its note, written as
+ * `#id` points at another node of the same map, the way `#heading` links
+ * point at a heading in a markdown page.
+ */
+import type { OrbitNode } from './types.js';
+import type { DiagnosticCollector } from './diagnostics.js';
+/** Whether a link points at a node of the same map: `#research`. */
+export declare const isNodeLink: (href: string | undefined) => href is string;
+/**
+ * The node a `#id` link points at: the node with that id, or the one whose
+ * id the fragment's text would get, so `#Research` and GitHub-style
+ * `#-research` anchors find `research` too.
+ */
+export declare const findLinkedNode: (root: OrbitNode, href: string) => OrbitNode | null;
+/** `findLinkedNode` with the map's nodes indexed by `indexNodes`, for checking many links at once. */
+export declare const findIndexedLinkedNode: (nodes: Map<string, OrbitNode>, href: string) => OrbitNode | null;
+/** The map's nodes by id; when ids repeat, the first in the tree, as `findNodeById` finds it. */
+export declare const indexNodes: (root: OrbitNode) => Map<string, OrbitNode>;
+/** The `#id` links a node has: its link, then the ones in its note. */
+export declare const nodeLinksOf: (node: OrbitNode) => string[];
+/** Where a parser saw a node's link (`inNote` false) or a link in its note: the line it's on, when it knows. */
+export type LinkLine = (node: OrbitNode, href: string, inNote: boolean) => number | undefined;
+/** Reports each `#id` link, in a node's link or note, that points at no node of the map, on its own line where `lineOf` knows it. */
+export declare const checkNodeLinks: (root: OrbitNode, diagnostics: DiagnosticCollector, lineOf?: LinkLine) => void;

package/dist/core/parser-markdown.d.ts

@@ -0,0 +1,42 @@
+import type { ParsedOrbitDocument } from './types.js';
+export { OrbitParseError } from './diagnostics.js';
+export { SUPPORTED_SCHEMA_VERSION } from './format-upgrades.js';
+export interface ParseOptions {
+    /**
+     * Throw an `OrbitParseError` on the first problem instead of recording a
+     * diagnostic and carrying on. Off by default; `orbit validate` turns it on.
+     */
+    strict?: boolean;
+    /**
+     * The name of the root Orbit makes up for a document with no single top
+     * heading and no title, in the reader's language. Default "Untitled map".
+     * Its id is `untitled-map` whatever its name.
+     */
+    untitled?: string;
+}
+/** Text of the generated root when a document has no single top-level heading or title. */
+export declare const UNTITLED_ROOT_TEXT = "Untitled map";
+/** The generated root's id, whatever the `untitled` option names it. */
+export declare const UNTITLED_ROOT_ID = "untitled-map";
+/** Whether an icon reads back from the start of a title (emoji do; other symbols need an `icon:` attribute). */
+export declare const isTitleIcon: (icon: string) => boolean;
+/** The emoji a title starts with, which a map reads as the node's icon, and the text after it; null for a title without one. */
+export declare const leadingEmoji: (title: string) => {
+    icon: string;
+    text: string;
+} | null;
+export interface TitleParts {
+    text: string;
+    icon?: string;
+    link?: string;
+    status?: string;
+    tags?: string[];
+}
+/**
+ * Reads a heading's or list item's text. `[ ]`, `[x]` and `[/]` set the
+ * status, an emoji first is the icon, hashtags at the end are tags, a link
+ * gives the node its link, and bold, italics, code and strikethrough show
+ * as plain text. A backslash keeps any of those characters literal.
+ */
+export declare const parseTitle: (raw: string) => TitleParts;
+export declare const parseOrbitMarkdown: (input: string, options?: ParseOptions) => ParsedOrbitDocument;

package/dist/core/parser-yaml.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedOrbitDocument } from './types.js';
+export interface ParseYamlOptions {
+    /** Throw on the first problem instead of recording a diagnostic. Off by default. */
+    strict?: boolean;
+    /** The name of the root Orbit makes up for several top-level nodes and no title. Default "Untitled map"; its id is `untitled-map` whatever its name. */
+    untitled?: string;
+}
+export declare const parseOrbitYAML: (input: string, options?: ParseYamlOptions) => ParsedOrbitDocument;

package/dist/core/render-to-svg.d.ts

@@ -0,0 +1,57 @@
+import { type OrbitNodeType, type OrbitStatusStyle } from './extensions.js';
+import type { OrbitDocument, OrbitNode, OrbitRendererTheme, OrbitThemePreset, ViewMode } from './types.js';
+import { type OrbitStrings } from './languages.js';
+/**
+ * The largest width or height the exporter accepts: a million pixels, far
+ * past any drawing. The label grid numbers its 64 px cells, and past about
+ * 6 × 10⁹ px a side those numbers stop being exact; past about 6 × 10¹⁷ its
+ * loops stop advancing and the export never finishes.
+ */
+export declare const MAX_SVG_EXPORT_SIZE = 1000000;
+export interface RenderToSVGOptions {
+    /** Width of the drawing, in pixels: positive, at most `MAX_SVG_EXPORT_SIZE`. Default 800. */
+    width?: number;
+    /** Height of the drawing, in pixels: positive, at most `MAX_SVG_EXPORT_SIZE`. Default 600. */
+    height?: number;
+    /** `focus` (default) or `all` for the overview. */
+    viewMode?: ViewMode;
+    /** The node at the center in focus mode, by id. Default: the root. */
+    focus?: string;
+    /** A theme name or an object of theme values. Default: the document's theme, or `paper`. */
+    theme?: OrbitThemePreset | (string & {}) | OrbitRendererTheme;
+    palette?: string[];
+    maxDepth?: number;
+    showRings?: boolean;
+    /** The SVG's title and accessible name. Default: the document's title, or the root's text. */
+    title?: string;
+    /** The language of the few words the drawing has (an untitled idea, the empty map): a BCP 47 tag. Default: English. */
+    language?: string;
+    /** Words to change, over the language's. */
+    strings?: Partial<OrbitStrings>;
+    /** Resolves relative image URLs. */
+    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;
+    /** Node types by name, before the registered ones: their icons, colors and tokens. */
+    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 drawn as, for display only (see `RendererOptions.nodeTypeFor`). */
+    nodeTypeFor?: (node: OrbitNode) => string | undefined;
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { renderToSVGString } from '@restless-dreams/orbit';
+ *
+ * const svg = renderToSVGString('# Launch\n## Research\n## Build', { width: 1200, height: 800, theme: 'cosmos' });
+ * ```
+ */
+export declare const renderToSVGString: (input: string | OrbitDocument | OrbitNode, options?: RenderToSVGOptions) => string;

package/dist/core/serializer-markdown.d.ts

@@ -0,0 +1,18 @@
+import type { OrbitDocument } from './types.js';
+export interface SerializeOptions {
+    /**
+     * Keep the source's own lines for everything an edit didn't change (the
+     * default, for a document parsed from markdown): its formatting, and the
+     * text Orbit doesn't read, such as other HTML comments or frontmatter
+     * keys of other apps. `false` writes the whole map in Orbit's own form.
+     */
+    keepSource?: boolean;
+}
+/**
+ * A map as orbit-md. A document parsed from markdown comes back as it was
+ * written, with only what changed since rewritten, so maps written by hand
+ * or by other apps keep their formatting and everything Orbit doesn't read.
+ * Other documents (built in code, or read from YAML) are written in Orbit's
+ * own form: headings for the root and its children, lists below them.
+ */
+export declare const serializeOrbitMarkdown: (doc: OrbitDocument, options?: SerializeOptions) => string;

package/dist/core/serializer-yaml.d.ts

@@ -0,0 +1,2 @@
+import type { OrbitDocument } from './types.js';
+export declare const serializeOrbitYAML: (doc: OrbitDocument) => string;

package/dist/core/source-patch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Saving an edited map without rewriting it. Every line an edit didn't
+ * change is written back as it was, and only what changed is written again,
+ * in place, in Orbit's own form: a renamed idea gets a new title, a moved
+ * one takes its lines along. A map written by hand, or by another app,
+ * keeps its formatting and everything Orbit doesn't read: other HTML
+ * comments, rules, the frontmatter keys of other apps.
+ *
+ * The result is read back before it's used: when it doesn't read as the
+ * edited map, saving falls back to rewriting the changed ideas whole, then
+ * to Orbit's own form for the whole map.
+ */
+import type { OrbitDocument } from './types.js';
+import { type DocumentSource } from './document-source.js';
+/**
+ * The document as markdown, its source's lines kept wherever nothing
+ * changed; null when that can't be done faithfully.
+ */
+export declare const patchMarkdown: (document: OrbitDocument, source: DocumentSource) => string | null;
+/**
+ * The patched text without checking that it reads back, or why it couldn't
+ * be made: for tests and debugging.
+ */
+export declare const patchedText: (document: OrbitDocument, source: DocumentSource, coarse?: boolean) => string;

package/dist/core/source.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Source text helpers shared by the dispatcher and both parsers. Normalizing
+ * never adds or removes lines, so diagnostics keep pointing at the line the
+ * author wrote.
+ */
+/**
+ * Strips a byte-order mark, converts CRLF/CR line endings to LF, and removes
+ * indentation shared by every non-blank line, so markdown indented inside
+ * HTML or a template literal parses like flush-left markdown.
+ */
+export declare const normalizeSource: (input: string) => string;
+/** The indentation every non-blank line shares, which `normalizeSource` removes. */
+export declare const sharedIndentation: (text: string) => string;
+export declare const dedent: (text: string) => string;
+export declare const firstContentLineIndex: (lines: string[]) => number;
+export interface FrontmatterBlock {
+    /** The YAML between the fences. */
+    yaml: string;
+    /** 0-based index of the opening `---` line. */
+    openIndex: number;
+    /** 0-based index of the closing `---` line. */
+    closeIndex: number;
+}
+/** Frontmatter is a `---` fenced block starting on the first non-blank line. */
+export declare const findFrontmatter: (lines: string[]) => FrontmatterBlock | null;
+/** 1-based line of the first `key:` entry inside a frontmatter or YAML block. */
+export declare const lineOfKey: (lines: string[], key: string, fromIndex?: number, toIndex?: number) => number | undefined;

package/dist/core/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Adds the orbit stylesheet, once, to the document or shadow root that holds
+ * `element`. Constructable stylesheets are used where available, so pages
+ * with a strict Content Security Policy keep working.
+ */
+export declare const ensureStyles: (element: Node) => void;

package/dist/core/suggest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * "Did you mean …?" for keys and values a document misspells: a known
+ * synonym (`colour` for `color`, `dark` for `night`), or the closest known name
+ * within a couple of typos, ignoring case.
+ */
+export declare const suggest: (input: string, candidates: readonly string[], synonyms?: Readonly<Record<string, string>>) => string | undefined;
+/** " Did you mean "x"?" when there is a suggestion, otherwise nothing. */
+export declare const didYouMean: (input: string, candidates: readonly string[], synonyms?: Readonly<Record<string, string>>) => string;