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

package/dist/layouts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tree';
+export * from './two-sided';
+export * from './org-chart';

package/dist/layouts/org-chart.d.ts

@@ -0,0 +1,9 @@
+import { type Layout, type LayoutOptions, type LayoutResult, type MarkmapNode } from '@markmap/core';
+/**
+ * Top-down tidy tree: the root at the top, children in a row below their parent.
+ * `levelGap` is the gap between levels; siblings are `siblingGap × 3`
+ * apart, doubled between cousins.
+ */
+export declare function layoutOrgChart(root: MarkmapNode, options: LayoutOptions): LayoutResult;
+/** Org chart: root at the top, growing downwards. */
+export declare const orgChartLayout: Layout;

package/dist/layouts/tree.d.ts

@@ -0,0 +1,7 @@
+import { type Layout, type LayoutOptions, type LayoutResult, type MarkmapNode } from '@markmap/core';
+/** Return the subtree that is visible when the `folded` nodes are collapsed. */
+export declare function visibleNodes(root: MarkmapNode, folded?: ReadonlySet<string>): MarkmapNode[];
+/** Tidy tree layout, root on the left, growing to the right. */
+export declare function layoutTree(root: MarkmapNode, options: LayoutOptions): LayoutResult;
+/** The classic markmap layout: a tidy tree growing to the right. */
+export declare const treeLayout: Layout;

package/dist/layouts/two-sided.d.ts

@@ -0,0 +1,14 @@
+import { type Layout, type LayoutOptions, type LayoutResult, type MarkmapNode } from '@markmap/core';
+/**
+ * How many of the root's first children go on the right; the rest go on the left. Splits
+ * the list where the two sides' leaf counts are closest, keeping document order on both
+ * sides and favoring the right on a tie.
+ */
+export declare function splitBranches(children: readonly MarkmapNode[]): number;
+/**
+ * A mind map: the root in the middle, its first branches growing to the right and the
+ * rest to the left, balanced by size. Both sides keep document order top to bottom.
+ */
+export declare function layoutTwoSided(root: MarkmapNode, options: LayoutOptions): LayoutResult;
+/** Root in the middle, branches on both sides. */
+export declare const twoSidedLayout: Layout;

package/dist/measure.d.ts

@@ -0,0 +1,11 @@
+import type { FontStyle, Measurer } from '@markmap/core';
+export declare function fontToCss(font: FontStyle): string;
+/**
+ * Approximates widths from Helvetica metrics, without a font or canvas. Good enough
+ * for Node rendering and tests; use {@link createCanvasMeasurer} in the browser.
+ */
+export declare const approximateMeasurer: Measurer;
+type Context2D = Pick<CanvasRenderingContext2D, 'font' | 'measureText'>;
+/** Measures with a canvas 2D context, caching results per font and text. */
+export declare function createCanvasMeasurer(ctx?: Context2D): Measurer;
+export {};

package/dist/options.d.ts

@@ -0,0 +1,33 @@
+import { type Layout, type MarkmapJSONOptions, type Theme } from '@markmap/core';
+import type { RenderOptions } from './render';
+/** Layouts Markdown can pick by name with the `layout` option. */
+export declare const builtinLayouts: Readonly<Record<string, Layout>>;
+/** Themes Markdown can pick by name with the `theme` option. */
+export declare const builtinThemes: Readonly<Record<string, Theme>>;
+export interface ResolveOptions {
+    /** Layouts the `layout` option may name. Defaults to {@link builtinLayouts}. */
+    layouts?: Readonly<Record<string, Layout>>;
+    /** Themes the `theme` option may name. Defaults to {@link builtinThemes}. */
+    themes?: Readonly<Record<string, Theme>>;
+}
+export interface ResolvedOptions<T> {
+    options: T;
+    /** The validated theme-independent options, for callers that use more of them. */
+    json: MarkmapJSONOptions;
+    /** Problems with the input, one per ignored value or unknown key. */
+    warnings: string[];
+}
+/**
+ * Apply the theme's own options (for example `color`) and return the keys it did not
+ * claim. Themes without options leave everything in `rest`.
+ */
+export declare function configureTheme(theme: Theme, input: Record<string, unknown>): {
+    theme: Theme;
+    rest: Record<string, unknown>;
+    warnings: string[];
+};
+/**
+ * Validate untrusted Markdown options (usually `frontmatter.markmap`) and apply them on
+ * top of `base`: shared keys first, then the theme's own keys. Anything left is reported.
+ */
+export declare function resolveRenderOptions<T extends Partial<RenderOptions>>(base: T, input: unknown, { layouts, themes }?: ResolveOptions): ResolvedOptions<T & Partial<RenderOptions>>;

