@markmap/parse 0.0.0-stage → 1.0.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/parse
 
-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.
+Parse Markdown into a Markmap tree.
+
+See the [Markmap README](https://github.com/markmap/markmap#readme) for how the packages fit together.

package/dist/html-image.d.ts

@@ -0,0 +1,19 @@
+import type { Root } from 'mdast';
+export interface HtmlImage {
+    src: string;
+    alt: string;
+    /** In px. Missing when not given, or not in px (such as a percentage). */
+    width?: number;
+    height?: number;
+}
+/**
+ * Read one GitHub-style `<img>` tag: exactly one tag, nothing around it, well-formed
+ * attributes. Only `src`, `alt`, `width` and `height` are kept; other attributes are
+ * ignored. Returns `undefined` for anything else, which callers then drop.
+ */
+export declare function parseHtmlImage(html: string): HtmlImage | undefined;
+/**
+ * Turn raw `<img>` tags into `image` nodes, inline and on their own line. All other raw
+ * HTML is left alone for later steps to drop.
+ */
+export declare function remarkHtmlImages(): (tree: Root) => void;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './parse';
+export * from './to-tree';
+export * from './plugins';
+export * from './html-image';

package/dist/index.js

@@ -0,0 +1,385 @@
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { parse as parse$1 } from "yaml";
+import { assignIds } from "@markmap/core";
+// src/html-image.ts
+var TAG = /^<img((?:\s+[a-z][a-z0-9-]*(?:\s*=\s*(?:"[^"<>]*"|'[^'<>]*'|[^\s"'=<>`]+))?)*)\s*\/?>$/i;
+var ATTR = /([a-z][a-z0-9-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/gi;
+var PIXELS = /^(\d+(?:\.\d+)?)(?:px)?$/;
+var ENTITIES = {
+	"&amp;": "&",
+	"&quot;": "\"",
+	"&#39;": "'",
+	"&lt;": "<",
+	"&gt;": ">"
+};
+var decode = (value) => value.replace(/&(?:amp|quot|#39|lt|gt);/g, (e) => ENTITIES[e]);
+function pixels(value) {
+	const match = value && PIXELS.exec(value.trim());
+	const n = match ? Number(match[1]) : 0;
+	return n > 0 ? n : void 0;
+}
+/**
+* Read one GitHub-style `<img>` tag: exactly one tag, nothing around it, well-formed
+* attributes. Only `src`, `alt`, `width` and `height` are kept; other attributes are
+* ignored. Returns `undefined` for anything else, which callers then drop.
+*/
+function parseHtmlImage(html) {
+	const match = TAG.exec(html.trim());
+	if (!match) return void 0;
+	const attrs = /* @__PURE__ */ new Map();
+	for (const [, name, ...values] of match[1].matchAll(ATTR)) {
+		const key = name.toLowerCase();
+		if (!attrs.has(key)) attrs.set(key, decode(values.find((v) => v != null) ?? ""));
+	}
+	const src = attrs.get("src")?.trim();
+	if (!src) return void 0;
+	return {
+		src,
+		alt: attrs.get("alt") ?? "",
+		width: pixels(attrs.get("width")),
+		height: pixels(attrs.get("height"))
+	};
+}
+function toImage(html) {
+	const parsed = parseHtmlImage(html.value);
+	if (!parsed) return void 0;
+	const size = {
+		...parsed.width && { width: parsed.width },
+		...parsed.height && { height: parsed.height }
+	};
+	return {
+		type: "image",
+		url: parsed.src,
+		alt: parsed.alt,
+		data: {
+			...size,
+			hProperties: size
+		}
+	};
+}
+/** Parents whose children are blocks, where an `<img>` line becomes its own paragraph. */
+var FLOW = /* @__PURE__ */ new Set([
+	"root",
+	"listItem",
+	"blockquote",
+	"footnoteDefinition"
+]);
+/**
+* Turn raw `<img>` tags into `image` nodes, inline and on their own line. All other raw
+* HTML is left alone for later steps to drop.
+*/
+function remarkHtmlImages() {
+	const visit = (node) => {
+		if (!("children" in node)) return;
+		const parent = node;
+		parent.children = parent.children.map((child) => {
+			if (child.type !== "html") {
+				visit(child);
+				return child;
+			}
+			const image = toImage(child);
+			if (!image) return child;
+			if (!FLOW.has(parent.type)) return image;
+			return {
+				type: "paragraph",
+				children: [image]
+			};
+		});
+	};
+	return (tree) => visit(tree);
+}
+// src/plugins.ts
+function visitParents(node, fn) {
+	if (!("children" in node)) return;
+	for (const child of node.children) visitParents(child, fn);
+	fn(node);
+}
+/**
+* Turn `==text==` into `mark` nodes. Like `**`, the opening `==` must be followed by
+* a non-space and the closing one preceded by a non-space. Delimiters can wrap other
+* inline nodes (`==a **b**==`) but not cross block boundaries.
+*/
+function remarkMark() {
+	return (tree) => visitParents(tree, (parent) => {
+		if (parent.children.some((child) => child.type === "text" && child.value.includes("=="))) parent.children = markChildren(parent.children);
+	});
+}
+function markChildren(children) {
+	const tokens = [];
+	for (const child of children) {
+		if (child.type !== "text") {
+			tokens.push({
+				delim: false,
+				node: child
+			});
+			continue;
+		}
+		child.value.split(/(==)/).forEach((part) => {
+			if (part === "==") tokens.push({
+				delim: true,
+				canOpen: false,
+				canClose: false
+			});
+			else if (part) tokens.push({
+				delim: false,
+				node: {
+					type: "text",
+					value: part
+				}
+			});
+		});
+	}
+	const edgeChar = (token, end) => {
+		if (!token) return "";
+		if (token.delim) return "=";
+		if (token.node.type === "text") return end ? token.node.value.at(-1) : token.node.value[0];
+		return "x";
+	};
+	tokens.forEach((token, i) => {
+		if (!token.delim) return;
+		const next = edgeChar(tokens[i + 1], false);
+		const prev = edgeChar(tokens[i - 1], true);
+		token.canOpen = !!next && !/\s/.test(next);
+		token.canClose = !!prev && !/\s/.test(prev);
+	});
+	const pairs = /* @__PURE__ */ new Map();
+	let open = -1;
+	tokens.forEach((token, i) => {
+		if (!token.delim) return;
+		if (open >= 0 && token.canClose && i > open + 1) {
+			pairs.set(open, i);
+			open = -1;
+		} else if (open < 0 && token.canOpen) open = i;
+	});
+	const build = (from, to) => {
+		const result = [];
+		const pushText = (value) => {
+			const last = result.at(-1);
+			if (last?.type === "text") last.value += value;
+			else result.push({
+				type: "text",
+				value
+			});
+		};
+		for (let i = from; i < to; i += 1) {
+			const token = tokens[i];
+			const close = pairs.get(i);
+			if (close != null) {
+				result.push({
+					type: "mark",
+					children: build(i + 1, close)
+				});
+				i = close;
+			} else if (token.delim) pushText("==");
+			else if (token.node.type === "text") pushText(token.node.value);
+			else result.push(token.node);
+		}
+		return result;
+	};
+	return build(0, tokens.length);
+}
+/** Replace `[text][ref]` and `![alt][ref]` with plain links and images, and drop definitions. */
+function remarkResolveReferences() {
+	return (tree) => {
+		const definitions = /* @__PURE__ */ new Map();
+		visitParents(tree, (parent) => {
+			for (const child of parent.children) if (child.type === "definition") definitions.set(child.identifier, child);
+		});
+		visitParents(tree, (parent) => {
+			parent.children = parent.children.flatMap((child) => {
+				if (child.type === "linkReference") {
+					const def = definitions.get(child.identifier);
+					return def ? [{
+						type: "link",
+						url: def.url,
+						title: def.title,
+						children: child.children
+					}] : child.children;
+				}
+				if (child.type === "imageReference") {
+					const def = definitions.get(child.identifier);
+					return def ? [{
+						type: "image",
+						url: def.url,
+						title: def.title,
+						alt: child.alt
+					}] : [{
+						type: "text",
+						value: child.alt ?? ""
+					}];
+				}
+				return [child];
+			});
+		});
+	};
+}
+// src/to-tree.ts
+/**
+* Convert an mdast tree into a Markmap tree.
+*
+* - Headings nest by depth; list items nest under the heading or item that contains them.
+* - Other blocks become notes of the node that owns them. Blocks before the first
+*   heading attach to the root.
+* - A lone top-level H1 becomes the root, unless `title` is given.
+* - Raw HTML, frontmatter and link definitions are dropped. A `<!-- markmap: … -->`
+*   comment in a label sets node options: `fold` folds the node, `foldAll` folds it
+*   and everything below.
+*/
+function toTree(mdast, options = {}) {
+	let root = createNode("root", options.title ? [{
+		type: "text",
+		value: options.title
+	}] : []);
+	const stack = [{
+		depth: 0,
+		node: root
+	}];
+	for (const block of mdast.children) if (block.type === "heading") {
+		while (stack.length > 1 && stack.at(-1).depth >= block.depth) stack.pop();
+		const node = createNode("heading", block.children, block);
+		node.data.depth = block.depth;
+		stack.at(-1).node.children.push(node);
+		stack.push({
+			depth: block.depth,
+			node
+		});
+	} else addBlock(stack.at(-1).node, block);
+	if (!options.title) root = promoteSingleH1(root);
+	return assignIds(root);
+}
+function createNode(type, label, source) {
+	const { content, directives } = readLabel(label);
+	const node = {
+		id: "",
+		type,
+		content,
+		notes: [],
+		data: {},
+		children: []
+	};
+	if (directives.has("fold")) node.data.fold = true;
+	if (directives.has("foldAll")) node.data.foldAll = true;
+	const start = source?.position?.start.offset;
+	const end = source?.position?.end.offset;
+	if (start != null && end != null) node.position = {
+		start,
+		end
+	};
+	return node;
+}
+function addBlock(parent, block) {
+	switch (block.type) {
+		case "list":
+			addList(parent, block);
+			return;
+		case "html":
+		case "yaml":
+		case "definition": return;
+		default: attach(parent, block);
+	}
+}
+function addList(parent, list) {
+	for (const item of list.children) parent.children.push(fromListItem(item, list));
+}
+function fromListItem(item, list) {
+	const [first, ...rest] = item.children;
+	const hasLabel = first?.type === "paragraph" || first?.type === "heading";
+	const node = createNode("listItem", hasLabel ? first.children : [], item);
+	if (list.ordered) node.data.ordered = true;
+	if (item.checked != null) node.data.checked = item.checked;
+	for (const block of hasLabel ? rest : item.children) addBlock(node, block);
+	return node;
+}
+function attach(node, block) {
+	const note = {
+		block: stripPositions(block),
+		after: node.children.length
+	};
+	node.notes.push(note);
+}
+function promoteSingleH1(root) {
+	const [only] = root.children;
+	if (root.children.length !== 1 || only.type !== "heading" || only.data.depth !== 1) return root;
+	only.notes = [...root.notes.map((a) => ({
+		...a,
+		after: 0
+	})), ...only.notes];
+	return only;
+}
+/** Drop mdast `position` fields so the tree stays small and serializable. */
+function stripPositions(value) {
+	if (Array.isArray(value)) return value.map(stripPositions);
+	if (value && typeof value === "object") {
+		const result = {};
+		for (const [key, child] of Object.entries(value)) if (key !== "position") result[key] = stripPositions(child);
+		return result;
+	}
+	return value;
+}
+var DIRECTIVE = /^<!--\s*markmap:\s*([\s\S]*?)\s*-->$/;
+/** Drop raw HTML from a label, collecting `<!-- markmap: … -->` directives on the way. */
+function readLabel(label) {
+	const directives = /* @__PURE__ */ new Set();
+	const clean = (nodes) => nodes.flatMap((node) => {
+		if (node.type === "html") {
+			const match = node.value.trim().match(DIRECTIVE);
+			for (const word of match?.[1].split(/\s+/) ?? []) if (word) directives.add(word);
+			return [];
+		}
+		if ("children" in node) return [{
+			...node,
+			children: clean(node.children)
+		}];
+		return [node];
+	});
+	const content = stripPositions(clean(label));
+	const last = content.at(-1);
+	if (last?.type === "text") {
+		last.value = last.value.trimEnd();
+		if (!last.value) content.pop();
+	}
+	return {
+		content,
+		directives
+	};
+}
+// src/parse.ts
+function parse(markdown, options = {}) {
+	const { mdast, gfm } = parseMdast(markdown, options.plugins ?? []);
+	const frontmatter = readFrontmatter(mdast);
+	return {
+		root: toTree(mdast, { title: typeof frontmatter.title === "string" ? frontmatter.title : void 0 }),
+		frontmatter,
+		gfm
+	};
+}
+/**
+* GFM depends on the most third-party code, and old browsers reject syntax it may use, like
+* regex lookbehind before Safari 16.4. A map without GFM is better than no map at all.
+*/
+function parseMdast(markdown, plugins, gfm = true) {
+	const processor = unified().use(remarkParse).use(gfm ? [remarkGfm] : []).use(remarkFrontmatter, ["yaml"]).use(remarkHtmlImages).use(remarkMark).use(remarkResolveReferences).use(plugins);
+	try {
+		return {
+			mdast: processor.runSync(processor.parse(markdown)),
+			gfm
+		};
+	} catch (error) {
+		if (!gfm || !(error instanceof SyntaxError)) throw error;
+		return parseMdast(markdown, plugins, false);
+	}
+}
+function readFrontmatter(mdast) {
+	const node = mdast.children.find((child) => child.type === "yaml");
+	if (!node) return {};
+	try {
+		const data = parse$1(node.value);
+		return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+	} catch {
+		return {};
+	}
+}
+export { parse, parseHtmlImage, remarkHtmlImages, remarkMark, remarkResolveReferences, toTree };

package/dist/parse.d.ts

@@ -0,0 +1,14 @@
+import type { MarkmapNode } from '@markmap/core';
+import { type PluggableList } from 'unified';
+export interface ParseOptions {
+    /** Extra unified plugins, applied after the built-in ones (gfm, frontmatter, highlight, references). */
+    plugins?: PluggableList;
+}
+export interface ParseResult {
+    root: MarkmapNode;
+    /** Parsed YAML frontmatter. Markmap options live under `markmap`; validate them with the theme in use. */
+    frontmatter: Record<string, unknown>;
+    /** Whether GFM was applied. It is skipped when the browser cannot run it, see `parseMdast`. */
+    gfm: boolean;
+}
+export declare function parse(markdown: string, options?: ParseOptions): ParseResult;

package/dist/plugins.d.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'mdast';
+/**
+ * Turn `==text==` into `mark` nodes. Like `**`, the opening `==` must be followed by
+ * a non-space and the closing one preceded by a non-space. Delimiters can wrap other
+ * inline nodes (`==a **b**==`) but not cross block boundaries.
+ */
+export declare function remarkMark(): (tree: Root) => void;
+/** Replace `[text][ref]` and `![alt][ref]` with plain links and images, and drop definitions. */
+export declare function remarkResolveReferences(): (tree: Root) => void;

package/dist/to-tree.d.ts

@@ -0,0 +1,18 @@
+import { type MarkmapNode } from '@markmap/core';
+import type { Root } from 'mdast';
+export interface ToTreeOptions {
+    /** Title for a synthesized root, usually from frontmatter. */
+    title?: string;
+}
+/**
+ * Convert an mdast tree into a Markmap tree.
+ *
+ * - Headings nest by depth; list items nest under the heading or item that contains them.
+ * - Other blocks become notes of the node that owns them. Blocks before the first
+ *   heading attach to the root.
+ * - A lone top-level H1 becomes the root, unless `title` is given.
+ * - Raw HTML, frontmatter and link definitions are dropped. A `<!-- markmap: … -->`
+ *   comment in a label sets node options: `fold` folds the node, `foldAll` folds it
+ *   and everything below.
+ */
+export declare function toTree(mdast: Root, options?: ToTreeOptions): MarkmapNode;

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@markmap/parse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Parse Markdown into a Markmap tree",
+  "homepage": "https://github.com/markmap/markmap#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markmap/markmap.git",
+    "directory": "packages/parse"
+  },
+  "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",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build:types": "tsc -b",
+    "build:js": "vite build"
+  }
 }