@coderminer/vue-markdown 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,122 @@
 
 All notable changes to `@coderminer/vue-markdown` are documented here.
 
+## [Unreleased]
+
+### Changed
+
+- The Vue peer range is now `>=3.3.0 <4.0.0`. CI runs the full suite against
+  Vue 3.3 and 3.4 in addition to the latest 3.x release.
+
+### Fixed
+
+- String tag overrides (`components: { h1: 'h2' }`), unknown-tag fallbacks, and
+  raw HTML element nodes render their children on Vue 3.3 and 3.4. The renderer
+  passed a slot function to an element vnode, which only Vue 3.5 resolves.
+
+## [1.0.1] - 2026-11-02
+
+Patch release that closes runtime and contract issues found after 1.0.0. The
+package has no external users yet, so it includes intentional contract
+tightenings: the `externalLinkTarget` type is narrowed and `mermaidPlugin()`
+rejects non-object arguments.
+
+### Added
+
+- The `MarkdownRenderer` `searchDebounce` prop delays parsing after the last
+  search query change, so search-as-you-type can avoid re-parsing large
+  documents on every keystroke. The initial query still applies immediately for
+  server rendering.
+
+### Fixed
+
+- `toc-change` no longer emits a transient empty array before the first parse
+  settles. A first document that really has no headings still emits one settled
+  `[]`. The TOC change check compares every field directly instead of
+  serializing the array.
+- `customTagsPlugin()` and `MarkdownCustomTag` normalize kebab-case attributes
+  to camelCase props (`start-line` becomes `startLine`). `data-*` and `aria-*`
+  stay in their DOM form. The click payload and host component bindings use the
+  normalized props.
+- `MermaidBlock` resets zoom on every render (retry, theme, renderer, and
+  source changes) and when returning from the source tab, not only when the
+  source text changes. The default error/fallback regions include a visible
+  retry button.
+- The Mermaid runtime clears a rejected lazy import so retry can recover from a
+  transient chunk failure. Initialization is keyed by the full configuration
+  and checked inside the render queue, so blocks with different themes cannot
+  reuse stale global Mermaid state.
+- `useMarkdownDocument` publishes a deduplicated diagnostics list for each run,
+  including failed runs, and exposes `clearDiagnostics()`. Entries count as
+  duplicates only when their code, message, severity, phase, plugin, source
+  range, and details all match, so distinct occurrences are preserved. Setup
+  diagnostics are snapshotted when plugin setup runs, so a plugin that retains
+  the setup context cannot append to the list on later runs. The renderer prunes
+  its reported-diagnostic set to the currently active entries instead of growing
+  it indefinitely.
+- `MarkdownRendererEvents` and `MermaidBlockEvents` are exported typed event
+  maps, and the event payload conventions are documented so consumers do not
+  need to discover each shape separately. Interaction events include the
+  originating DOM event; the docs no longer claim every payload is serializable.
+- The default `searchPlugin()` no longer walks the document tree when the query
+  is empty, and the renderer skips match counting for an empty query.
+- A side TOC column now constrains its height and scrolls internally when the
+  table of contents is longer than the viewport. The stacked mobile layout
+  resets that cap so the TOC expands above the content.
+- `MarkdownRenderer` now validates every scalar prop at runtime, not only the
+  enum props. Invalid enums, booleans, strings, and numeric values report a
+  `prop-*` warning and use the documented fallback instead of reaching the
+  renderer or pipeline. An omitted optional `baseUrl` is valid and emits no
+  diagnostic. The `externalLinkTarget` prop and document option are typed as
+  `'_self' | '_blank'` instead of `string`, and `theme` is inferred as a runtime
+  string prop.
+- `MermaidBlock` invalidates in-flight renders on unmount, so a late result
+  cannot emit `rendered`/`error` or write state after the component is gone.
+  `resetMermaidRuntime()` keeps the serialized queue tail and monotonic render
+  counter, so an explicit reset cannot interleave renders or reuse DOM IDs.
+- `mermaidPlugin()` rejects non-object arguments with a clear error instead of
+  silently ignoring them. Its only supported option remains `languages`.
+- The built library no longer resolves Node-only dependency variants. This
+  removes `node:process`, `node:path`, and `node:url` imports (including
+  `process.cwd`) from browser output and prevents crashes when rendering.
+- `renderMermaid()` and `MermaidBlock` now report a clear error for non-string
+  sources, such as an un-awaited `renderMermaid()` Promise, instead of throwing
+  `trim is not a function`. Empty and non-browser sources also explain how to
+  recover.
+- `MermaidBlock` now distinguishes an invalid renderer result, empty renderer
+  output, and SVG rejected completely by sanitization, with an actionable hint
+  for each. Thrown renderer errors are prefixed with the failure stage. The
+  invalid `mermaidRenderer` diagnostic now names the actual fallback, the
+  built-in runtime.
+- Default heading IDs collapse consecutive whitespace and hyphen runs, so
+  `My   -   Heading` becomes `my-heading` instead of `my-----heading`. Custom
+  sluggers keep their own formatting; only duplicate suffixes are added.
+- The base renderer no longer statically includes the HTML parser. Mermaid SVG
+  sanitization loads it only after a diagram renders, the math entry uses it for
+  KaTeX markup, and the default highlight.js adapter now produces hast through
+  `lowlight` instead of parsing HTML. The highlight entry no longer pulls the
+  HTML parser, and the highlight entry resolves `highlight.js` language subpaths
+  from the host peer dependency instead of bundling a second copy.
+- Published JavaScript no longer contains `sourceMappingURL` comments for maps
+  that are excluded from the tarball.
+- The `highlight` entry no longer exports `highlightedNodesFromHtml`; adapters
+  that already produce hast use `highlightedNodesFromHast`. This keeps the HTML
+  parser out of the highlight entry.
+
+### Documentation
+
+- Document the Mermaid renderer layers and their precedence: per-block
+  `renderer` > provider/preset `mermaidRenderer` > built-in runtime. Clarify
+  that `mermaidPlugin()` only converts fences and that `renderMermaid()` is an
+  async function, not a `MermaidRenderer` object, so it must be wrapped when
+  passed explicitly. Explain why `resetMermaidRuntime()` is not a lifecycle
+  hook and cannot unload the browser module cache.
+- Document the raw-HTML attribute casing rule: HTML lowercases attribute names,
+  so use kebab-case (`start-line`) for camelCase custom props (`startLine`).
+- Add a complete sample plugin (`demo/plugins/samplePlugin.ts`) and a
+  step-by-step plugin guide that exercises source, remark, rehype, component,
+  document, label, token, setup/cleanup, and error hooks.
+
 ## [1.0.0] - 2026-11-01
 
 First stable release of the Vue 3 Markdown component suite.

