@markmap/core 0.0.0-stage → 1.0.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Gerald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @markmap/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Markmap types, tree utilities and plugin contracts.
+
+See the [Markmap README](https://github.com/markmap/markmap#readme) for how the packages fit together.

package/dist/content.d.ts

@@ -0,0 +1,75 @@
+import type { Root as HastRoot } from 'hast';
+import type { Rect, Size } from './geometry';
+import type { FontStyle, Paint, Primitive } from './primitives';
+import type { Measurer, Theme } from './theme';
+import type { Inline, MarkmapNode } from './types';
+/** Font and color of a piece of text. */
+export interface TextStyle {
+    font: FontStyle;
+    fill: Paint;
+}
+/** Drawing around a styled span. Spans may wrap across lines; each line gets its own piece. */
+export interface Decoration {
+    /** Background behind the span. */
+    background?: Paint;
+    /** Corner radius of the background. */
+    radius?: number;
+    /** Horizontal space added inside both ends of the span, in px. */
+    padding?: number;
+    /** Line through the middle of the text. */
+    strike?: Paint;
+    /** Makes the span a link. Unsafe URLs must be dropped before this point. */
+    href?: string;
+}
+export interface StyleResult {
+    font?: Partial<FontStyle>;
+    fill?: Paint;
+    decoration?: Decoration;
+}
+export interface InlineContext {
+    theme: Theme;
+    measurer: Measurer;
+    node: MarkmapNode;
+    /** Label wrap width in px; `0` or missing when labels do not wrap. */
+    wrapWidth?: number;
+    /**
+     * Report work that will change a measurement, such as an image loading to learn its
+     * size. The caller renders again once it settles; plugins should cache the result so
+     * the next measurement is final.
+     */
+    defer?(task: Promise<unknown>): void;
+}
+export interface AtomSize extends Size {
+    /** Distance from the top of the atom to the text baseline it sits on. */
+    baseline: number;
+}
+/** Draws an inline node as an unbreakable box, e.g. a checkbox, formula or icon. */
+export interface AtomRenderer<T extends Inline = Inline> {
+    measure(inline: T, style: TextStyle, ctx: InlineContext): AtomSize;
+    /** Primitives in text coordinates. `box` is where the atom was placed. */
+    render(inline: T, box: Rect, style: TextStyle, ctx: InlineContext): Primitive[];
+}
+export type InlineStyler<T extends Inline = Inline> = (inline: T, style: TextStyle, ctx: InlineContext) => StyleResult;
+export interface ContentPlugin {
+    name: string;
+    /** Rewrite a node's inline content before layout, e.g. to add a checkbox. */
+    transform?(content: Inline[], node: MarkmapNode): Inline[];
+    /** Style the text inside inline nodes, keyed by inline type. */
+    styles?: {
+        [K in Inline['type']]?: InlineStyler<Extract<Inline, {
+            type: K;
+        }>>;
+    };
+    /** Draw inline nodes as boxes, keyed by inline type. */
+    atoms?: {
+        [K in Inline['type']]?: AtomRenderer<Extract<Inline, {
+            type: K;
+        }>>;
+    };
+    /**
+     * Change the HTML of a note popover, e.g. to draw math. Runs after the
+     * Markdown's HTML has been sanitized, so markup added here is trusted as is,
+     * including `raw` nodes. Never copy unescaped text from the tree into raw markup.
+     */
+    popover?(tree: HastRoot): void | Promise<void>;
+}

package/dist/geometry.d.ts

@@ -0,0 +1,25 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Rect extends Point, Size {
+}
+/** Affine transform `[a, b, c, d, e, f]`, as in SVG `matrix()` and canvas `setTransform()`. */
+export type Matrix = [number, number, number, number, number, number];
+export type Side = 'left' | 'right' | 'top' | 'bottom';
+/** Where an edge leaves or enters a node, and which side it faces. */
+export interface Anchor extends Point {
+    side: Side;
+}
+export declare function translate(x: number, y: number): Matrix;
+/** Scale by `k` around the point (`cx`, `cy`). */
+export declare function scaleAround(k: number, cx: number, cy: number): Matrix;
+/** `a` applied after `b`, as in SVG `transform="matrix(a) matrix(b)"`. */
+export declare function multiply(a: Matrix, b: Matrix): Matrix;
+export declare function unionRects(rects: Iterable<Rect>): Rect;
+export declare function expandRect(rect: Rect, by: number): Rect;
+export declare function oppositeSide(side: Side): Side;

package/dist/id.d.ts

@@ -0,0 +1,10 @@
+import type { MarkmapNode } from './types';
+export declare const ROOT_ID = "root";
+/** 32-bit FNV-1a hash of a string, in base 36. */
+export declare function hashString(input: string): string;
+/**
+ * Assign stable ids in place. The root is always `root`. Every other id is a hash of
+ * the parent id and the node's plain text, so ids survive edits elsewhere in the
+ * document. Siblings with the same text are told apart by their occurrence index.
+ */
+export declare function assignIds(root: MarkmapNode): MarkmapNode;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type * from './content';
+export type * from './layout';
+export type * from './mdast';
+export type * from './primitives';
+export type * from './theme';
+export type * from './types';
+export * from './geometry';
+export * from './id';
+export * from './tree';
+export * from './options';

package/dist/index.js

@@ -0,0 +1,236 @@
+// src/geometry.ts
+function translate(x, y) {
+	return [
+		1,
+		0,
+		0,
+		1,
+		x,
+		y
+	];
+}
+/** Scale by `k` around the point (`cx`, `cy`). */
+function scaleAround(k, cx, cy) {
+	return [
+		k,
+		0,
+		0,
+		k,
+		cx * (1 - k),
+		cy * (1 - k)
+	];
+}
+/** `a` applied after `b`, as in SVG `transform="matrix(a) matrix(b)"`. */
+function multiply(a, b) {
+	const [a0, a1, a2, a3, a4, a5] = a;
+	const [b0, b1, b2, b3, b4, b5] = b;
+	return [
+		a0 * b0 + a2 * b1,
+		a1 * b0 + a3 * b1,
+		a0 * b2 + a2 * b3,
+		a1 * b2 + a3 * b3,
+		a0 * b4 + a2 * b5 + a4,
+		a1 * b4 + a3 * b5 + a5
+	];
+}
+function unionRects(rects) {
+	let [x0, y0, x1, y1] = [
+		Infinity,
+		Infinity,
+		-Infinity,
+		-Infinity
+	];
+	for (const r of rects) {
+		x0 = Math.min(x0, r.x);
+		y0 = Math.min(y0, r.y);
+		x1 = Math.max(x1, r.x + r.width);
+		y1 = Math.max(y1, r.y + r.height);
+	}
+	if (x0 > x1) return {
+		x: 0,
+		y: 0,
+		width: 0,
+		height: 0
+	};
+	return {
+		x: x0,
+		y: y0,
+		width: x1 - x0,
+		height: y1 - y0
+	};
+}
+function expandRect(rect, by) {
+	return {
+		x: rect.x - by,
+		y: rect.y - by,
+		width: rect.width + by * 2,
+		height: rect.height + by * 2
+	};
+}
+var OPPOSITE = {
+	left: "right",
+	right: "left",
+	top: "bottom",
+	bottom: "top"
+};
+function oppositeSide(side) {
+	return OPPOSITE[side];
+}
+// src/tree.ts
+/** Visit every node in pre-order. */
+function walkTree(root, visitor) {
+	const visit = (node, parent, depth) => {
+		if (visitor(node, parent, depth) === false) return;
+		for (const child of node.children) visit(child, node, depth + 1);
+	};
+	visit(root, void 0, 0);
+}
+/** Return the path from the root to the node with `id`, both included, or `undefined`. */
+function findPath(root, id) {
+	if (root.id === id) return [root];
+	for (const child of root.children) {
+		const path = findPath(child, id);
+		if (path) return [root, ...path];
+	}
+}
+function findNode(root, id) {
+	return findPath(root, id)?.at(-1);
+}
+/** Plain text of inline content, as used for ids, search and accessibility labels. */
+function toPlainText(content) {
+	let text = "";
+	for (const node of content) if ("value" in node) text += node.value;
+	else if (node.type === "image" || node.type === "imageReference") text += node.alt ?? "";
+	else if (node.type === "break") text += "\n";
+	else if ("children" in node) text += toPlainText(node.children);
+	return text;
+}
+// src/id.ts
+var ROOT_ID = "root";
+/** 32-bit FNV-1a hash of a string, in base 36. */
+function hashString(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i += 1) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36).padStart(7, "0");
+}
+/**
+* Assign stable ids in place. The root is always `root`. Every other id is a hash of
+* the parent id and the node's plain text, so ids survive edits elsewhere in the
+* document. Siblings with the same text are told apart by their occurrence index.
+*/
+function assignIds(root) {
+	const assign = (node, id) => {
+		node.id = id;
+		const seen = /* @__PURE__ */ new Map();
+		for (const child of node.children) {
+			const text = toPlainText(child.content);
+			const index = seen.get(text) ?? 0;
+			seen.set(text, index + 1);
+			assign(child, hashString(`${id}\0${text}${index ? `\0${index}` : ""}`));
+		}
+	};
+	assign(root, ROOT_ID);
+	return root;
+}
+// src/options.ts
+/**
+* A CSS value that cannot break out of a declaration or a `<style>` element.
+* Colors from Markdown end up in embedded CSS, so they must pass this check.
+*/
+function isSafeCSSValue(value) {
+	return value.length > 0 && value.length <= 100 && !/[;{}<>\\'"]|\/\*/.test(value);
+}
+var validators = {
+	number(min, integer = false) {
+		return (value, key) => {
+			if (typeof value !== "number" || !Number.isFinite(value)) return { warning: `\`${key}\` must be a number` };
+			if (value < min || integer && !Number.isInteger(value)) return { warning: `\`${key}\` must be ${integer ? "an integer " : ""}>= ${min}` };
+			return { value };
+		};
+	},
+	/** A short non-empty string, such as a name to look up. */
+	string() {
+		return (value, key) => typeof value === "string" && value.trim() && value.length <= 100 ? { value: value.trim() } : { warning: `\`${key}\` must be a non-empty string` };
+	},
+	oneOf(values) {
+		return (value, key) => values.includes(value) ? { value } : { warning: `\`${key}\` must be one of ${values.map((v) => `\`${v}\``).join(", ")}` };
+	},
+	boolean() {
+		return (value, key) => typeof value === "boolean" ? { value } : { warning: `\`${key}\` must be true or false` };
+	},
+	/** One CSS color or a list of them; always normalized to a list. Unsafe values are dropped. */
+	colors() {
+		return (value, key) => {
+			const colors = typeof value === "string" ? [value] : value;
+			if (!Array.isArray(colors) || !colors.length) return { warning: `\`${key}\` must be a color or a list of colors` };
+			const safe = colors.filter((c) => typeof c === "string" && isSafeCSSValue(c.trim())).map((c) => c.trim());
+			return {
+				value: safe.length ? safe : void 0,
+				warning: safe.length < colors.length ? `\`${key}\` has invalid colors, which were ignored` : void 0
+			};
+		};
+	}
+};
+var CORE_SCHEMA = {
+	foldLevel: validators.number(0, true),
+	wrapWidth: validators.number(0),
+	levelGap: validators.number(0),
+	siblingGap: validators.number(0),
+	zoom: validators.boolean(),
+	pan: validators.boolean(),
+	fitPadding: validators.number(0),
+	fitMaxScale: validators.number(.01),
+	minScale: validators.number(.001),
+	maxScale: validators.number(.01),
+	duration: validators.number(0),
+	layout: validators.string(),
+	theme: validators.string(),
+	colorScheme: validators.oneOf([
+		"light",
+		"dark",
+		"auto"
+	])
+};
+/** Validate untrusted options against a schema. */
+function validateOptions(input, schema) {
+	const options = {};
+	const rest = {};
+	const warnings = [];
+	if (input == null) return {
+		options,
+		rest,
+		warnings
+	};
+	if (typeof input !== "object" || Array.isArray(input)) return {
+		options,
+		rest,
+		warnings: ["`markmap` options must be an object"]
+	};
+	for (const [key, raw] of Object.entries(input)) {
+		const validate = Object.hasOwn(schema, key) ? schema[key] : void 0;
+		if (!validate) {
+			rest[key] = raw;
+			continue;
+		}
+		const { value, warning } = validate(raw, key);
+		if (warning) warnings.push(warning);
+		if (value !== void 0) options[key] = value;
+	}
+	return {
+		options,
+		rest,
+		warnings
+	};
+}
+/** Validate the theme-independent options. Theme keys are returned in `rest`. */
+function readJSONOptions(input) {
+	return validateOptions(input, CORE_SCHEMA);
+}
+/** Warnings for keys that no schema claimed. */
+function unknownOptionWarnings(rest) {
+	return Object.keys(rest).map((key) => `Unknown option \`${key}\``);
+}
+export { ROOT_ID, assignIds, expandRect, findNode, findPath, hashString, isSafeCSSValue, multiply, oppositeSide, readJSONOptions, scaleAround, toPlainText, translate, unionRects, unknownOptionWarnings, validateOptions, validators, walkTree };

