npm - @powerduck/md-editor - Versions diffs - 0.10.10 → 0.11.2 - Mend

@powerduck/md-editor 0.10.10 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +185 -397
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,467 +1,255 @@
 # @powerduck/md-editor
-High-performance embeddable Markdown editor built on the markdown-it ecosystem. Supports KaTeX math formulas (self-contained, no texmath), Markmap mindmaps, highlight.js code blocks with traffic-light UI and copy button, github-markdown-css preview styling, admonition/tip blocks, rich toolbar with image/video/YouTube/table popup dialogs, keyboard shortcuts with help dialog, configurable toolbar, image upload hook, standalone `renderMarkdown()` API, native React integration, block-level incremental rendering with debounced scheduling. Ships in two modes: **simple** (no toolbar, pure edit + preview) and **complex** (toolbar + status bar). Styled via CSS custom properties with light/dark themes.
+[![npm version](https://img.shields.io/npm/v/@powerduck/md-editor)](https://www.npmjs.com/package/@powerduck/md-editor)
+[![license](https://img.shields.io/npm/l/@powerduck/md-editor)](https://github.com/PowerDuckie/md-editor/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/md-editor)](https://www.npmjs.com/package/@powerduck/md-editor)
-## Features
+High-performance embeddable Markdown editor with syntax highlighting, math formulas, mindmaps, @mentions, document link cards, and incremental rendering. Built on CodeMirror 6 with a React wrapper.
-- **Markdown editing** powered by CodeMirror 6 with markdown syntax highlighting
-- **Math formulas** via self-contained KaTeX plugin (`$E=mc^2$` inline, `$$...$$` block) -- no texmath dependency, no double-rendering
-- **Mindmaps** via Markmap (```` ```mindmap ```` code fences)
-- **Code highlighting** via highlight.js -- 20+ languages, macOS-style traffic-light header, one-click copy button
-- **Admonition blocks** -- `:::notice`, `:::warning`, `:::tip`, `:::danger`, `:::info`, `:::success` with icons and colored borders
-- **github-markdown-css** preview -- proper heading, list, table, and typography styling
-- **Rich toolbar** -- heading, bold, italic, link, image, video, YouTube, quote, lists, code, table, math, mindmap, horizontal rule, tip block, preview toggle, help, theme toggle
-- **Popup dialogs** -- image URL, video URL, YouTube URL/ID, table rows/columns
-- **Keyboard shortcuts** -- Ctrl+B bold, Ctrl+I italic, Ctrl+K link, etc. with a Help dialog listing all shortcuts
-- **Configurable toolbar** -- show/hide items, custom labels and icons via `toolbar` option
-- **Image upload hook** -- paste/drop images, call `onImageUpload(file)` to get a URL
-- **Video rendering** -- `.mp4`, `.webm`, `.ogg` links render as `<video>` elements
-- **Standalone renderer** -- `renderMarkdown(source, options)` for consistent styling outside the editor
-- **Block-level incremental rendering** -- only changed sections re-render
-- **Adaptive debounce** -- preview render delay scales with document length
-- **Simple / Complex modes** -- toggle toolbar and status bar at runtime
-- **Light / Dark themes** -- CSS custom properties, inherits host design tokens
-- **React component** -- `forwardRef` with imperative handle
-## Installation
+---
-```bash
-npm install @powerduck/md-editor
-```
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
-## Usage
+- **CodeMirror 6 Core** — Incremental rendering, virtual scrolling, and 60fps editing for large documents
+- **KaTeX Math** — Render LaTeX math formulas inline and in display blocks
+- **Markmap Mindmaps** — Visualize markdown outlines as interactive mindmaps
+- **highlight.js Code Blocks** — Syntax highlighting for 190+ programming languages
+- **@mentions** — Type `@` to search and mention users with avatars and descriptions
+- **Document Link Cards** — Type `/` to insert rich doc-link preview cards with thumbnails
+- **Admonition Blocks** — `:::tip`, `:::warning`, `:::note`, and more
+- **Simple & Complex Modes** — Lightweight mode for comments, full-featured mode for docs
+- **Light & Dark Themes** — Built-in themes with CSS variable customization
-### Vanilla JS
+---
-```ts
-import { MarkdownEditor } from '@powerduck/md-editor';
-import '@powerduck/md-editor/dist/style.css';
-const editor = new MarkdownEditor('#editor', {
-  value: '# Hello\n\nStart typing...',
-  mode: 'complex', // 'simple' | 'complex'
-  theme: 'light',  // 'light' | 'dark'
-  math: true,
-  mindmap: true,
-  onChange: (value) => console.log(value)
-});
+## Quick Start
+### Install
+```bash
+npm install @powerduck/md-editor
 ```
-### React
+### React Component
 ```tsx
-import { MarkdownEditorReact } from '@powerduck/md-editor/react';
-import '@powerduck/md-editor/dist/style.css';
+import { useRef, useState } from "react";
+import {
+  MarkdownEditorReact,
+  type MarkdownEditorHandle,
+} from "@powerduck/md-editor/react";
+import "@powerduck/md-editor/dist/style.css";
 function App() {
+  const [value, setValue] = useState("# Hello\n\nStart typing...");
+  const editorRef = useRef<MarkdownEditorHandle>(null);
   return (
-    <MarkdownEditorReact
-      defaultValue="# Hello"
-      mode="complex"
-      onChange={(v) => console.log(v)}
-    />
+    <div style={{ height: "600px" }}>
+      <MarkdownEditorReact
+        ref={editorRef}
+        value={value}
+        onChange={setValue}
+        mode="complex"
+        theme="light"
+      />
+      <button onClick={() => console.log(editorRef.current?.getHtml())}>
+        Get HTML
+      </button>
+    </div>
   );
 }
 ```
-## API
-### MarkdownEditorOptions
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `value` | `string` | `''` | Initial content |
-| `mode` | `'simple' \| 'complex'` | `'simple'` | Toolbar + status bar in complex mode |
-| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
-| `math` | `boolean` | `true` | Enable KaTeX math |
-| `mindmap` | `boolean` | `true` | Enable Markmap mindmaps |
-| `codeHighlight` | `boolean` | `true` | Enable highlight.js code blocks with copy button |
-| `tips` | `boolean` | `true` | Enable admonition/tip blocks (:::notice, :::warning, etc.) |
-| `preview` | `boolean` | `true` | Show preview pane |
-| `toolbar` | `ToolbarConfig` | all items | Configure which toolbar items show, their labels and icons |
-| `onImageUpload` | `(file: File) => Promise<string>` | - | Image upload hook for paste/drop |
-| `autoPreview` | `boolean` | `true` | Auto-render preview on edit |
-| `renderDebounce` | `number \| false` | adaptive | Preview debounce in ms |
-| `onChange` | `(value: string) => void` | - | Change callback |
-### Methods
-- `getValue(): string`
-- `setValue(value: string): void`
-- `getHtml(): string`
-- `renderNow(): void` -- manual preview render (use with `autoPreview: false`)
-- `setMode(mode: EditorMode): void`
-- `setTheme(theme: EditorTheme): void`
-- `setAutoPreview(auto: boolean): void`
-- `focus(): void`
-- `destroy(): void`
-## Mindmap Syntax
-````markdown
-```mindmap
-# Root topic
-## Branch one
-- Child A
-- Child B
-## Branch two
-- Child C
-```
-````
-## Code Blocks
-Code fences are automatically highlighted with highlight.js (20+ languages including JavaScript, TypeScript, Python, JSON, Bash, CSS, HTML, SQL, YAML, Go, Rust, Java, C/C++). Each code block gets a macOS-style header with traffic-light dots, a language label, and a copy button.
+### Vanilla JS
-````markdown
 ```typescript
-interface User {
-  name: string;
-  age: number;
-}
-```
-````
-Unknown languages are auto-detected; if detection fails, the content is HTML-escaped and displayed as plain text. Disable code highlighting with `codeHighlight: false`.
-## Media Insertion
-The complex-mode toolbar includes popup dialogs for inserting media:
-- **Image** (`image` button): URL + alt text -> `![alt](url)`
-- **Video** (`video` button): URL (.mp4, .webm, .ogg) -> renders as `<video controls>` in preview
-- **YouTube** (`youtube` button): accepts any YouTube URL format (watch?v=, youtu.be, embed, shorts) or raw 11-char ID -> inserts a linked thumbnail image that opens the video on click
-YouTube insertion extracts the video ID automatically and produces:
-```markdown
-[![YouTube video](https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)
-```
-## Standalone Renderer
-Use `renderMarkdown()` to render markdown with the same styling and plugins as the editor preview, without mounting an editor:
-```ts
-import { renderMarkdown } from '@powerduck/md-editor';
-import '@powerduck/md-editor/dist/style.css';
-const html = renderMarkdown('# Hello\n\n$E=mc^2$\n\n:::tip\nWorks!\n:::');
-container.innerHTML = html;
-```
-Options: `math`, `mindmap`, `codeHighlight`, `tips`, `html`, `breaks` -- all default to `true` except `html` and `breaks`.
-## Keyboard Shortcuts
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl+B` / `Cmd+B` | Bold |
-| `Ctrl+I` / `Cmd+I` | Italic |
-| `Ctrl+Alt+1` | Heading |
-| `Ctrl+K` / `Cmd+K` | Insert link |
-| `Ctrl+Alt+C` | Code block |
-| `Ctrl+Shift+.` | Blockquote |
-| `Ctrl+Shift+8` | Unordered list |
-| `Ctrl+Shift+7` | Ordered list |
-| `Ctrl+Alt+M` | Math formula |
-| `Ctrl+Alt+P` | Toggle preview |
-| `Ctrl+Shift+L` | Toggle theme |
-Click the **Help** (?) button in the toolbar to see all shortcuts at runtime.
-## Configurable Toolbar
-Control which buttons appear and customize their labels/icons:
+import { MarkdownEditor } from "@powerduck/md-editor";
+import "@powerduck/md-editor/dist/style.css";
-```ts
-// Only show specific buttons
-new MarkdownEditor('#editor', {
-  mode: 'complex',
-  toolbar: ['bold', 'italic', 'link', 'code']
+const editor = new MarkdownEditor("#editor", {
+  value: "# Hello\n\nStart typing...",
+  mode: "complex",
+  theme: "light",
+  onChange: (value) => console.log(value.length, "chars"),
 });
-// Fine-grained control
-new MarkdownEditor('#editor', {
-  mode: 'complex',
-  toolbar: {
-    bold: { label: 'Make bold', icon: '<b>B</b>' },
-    image: { show: false },
-    youtube: { show: false }
-  }
-});
+const html = editor.getHtml();
 ```
-## Image Upload
+---
-Provide an upload hook to handle pasted/dropped images:
+## Links
-```ts
-new MarkdownEditor('#editor', {
-  mode: 'complex',
-  onImageUpload: async (file) => {
-    const formData = new FormData();
-    formData.append('file', file);
-    const res = await fetch('/api/upload', { method: 'POST', body: formData });
-    const { url } = await res.json();
-    return url; // inserted as ![filename](url)
-  }
-});
-```
-## Admonition Blocks
-```markdown
-:::tip Pro tip
-Use admonition blocks for callouts.
-:::
-:::warning
-This action cannot be undone.
-:::
-:::danger
-Destructive operation.
-:::
-```
+- [Official Website](https://www.powerduck.com/opensource/md-editor.html)
+- [Documentation](https://www.powerduck.com/docs/md-editor/introduction)
+- [Live Demo](https://www.powerduck.com/demo/md-editor)
+- [GitHub](https://github.com/PowerDuckie/md-editor)
+- [npm](https://www.npmjs.com/package/@powerduck/md-editor)
-Supported types: `notice`, `info`, `tip`, `success`, `warning`, `danger`.
+---
-## Performance
+## Features
-- **Block splitting**: documents are split at ATX headings (`#` through `######`). Content inside code fences is never split.
-- **Incremental rendering**: unchanged blocks reuse their DOM nodes directly, including already-hydrated mindmap SVGs.
-- **Content-hash cache**: render results are cached by content hash, so undo/redo and copy-paste hit the cache.
-- **Adaptive debounce**: `adaptiveDebounceMs(docLength)` scales from 120ms to 600ms based on document size.
-- **`content-visibility: auto`**: off-screen blocks skip layout and paint entirely.
+- **CodeMirror 6 core** — incremental rendering, virtual scrolling, and 60fps editing for large documents
+- **KaTeX math** — render LaTeX math formulas inline and in display blocks
+- **Markmap mindmaps** — visualize markdown outlines as interactive mindmaps
+- **highlight.js code blocks** — syntax highlighting for 190+ programming languages
+- **@mentions** — type `@` to search and mention users with avatars and descriptions
+- **Document link cards** — type `/` to insert rich doc-link preview cards with thumbnails
+- **Admonition blocks** — `:::tip`, `:::warning`, `:::note`, and more
+- **Simple & complex modes** — lightweight mode for comments, full-featured mode for docs
+- **Light & dark themes** — built-in themes with CSS variable customization
+- **Image upload hooks** — custom upload handlers with paste and drag-and-drop support
+- **Toolbar & slash commands** — rich formatting toolbar and `/` command palette
+- **Dual ESM/CJS builds** — works with `import` and `require`, with bundled TypeScript declarations
-## Development
+---
-```bash
-npm install
-npm run typecheck       # src only
-npm run typecheck:test  # src + tests
-npm test                # run all tests (vitest + jsdom)
-npm run build           # vite build + d.ts generation
-```
+## @mention Integration
-## React Demo
-```jsx
-import { useRef, useCallback } from "react";
-import { type MentionItem, type DocItem } from "@powerduck/md-editor";
-import {
-  MarkdownEditorReact,
-  type MarkdownEditorHandle,
-} from "@powerduck/md-editor/react";
-import "@powerduck/md-editor/dist/style.css";
+```typescript
+import { MarkdownEditor, type MentionItem } from "@powerduck/md-editor";
 const USERS: MentionItem[] = [
   {
     id: "1",
     label: "Alice",
-    avatar: "https://i.pravatar.cc/40?u=alice",
+    avatar: "https://example.com/a.png",
     description: "alice@example.com",
   },
-  {
-    id: "2",
-    label: "Bob",
-    avatar: "https://i.pravatar.cc/40?u=bob",
-    description: "bob@example.com",
-  },
-  { id: "3", label: "Charlie", description: "charlie@example.com" },
+  { id: "2", label: "Bob", description: "bob@example.com" },
 ];
-const DOCS: DocItem[] = [
-  {
-    id: "d1",
-    title: "Getting Started",
-    url: "https://docs.example.com/start",
-    description: "Quick start guide",
-    thumbnail: "https://picsum.photos/seed/start/96/72",
+new MarkdownEditor("#editor", {
+  mode: "complex",
+  mention: {
+    onMentionSearch: async (query) =>
+      USERS.filter((u) => u.label.toLowerCase().includes(query.toLowerCase())),
+    onMentionSelect: (item) => `[@${item.label}](mention:${item.id})`,
+    minChars: 0,
+    maxItems: 8,
   },
-  {
-    id: "d2",
-    title: "API Reference",
-    url: "https://docs.example.com/api",
-    description: "Full API documentation",
-  },
-  {
-    id: "d3",
-    title: "Changelog",
-    url: "https://docs.example.com/changelog",
-    description: "Release notes",
-  },
-];
+});
+```
-function App() {
-  const editorRef = useRef<MarkdownEditorHandle>(null);
+---
-  const handleSave = useCallback(() => {
-    const markdown = editorRef.current?.getValue() ?? "";
-    console.log("Saving:", markdown);
-  }, []);
-  // Stable callbacks so the editor does not recreate on every render
-  const searchUsers = useCallback(async (query: string) => {
-    return USERS.filter((u) =>
-      u.label.toLowerCase().includes(query.toLowerCase()),
-    );
-  }, []);
-  const searchDocs = useCallback(async (query: string) => {
-    return DOCS.filter((d) =>
-      d.title.toLowerCase().includes(query.toLowerCase()),
-    );
-  }, []);
-  const fetchDocMeta = useCallback(async (url: string) => {
-    // In production, route through your backend to avoid CORS:
-    // const res = await fetch(`/api/og?url=${encodeURIComponent(url)}`);
-    // return res.json();
-    // For demo: return whatever metadata the item already has
-    const doc = DOCS.find((d) => d.url === url);
-    return {
-      title: doc?.title ?? new URL(url).hostname,
-      description: doc?.description,
-      thumbnail: doc?.thumbnail,
-      url,
-    };
-  }, []);
+## Document Link Card
-  return (
-    <div style={{ padding: 24, maxWidth: 1100, margin: "0 auto" }}>
-      <div style={{ marginBottom: 12, display: "flex", gap: 8 }}>
-        <button onClick={handleSave}>Save</button>
-        <button onClick={() => editorRef.current?.setTheme("dark")}>
-          Dark
-        </button>
-        <button onClick={() => editorRef.current?.setTheme("light")}>
-          Light
-        </button>
-      </div>
+```typescript
+import { MarkdownEditor, type DocItem } from "@powerduck/md-editor";
-      <MarkdownEditorReact
-        ref={editorRef}
-        defaultValue={[
-          "# Welcome",
-          "",
-          "Type **@** to mention a user, or **/** to insert a document link.",
-          "",
-          "## Task list",
-          "- [ ] This is checked (green)",
-          "- [x] This is unchecked",
-          "- [ x] Spaces inside brackets also work",
-          "",
-          "## Table",
-          "| Name | Role |",
-          "|------|------|",
-          "| Alice | Admin |",
-          "| Bob | Editor |",
-        ].join("\n")}
-        mode="complex"
-        theme="light"
-        onChange={(v) => console.log("auto-save:", v.length)}
-        mention={{
-          onMentionSearch: searchUsers,
-          minChars: 0,
-          maxItems: 8,
-        }}
-        docLink={{
-          onDocSearch: searchDocs,
-          onFetchDocMeta: fetchDocMeta,
-          insertStyle: "auto",
-          minChars: 0,
-          maxItems: 8,
-        }}
-      />
-    </div>
-  );
-}
+const DOCS: DocItem[] = [
+  {
+    id: "1",
+    title: "Getting Started",
+    url: "https://docs.example.com/getting-started",
+    thumbnail: "https://example.com/thumb.jpg",
+    description: "Quick start tutorial",
+  },
+];
-export default App;
+new MarkdownEditor("#editor", {
+  mode: "complex",
+  docLink: {
+    onDocSearch: async (query) =>
+      DOCS.filter((d) => d.title.toLowerCase().includes(query.toLowerCase())),
+    insertStyle: "card",
+    minChars: 0,
+    maxItems: 6,
+  },
+});
 ```
-## Changelog
+---
-### v0.8.4
+## API Reference
-- **Fixed**: React component `MarkdownEditorReact` now passes through all extra props (`mention`, `docLink`, `toolbar`, `onImageUpload`, `includeCommonHeaders`, `includeCookies`, `placeholder`, etc.) to the underlying `MarkdownEditor` instance. Previously only a subset of props were forwarded, so `mention` and `docLink` configs were silently ignored.
-- **Test**: 311 tests, all passing, zero unhandled errors.
+### React Props
-### v0.8.3
+| Prop             | Type                      | Default     | Description                             |
+| ---------------- | ------------------------- | ----------- | --------------------------------------- |
+| `value`          | `string`                  | -           | Markdown content (controlled)           |
+| `defaultValue`   | `string`                  | -           | Initial markdown content (uncontrolled) |
+| `onChange`       | `(value: string) => void` | -           | Content change callback                 |
+| `mode`           | `"simple" \| "complex"`   | `"complex"` | Editor mode                             |
+| `theme`          | `"light" \| "dark"`       | `"light"`   | Color theme                             |
+| `math`           | `boolean`                 | `true`      | Enable KaTeX math rendering             |
+| `mindmap`        | `boolean`                 | `true`      | Enable Markmap mindmaps                 |
+| `codeHighlight`  | `boolean`                 | `true`      | Enable highlight.js code blocks         |
+| `tips`           | `boolean`                 | `true`      | Enable admonition blocks                |
+| `preview`        | `boolean`                 | `true`      | Show preview pane                       |
+| `autoPreview`    | `boolean`                 | `true`      | Auto-update preview                     |
+| `renderDebounce` | `number`                  | `200`       | Preview render debounce in ms           |
+| `mention`        | `MentionConfig`           | -           | @mention configuration                  |
+| `docLink`        | `DocLinkConfig`           | -           | Document link card configuration        |
-- **Changed**: Task list checkbox semantics inverted per project convention. `- [ ]` now renders as **checked** (green checkmark); `- [x]` / `- [X]` renders as **unchecked** (empty box). `toggleTaskList()` and all tests updated accordingly.
-- **Improved**: Clicking the @mention or document-link toolbar button without configuring the search hook now logs a clear `console.warn` explaining that `mention.onMentionSearch` / `docLink.onDocSearch` must be provided.
-- **Test**: 310 tests, all passing, zero unhandled errors.
+### Imperative Handle (React)
-### v0.8.2
-- **Fixed**: @mention and `/` doc-link dropdowns did not appear. Root cause: v0.8.1 mounted dropdowns inside `.md-editor-root` where ancestor `overflow:hidden` / stacking contexts could clip or misplace `position:fixed` elements. Reverted to `document.body` mounting with `position:fixed`, and added explicit light/dark colors via `data-theme` attribute (no dependency on editor-scoped CSS variables).
-- **Fixed**: Clicking toolbar button icons (SVG) did not open popups. Root cause: `mousedown` event bubbled to `document` and triggered the newly-opened Popup's outside-click handler (because `e.target` was the SVG, not the button). Fixed in two ways: Popup now uses `anchor.contains(target)` instead of `target !== anchor`; toolbar `mousedown` handler calls `e.stopPropagation()`.
-- **Fixed**: Task list checkboxes now render with a clear green checkmark when checked (`- [x]` or `- [X]`). Previously used native `accent-color` (orange) which was hard to distinguish in disabled state. Custom checkbox: gray border when unchecked, solid green with white checkmark when checked.
-- **Added**: Help dialog now includes a "Syntax" section with quick-reference guidance for task lists, @mentions, document links, math, mindmaps, and callouts.
-- **Fixed**: Help dialog and all popup-internal styles no longer use editor-scoped CSS variables (undefined when popup is on `document.body`), ensuring consistent light/dark rendering.
-- **Test**: 310 tests, all passing, zero unhandled errors.
-### v0.8.1
+```typescript
+interface MarkdownEditorHandle {
+  getValue(): string;
+  setValue(value: string): void;
+  getHtml(): string;
+  focus(): void;
+  blur(): void;
+  clear(): void;
+}
+```
-- **Fixed**: Toolbar buttons now use `mousedown` + `preventDefault` instead of `click`, preventing the editor from losing focus and collapsing the selection before wrap operations. This fixes the long-standing issue where selecting text and clicking quote/list/other toolbar buttons replaced the selection with placeholder text ("quoted text", "list item").
-- **Fixed**: `toggleTaskList()` mixed-state logic. Previously, a mix of checked and unchecked items (or all-unchecked) removed all task markers. Now: mixed or all-unchecked → check all; all-checked → uncheck all. Also supports uppercase `[X]` markers.
-- **Fixed**: Code block copy button now falls back to `document.execCommand('copy')` when `navigator.clipboard` is unavailable (non-HTTPS contexts), instead of silently failing.
-- **Fixed**: @mention and doc-link dropdowns now close when the editor loses focus (blur), with a 150ms delay so clicks on the dropdown itself register first.
-- **Fixed**: @mention and doc-link dropdowns had transparent backgrounds because they used editor-scoped CSS variables (`--_surface`) while being appended to `document.body`. Now appended inside `.md-editor-root` with `position: fixed` (not clipped by `overflow: hidden`), so theme variables resolve correctly.
-- **Fixed**: Popup dialogs (image, video, YouTube, table, help, callout) now respect the editor theme. Previously always light-themed; now dark-themed when the editor is in dark mode.
-- **Test**: 310 tests, all passing, zero unhandled errors.
+### MentionConfig
-### v0.8.0
+```typescript
+interface MentionConfig {
+  onMentionSearch: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  onMentionSelect?: (item: MentionItem) => string;
+  minChars?: number;
+  maxItems?: number;
+  triggerChar?: string;
+}
+```
-- **Added**: Document/article link inserter. Type `/` to open a searchable dropdown of documents. `onDocSearch(query)` returns matching documents; on selection, inserts either a plain markdown link or a `:::doc-link` preview card.
-- **Added**: `:::doc-link` preview card rendering — displays title, thumbnail, description, and domain as a clickable card. Auto-fetches Open Graph / meta tags via `onFetchDocMeta(url)` hook; falls back to plain link when metadata is unavailable or fetch fails.
-- **Added**: `insertStyle` option: `'auto'` (default, card when meta available), `'card'` (always card, fallback to link), `'link'` (always plain link).
-- **Added**: `docLink` option to `MarkdownEditorOptions` and `CodeEditorOptions`, with `triggerChar`, `minChars`, `maxItems` configuration.
-- **Added**: Toolbar button for document link insertion.
-- **Test**: 307 tests, all passing, zero unhandled errors.
+### DocLinkConfig
-### v0.7.0
+```typescript
+interface DocLinkConfig {
+  onDocSearch: (query: string) => DocItem[] | Promise<DocItem[]>;
+  onFetchDocMeta?: (url: string) => Promise<DocMeta>;
+  insertStyle?: "card" | "link" | "auto";
+  minChars?: number;
+  maxItems?: number;
+  triggerChar?: string;
+}
+```
-- **Fixed**: Mindmap nested code fences no longer lose content. Custom block rule tracks fence nesting depth (lines with info string open, bare backticks close), so ` ```js ` inside a ` ```mindmap ` block is preserved.
-- **Added**: Task list (checkbox) toolbar button and `toggleTaskList()` API. Toggles `- [ ]` / `- [x]` on current line or selected lines. Renders as checkboxes in preview. Keyboard shortcut: `Ctrl+Shift+9`.
-- **Added**: @mention dropdown with configurable hooks. `onMentionSearch(query)` returns matching items, `onMentionSelect(item)` returns replacement text. Supports keyboard navigation (ArrowUp/Down, Enter, Escape), avatars, descriptions, `minChars`, and `maxItems` options.
-- **Added**: `mention` option to `MarkdownEditorOptions` and `CodeEditorOptions`.
-- **Test**: 281 tests, all passing, zero unhandled errors.
+---
-### v0.6.0
+## TypeScript Types
-- **Fixed**: Mindmap `transform: translate(NaN,NaN) scale(NaN)` console errors (hundreds per mindmap). Root cause: `autoFit: true` computed transform on zero-size SVG before layout, and d3-zoom scheduled hundreds of animation frames each throwing "Expected number". Fix: create with `autoFit: false`, set safe default transform immediately, defer `fit()` to next animation frame with dimension guard.
-- **Fixed**: Code block colors now sync with editor theme (light/dark). Previously hardcoded to atom-one-dark in all themes. Now uses CSS variables (`--code-bg`, `--code-fg`, `--code-keyword`, etc.) with GitHub-style light and dark palettes.
-- **Fixed**: UL/OL list styling in preview now has consistent spacing, bullet alignment, and line height.
-- **Improved**: Removed `highlight.js/styles/atom-one-dark.css` import; syntax highlighting colors are now fully theme-aware via CSS variables.
-- **Improved**: Removed stale `markdown-it-texmath` from vite external deps (removed in v0.4.0).
-- **Improved**: Vitest config now excludes `__MACOSX` and AppleDouble (`._*`) files to prevent false test failures from macOS zip artifacts.
-- **Test**: 251 tests, all passing, zero unhandled errors.
+```typescript
+import type {
+  MentionItem,
+  DocItem,
+  DocMeta,
+  MentionConfig,
+  DocLinkConfig,
+  MarkdownEditorHandle,
+  MarkdownEditorProps,
+} from "@powerduck/md-editor";
+```
-### v0.5.0
+---
-- **Fixed**: Admonition `:::` closing marker no longer leaks into rendered body content.
-- **Fixed**: Quote, unordered list, and ordered list toolbar actions now wrap selected text (or the current line) instead of replacing it.
-- **Improved**: Tip/admonition toolbar button now opens a type-picker popup with all six styles (notice, info, tip, success, warning, danger).
-- **Improved**: Help dialog now displays keyboard shortcuts with styled key caps and modifier-key symbols (⌘, ⌥, ⇧).
-- **Improved**: All toolbar icons redesigned in a clean Lucide/Feather line style for a modern Western aesthetic.
-- **Fixed**: Mindmap `transform: translate(NaN,NaN)` error guarded when SVG has zero layout size.
-- **Added**: `formatShortcutHtml()` export for rendering styled key caps.
-- **Test**: 251 tests, all passing.
+## Browser Support
-### v0.4.0
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
-- Self-contained KaTeX math plugin (removed `markdown-it-texmath`); currency `$5` no longer misparsed.
-- Image upload hook `onImageUpload(file)` with paste/drag support.
-- 11 keyboard shortcuts with macOS Cmd auto-mapping.
-- Help dialog listing all shortcuts.
-- Table rows/columns popup dialog.
-- Theme toggle fixed for dark mode with github-markdown-css.
-- Admonition/tip blocks (`:::notice`, `:::warning`, etc.).
-- Configurable toolbar (include-list or per-item show/label/icon).
-- Standalone `renderMarkdown(source, options)` API export.
+---
 ## License
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/md-editor",
-  "version": "0.10.10",
+  "version": "0.11.2",
   "description": "High-performance embeddable Markdown editor: KaTeX math, Markmap mindmaps, highlight.js code blocks with copy button, github-markdown-css preview, admonition blocks, rich toolbar with image/video/YouTube/table popups, keyboard shortcuts, configurable toolbar, image upload hook, standalone renderMarkdown API, React component, block-level incremental rendering. Simple and complex modes, light/dark themes.",
   "type": "module",
   "main": "dist/index.cjs",