package/README.md

@@ -38,7 +38,7 @@ export.
 npm install @coderminer/vue-markdown
 ```
 
-Requires Node 20+ and Vue 3.5+.
+Requires Node 20+ and Vue 3.3+.
 
 Optional engines are peer dependencies. Install only the ones you use:
 
@@ -352,6 +352,10 @@ of the parse memo key, so `:plugins="[docsPlugin]"` created inline in a template
 re-parses on every parent render. A failing plugin is isolated and never corrupts
 the last good document.
 
+`disablePlugins` matches the plugin `name`, not the exported factory name.
+Unknown names report a `plugin-unknown` warning. See the
+[plugin name table](docs/guide/plugins.md#disableplugins-names) for the full list.
+
 ### Headless rendering
 
 ```ts
@@ -440,7 +444,7 @@ component manifest, lives in the
 | `labels` | `Partial<MarkdownLabels>` | `{}` | String or function labels for built-in text. |
 | `preset` | `MarkdownPreset \| MarkdownPreset[]` | — | Applies one or more presets. |
 | `plugins` | `PluginInput[]` | `defaultPlugins` | Replaces the default plugin set when provided. Add `htmlPlugin()` for sanitized raw HTML. |
-| `disablePlugins` | `string[]` | `[]` | Removes named plugins from the resolved set. |
+| `disablePlugins` | `string[]` | `[]` | Removes named plugins from the resolved set. Unknown names report a `plugin-unknown` warning. |
 | `remarkPlugins` | `PluggableList` | `[]` | Runs after library remark plugins. |
 | `rehypePlugins` | `PluggableList` | `[]` | Runs after library rehype plugins and the built-in sanitizer. |
 | `remarkRehypeOptions` | `Record<string, unknown>` | `{}` | Merged into the conversion step. |
@@ -465,6 +469,7 @@ component manifest, lives in the
 | `tocPlacement` | `'top' \| 'left' \| 'right' \| 'hidden'` | `'top'` | Stack the TOC, place it beside the content, or hide it. |
 | `search` | `string` | `''` | Highlights matches and emits `search-change`. |
 | `searchCaseSensitive` | `boolean` | `false` | Makes the `search` match case-sensitive. |
+| `searchDebounce` | `number` | `0` | Milliseconds before a new query is parsed. |
 | `showError` | `boolean` | `true` | Renders the error region on failure. |
 | `tokens` | `Record<string, string>` | `{}` | Inline `--vmd-*` custom properties on the root. |
 | `theme` | `'light' \| 'dark' \| 'auto' \| 'custom'` | `'light'` | Sets `data-vmd-theme` on the root. |

package/README.zh-CN.md