package/dist/layout.d.ts

@@ -0,0 +1,63 @@
+import type { Point, Rect, Side, Size } from './geometry';
+import type { NodeContext } from './theme';
+import type { MarkmapNode } from './types';
+export interface LayoutNode {
+    node: MarkmapNode;
+    parent?: LayoutNode;
+    /** Visible children: empty when the node is folded. */
+    children: LayoutNode[];
+    depth: number;
+    folded: boolean;
+    rect: Rect;
+    /**
+     * The way this node grows away from its parent, and its children away from it. Edges
+     * leave the parent on this side and enter the node on the opposite one. For the root,
+     * the side of its fold toggle.
+     */
+    direction: Side;
+}
+export interface LayoutResult {
+    /** Visible nodes in pre-order. */
+    nodes: LayoutNode[];
+    byId: Map<string, LayoutNode>;
+    /** Union of all node rects. */
+    bounds: Rect;
+}
+export interface LayoutOptions {
+    /** Box size of each visible node. */
+    sizes: ReadonlyMap<string, Size>;
+    folded?: ReadonlySet<string>;
+    /** Gap between a node and its children. */
+    levelGap?: number;
+    /** Gap between siblings; doubled between cousins. */
+    siblingGap?: number;
+}
+/** A node in one animation frame: where it is and how present it is. */
+export interface FrameNode {
+    node: MarkmapNode;
+    ctx: NodeContext;
+    rect: Rect;
+    /** `1` when fully shown, `0` when gone. Themes decide how it looks; the default is a fade. */
+    presence: number;
+}
+/** One frame. Extra fields on the nodes are kept by interpolation. */
+export interface LayoutFrame<N extends FrameNode = FrameNode> {
+    nodes: N[];
+}
+export interface InterpolateContext<N extends FrameNode = FrameNode> {
+    /** A point on one side of a frame node, as the theme draws it. */
+    anchor(item: N, side: Side): Point;
+}
+/** Places nodes, and optionally decides how they move between two placements. */
+export interface Layout {
+    name: string;
+    layout(root: MarkmapNode, options: LayoutOptions): LayoutResult;
+    /**
+     * The frame `t` (already eased, 0 to 1) of the way from `from` to `to`. `from` may be
+     * a frame of an earlier animation. Nodes only in `to` are entering, nodes only in
+     * `from` are leaving; return entering nodes in `to` order, then leaving ones. Defaults
+     * to straight-line moves, with entering and leaving nodes growing out of and shrinking
+     * into their nearest ancestor's anchor.
+     */
+    interpolate?<N extends FrameNode>(from: LayoutFrame<N>, to: LayoutFrame<N>, t: number, ctx: InterpolateContext<N>): LayoutFrame<N>;
+}

