@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/web-page/page.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A map as a web page: one HTML file with Orbit, the map and its pictures
+ * inside, which opens in any browser, offline. Readers explore it with
+ * Orbit's own controls, or present it: one idea at a time, in reading order,
+ * with its note as a caption (see runtime.ts, the page's script). Printed,
+ * it's the map laid out for paper (print-layout.ts) instead.
+ */
+import { type OrbitStrings } from '../languages.js';
+import type { OrbitDocument, OrbitRendererTheme, ViewMode } from '../types.js';
+export interface OrbitWebPageOptions {
+    /**
+     * Orbit's web page script, the file `@restless-dreams/orbit/web-page.js`,
+     * as text. It goes inside the page, so the page needs nothing else.
+     */
+    script: string;
+    /** The page's title. Default: the map's `title`, or its root's text. */
+    title?: string;
+    /** The map's theme, instead of its frontmatter's: a theme name or `{ preset, tokens }`. */
+    theme?: string | OrbitRendererTheme;
+    /** How the map opens: `focus` (default) or `all`, the overview. */
+    viewMode?: ViewMode;
+    /** The node in focus when the map opens, by id. Default: the root. */
+    focus?: string;
+    /** The language of the page and the map's words: a tag like `es`. Default: English. */
+    language?: string;
+    /** Single words to change: `{ present: 'Show' }`. */
+    strings?: Partial<OrbitStrings>;
+    /**
+     * Pictures to put inside the page, by the address the map gives them:
+     * `{ 'photos/summit.jpg': 'data:image/jpeg;base64,…' }`. A node's picture,
+     * a video's thumbnail and pictures in notes are swapped for them, so they
+     * show wherever the page goes.
+     */
+    media?: Record<string, string>;
+}
+/** What a web page carries for its script, as JSON in `#orbit-page`. */
+export interface WebPageData {
+    /** The map, in markdown or YAML. */
+    source: string;
+    theme?: string | OrbitRendererTheme;
+    viewMode?: ViewMode;
+    focus?: string;
+    language?: string;
+    strings?: Partial<OrbitStrings>;
+    media: Record<string, string>;
+}
+/**
+ * The map as one HTML page, with Orbit inside (`options.script`): open it in
+ * any browser, offline, to explore the map or present it.
+ *
+ * ```ts
+ * import { readFileSync } from 'node:fs';
+ * import { exportWebPage } from '@restless-dreams/orbit';
+ *
+ * const script = readFileSync(new URL(import.meta.resolve('@restless-dreams/orbit/web-page.js')), 'utf8');
+ * const html = exportWebPage(markdown, { script, theme: 'night' });
+ * ```
+ */
+export declare const exportWebPage: (input: string | OrbitDocument, options: OrbitWebPageOptions) => string;

package/dist/core/web-page/runtime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The script of a map shared as a web page (see page.ts). It draws the map
+ * from the page's JSON, with its pictures swapped for the ones inside the
+ * page, and presents it on request: one idea at a time, in reading order,
+ * with its note as a caption, stepped with keys, buttons or swipes, full
+ * screen where the browser allows. Printed, it's the map laid out for paper.
+ */
+import type { OrbitSVGRenderer } from '../svg-renderer.js';
+import type { OrbitDocument } from '../types.js';
+/** Draws the page's map and lets it be presented. Returns the map, or null on a page that isn't one. */
+export declare const startWebPage: (page?: Document) => OrbitSVGRenderer | null;
+/** The map with its pictures swapped for the ones inside the page, wherever the map shows them. */
+export declare const withMedia: (map: OrbitDocument, media: Record<string, string>) => OrbitDocument;

package/dist/core/web-page/start.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * Tiny YAML subset parser + emitter for Orbit, with no dependencies.
+ * Reads what maps and the frontmatter of other apps (Obsidian, static site
+ * generators) write: maps, block lists (indented under their key or not),
+ * flow lists and maps (`[a, b]`, `{name: Ana}`), strings, numbers,
+ * booleans and null, block scalars (`|` literal, `>` folded), plain and
+ * quoted strings over several lines, comments, anchors, aliases and merge
+ * keys (`&base`, `*base`, `<<: *base`). Not read: tags (`!!str`) and
+ * complex keys (`? key`).
+ *
+ * One leniency on purpose: a value that starts with `#` is text, not a
+ * comment, so `color: #FF6B6B` reads as the color people mean.
+ */
+export declare class YamlMiniError extends Error {
+    /** 1-based line of the problem in the text given to the parser. */
+    line: number;
+    /** The problem, without where it is. */
+    reason: string;
+    constructor(reason: string, line: number);
+}
+export type YamlValue = string | number | boolean | null | YamlValue[] | {
+    [k: string]: YamlValue;
+};
+/**
+ * The line `key` was written on in a map the last `parseYaml` read, or the
+ * map's first key's line without one: for problems that point at a node of
+ * a YAML document. Flow maps (`{ … }`) have none.
+ */
+export declare const yamlLineOf: (map: object, key?: string) => number | undefined;
+/** The line item `index` of a block list starts on. */
+export declare const yamlItemLine: (list: object, index: number) => number | undefined;
+export declare const parseYaml: (input: string) => YamlValue;
+/**
+ * Sets `obj[key]`, even when `key` is `__proto__`: a plain assignment would
+ * then change the object's prototype and lose the key, so it becomes an own
+ * enumerable data property.
+ */
+export declare const assignKey: (obj: Record<string, unknown>, key: string, value: unknown) => void;
+export declare const emitYaml: (value: YamlValue) => string;
+/**
+ * Whether a string written plain would read back as itself: no when other
+ * YAML readers would take it for a number or boolean, and no when this
+ * parser itself would hand back something else. Used by the emitter.
+ */
+export declare const needsQuotes: (s: string) => boolean;
+/**
+ * Whether a one-line value written plain after `key:` reads back as the same
+ * string through this parser: no anchors (`&a`), aliases (`*a`), block-scalar
+ * starts (`|`, `>+`), comments (` #`), or scalars read as something else
+ * (`~`, `.5`). Unlike `needsQuotes` this ignores what *other* YAML readers
+ * would do; markdown-writing uses it for values inside `<!-- orbit … -->`
+ * comments, which only Orbit reads.
+ */
+export declare const plainScalarReadsBack: (s: string) => boolean;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './core/index.js';