@mdaemon/html-editor-react 1.8.3 → 1.9.0

package/README.md

@@ -1,19 +1,25 @@
-[![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmdaemon-technologies%2FMDHTMLEditor-react%2Fmaster%2Fpackage.json&query=%24.version&prefix=v&label=npm&color=blue)](https://www.npmjs.com/package/@mdaemon/html-editor-react) [![install size](https://packagephobia.com/badge?p=@mdaemon/html-editor-react)](https://packagephobia.com/result?p=@mdaemon/html-editor-react) [![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmdaemon-technologies%2FMDHTMLEditor-react%2Fmaster%2Fpackage.json&query=%24.license&prefix=v&label=license&color=green)](https://github.com/mdaemon-technologies/MDHTMLEditor-react/blob/master/LICENSE) [![Node.js CI](https://github.com/mdaemon-technologies/MDHTMLEditor-react/actions/workflows/ci.yml/badge.svg)](https://github.com/mdaemon-technologies/MDHTMLEditor-react/actions/workflows/ci.yml)
+# @mdaemon/html-editor-react
 
-# MDHTMLEditor React
+[![npm](https://img.shields.io/npm/v/@mdaemon/html-editor-react?color=blue)](https://www.npmjs.com/package/@mdaemon/html-editor-react)
+[![license](https://img.shields.io/npm/l/@mdaemon/html-editor-react?color=green)](LICENSE)
+[![node](https://img.shields.io/node/v/@mdaemon/html-editor-react)](https://nodejs.org)
+[![install size](https://packagephobia.com/badge?p=@mdaemon/html-editor-react)](https://packagephobia.com/result?p=@mdaemon/html-editor-react)
+[![CI](https://github.com/mdaemon-technologies/MDHTMLEditor-react/actions/workflows/ci.yml/badge.svg)](https://github.com/mdaemon-technologies/MDHTMLEditor-react/actions/workflows/ci.yml)
+
+React wrapper for MDHTMLEditor
 
 A React wrapper for [MDHTMLEditor](https://github.com/mdaemon-technologies/MDHTMLEditor) — a WYSIWYG HTML editor built on TipTap. Provides a drop-in replacement for `@tinymce/tinymce-react` with no license key required.
 
-## Installation
+## Install
 
 ```bash
-npm install @mdaemon/html-editor-react @mdaemon/html-editor
+npm install @mdaemon/html-editor-react
 ```
 
 **Peer dependencies:** `react` and `react-dom` (v18 or v19).
 
 **TipTap:** the editor is built on TipTap 3, and this package tracks the same version the
-engine uses — currently **3.31.3** (`@mdaemon/html-editor` `^1.12.3`,
+engine uses — currently **3.31.3** (`@mdaemon/html-editor` `^1.13.0`,
 `@tiptap/react` `^3.31.3`). If your app depends on any `@tiptap/*` package directly, keep
 it on that version too: ProseMirror throws at runtime if two copies of `@tiptap/core` /
 `@tiptap/pm` end up in the bundle. If you only use `<Editor>` or `useEditor`, there is
@@ -260,6 +266,7 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `browser_spellcheck` | `boolean` | `true` | Enable browser spell check. |
 | `entity_encoding` | `'raw' \| 'named' \| 'numeric'` | `'raw'` | HTML entity encoding mode. |
 | `paste_from_office` | `boolean` | `true` | Clean and preserve formatting when pasting from Microsoft Word/Excel. Pasted list indentation is normalized either way &mdash; see [Lists & Indentation](#lists--indentation). |
+| `paste_markdown` | `boolean` | `false` | Start with paste-as-Markdown on, so a paste is read as Markdown and inserted as real formatting. Toggle at runtime via `getEditor()?.setPasteMarkdown()` or the `pastemarkdown` toolbar button &mdash; see [Pasting Markdown](#pasting-markdown). |
 | `speech_to_text` | `boolean` | `true` | Enable the `speechtotext` and `dictate` toolbar buttons (requires the Web Speech API). |
 | `convert_unsafe_embeds` | `boolean` | `true` | Sanitize embedded content. |
 | `format_empty_lines` | `boolean` | `true` | Preserve blank lines outside the editor. On the way out (`getContent()`, the `onChange` payload, preview, and the source dialog) each empty block is filled with a `<br>` &mdash; bare empty blocks otherwise collapse to zero height in mail clients; on the way in (`setContent()`, `insertContent()`, templates) it is stripped back out, so `setContent(getContent(x))` is stable across round-trips. A block is only "empty" if it has no visible content &mdash; a `<div>&nbsp;</div>` spacer counts as content and is left alone. Set `false` to pass content through unchanged in both directions. |
@@ -455,6 +462,74 @@ Lists pasted from Word, Outlook, Google Docs, another editor, or a web page are
 
 Word/Excel cleaning as a whole can be turned off with [`paste_from_office: false`](#configuration); list indentation is normalized either way.
 
+## Pasting Markdown
+
+Chat apps, AI assistants and README files hand out Markdown, which by default pastes in as
+the raw `#`, `*` and `|` characters. The editor's **Paste Markdown** mode reads a paste
+as Markdown and inserts it as real formatting: headings, bold, italic, strikethrough, inline
+code, links, images, bullet/ordered/nested lists, blockquotes, horizontal rules, fenced code
+blocks with their language, and GFM tables.
+
+The mode is **off by default** and, like TinyMCE's *Paste as text*, stays on once turned on
+until it is turned off again. It is per editor instance and the editor does not persist it.
+
+Turn it on at init with the `paste_markdown` config option, or at runtime through the raw
+editor instance:
+
+```tsx
+<Editor config={{ paste_markdown: true }} />
+
+// At runtime
+editorRef.current?.getEditor()?.setPasteMarkdown(true);
+const on = editorRef.current?.getEditor()?.isPasteMarkdownEnabled();
+
+// Or toggle it the TinyMCE way
+editorRef.current?.getEditor()?.execCommand('mceTogglePasteMarkdown');
+```
+
+The `pastemarkdown` toolbar button lets the user toggle the mode. It is deliberately **not**
+in any default toolbar, so no existing layout changes &mdash; add it to a `toolbar` string
+to offer it:
+
+```tsx
+<Editor config={{ toolbar: 'bold italic | copy cut paste pastemarkdown | undo redo' }} />
+```
+
+While the mode is on the button shows the active background, a dot badge and
+`aria-pressed="true"`, and the toolbar's `paste` button converts as well.
+
+To remember the user's choice, listen for the `pastemarkdownchange` event &mdash; fired with
+the new boolean, and only when it actually changes &mdash; and pass the saved value back as
+`paste_markdown` next time:
+
+```tsx
+<Editor
+  config={{ paste_markdown: savedPreference }}
+  onInit={(editor) => {
+    editor.on('pastemarkdownchange', (enabled) => savePreference(enabled));
+  }}
+/>
+```
+
+A few things worth knowing:
+
+- **A single newline is a line break**, not a continuation of the paragraph, because chat and
+  assistant output is written that way. A blank line still starts a new paragraph.
+- **Task lists paste as plain bullets** (`- [ ] item` becomes a bullet reading `item`) &mdash;
+  the editor has no checkbox node.
+- While the mode is on the clipboard's `text/plain` is used and its `text/html` ignored, so
+  syntax-highlighted HTML copied from a code editor does not paste as coloured code. Markdown
+  mode also takes precedence over the built-in code-block paste for clipboards that VS Code
+  (and editors that copy the way it does) mark as code.
+- Pastes that carry files (images), Markdown pasted inside a code block, and drag-and-drop are
+  never converted. A URL pasted over a selection still becomes a link either way.
+- **Pasted Markdown cannot run script.** Raw HTML inside the Markdown is escaped to visible
+  text, the converted HTML is sanitized in an inert document before it reaches ProseMirror,
+  and links are limited to the schemes TipTap allows.
+- Conversion runs on a budget so a crafted paste cannot freeze the tab: input over 256 KB, any
+  single paragraph, heading, list item or table cell over 5,000 characters, or a parse that
+  takes longer than 750 ms is abandoned and the text goes in as an ordinary paste instead.
+
 ## Templates
 
 Enable the template dropdown and provide a `templates` array:
@@ -484,7 +559,7 @@ const templates: Template[] = [
 
 The `Template` interface:
 
-```typescript
+```ts
 interface Template {
   id?: number | string;
   title: string;
@@ -606,7 +681,8 @@ Buttons after `||` begin collapsed behind a toggle (`...`) button.
 | `removeformat` | Strip all formatting |
 | `copy` | Copy selection |
 | `cut` | Cut selection |
-| `paste` | Paste from clipboard |
+| `paste` | Paste from clipboard (follows the paste-as-Markdown mode) |
+| `pastemarkdown` | Toggle paste-as-Markdown mode &mdash; not in any default toolbar (see [Pasting Markdown](#pasting-markdown)) |
 | `undo` | Undo |
 | `redo` | Redo |
 | `image` | Insert image (upload or URL) |
@@ -620,7 +696,7 @@ Buttons after `||` begin collapsed behind a toggle (`...`) button.
 | `anchor` | Insert a named anchor (`<a id>` target) |
 | `codesample` | Toggle code sample |
 | `fullscreen` | Toggle fullscreen |
-| `preview` | Preview in new window |
+| `preview` | Preview in new window (the window carries a Content Security Policy that blocks script) |
 | `searchreplace` | Find & Replace dialog |
 | `speechtotext` | Open Speech to Text dialog (requires `speech_to_text` + browser support) |
 | `dictate` | Toggle inline dictation &mdash; inserts speech at the cursor (requires `speech_to_text` + browser support) |
@@ -807,16 +883,6 @@ Key differences:
 - `plugins` option is not needed &mdash; all features are built in
 - Toolbar customization uses `basicEditor: true/false` or a `toolbar` string
 
-## Running the Demo
-
-A demo app is included to see the editor in action:
-
-```bash
-npm run demo
-```
-
-This starts a Vite dev server at `http://localhost:5173` with three sections: the `<Editor>` component, the `useEditor` hook, and a [Fonts](#fonts) panel with a live `getFontFamily()` / `getFontSize()` readout that follows the cursor and buttons for the block-font commands.
-
 ## Development
 
 The package is bundled with [Vite 8](https://vite.dev/) (Rolldown) and ships ES, CommonJS, and TypeScript declaration outputs.
@@ -836,6 +902,24 @@ The package is bundled with [Vite 8](https://vite.dev/) (Rolldown) and ships ES,
 
 Lint, typecheck, and tests run automatically in [CI](.github/workflows/ci.yml) on every push and pull request to `master` across Node 20, 22, 24, and 26.
 
+### Running the Demo
+
+A demo app is included to see the editor in action:
+
+```bash
+npm run demo
+```
+
+This starts a Vite dev server at `http://localhost:5173` with three sections: the `<Editor>` component, the `useEditor` hook, and a [Fonts](#fonts) panel with a live `getFontFamily()` / `getFontSize()` readout that follows the cursor and buttons for the block-font commands.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
-LGPL-3.0-or-later &mdash; [MDaemon Technologies, Ltd.](https://www.mdaemon.com)
+Published under the [LGPL-3.0-or-later](LICENSE) license.
+
+Published by **MDaemon Technologies, Ltd.**  
+Simple Secure Email  
+[https://www.mdaemon.com](https://www.mdaemon.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdaemon/html-editor-react",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "React wrapper for MDHTMLEditor",
   "homepage": "https://github.com/mdaemon-technologies/MDHTMLEditor-react",
   "repository": {
@@ -48,12 +48,15 @@
     "url": "https://www.mdaemon.com"
   },
   "license": "LGPL-3.0-or-later",
+  "engines": {
+    "node": ">=20"
+  },
   "peerDependencies": {
     "react": "^19.0.0 || ^18.0.0",
     "react-dom": "^19.0.0 || ^18.0.0"
   },
   "dependencies": {
-    "@mdaemon/html-editor": "^1.12.3",
+    "@mdaemon/html-editor": "^1.13.0",
     "@tiptap/react": "^3.31.3"
   },
   "devDependencies": {