autumnnote 2.4.0 → 2.6.0

package/README.md

@@ -27,17 +27,18 @@ A **zero-dependency WYSIWYG rich-text editor** built with vanilla JavaScript (ES
 
 1. [Features](#features)
 2. [Installation](#installation)
-3. [Framework Wrappers](#framework-wrappers)
-4. [Quick Start](#quick-start)
-5. [Plugin API](#plugin-api)
-6. [API](#api)
-7. [Options](#options)
-8. [Toolbar Customisation](#toolbar-customisation)
-9. [Keyboard Shortcuts](#keyboard-shortcuts)
-10. [Mentions](#mentions)
-11. [Project Structure](#project-structure)
-12. [Comparison](#comparison)
-13. [License](#license)
+3. [Minimal build](#minimal-build)
+4. [Framework Wrappers](#framework-wrappers)
+5. [Quick Start](#quick-start)
+6. [Plugin API](#plugin-api)
+7. [API](#api)
+8. [Options](#options)
+9. [Toolbar Customisation](#toolbar-customisation)
+10. [Keyboard Shortcuts](#keyboard-shortcuts)
+11. [Mentions](#mentions)
+12. [Project Structure](#project-structure)
+13. [Comparison](#comparison)
+14. [License](#license)
 
 ---
 
@@ -60,7 +61,23 @@ A **zero-dependency WYSIWYG rich-text editor** built with vanilla JavaScript (ES
 ### Insert
 - **Horizontal rule** — inserts an `<hr>` at the current caret position
 - **Link dialog** — URL, display text (auto-filled from selection), "Open in new tab" checkbox; edits existing links when caret is inside an `<a>`
-- **Image dialog** — insert by URL with alt text, or file upload (base64 embed); enforces `maxImageSize`; file input restricted to browser-renderable MIME types; supports custom `onImageUpload` handler for server-side upload
+- **Image dialog** — insert by URL with alt text, or file upload (base64 embed); enforces `maxImageSize`; file input restricted to browser-renderable MIME types
+- **Server-side image upload** — return the uploaded URL from `onImageUpload` (or a promise of it) and the editor drops in a dimmed placeholder previewing the local file straight away, then swaps in the real URL when it lands. Report progress with the supplied `setProgress(file, ratio)`; a rejection marks the image failed and fires `imageError` with a `retry()` for that file. A handler that returns nothing keeps the previous behaviour and inserts the image itself:
+
+  ```js
+  AutumnNote.create('#editor', {
+    async onImageUpload(files, { setProgress }) {
+      return Promise.all(files.map(async (file) => {
+        const body = new FormData();
+        body.append('file', file);
+        setProgress(file, 0.1);
+        const res = await fetch('/api/upload', { method: 'POST', body });
+        setProgress(file, 1);
+        return (await res.json()).url;   // inserted in place of the placeholder
+      }));
+    },
+  });
+  ```
 - **Image crop overlay** — inline interactive crop tool triggered from the image tooltip; corner and edge drag handles; canvas-based crop export; CORS fallback warning
 - **Video dialog** — paste a YouTube watch/short URL, Vimeo URL, or direct `.mp4 / .webm / .ogg` URL; configurable width; renders as responsive `<iframe>` or `<video>`
 - **Table** — interactive grid picker (up to 10x10); optional header row (`tableHeaderRow`); floating tooltip for full row/column/cell management
@@ -187,6 +204,34 @@ import 'autumnnote/dist/autumnnote.css';
 
 ---
 
+## Minimal build
+
+The default entry installs every module. When you only need basic formatting,
+import `autumnnote/core` instead — it leaves the dialogs, floating tooltips,
+emoji and icon pickers and the crop overlay out of the bundle entirely rather
+than shipping them switched off:
+
+```js
+import AutumnNote from 'autumnnote/core';
+import 'autumnnote/dist/autumnnote.css';   // same stylesheet as the full build
+
+AutumnNote.create('#editor', {
+  toolbar: [['bold', 'italic', 'underline'], ['ul', 'ol'], ['undo', 'redo']],
+});
+```
+
+| Entry | Modules | ES bundle (gzip) |
+|---|---|---|
+| `autumnnote` | all | 84.1 KiB |
+| `autumnnote/core` | editor, toolbar, statusbar, clipboard, placeholder | **44.2 KiB** |
+
+Same API, same types, same stylesheet — the difference is only which modules are
+installed. A toolbar button whose module is absent still renders, but invoking it
+logs a warning and does nothing, so give this preset a toolbar naming only
+buttons the core modules serve.
+
+---
+
 ## Framework Wrappers
 
 Official React and Vue 3 wrappers are available as separate packages in this monorepo (managed with pnpm workspaces).
@@ -312,18 +357,44 @@ const editor = AutumnNote.create('#my-editor', {
 
 ### Custom image upload
 
+Return the URL and the editor places the image for you — a placeholder appears
+at the caret immediately and is replaced when the upload resolves:
+
+```js
+AutumnNote.create('#my-editor', {
+  async onImageUpload(files, { setProgress }) {
+    return Promise.all(files.map(async (file) => {
+      const fd = new FormData();
+      fd.append('file', file);
+      setProgress(file, 0.1);
+      const res = await fetch('/api/upload', { method: 'POST', body: fd });
+      setProgress(file, 1);
+      return (await res.json()).url;
+    }));
+  },
+  onImageError({ file, message, retry }) {
+    console.warn(message, file?.name);
+    retry?.();          // re-sends just that file
+  },
+});
+```
+
+Returning nothing keeps the original behaviour — the handler inserts the image
+itself and no placeholder is shown:
+
 ```js
 const editor = AutumnNote.create('#my-editor', {
   onImageUpload(files) {
-    const fd = new FormData();
-    fd.append('file', files[0]);
-    fetch('/api/upload', { method: 'POST', body: fd })
-      .then(r => r.json())
-      .then(({ url }) => editor.invoke('editor.insertImage', url, files[0].name));
+    upload(files[0]).then(({ url }) =>
+      editor.invoke('editor.insertImage', url, files[0].name));
   },
 });
 ```
 
+> `onImageUpload` **uploads** and resolves to any URL the sanitiser accepts.
+> `imageProcessor` **transforms** a file and must resolve to a data URL — use it
+> for compression or format conversion, not for sending the file somewhere.
+
 ### Bubble toolbar
 
 ```js
@@ -474,7 +545,7 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `blur` | `context` | Editor lost focus. |
 | `init` | `context` | Fired once after the editor has fully initialised. |
 | `imageUpload` | `files: FileList` | Fired when images are dropped or pasted (when `onImageUpload` is provided). |
-| `imageError` | `{ file, message }` | Fired when an image is rejected (e.g. over `maxImageSize`). |
+| `imageError` | `{ file, message, error?, retry? }` | Fired when an image is rejected (e.g. over `maxImageSize`) or an upload fails. `retry()` is present on upload failures and re-sends that one file. |
 | `paste` | `{ text, html }` | Fired after every paste event. |
 | `pasteError` | `{ message, size?, maxBytes? }` | Fired when paste/drop exceeds `maxPasteSize` or a dropped Markdown file cannot be read. |
 | `selectionChange` | `context` | Fired when the cursor or selection changes. |
@@ -542,7 +613,7 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `onFocus` | `Function` | `null` | `(context) => void` — called when the editor gains focus. |
 | `onBlur` | `Function` | `null` | `(context) => void` — called when the editor loses focus. |
 | `onInit` | `Function` | `null` | `(context) => void` — called once after the editor is initialised. |
-| `onImageUpload` | `Function` | `null` | `(files: FileList) => void` — custom upload handler. Overrides base64 embed. |
+| `onImageUpload` | `Function` | `null` | `(files, { context, setProgress }) => void \| string \| string[] \| Promise<…>` — upload handler; overrides the base64 embed. Return the uploaded URL(s) to have the editor insert them, or nothing to insert them yourself. |
 | `onImageError` | `Function` | `null` | `({ file, message }) => void` — called when an image is rejected. |
 | `onPaste` | `Function` | `null` | `({ text, html }) => void` — called after every paste event. |
 | `onPasteError` | `Function` | `null` | `({ message, size?, maxBytes? }) => void` — called when pasted or dropped content cannot be processed. |
@@ -718,10 +789,11 @@ src/
 │   │   ├── env.js            Browser/platform detection (lazy — SSR-safe)
 │   │   ├── detectLang.js     Code-block language detection for Prism highlighting
 │   │   ├── markdown.js       Bidirectional HTML ↔ Markdown conversion (with GFM checklists)
-│   │   └── sanitise.js       DOM-based HTML and URL sanitiser
+│   │   └── sanitise.js       DOM-based HTML and URL sanitiser (string or nodes)
 │   ├── editing/
 │   │   ├── History.js        Undo/redo stack (configurable depth)
-│   │   ├── Style.js          Formatting commands (execCommand + DOM list/checklist transitions)
+│   │   ├── insert.js         Range-based insertHTML/insertText/insertHorizontalRule
+│   │   ├── Style.js          Formatting commands (native insertion, execCommand fallback)
 │   │   ├── Table.js          Table creation and cell manipulation
 │   │   └── Typing.js         Tab/Enter/ArrowKey behaviour and FA icon caret handling
 │   ├── module/