package/dist/mdast.d.ts

@@ -0,0 +1,28 @@
+import type { Node, Parent, PhrasingContent } from 'mdast';
+/** `==highlighted==` text. */
+export interface Mark extends Parent {
+    type: 'mark';
+    children: PhrasingContent[];
+}
+/** A task-list checkbox, added before a node's label at render time. */
+export interface Checkbox extends Node {
+    type: 'checkbox';
+    checked: boolean;
+}
+/** Marks a node that has notes, added after its label at render time. */
+export interface NoteMarker extends Node {
+    type: 'noteMarker';
+    count: number;
+}
+declare module 'mdast' {
+    interface PhrasingContentMap {
+        mark: Mark;
+        checkbox: Checkbox;
+        noteMarker: NoteMarker;
+    }
+    interface RootContentMap {
+        mark: Mark;
+        checkbox: Checkbox;
+        noteMarker: NoteMarker;
+    }
+}

package/dist/options.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Options that can be written in Markdown frontmatter under the `markmap` key and
+ * apply to every theme. Themes add their own keys, see `Theme.options`.
+ */
+export interface MarkmapJSONOptions {
+    /** Fold nodes at this depth and deeper when first shown. Leave out to expand everything. */
+    foldLevel?: number;
+    /** Wrap labels wider than this, in px. `0` disables wrapping. */
+    wrapWidth?: number;
+    levelGap?: number;
+    siblingGap?: number;
+    zoom?: boolean;
+    pan?: boolean;
+    fitPadding?: number;
+    fitMaxScale?: number;
+    /** Smallest scale to zoom out to. `fit()` may go further to show everything. */
+    minScale?: number;
+    /** Largest scale to zoom in to. */
+    maxScale?: number;
+    /** Length of fold, update and fit animations, in ms. `0` disables them. */
+    duration?: number;
+    /** Name of a registered layout, such as `two-sided` or `org-chart`. */
+    layout?: string;
+    /** Name of a registered theme, such as `cards`. Its own options apply on top. */
+    theme?: string;
+    /** `light`, `dark`, or `auto` to follow the reader's system setting. */
+    colorScheme?: 'light' | 'dark' | 'auto';
+}
+/**
+ * Checks one untrusted option value. Return `value` to keep it (possibly normalized),
+ * `warning` to report a problem, or both when part of the value was dropped.
+ */
+export type OptionValidator = (value: unknown, key: string) => {
+    value?: unknown;
+    warning?: string;
+};
+export type OptionSchema = Record<string, OptionValidator>;
+/**
+ * A CSS value that cannot break out of a declaration or a `<style>` element.
+ * Colors from Markdown end up in embedded CSS, so they must pass this check.
+ */
+export declare function isSafeCSSValue(value: string): boolean;
+export declare const validators: {
+    number(min: number, integer?: boolean): OptionValidator;
+    /** A short non-empty string, such as a name to look up. */
+    string(): OptionValidator;
+    oneOf<T extends string>(values: readonly T[]): OptionValidator;
+    boolean(): OptionValidator;
+    /** One CSS color or a list of them; always normalized to a list. Unsafe values are dropped. */
+    colors(): OptionValidator;
+};
+export interface ValidatedOptions<T> {
+    options: T;
+    /** Keys the schema does not know, left for another schema (such as the theme's). */
+    rest: Record<string, unknown>;
+    /** Problems found, one per ignored or partly ignored value. */
+    warnings: string[];
+}
+/** Validate untrusted options against a schema. */
+export declare function validateOptions<T = Record<string, unknown>>(input: unknown, schema: OptionSchema): ValidatedOptions<T>;
+/** Validate the theme-independent options. Theme keys are returned in `rest`. */
+export declare function readJSONOptions(input: unknown): ValidatedOptions<MarkmapJSONOptions>;
+/** Warnings for keys that no schema claimed. */
+export declare function unknownOptionWarnings(rest: Record<string, unknown>): string[];