@@ -36,7 +36,7 @@ Markdown 直接渲染成 Vue VNode：不经过 HTML 字符串往返，也不使
 npm install @coderminer/vue-markdown
 ```
 
-需要 Node 20+ 和 Vue 3.5+。
+需要 Node 20+ 和 Vue 3.3+。
 
 可选引擎都是 peer 依赖，只安装实际用到的部分：
 
@@ -319,7 +319,9 @@ const plugins = [docsPlugin]
 会被隔离，不会破坏上一份正常文档。
 
 `toc`、`code`、`link` 是内核不变标记：即使写进 `disablePlugins` 也不会被移除，只会
-报告一条 `plugin-core` 诊断。
+报告一条 `plugin-core` 诊断。`disablePlugins` 匹配插件的 `name`，不是导出的工厂函数名；
+未知名称会报告 `plugin-unknown` 警告。完整列表见
+[插件名称表](docs/zh/guide/plugins.md#disableplugins-名称)。
 
 ### 无头渲染
 
@@ -411,7 +413,7 @@ const asyncHtml = await exportMarkdownHtml(source, { plugins: [docsPlugin] })
 | `labels` | `Partial<MarkdownLabels>` | `{}` | 内置文案，支持字符串或函数。 |
 | `preset` | `MarkdownPreset \| MarkdownPreset[]` | — | 应用一个或多个预设。 |
 | `plugins` | `PluginInput[]` | `defaultPlugins` | 传入后替换默认插件集合；加入 `htmlPlugin()` 可启用净化后的原始 HTML。 |
-| `disablePlugins` | `string[]` | `[]` | 按名称移除解析后的非内核插件。 |
+| `disablePlugins` | `string[]` | `[]` | 按名称移除解析后的非内核插件；未知名称会报告 `plugin-unknown` 警告。 |
 | `remarkPlugins` | `PluggableList` | `[]` | 在库内置 remark 插件之后运行。 |
 | `rehypePlugins` | `PluggableList` | `[]` | 在库内置 rehype 插件和内置净化器之后运行。 |
 | `remarkRehypeOptions` | `Record<string, unknown>` | `{}` | 合并到 mdast → hast 转换步骤。 |
@@ -436,6 +438,7 @@ const asyncHtml = await exportMarkdownHtml(source, { plugins: [docsPlugin] })
 | `tocPlacement` | `'top' \| 'left' \| 'right' \| 'hidden'` | `'top'` | 目录置顶、放在内容左侧/右侧，或隐藏。 |
 | `search` | `string` | `''` | 高亮匹配项并触发 `search-change`。 |
 | `searchCaseSensitive` | `boolean` | `false` | 让 `search` 区分大小写。 |
+| `searchDebounce` | `number` | `0` | 新查询解析前的等待毫秒数。 |
 | `showError` | `boolean` | `true` | 失败时渲染错误区域。 |
 | `tokens` | `Record<string, string>` | `{}` | 写在根元素上的内联 `--vmd-*` 自定义属性。 |
 | `theme` | `'light' \| 'dark' \| 'auto' \| 'custom'` | `'light'` | 设置根元素的 `data-vmd-theme`。 |

package/dist/chunks/MarkdownBlockquote-DVXziX2t.js

@@ -14,5 +14,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownBlockquote-DVXziX2t.js.map

package/dist/chunks/MarkdownBreak-BwCi2Itt.js

@@ -14,5 +14,3 @@ var r = {
 	}
 });
 export { i as t };
-
-//# sourceMappingURL=MarkdownBreak-BwCi2Itt.js.map

package/dist/chunks/MarkdownCode-B1k9tmW5.js

@@ -61,5 +61,3 @@ var y = {
 	}
 });
 export { v as n, b as t };
-
-//# sourceMappingURL=MarkdownCode-B1k9tmW5.js.map

package/dist/chunks/MarkdownConfigProvider-5N3ylrIu.js

@@ -47,5 +47,3 @@ var c = /* @__PURE__ */ o(e(e({}, { name: "MarkdownConfigProvider" }), {}, {
 	}
 }));
 export { c as t };
-
-//# sourceMappingURL=MarkdownConfigProvider-5N3ylrIu.js.map

package/dist/chunks/MarkdownContent-BAK6dqo7.js

@@ -11,5 +11,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownContent-BAK6dqo7.js.map

package/dist/chunks/MarkdownCustomTag-lZJHsD6f.js

@@ -0,0 +1,46 @@
+import { i as e } from "./normalize-VKfQXZiK.js";
+import { t } from "./objectSpread2-CtBNx0TF.js";
+import { r as n } from "./context-8NfW6fxI.js";
+import { computed as r, createBlock as i, defineComponent as a, mergeProps as o, openBlock as s, renderSlot as c, resolveDynamicComponent as l, withCtx as u } from "vue";
+// src/components/MarkdownCustomTag.vue
+var d = /* @__PURE__ */ a(t(t({}, {
+	name: "MarkdownCustomTag",
+	inheritAttrs: !1
+}), {}, {
+	__name: "MarkdownCustomTag",
+	props: {
+		node: {},
+		children: {},
+		tag: {},
+		customProps: {}
+	},
+	setup(a) {
+		let d = a, f = n(), p = r(() => {
+			var e;
+			return (e = d.tag) == null ? d.node.tag : e;
+		}), m = r(() => f.components[p.value]), h = r(() => {
+			let e = m.value;
+			return typeof e == "string" || typeof e == "object" || typeof e == "function" ? e : "span";
+		}), g = r(() => {
+			var n;
+			return t(t(t({}, e(d.node.attrs)), d.node.props), (n = d.customProps) == null ? {} : n);
+		});
+		function _(e) {
+			f.onCustomTagClick({
+				tag: p.value,
+				props: g.value,
+				node: d.node,
+				event: e
+			});
+		}
+		return (e, t) => (s(), i(l(h.value), o(g.value, {
+			"data-vmd-part": "custom-tag",
+			class: "vmd-custom-tag",
+			onClick: _
+		}), {
+			default: u(() => [c(e.$slots, "default")]),
+			_: 3
+		}, 16));
+	}
+}));
+export { d as t };

package/dist/chunks/MarkdownEmphasis-CppivOEu.js

@@ -14,5 +14,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownEmphasis-CppivOEu.js.map

package/dist/chunks/MarkdownEmpty-Av5k6bqa.js

@@ -12,5 +12,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownEmpty-Av5k6bqa.js.map

package/dist/chunks/MarkdownError-C0sPs5W0.js

@@ -15,5 +15,3 @@ var c = {
 	}
 });
 export { u as t };
-
-//# sourceMappingURL=MarkdownError-C0sPs5W0.js.map

package/dist/chunks/MarkdownFootnoteReference-Dy3Khwyj.js

@@ -20,5 +20,3 @@ var s = ["data-state", "aria-label"], c = /* @__PURE__ */ i({
 	}
 });
 export { c as t };
-
-//# sourceMappingURL=MarkdownFootnoteReference-Dy3Khwyj.js.map

package/dist/chunks/MarkdownFootnotes-BRPzkbXv.js

@@ -19,5 +19,3 @@ var s = ["aria-label"], c = /* @__PURE__ */ i({
 	}
 });
 export { c as t };
-
-//# sourceMappingURL=MarkdownFootnotes-BRPzkbXv.js.map

package/dist/chunks/MarkdownHeading-DaNcP0_6.js

@@ -27,5 +27,3 @@ var p = ["href", "aria-label"], m = /* @__PURE__ */ s({
 	}
 });
 export { m as t };
-
-//# sourceMappingURL=MarkdownHeading-DaNcP0_6.js.map

package/dist/chunks/MarkdownHorizontalRule-QNe_cuUI.js

@@ -14,5 +14,3 @@ var r = {
 	}
 });
 export { i as t };
-
-//# sourceMappingURL=MarkdownHorizontalRule-QNe_cuUI.js.map

package/dist/chunks/MarkdownHtml-66lYkvwM.js

@@ -11,5 +11,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownHtml-66lYkvwM.js.map

package/dist/chunks/MarkdownImage-BRy76svs.js

@@ -49,5 +49,3 @@ var a = [
 	}
 });
 export { s as t };
-
-//# sourceMappingURL=MarkdownImage-BRy76svs.js.map

package/dist/chunks/MarkdownInlineCode-MXZYFwex.js

@@ -14,5 +14,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownInlineCode-MXZYFwex.js.map

package/dist/chunks/MarkdownLink-Dbx3NwgV.js

@@ -43,5 +43,3 @@ var s = [
 	}
 });
 export { c as t };
-
-//# sourceMappingURL=MarkdownLink-Dbx3NwgV.js.map

package/dist/chunks/MarkdownList-BJ-_C71k.js

@@ -18,5 +18,3 @@ var s = /* @__PURE__ */ n({
 	}
 });
 export { s as t };
-
-//# sourceMappingURL=MarkdownList-BJ-_C71k.js.map

package/dist/chunks/MarkdownListItem-Z1EHIY26.js

@@ -14,5 +14,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownListItem-Z1EHIY26.js.map

package/dist/chunks/MarkdownLoading-D-RYtXxf.js

@@ -13,5 +13,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownLoading-D-RYtXxf.js.map

package/dist/chunks/MarkdownParagraph-BxLSmSaG.js

@@ -14,5 +14,3 @@ var i = {
 	}
 });
 export { a as t };
-
-//# sourceMappingURL=MarkdownParagraph-BxLSmSaG.js.map