@mdaemon/html-editor-react 1.10.0 → 1.12.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
+[![install size](https://img.shields.io/npm/unpacked-size/@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
@@ -19,8 +19,8 @@ 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.13.1`,
-`@tiptap/react` `^3.31.3`). If your app depends on any `@tiptap/*` package directly, keep
+engine uses — currently **3.32.0** (`@mdaemon/html-editor` `^1.17.0`,
+`@tiptap/react` `^3.32.0`). 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
 nothing to do.
@@ -233,7 +233,7 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `height` | `string \| number` | `300` | Editor height. |
 | `min_height` | `string \| number` | &mdash; | Minimum editor height. |
 | `max_height` | `string \| number` | &mdash; | Maximum editor height. |
-| `language` | `string` | `'en'` | UI language code. 31 languages built in. |
+| `language` | `string` | `'en'` | UI language code. 32 languages built in &mdash; see [Supported Languages](#supported-languages). |
 | `skin` | `'oxide' \| 'oxide-dark' \| 'confab' \| 'confab-dark'` | `'oxide'` | Toolbar and dialog theme. |
 | `content_css` | `'default' \| 'dark' \| 'confab' \| 'confab-dark'` | `'default'` | Content area theme. |
 | `content_style` | `string` | &mdash; | Custom CSS injected into the editing surface. |
@@ -246,7 +246,7 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `block_formats` | `string` | *(Paragraph + H1&ndash;H6)* | Block-format dropdown definitions for the `blocks` button (`Name=tag;...`). |
 | `style_formats` | `StyleFormat[]` | *(subset)* | Named styles for the `styles` dropdown (CKEditor `stylesSet`-compatible). |
 | `forced_root_block` | `'p' \| 'div'` | `'p'` | Block element produced on Enter. `'div'` gives CKEditor `ENTER_DIV` parity. |
-| `trailingNode` | `boolean` | `false` | Append an empty trailing paragraph after a block node (table, image, code block) so the cursor can sit after it. |
+| `trailingNode` | `boolean` | `false` | Append an empty trailing paragraph after a block node (table, code block) so the cursor can sit after it. |
 | `directionality` | `'ltr' \| 'rtl'` | `'ltr'` | Text direction. |
 | `toolbar` | `string` | *(preset)* | Custom toolbar layout string. |
 | `toolbar_mode` | `'sliding' \| 'floating' \| 'wrap'` | `'wrap'` | Toolbar overflow behavior. |
@@ -254,10 +254,19 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `toolbar_narrow_breakpoint` | `number` | &mdash; | Pixel width below which the toolbar collapses into the overflow toggle. |
 | `toolbar_priority` | `Record<string, number>` | &mdash; | Per-button overflow priority &mdash; higher values stay visible longer as the toolbar narrows. |
 | `menubar` | `boolean` | `false` | Show a TinyMCE-style menu bar above the toolbar. |
-| `contextmenu` | `boolean \| string` | `''` | Enable a right-click context menu. Pass a button-list string to customize its contents. |
+| `contextmenu` | `boolean \| string` | `''` | Right-click menu. A string naming `table` (or `true`) opens the table menu on a right-click in a table. Off by default, because it replaces the browser's menu and its spelling suggestions &mdash; see [Tables](#tables). |
+| `table_toolbar` | `string \| false` | *(TinyMCE defaults)* | Buttons of the toolbar that floats above a table while the cursor is in it, as a toolbar string. `false` turns it off. Off by default in the basic editor. |
+| `table_grid` | `boolean` | `true` | Insert tables from a size grid in the table menu. `false` opens the Insert table dialog instead. |
+| `table_default_attributes` | `Record<string, string>` | `{ border: '1' }` | Attributes of a table the user inserts (`border`, `cellpadding`, `cellspacing`). |
+| `table_default_styles` | `Record<string, string>` | `{ 'border-collapse': 'collapse', width: '100%' }` | Style of a table the user inserts. |
+| `table_default_header_rows` | `number` | `0` | Header rows of an inserted table. |
+| `table_default_header_cols` | `number` | `0` | Header columns of an inserted table. |
+| `table_tab_navigation` | `boolean` | `true` | Tab and Shift+Tab move between table cells. `false` makes them indent the paragraph in the cell. |
 | `quickbars_selection_toolbar` | `string` | `'bold italic \| quicklink blockquote'` | Inline floating toolbar shown over a text selection. |
 | `quickbars_image_toolbar` | `boolean` | `false` | Inline floating toolbar shown when an image is selected. |
 | `quickbars_insert_toolbar` | `boolean` | `false` | Inline floating toolbar shown on empty lines for quick insertion. |
+| `object_resizing` | `boolean \| string` | `true` | Show drag handles on a selected image to resize it. `false` turns resizing off; a CSS selector string (TinyMCE-style, e.g. `'img[alt]'`) limits it to the images that match &mdash; see [Resizing Images](#resizing-images). |
+| `resize_img_proportional` | `boolean` | `true` | Corner handles keep the image's aspect ratio. Holding Shift while dragging does the opposite for that drag. |
 | `elementpath` | `boolean` | `false` | Show a breadcrumb of the node path at the cursor in the status bar. |
 | `valid_children` | `string` | &mdash; | TinyMCE-style rules controlling which child elements are allowed. |
 | `auto_focus` | `string` | &mdash; | Auto-focus on init. |
@@ -267,6 +276,7 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `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). |
+| `quote_marker_class` | `string` | &mdash; | Class that marks a reply's quoted original. A `<blockquote>` or `<div>` whose class is exactly this value keeps the class and its margin, padding and border in `getContent()`, so the quote can be found again. One class name; off when unset or empty. See the [engine docs](https://github.com/mdaemon-technologies/MDHTMLEditor#quoted-original-of-a-reply). |
 | `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. |
@@ -281,8 +291,11 @@ The `config` prop (or `useEditor`'s `config` option) accepts an `EditorConfig` o
 | `images_file_types` | `string` | *(permissive)* | Comma/space-separated accepted extensions (e.g. `'jpg,jpeg,png,gif'`). |
 | `images_upload_validate` | `(file: File) => string \| null` | &mdash; | Pre-upload hook; return a message to reject the file, or `null` to allow. |
 | `images_upload_error` | `(message: string) => void` | &mdash; | Caller-supplied alert for drag-drop/paste upload rejections and failures. |
+| `images_upload_error_message` | `(response: unknown, status: number) => string \| null \| undefined` | &mdash; | Words the message for a failed upload from the server's reply (parsed JSON body, or `null`, and the HTTP status). Return `null`/`undefined` for the editor's own translated message &mdash; see [Image Upload](#image-upload). |
 | `setup` | `(editor) => void` | &mdash; | Pre-init callback for registering custom toolbar buttons. |
 
+The table dialogs and pickers have further options (`table_appearance_options`, `table_advtab`, `table_row_advtab`, `table_cell_advtab`, `table_border_widths`, `table_border_styles`, `table_background_color_map`, `table_border_color_map`) &mdash; see the [engine docs](https://github.com/mdaemon-technologies/MDHTMLEditor#tables).
+
 ### Dark Theme
 
 ```tsx
@@ -325,7 +338,7 @@ Opt into the additional editing surfaces exposed by `@mdaemon/html-editor` 1.6.0
 <Editor
   config={{
     menubar: true,                  // menu bar above the toolbar
-    contextmenu: true,              // right-click context menu
+    contextmenu: 'table',           // right-click table menu in a table
     quickbars_selection_toolbar: 'bold italic | quicklink blockquote',
     quickbars_image_toolbar: true,  // floating toolbar when an image is selected
     elementpath: true,              // breadcrumb status bar at the cursor
@@ -333,7 +346,8 @@ Opt into the additional editing surfaces exposed by `@mdaemon/html-editor` 1.6.0
 />
 ```
 
-`contextmenu` also accepts a button-list string to customize its contents, and
+`contextmenu` replaces the browser's menu (and its spelling suggestions) only for a
+right-click in a table; Ctrl+right-click still shows the browser's menu.
 `quickbars_insert_toolbar` shows a floating insert toolbar on empty lines.
 
 ### Read-Only Mode
@@ -434,7 +448,7 @@ The `indent` / `outdent` toolbar buttons, `execCommand('indent' | 'outdent')`, a
 | Paragraph, heading | Adds a `margin-left` in 40px steps (max 400px) | Removes one step |
 | Code block | Inserts a literal tab | Nothing |
 
-Inside a list the indent is written to the `<li>` rather than to the paragraph inside it, so the bullet or number moves with the text. Because it is an inline `margin-left`, it survives in the exported HTML &mdash; in a mail client, say &mdash; without the editor's stylesheet. In a table, <kbd>Tab</kbd> still moves between cells; the toolbar buttons indent the paragraph in the cell.
+Inside a list the indent is written to the `<li>` rather than to the paragraph inside it, so the bullet or number moves with the text. Because it is an inline `margin-left`, it survives in the exported HTML &mdash; in a mail client, say &mdash; without the editor's stylesheet. In a table, <kbd>Tab</kbd> still moves between cells (unless `table_tab_navigation: false`); the toolbar buttons indent the paragraph in the cell.
 
 ### Ordered List Numbering
 
@@ -687,7 +701,12 @@ Buttons after `||` begin collapsed behind a toggle (`...`) button.
 | `undo` | Undo |
 | `redo` | Redo |
 | `image` | Insert image (upload or URL) |
-| `table` | Table dropdown (insert table + row/column/cell operations) |
+| `table` | Table menu: Insert table size grid, Cell / Row / Column submenus, Table properties, caption and Delete table (see [Tables](#tables)) |
+| `tableinsertdialog`, `tableprops`, `tabledelete`, `tablecellprops`, `tablerowprops`, `tablemergecells`, `tablesplitcells` | Insert table dialog, properties dialogs, delete table, merge and split cells |
+| `tableinsertrowbefore`, `tableinsertrowafter`, `tabledeleterow`, `tableinsertcolbefore`, `tableinsertcolafter`, `tabledeletecol` | Insert and delete rows and columns |
+| `tablecutrow`, `tablecopyrow`, `tablepasterowbefore`, `tablepasterowafter`, `tablecutcol`, `tablecopycol`, `tablepastecolbefore`, `tablepastecolafter` | Row and column clipboard |
+| `tablecaption`, `tablerowheader`, `tablecolheader` | Toggle caption, header row, header column |
+| `tablecellvalign`, `tablecellborderwidth`, `tablecellborderstyle`, `tablecellbackgroundcolor`, `tablecellbordercolor` | Cell vertical alignment, border and background menus and pickers |
 | `hr` | Insert horizontal rule |
 | `charmap` | Special character picker |
 | `emoticons` | Emoji picker with search |
@@ -695,7 +714,7 @@ Buttons after `||` begin collapsed behind a toggle (`...`) button.
 | `link` | Insert/edit hyperlink (with the caret on a link, edits that link in place) |
 | `unlink` | Remove the link at the cursor |
 | `anchor` | Insert a named anchor (`<a id>` target) |
-| `codesample` | Toggle code sample |
+| `codesample` | Toggle code sample on the lines the selection touches (lines split by Shift+Enter outside the selection stay text) |
 | `fullscreen` | Toggle fullscreen |
 | `preview` | Preview in new window (the window carries a Content Security Policy that blocks script) |
 | `searchreplace` | Find & Replace dialog |
@@ -726,6 +745,79 @@ SVGs are automatically sanitized (script tags, event handlers, and dangerous ele
 />
 ```
 
+Upload failures are shown in the editor's language. When your server explains a refusal in its reply, `images_upload_error_message` lets you word the message yourself. It receives the parsed JSON body (`null` when the body is not JSON) and the HTTP status, and returns the message to show, or `null`/`undefined` to keep the editor's own. It is not called for a network error or an aborted request. The message is shown in the image dialog, and passed to `images_upload_error` for a dropped or pasted image.
+
+```tsx
+<Editor
+  config={{
+    images_upload_url: '/api/upload',
+    // The server answers a refusal with HTTP 200 and {"error": "<reason>"}
+    images_upload_error_message: (response) => {
+      const error = (response as { error?: unknown } | null)?.error;
+      return typeof error === 'string' ? error : null;
+    },
+    images_upload_error: (message) => showAlert(message),
+  }}
+/>
+```
+
+### Resizing Images
+
+Click an image in the full editor to select it, and drag one of the eight handles to resize it. Corners keep the aspect ratio (hold Shift to stretch freely), sides change only the width or the height, and Escape cancels the drag. The new size is saved in the image's `width` and `height` attributes, as TinyMCE does, as one undo step that fires `onDirty` and `onChange` like any other edit. Handles are hidden in read-only mode.
+
+Resizing is on by default. Set `object_resizing: false` to turn it off, or pass a CSS selector to allow it only for the images that match. The `objectresizestart` and `objectresized` events have no props; register them on the editor in `onInit`:
+
+```tsx
+<Editor
+  config={{
+    object_resizing: 'img[alt]',   // or true (default) / false
+    resize_img_proportional: true, // corners keep the aspect ratio (default)
+  }}
+  onInit={(editor) => {
+    editor.on('objectresized', ({ width, height }) => {
+      console.log(`Image resized to ${width} × ${height}`);
+    });
+  }}
+/>
+```
+
+Images are inline, as in TinyMCE and mail HTML: a link around an image is kept, and an `<img>` that is not already in a line of text is put in a `<p>` (or a `<div>` with `forced_root_block: 'div'`).
+
+### Image Maps
+
+In the full editor, an `<img usemap="#name">` and its `<map name="name">` with the `<area>` hotspots are kept through loading, `insertContent()`, paste and the Source view, with their values checked (an area `href` gets the same check as a link's). While editing, a map is shown as a small marker and its hotspots do nothing; they work in the saved HTML. Maps have no toolbar button &mdash; edit them in the Source view. An image with a map has no resize handles. The basic editor has no images, so it drops maps. See the [engine docs](https://github.com/mdaemon-technologies/MDHTMLEditor#image-maps) for what is kept.
+
+## Tables
+
+Table editing follows TinyMCE's table plugin. The `table` toolbar button opens the table menu: Insert table (a 10×10 size grid, or a dialog with `table_grid: false`), Cell, Row and Column submenus, Table properties, Toggle caption and Delete table. The [table buttons](#available-toolbar-buttons) can also go in the `toolbar` string. While the cursor is in a table, a context toolbar floats above it (`table_toolbar`), and `contextmenu: 'table'` adds a right-click table menu.
+
+A new table is inserted with `border="1"` and `border-collapse: collapse; width: 100%`, so its borders show in mail clients, and with no header row unless `table_default_header_rows` / `table_default_header_cols` ask for one. Tables keep their borders, padding, spacing, sizes, alignment, backgrounds and caption in `getContent()`, including the legacy `bgcolor`, `valign`, `width`, `height` and `align` attributes common in email.
+
+Table commands, queries and events have no props; reach them through the editor from `onInit` or `getEditor()`:
+
+```tsx
+<Editor
+  config={{
+    table_toolbar: 'tableprops tabledelete | tableinsertrowafter tabledeleterow',
+    table_default_header_rows: 1,
+    contextmenu: 'table',
+  }}
+  onInit={(editor) => {
+    editor.on('tablemodified', ({ table, structure, style }) => {
+      console.log('Table changed', { structure, style });
+    });
+  }}
+/>
+
+// Later, from a ref
+const editor = editorRef.current?.getEditor();
+editor?.execCommand('mceInsertTable', false, { rows: 3, columns: 4 });
+editor?.isTableCommandEnabled('mceTableMergeCells'); // would merging apply?
+editor?.queryCommandValue('mceTableCellType');      // 'th', 'td', or '' outside a table
+```
+
+A table command returns `false` when it did not apply (outside a table, read-only, or nothing to do). See the [engine docs](https://github.com/mdaemon-technologies/MDHTMLEditor#tables) for every command, dialog, and the formatting a table keeps.
+
 ## Localization
 
 ### Set Language at Init
@@ -745,6 +837,8 @@ setTranslate((key) => myTranslations[key] ?? key);
 <Editor translate={(key) => myTranslations[key] ?? key} config={{}} />
 ```
 
+The built-in locale is the fallback: when your function returns an empty string (or, through `setTranslate()`, `null` or `undefined`), the editor shows its own translation for that key. A custom function therefore only needs the strings it wants to change. Keys with a placeholder, such as `Upload failed: {status}` and `Confidence: {percent}%`, must keep it in the translation.
+
 ### Change Language at Runtime
 
 ```tsx
@@ -754,6 +848,8 @@ const editorRef = useRef<EditorRef>(null);
 editorRef.current?.getEditor()?.setLanguage('fr');
 ```
 
+`setLanguage()` keeps a custom translate function; it changes only the fallback locale.
+
 ### Supported Languages
 
 | Code | Language | Code | Language |
@@ -764,15 +860,15 @@ editorRef.current?.getEditor()?.setLanguage('fr');
 | `zh` | Chinese | `pt` | Portugues |
 | `cs` | Cesky | `ro` | Romana |
 | `da` | Dansk | `ru` | Russian |
-| `en-gb` | English (UK) | `sr` | Srpski |
-| `fi` | Suomi | `sl` | Slovenscina |
-| `fr` | Francais | `es` | Espanol |
-| `fr-ca` | Canadien francais | `sv` | Svenska |
-| `de` | Deutsch | `zh-tw` | Chinese (Taiwan) |
-| `el` | Greek | `th` | Thai |
-| `hu` | Magyar | `tr` | Turkce |
-| `id` | Bahasa Indonesia | `vi` | Tieng Viet |
-| `it` | Italiano | | |
+| `en-gb` | English (UK) | `sr` | Srpski (Cyrillic) |
+| `fi` | Suomi | `sr-latn` | Srpski (latinica) |
+| `fr` | Francais | `sl` | Slovenscina |
+| `fr-ca` | Canadien francais | `es` | Espanol |
+| `de` | Deutsch | `sv` | Svenska |
+| `el` | Greek | `zh-tw` | Chinese (Taiwan) |
+| `hu` | Magyar | `th` | Thai |
+| `id` | Bahasa Indonesia | `tr` | Turkce |
+| `it` | Italiano | `vi` | Tieng Viet |
 | `ja` | Japanese | | |
 | `ko` | Korean | | |
 
@@ -799,7 +895,8 @@ setGetFileSrc((path) => `https://cdn.example.com${path}`);
 | Ctrl/Cmd + Z | Undo |
 | Ctrl/Cmd + Shift + Z | Redo |
 | Ctrl/Cmd + F | Find & Replace |
-| Tab | Increase indent &mdash; nests or indents a list item, moves to the next table cell, inserts a tab in a code block, or indents the block ([details](#lists--indentation)) |
+| Ctrl + Alt + C (Cmd + Option + C on macOS) | Toggle code sample |
+| Tab | Increase indent &mdash; nests or indents a list item, moves to the next table cell (unless `table_tab_navigation: false`), inserts a tab in a code block, or indents the block ([details](#lists--indentation)) |
 | Shift + Tab | Decrease indent &mdash; un-nests a list item, moves to the previous table cell, or removes block indent ([details](#lists--indentation)) |
 | Esc, then Tab | Move focus to the next element outside the editor (keyboard escape) |
 | Esc, then Shift + Tab | Move focus to the previous element outside the editor |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdaemon/html-editor-react",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "React wrapper for MDHTMLEditor",
   "homepage": "https://github.com/mdaemon-technologies/MDHTMLEditor-react",
   "repository": {
@@ -56,7 +56,7 @@
     "react-dom": "^19.0.0 || ^18.0.0"
   },
   "dependencies": {
-    "@mdaemon/html-editor": "^1.14.0",
+    "@mdaemon/html-editor": "^1.17.0",
     "@tiptap/react": "^3.32.0"
   },
   "devDependencies": {