package/dist/primitives.d.ts

@@ -0,0 +1,108 @@
+import type { Matrix, Rect } from './geometry';
+/** A CSS color, usually `var(--mm-…)` so themes and user CSS apply. */
+export type Paint = string;
+export type Backend = 'svg' | 'canvas';
+export interface FontStyle {
+    family: string;
+    /** Font size in px. */
+    size: number;
+    weight: number;
+    style: 'normal' | 'italic';
+    /** Line height in px. */
+    lineHeight: number;
+}
+/** A piece of text with one font and color. `x`/`y` are the baseline start, relative to the text primitive. */
+export interface TextRun {
+    text: string;
+    x: number;
+    y: number;
+    font: FontStyle;
+    fill?: Paint;
+    /** Measured width, when known, so backends can skip measuring text they only sketch. */
+    width?: number;
+}
+interface PrimitiveBase {
+    /** Backends that can draw this primitive. Omit for all. */
+    backends?: Backend[];
+}
+export interface GroupPrimitive extends PrimitiveBase {
+    kind: 'group';
+    /** Identity for patching and animation, unique among all groups. */
+    key?: string;
+    nodeId?: string;
+    transform?: Matrix;
+    opacity?: number;
+    /** Hide what falls outside this rectangle, in the group's own coordinates. */
+    clip?: Rect;
+    /**
+     * Where the group draws, in its parent's coordinates, if that is cheap to tell.
+     * Backends can skip top-level groups that are out of view.
+     */
+    bounds?: Rect;
+    children: Primitive[];
+}
+export interface RectPrimitive extends PrimitiveBase {
+    kind: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    r?: number;
+    fill?: Paint;
+    stroke?: Paint;
+    strokeWidth?: number;
+}
+export interface PathPrimitive extends PrimitiveBase {
+    kind: 'path';
+    d: string;
+    fill?: Paint;
+    stroke?: Paint;
+    strokeWidth?: number;
+}
+/** Pre-wrapped, pre-measured text. */
+export interface TextPrimitive extends PrimitiveBase {
+    kind: 'text';
+    x: number;
+    y: number;
+    runs: TextRun[];
+}
+export interface ImagePrimitive extends PrimitiveBase {
+    kind: 'image';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    src: string;
+    /** Drawn instead when a backend finds the image cannot be loaded. */
+    fallback?: Primitive[];
+}
+/** A hit area that opens `href`. Draws nothing. */
+export interface LinkPrimitive extends PrimitiveBase {
+    kind: 'link';
+    href: string;
+    rect: Rect;
+}
+/**
+ * An interactive-only hit area that triggers a view action, such as opening a node's
+ * notes. Draws nothing and is never exported.
+ */
+export interface HitPrimitive extends PrimitiveBase {
+    kind: 'hit';
+    rect: Rect;
+    action: string;
+}
+/** Interactive-only HTML. Never exported. */
+export interface OverlayPrimitive extends PrimitiveBase {
+    kind: 'overlay';
+    rect: Rect;
+    html: () => HTMLElement;
+}
+/** Escape hatch for drawing a backend cannot express with other primitives. */
+export interface CustomPrimitive extends PrimitiveBase {
+    kind: 'custom';
+    /** SVG markup. */
+    svg?: () => string;
+    canvas?: (ctx: CanvasRenderingContext2D) => void;
+}
+export type Primitive = GroupPrimitive | RectPrimitive | PathPrimitive | TextPrimitive | ImagePrimitive | LinkPrimitive | HitPrimitive | OverlayPrimitive | CustomPrimitive;
+export {};

