@powerduck/md-editor 0.11.1 → 0.11.2

package/README.md

@@ -1,17 +1,24 @@
 # @powerduck/md-editor
 
-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.
-
 [![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)
 
-## Links
+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.
 
-- [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.html)
-- [GitHub](https://github.com/PowerDuckie/md-editor)
-- [npm](https://www.npmjs.com/package/@powerduck/md-editor)
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
+
+- **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
 
 ---
 
@@ -27,7 +34,10 @@ npm install @powerduck/md-editor
 
 ```tsx
 import { useRef, useState } from "react";
-import { MarkdownEditorReact, type MarkdownEditorHandle } from "@powerduck/md-editor/react";
+import {
+  MarkdownEditorReact,
+  type MarkdownEditorHandle,
+} from "@powerduck/md-editor/react";
 import "@powerduck/md-editor/dist/style.css";
 
 function App() {
@@ -64,21 +74,50 @@ const editor = new MarkdownEditor("#editor", {
   onChange: (value) => console.log(value.length, "chars"),
 });
 
-// Read and write content
-const markdown = editor.getValue();
-editor.setValue("# Updated content");
-
-// Render to HTML
 const html = editor.getHtml();
 ```
 
-### @mention Integration
+---
+
+## Links
+
+- [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)
+
+---
+
+## Features
+
+- **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
+
+---
+
+## @mention Integration
 
 ```typescript
 import { MarkdownEditor, type MentionItem } from "@powerduck/md-editor";
 
 const USERS: MentionItem[] = [
-  { id: "1", label: "Alice", avatar: "https://example.com/a.png", description: "alice@example.com" },
+  {
+    id: "1",
+    label: "Alice",
+    avatar: "https://example.com/a.png",
+    description: "alice@example.com",
+  },
   { id: "2", label: "Bob", description: "bob@example.com" },
 ];
 
@@ -94,14 +133,21 @@ new MarkdownEditor("#editor", {
 });
 ```
 
-### Document Link Card
+---
+
+## Document Link Card
 
 ```typescript
 import { MarkdownEditor, type DocItem } from "@powerduck/md-editor";
 
 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" },
-  { id: "d2", title: "API Reference", url: "https://docs.example.com/api", description: "Full API documentation" },
+  {
+    id: "1",
+    title: "Getting Started",
+    url: "https://docs.example.com/getting-started",
+    thumbnail: "https://example.com/thumb.jpg",
+    description: "Quick start tutorial",
+  },
 ];
 
 new MarkdownEditor("#editor", {
@@ -109,288 +155,101 @@ new MarkdownEditor("#editor", {
   docLink: {
     onDocSearch: async (query) =>
       DOCS.filter((d) => d.title.toLowerCase().includes(query.toLowerCase())),
-    onFetchDocMeta: async (url) => {
-      const res = await fetch(`/api/og?url=${encodeURIComponent(url)}`);
-      return res.json();
-    },
-    insertStyle: "auto", // "auto" | "card" | "link"
+    insertStyle: "card",
     minChars: 0,
-    maxItems: 8,
+    maxItems: 6,
   },
 });
 ```
 
 ---
 
-## Features
-
-- **Syntax highlighting** — CodeMirror 6 with Markdown grammar and token colors
-- **Math formulas** — KaTeX rendering for inline `$...$` and block `$$...$$`
-- **Mindmaps** — Markmap interactive SVG diagrams from ```` ```mindmap ```` fenced blocks
-- **Code blocks** — highlight.js with traffic-light header and copy button
-- **@mentions** — Searchable dropdown with custom search/select hooks, inserts `[@label](mention:id)` for renderer distinction
-- **Document link cards** — Insert plain links or preview cards with auto-fetched title/thumbnail/description, with custom fetch hook
-- **Image upload** — Paste/drag/select image files with custom upload hook
-- **Task lists** — `- [ ]` / `- [x]` with clickable toggles in preview
-- **Callouts** — `:::notice`, `:::warning`, `:::danger`, etc.
-- **Tables** — Quick-insert popup with configurable rows/columns
-- **Incremental rendering** — Block-level DOM reuse for large documents, adaptive debounce
-- **Themes** — Light and dark themes with CSS custom properties
-- **Two modes** — `simple` (pure edit + preview) and `complex` (toolbar + status bar + line numbers)
-- **React wrapper** — `forwardRef` component with controlled/uncontrolled value and imperative handle
-- **Dual ESM/CJS builds** — Works with `import` and `require`
-
----
-
-## MarkdownEditorOptions
+## API Reference
+
+### React Props
+
+| 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        |
+
+### Imperative Handle (React)
 
 ```typescript
-interface MarkdownEditorOptions {
-  value?: string;
-  mode?: "simple" | "complex"; // default: "simple"
-  theme?: "light" | "dark"; // default: "light"
-  math?: boolean; // default: true
-  mindmap?: boolean; // default: true
-  codeHighlight?: boolean; // default: true
-  tips?: boolean; // default: true
-  preview?: boolean; // default: true
-  onChange?: (value: string) => void;
-  toolbar?: ToolbarConfig;
-  onImageUpload?: (file: File) => Promise<string>;
-  mention?: MentionOptions;
-  docLink?: DocLinkOptions;
-  renderDebounce?: number | false; // adaptive by default
-  autoPreview?: boolean; // default: true
+interface MarkdownEditorHandle {
+  getValue(): string;
+  setValue(value: string): void;
+  getHtml(): string;
+  focus(): void;
+  blur(): void;
+  clear(): void;
 }
 ```
 
-### MentionOptions
+### MentionConfig
 
 ```typescript
-interface MentionOptions {
-  onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
-  onMentionSelect?: (item: MentionItem) => string; // default: `[@label](mention:id)`
-  minChars?: number; // default: 0
-  maxItems?: number; // default: 8
-}
-
-interface MentionItem {
-  id: string;
-  label: string;
-  avatar?: string;
-  description?: string;
-  [key: string]: unknown;
+interface MentionConfig {
+  onMentionSearch: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  onMentionSelect?: (item: MentionItem) => string;
+  minChars?: number;
+  maxItems?: number;
+  triggerChar?: string;
 }
 ```
 
-### DocLinkOptions
+### DocLinkConfig
 
 ```typescript
-interface DocLinkOptions {
-  onDocSearch?: (query: string) => DocItem[] | Promise<DocItem[]>;
+interface DocLinkConfig {
+  onDocSearch: (query: string) => DocItem[] | Promise<DocItem[]>;
   onFetchDocMeta?: (url: string) => Promise<DocMeta>;
-  insertStyle?: "card" | "link" | "auto"; // default: "auto"
-  triggerChar?: string; // default: "/"
-  minChars?: number; // default: 0
-  maxItems?: number; // default: 8
-}
-
-interface DocItem {
-  id: string;
-  title: string;
-  url: string;
-  thumbnail?: string;
-  description?: string;
-  [key: string]: unknown;
+  insertStyle?: "card" | "link" | "auto";
+  minChars?: number;
+  maxItems?: number;
+  triggerChar?: string;
 }
 ```
 
 ---
 
-## React Component Props
-
-```typescript
-interface MarkdownEditorProps extends Omit<MarkdownEditorOptions, "value" | "onChange"> {
-  value?: string; // controlled value
-  defaultValue?: string; // uncontrolled initial value (mount only)
-  onChange?: (value: string) => void;
-  className?: string;
-  style?: CSSProperties;
-}
-
-interface MarkdownEditorHandle {
-  getValue: () => string;
-  setValue: (value: string) => void;
-  getHtml: () => string;
-  focus: () => void;
-  setMode: (mode: "simple" | "complex") => void;
-  setTheme: (theme: "light" | "dark") => void;
-  renderNow: () => void;
-}
-```
-
-> **Performance note:** Structural options (`mode`, `math`, `mindmap`, `preview`, `autoPreview`, `renderDebounce`) recreate the underlying instance when they change. `value`, `onChange`, and `theme` use lightweight sync paths and never recreate the instance, so controlled usage stays responsive on large documents.
-
----
-
-## Toolbar Actions
-
-22 built-in toolbar actions in default order:
-
-`heading`, `bold`, `italic`, `link`, `image`, `video`, `youtube`, `quote`, `ul`, `ol`, `tasklist`, `mention`, `doclink`, `code`, `table`, `math`, `mindmap`, `hr`, `tips`, `preview`, `help`, `theme`
-
-### Configure Toolbar
-
-```typescript
-// Array form: include-list (only these actions show, in this order)
-new MarkdownEditor("#editor", {
-  mode: "complex",
-  toolbar: ["bold", "italic", "link", "code", "math"],
-});
-
-// Record form: per-item overrides (everything not listed stays visible)
-new MarkdownEditor("#editor", {
-  mode: "complex",
-  toolbar: {
-    bold: { label: "Make bold" },
-    image: { show: false },
-    youtube: { show: false },
-  },
-});
-```
-
----
-
-## Standalone Rendering
-
-```typescript
-import { renderMarkdown } from "@powerduck/md-editor";
-import "@powerduck/md-editor/dist/style.css";
-
-const html = renderMarkdown("# Hello\n\n$E=mc^2$", { math: true });
-document.getElementById("output")!.innerHTML = html;
-```
-
-> `renderMarkdown` returns a string and does not mount an editor. Mindmap placeholders are emitted as inert `<div>`s; call `Renderer.hydrate` yourself if you need live diagrams outside the editor.
-
----
-
-## Public API (Vanilla JS)
+## TypeScript Types
 
 ```typescript
-class MarkdownEditor {
-  constructor(container: HTMLElement | string, options?: MarkdownEditorOptions);
-
-  getValue(): string;
-  setValue(value: string): void;
-  getHtml(): string;
-  renderNow(): void;
-  setAutoPreview(auto: boolean): void;
-  setMode(mode: "simple" | "complex"): void;
-  setTheme(theme: "light" | "dark"): void;
-  focus(): void;
-  destroy(): void;
-}
-```
-
----
-
-## Keyboard Shortcuts
-
-| Shortcut | Action |
-|---|---|
-| `Ctrl/Cmd + B` | Bold |
-| `Ctrl/Cmd + I` | Italic |
-| `Ctrl/Cmd + K` | Link |
-| `Ctrl/Cmd + S` | (custom via onChange) |
-
----
-
-## Mindmap Syntax
-
-````markdown
-```mindmap
-# Root topic
-## Branch one
-- Child A
-- Child B
-## Branch two
-- Child C
-```
-````
-
-Renders as an interactive markmap SVG diagram in the preview pane.
-
----
-
-## Math Syntax
-
-```markdown
-Inline: $E = mc^2$
-
-Block:
-$$
-\int_{a}^{b} f(x)\,dx
-$$
-```
-
-Powered by KaTeX.
-
----
-
-## Callout Syntax
-
-```markdown
-:::notice Title
-Notice content.
-:::
-
-:::warning Warning
-Warning content.
-:::
-
-:::danger Danger
-Danger content.
-:::
-
-:::tip Tip
-Tip content.
-:::
-```
-
-Available types: `notice`, `info`, `tip`, `success`, `warning`, `danger`.
-
----
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Type check
-npm run typecheck
-
-# Build (ESM + CJS + type declarations + CSS)
-npm run build
-
-# Run tests
-npm test
-
-# Dev server
-npm run dev
+import type {
+  MentionItem,
+  DocItem,
+  DocMeta,
+  MentionConfig,
+  DocLinkConfig,
+  MarkdownEditorHandle,
+  MarkdownEditorProps,
+} from "@powerduck/md-editor";
 ```
 
 ---
 
-## Related Packages
+## Browser Support
 
-- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
-- [`@powerduck/conf-patch`](https://www.npmjs.com/package/@powerduck/conf-patch) — Configuration file editor with atomic writes and locking
-- [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
 
 ---
 
 ## License
 
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/md-editor",
-  "version": "0.11.1",
+  "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",