package/dist/paint.d.ts

@@ -0,0 +1,12 @@
+import type { Paint, Theme } from '@markmap/core';
+/** Finds a token's value by name, without the leading `--`. */
+export type TokenLookup = Readonly<Record<string, string>> | ((name: string) => string | undefined);
+/**
+ * Resolve CSS custom properties in a paint, for drawing outside CSS (canvas, PNG export).
+ * Every `var(--name)` and `var(--name, fallback)` is replaced by the token's value, which
+ * may refer to other tokens, or else by its fallback. Anything else is kept as is.
+ * Returns `undefined` when a variable has neither, or tokens refer to each other in a loop.
+ */
+export declare function resolvePaint(paint: Paint | undefined, tokens: TokenLookup): string | undefined;
+/** A theme's tokens for one color scheme: dark tokens override light ones. */
+export declare function themeTokens(theme: Pick<Theme, 'tokens' | 'darkTokens'>, scheme?: 'light' | 'dark'): Record<string, string>;

package/dist/render.d.ts

@@ -0,0 +1,74 @@
+import { type ContentPlugin, type FrameNode, type Layout, type LayoutResult, type Measurer, type MarkmapNode, type NodeContext, type Primitive, type Rect, type Size, type Theme } from '@markmap/core';
+import { type TextLayout } from './text';
+export interface RenderOptions {
+    measurer: Measurer;
+    theme?: Theme;
+    /** Where nodes go. Defaults to {@link treeLayout}. */
+    layout?: Layout;
+    /** Ids of collapsed nodes. */
+    folded?: ReadonlySet<string>;
+    /** Wrap labels wider than this, in px. `0` disables wrapping. */
+    wrapWidth?: number;
+    levelGap?: number;
+    siblingGap?: number;
+    /** Inline content renderers. Defaults to {@link defaultContentPlugins}. */
+    plugins?: readonly ContentPlugin[];
+}
+export interface RenderResult {
+    theme: Theme;
+    layout: LayoutResult;
+    /** Edges first, then nodes, so nodes draw on top. */
+    primitives: Primitive[];
+    /** Area covered by the drawing, including strokes and fold circles. */
+    bounds: Rect;
+    /** Theme context of every visible node, by id. */
+    contexts: Map<string, NodeContext>;
+    /** The final frame, as a starting point for animations. */
+    state: DrawState;
+    /**
+     * Settles when content that was measured with a placeholder (such as an image of
+     * unknown size) is ready. Render again then to get the final layout.
+     */
+    pending?: Promise<void>;
+}
+export interface MeasuredNode {
+    text: TextLayout;
+    box: Size;
+}
+/** Ids from the root to every node, both included. */
+export declare function nodePaths(root: MarkmapNode): Map<string, readonly string[]>;
+/**
+ * Measure the label and box of every visible node. Content that is not ready yet (see
+ * {@link InlineContext.defer}) is reported to `defer`.
+ */
+export declare function measureTree(root: MarkmapNode, options: RenderOptions, defer?: (task: Promise<unknown>) => void): Map<string, MeasuredNode>;
+/** Measure, lay out and draw a tree as backend-neutral primitives. */
+export declare function renderTree(root: MarkmapNode, options: RenderOptions): RenderResult;
+/**
+ * Render, wait for content that was measured with a placeholder, and render again, until
+ * everything is final (at most `rounds` times). Useful outside a live view, e.g. for
+ * exporting SVG with images.
+ */
+export declare function renderTreeAsync(root: MarkmapNode, options: RenderOptions, rounds?: number): Promise<RenderResult>;
+/** A node as drawn in one frame: final, or somewhere along an animation. */
+export interface DrawNode extends FrameNode {
+    /** Parent in the same state; nodes without one get no edge. */
+    parentId?: string;
+    text: TextLayout;
+}
+/** Everything needed to draw one frame. Parents come before their children. */
+export interface DrawState {
+    nodes: DrawNode[];
+}
+/**
+ * Draw a state as primitives: edges first, then nodes, each in a keyed group so
+ * backends can patch them. Edge anchors come from the theme, so animating node rects
+ * moves edges along with them.
+ */
+export declare function drawState(state: DrawState, theme: Theme): Primitive[];
+/**
+ * Bounding box of rects, paths and images, including stroke widths. Curve control
+ * points are included, so curves give a safe over-estimate. Text is not included:
+ * it sits inside node boxes, which callers add from the layout.
+ */
+export declare function primitiveBounds(primitives: Primitive[]): Rect;