package/dist/theme.d.ts

@@ -0,0 +1,71 @@
+import type { Anchor, Matrix, Rect, Side, Size } from './geometry';
+import type { OptionSchema } from './options';
+import type { FontStyle, Paint, Primitive } from './primitives';
+import type { MarkmapNode } from './types';
+/** Measures the advance width of a single-font string, in px. */
+export interface Measurer {
+    measure(text: string, font: FontStyle): number;
+}
+export interface NodeContext {
+    depth: number;
+    /** Ids from the root to this node, both included. Ids are stable, so themes can hash them for colors. */
+    path: readonly string[];
+    hasChildren: boolean;
+    folded: boolean;
+    /** The way the node grows away from its parent, from the layout. */
+    direction: Side;
+}
+/** What is known about a node before layout: everything but its direction. */
+export type MeasureContext = Omit<NodeContext, 'direction'>;
+export interface EdgeContext {
+    source: MarkmapNode;
+    target: MarkmapNode;
+    /** Context of the target node. */
+    node: NodeContext;
+}
+/** How a node looks part way into or out of the drawing. */
+export interface PresenceStyle {
+    opacity?: number;
+    /** Applied in node-local coordinates (the box starts at 0, 0), before the node's position. */
+    transform?: Matrix;
+}
+export type TextAlign = 'start' | 'center' | 'end';
+export interface Theme {
+    name: string;
+    /** Theme-specific Markdown options, such as colors. Validated before `configure` sees them. */
+    options?: OptionSchema;
+    /** A copy of the theme with validated `options` applied. */
+    configure?(options: Record<string, unknown>): Theme;
+    /** Emitted as CSS variables, e.g. `{ 'mm-text': '#333' }` → `--mm-text: #333`. */
+    tokens: Record<string, string>;
+    /** Tokens that change in dark mode; the rest of `tokens` still applies. */
+    darkTokens?: Record<string, string>;
+    font: FontStyle;
+    /** Font family for inline code. */
+    codeFontFamily: string;
+    textFill: Paint;
+    node: {
+        /** `[top, right, bottom, left]` around the content. */
+        padding: [number, number, number, number];
+        minHeight?: number;
+        /** Box size from content size. Defaults to content plus padding, at least `minHeight` tall. */
+        measure?(content: Size, node: MarkmapNode, ctx: MeasureContext): Size;
+        /** Alignment of wrapped label lines. Defaults to `start`. */
+        textAlign?(ctx: NodeContext): TextAlign;
+        /**
+         * How a node looks while `presence` goes from 0 (absent) to 1 (shown), as it enters
+         * or leaves. Its edge gets the same opacity. Defaults to fading.
+         */
+        presence?(presence: number, box: Size, ctx: NodeContext): PresenceStyle;
+        /** Chrome in node-local coordinates (the box starts at 0, 0). */
+        render(node: MarkmapNode, box: Size, ctx: NodeContext): Primitive[];
+        /**
+         * Where edges meet the node on one side, in layout coordinates. Edges to children
+         * leave on `ctx.direction` and the edge from the parent enters on the opposite side.
+         */
+        anchor(rect: Rect, side: Side, ctx: NodeContext): Anchor;
+    };
+    edge: {
+        render(from: Anchor, to: Anchor, ctx: EdgeContext): Primitive[];
+    };
+}

