@powerduck/md-editor 0.2.0 → 0.5.0

package/README.md

@@ -1,17 +1,28 @@
 # @powerduck/md-editor
 
-High-performance embeddable Markdown editor built on the markdown-it ecosystem. Supports KaTeX math formulas, Markmap mindmaps, 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.
+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.
 
 ## Features
 
 - **Markdown editing** powered by CodeMirror 6 with markdown syntax highlighting
-- **Math formulas** via KaTeX (`$E=mc^2$` inline, `$$...$$` block)
+- **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
+- **Zero Chinese** -- all code, comments, and UI strings in American English
 
 ## Installation
 
@@ -65,7 +76,11 @@ function App() {
 | `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 |
@@ -95,6 +110,123 @@ function App() {
 ```
 ````
 
+## 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.
+
+````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:
+
+```ts
+// Only show specific buttons
+new MarkdownEditor('#editor', {
+  mode: 'complex',
+  toolbar: ['bold', 'italic', 'link', 'code']
+});
+
+// Fine-grained control
+new MarkdownEditor('#editor', {
+  mode: 'complex',
+  toolbar: {
+    bold: { label: 'Make bold', icon: '<b>B</b>' },
+    image: { show: false },
+    youtube: { show: false }
+  }
+});
+```
+
+## Image Upload
+
+Provide an upload hook to handle pasted/dropped images:
+
+```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.
+:::
+```
+
+Supported types: `notice`, `info`, `tip`, `success`, `warning`, `danger`.
+
 ## Performance
 
 - **Block splitting**: documents are split at ATX headings (`#` through `######`). Content inside code fences is never split.

package/dist/Editor.d.ts

@@ -5,15 +5,35 @@ export interface CodeEditorOptions {
     /** Show line numbers. Off in simple mode, on in complex mode by default. */
     lineNumbers?: boolean;
     placeholder?: string;
+    /** Called when an image file is pasted or dropped into the editor. */
+    onImageFile?: (file: File) => void;
 }
 export declare class CodeEditor {
     readonly view: EditorView;
     private lineNumbersCompartment;
+    private customKeymapCompartment;
+    private onImageFile?;
     constructor(container: HTMLElement, options: CodeEditorOptions);
+    private handlePaste;
+    private handleDrop;
+    /**
+     * Register custom keyboard shortcuts. Each entry is a CodeMirror keymap
+     * spec: { key: 'Mod-b', run: (view) => boolean }.
+     */
+    setKeymap(bindings: Array<{
+        key: string;
+        run: (view: EditorView) => boolean;
+    }>): void;
     getValue(): string;
     setValue(value: string): void;
     setLineNumbers(enabled: boolean): void;
     insertAtCursor(text: string): void;
+    /**
+     * Wrap the current selection with prefix and suffix. If nothing is
+     * selected, insert prefix + placeholder + suffix and select the placeholder.
+     */
+    wrapSelection(prefix: string, suffix: string, placeholder: string): void;
+    getSelection(): string;
     focus(): void;
     destroy(): void;
 }

package/dist/Renderer.d.ts

@@ -1,9 +1,14 @@
 import MarkdownIt from 'markdown-it';
+import 'github-markdown-css/github-markdown.css';
 export interface RendererOptions {
     /** Enable KaTeX math rendering. Default: true. */
     math?: boolean;
     /** Enable Markmap mindmap rendering. Default: true. */
     mindmap?: boolean;
+    /** Enable syntax highlighting for code blocks. Default: true. */
+    codeHighlight?: boolean;
+    /** Enable admonition/tip blocks (:::notice, :::warning, etc.). Default: true. */
+    tips?: boolean;
     /** Allow raw HTML in markdown source. Default: false (safer). */
     html?: boolean;
     /** Convert soft line breaks to <br>. Default: false. */
@@ -20,3 +25,18 @@ export declare class Renderer {
      */
     hydrate(container: HTMLElement): Promise<void>;
 }
+/**
+ * Standalone markdown rendering function with the same styling and plugins
+ * as the editor preview. Use this in other parts of your app to render
+ * markdown consistently without mounting an editor.
+ *
+ * @example
+ * ```ts
+ * import { renderMarkdown } from '@powerduck/md-editor';
+ * import '@powerduck/md-editor/dist/style.css';
+ *
+ * const html = renderMarkdown('# Hello\n\n$E=mc^2$');
+ * container.innerHTML = html;
+ * ```
+ */
+export declare function renderMarkdown(source: string, options?: RendererOptions): string;

package/dist/Toolbar.d.ts

@@ -3,7 +3,7 @@ export interface ToolbarAction {
     title: string;
     /** SVG/HTML icon markup */
     icon: string;
-    handler: () => void;
+    handler: (button: HTMLButtonElement) => void;
     /** Append a group separator after this button */
     groupEnd?: boolean;
     /** Whether this is a toggle button (e.g. preview visibility, theme) */

package/dist/icons.d.ts

@@ -11,5 +11,13 @@ export declare const icons: {
     readonly refresh: string;
     readonly moon: string;
     readonly sun: string;
+    readonly image: string;
+    readonly video: string;
+    readonly youtube: string;
+    readonly quote: string;
+    readonly list: string;
+    readonly listOrdered: string;
+    readonly hr: string;
+    readonly help: string;
 };
 export type IconName = keyof typeof icons;