package/dist/svg.d.ts

@@ -0,0 +1,31 @@
+import { type Primitive, type Theme } from '@markmap/core';
+import type { RenderResult } from './render';
+export interface SVGStringOptions {
+    /** Space around the drawing, in px. */
+    padding?: number;
+    /** Fill the background with `--mm-bg`. */
+    background?: boolean;
+    /** Which tokens to use. Defaults to `light`. */
+    colorScheme?: ColorScheme;
+}
+/** `auto` follows the reader's `prefers-color-scheme`. */
+export type ColorScheme = 'light' | 'dark' | 'auto';
+export declare function escapeXml(value: string): string;
+export interface PrimitivesToSVGOptions {
+    /** Emit hit areas for view actions. Off for exports. */
+    interactive?: boolean;
+}
+/**
+ * Serialize primitives as SVG markup. Primitive lists are treated as immutable: the
+ * markup of each list is cached, which makes redrawing animation frames cheap.
+ */
+export declare function primitivesToSVG(primitives: Primitive[], options?: PrimitivesToSVGOptions): string;
+/** Theme tokens as CSS custom property declarations. */
+export declare function tokensToCSS(theme: Theme | Record<string, string>): string;
+/**
+ * Rules that set a theme's tokens on `selector`. Dark tokens override light ones for
+ * `dark`, and inside a `prefers-color-scheme: dark` query for `auto`.
+ */
+export declare function themeCSS(theme: Theme, colorScheme?: ColorScheme, selector?: string): string;
+/** A standalone SVG document. Theme tokens are embedded so user CSS can still override them. */
+export declare function toSVGString(result: RenderResult, options?: SVGStringOptions): string;

package/dist/text.d.ts

@@ -0,0 +1,20 @@
+import type { ContentPlugin, Inline, InlineContext, Primitive, Size, TextRun, TextAlign, TextStyle } from '@markmap/core';
+export interface TextLayout extends Size {
+    /** Backgrounds, text, strike lines, atoms and link areas, in text coordinates. */
+    primitives: Primitive[];
+    runs: TextRun[];
+    lines: number;
+}
+export interface TextLayoutOptions {
+    style: TextStyle;
+    /** Wrap lines longer than this, in px. `0` or less disables wrapping. */
+    wrapWidth?: number;
+    plugins: readonly ContentPlugin[];
+    ctx: InlineContext;
+    /** Alignment of lines within the widest one. Defaults to `start`. */
+    align?: TextAlign;
+}
+/** Apply plugin transforms to a node's content, in plugin order. */
+export declare function transformContent(plugins: readonly ContentPlugin[], ctx: InlineContext): Inline[];
+/** Lay out inline content into runs, decorations and atoms, wrapping at `wrapWidth`. */
+export declare function layoutText(content: readonly Inline[], options: TextLayoutOptions): TextLayout;