package/dist/tree.d.ts

@@ -0,0 +1,10 @@
+import type { Inline, MarkmapNode } from './types';
+/** Return `false` from the visitor to skip a node's children. */
+export type TreeVisitor = (node: MarkmapNode, parent: MarkmapNode | undefined, depth: number) => void | false;
+/** Visit every node in pre-order. */
+export declare function walkTree(root: MarkmapNode, visitor: TreeVisitor): void;
+/** Return the path from the root to the node with `id`, both included, or `undefined`. */
+export declare function findPath(root: MarkmapNode, id: string): MarkmapNode[] | undefined;
+export declare function findNode(root: MarkmapNode, id: string): MarkmapNode | undefined;
+/** Plain text of inline content, as used for ids, search and accessibility labels. */
+export declare function toPlainText(content: readonly Inline[]): string;

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+import type { BlockContent, DefinitionContent, PhrasingContent } from 'mdast';
+/** Inline content of a node label: a subset of mdast phrasing content. */
+export type Inline = PhrasingContent;
+/** A block that is not a heading or list item, attached to the node that owns it. */
+export type MdastBlock = BlockContent | DefinitionContent;
+export interface Note {
+    block: MdastBlock;
+    /** Number of children that precede this block in source order. */
+    after: number;
+}
+export interface MarkmapNode {
+    /** Stable id derived from the parent path and content. */
+    id: string;
+    type: 'heading' | 'listItem' | (string & {});
+    content: Inline[];
+    notes: Note[];
+    /** Plugin data such as fold, checked, color or icon. */
+    data: Record<string, unknown>;
+    /** Source offsets, for click-to-source and graph-to-Markdown editing. */
+    position?: {
+        start: number;
+        end: number;
+    };
+    children: MarkmapNode[];
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@markmap/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-next.0",
+  "description": "Markmap types, tree utilities and plugin contracts",
+  "homepage": "https://github.com/markmap/markmap#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markmap/markmap.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build:types": "tsc -b",
+    "build:js": "vite build"
+  }
 }