package/dist/themes/branch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pick a color index for a node from its path of ids, for themes that color by branch.
+ * The node's id is hashed, so colors stay put as the tree changes. With `colorDepth`
+ * (the root is level 1), nodes deeper than that level use their ancestor's id instead.
+ */
+export declare function branchIndex(path: readonly string[], count: number, colorDepth?: number): number;
+/** The d3 category10 palette, used by the built-in themes. */
+export declare const DEFAULT_COLORS: readonly string[];
+/** Options shared by themes that color by branch. */
+export interface BranchColorOptions {
+    /** Branch colors, cycled through. One color paints every branch the same. */
+    color?: string[];
+    /** Nodes deeper than this level (the root is level 1) take their ancestor's color. `0` disables. */
+    colorDepth?: number;
+}
+/** Branch color tokens and a lookup from a node's path to its `var(--mm-branch-N)`. */
+export declare function branchColors(options: BranchColorOptions): {
+    tokens: {
+        [k: string]: string;
+    };
+    colorOf: (path: readonly string[]) => string;
+};

package/dist/themes/cards.d.ts

@@ -0,0 +1,6 @@
+import { type Theme } from '@markmap/core';
+import { type BranchColorOptions } from './branch';
+export type CardsThemeOptions = BranchColorOptions;
+/** Each node in a rounded card outlined in its branch color. */
+export declare function createCardsTheme(options?: CardsThemeOptions): Theme;
+export declare const cardsTheme: Theme;

package/dist/themes/classic.d.ts

@@ -0,0 +1,6 @@
+import type { Theme } from '@markmap/core';
+import { type BranchColorOptions } from './branch';
+export type ClassicThemeOptions = BranchColorOptions;
+/** The original markmap look: underlined labels, curved edges and fold circles. */
+export declare function createClassicTheme(options?: ClassicThemeOptions): Theme;
+export declare const classicTheme: Theme;

package/dist/themes/minimal.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from '@markmap/core';
+/** Plain text joined by thin gray lines; a small dot marks nodes that fold. */
+export declare const minimalTheme: Theme;

package/dist/themes/shared.d.ts

@@ -0,0 +1,38 @@
+import type { Anchor, Point, Side, TextAlign, Theme } from '@markmap/core';
+/** Tokens for inline content, shared by the built-in themes. */
+export declare const CONTENT_TOKENS: {
+    'mm-link': string;
+    'mm-code-bg': string;
+    'mm-code-text': string;
+    'mm-mark-bg': string;
+    'mm-checkbox': string;
+    'mm-note-dot': string;
+    'mm-syntax-keyword': string;
+    'mm-syntax-string': string;
+    'mm-syntax-comment': string;
+    'mm-syntax-number': string;
+    'mm-syntax-title': string;
+    'mm-syntax-attr': string;
+};
+export declare const DARK_CONTENT_TOKENS: {
+    'mm-link': string;
+    'mm-code-bg': string;
+    'mm-code-text': string;
+    'mm-mark-bg': string;
+    'mm-checkbox': string;
+    'mm-note-dot': string;
+    'mm-syntax-keyword': string;
+    'mm-syntax-string': string;
+    'mm-syntax-comment': string;
+    'mm-syntax-number': string;
+    'mm-syntax-title': string;
+    'mm-syntax-attr': string;
+};
+export declare const SYSTEM_FONT: Theme['font'];
+export declare const CODE_FONT = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+/** Wrapped lines hug the edge that faces the parent. */
+export declare function alignFor(direction: Side): TextAlign;
+/** An S-curve that leaves and arrives along the anchors' axis. */
+export declare function sCurve(from: Anchor, to: Point): string;
+/** The middle of one side of a box at (0, 0), pushed `gap` px outwards. */
+export declare function sidePoint(width: number, height: number, side: Side, gap?: number): Point;

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@markmap/render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-next.0",
+  "description": "Measure, lay out and render Markmap trees to primitives and SVG",
+  "homepage": "https://github.com/markmap/markmap#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markmap/markmap.git",
+    "directory": "packages/render"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@markmap/core": "1.0.0-next.0",
+    "d3-flextree": "^2.1.2"
+  },
+  "devDependencies": {
+    "@markmap/parse": "1.0.0-next.0",
+    "@types/d3-flextree": "^2.1.4"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build:types": "tsc -b",
+    "build:js": "vite build"
+  }
 }