autumnnote 2.7.0 → 3.0.0

package/README.md

@@ -33,12 +33,13 @@ A **zero-dependency WYSIWYG rich-text editor** built with vanilla JavaScript (ES
 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)
+9. [Theming](#theming)
+10. [Toolbar Customisation](#toolbar-customisation)
+11. [Keyboard Shortcuts](#keyboard-shortcuts)
+12. [Mentions](#mentions)
+13. [Project Structure](#project-structure)
+14. [Comparison](#comparison)
+15. [License](#license)
 
 ---
 
@@ -359,12 +360,16 @@ const editor = AutumnNote.create('#my-editor', {
 
 ```js
 const editor = AutumnNote.create('#my-editor', { theme: 'dark' });
+// or follow the OS setting, and switch later without re-creating
+editor.updateOptions({ theme: 'auto' });
 ```
 
+The theme applies to that editor only — a light and a dark editor can share a page. See [Theming](#theming) for colours.
+
 ### Read-only preview
 
 ```js
-const preview = AutumnNote.create('#preview', { readOnly: true });
+const preview = AutumnNote.create('#preview', { readOnly: true, statusbar: false });
 preview.setHTML(savedHtml);
 ```
 
@@ -519,6 +524,7 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `AutumnNote.registerLocale(code, locale)` | Registers a locale so `lang: '<code>'` can select it. Only English ships in the ESM build — see [Languages](#languages). |
 | `AutumnNote.registerModule(name, Class)` | Registers a custom module included in every future instance. |
 | `AutumnNote.registerButton(btnDef)` | Adds a button to the global registry. Call `editor.invoke('toolbar.rebuild')` afterwards to render it on existing instances. |
+| `AutumnNote.registerIcon(name, icon)` | Sets the icon for a button or icon name in every editor: SVG markup, or a CSS class list such as `'bi bi-type-bold'`. |
 | `AutumnNote.registerSlashCommand(command)` | Adds or replaces a slash-menu command for future instances. |
 | `AutumnNote.use(plugin, options?)` | Installs a plugin globally — see [Plugin API](#plugin-api). |
 | `AutumnNote.hasPlugin(name)` | Returns `true` if a plugin with that name is registered globally. |
@@ -560,20 +566,28 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 
 ### Events
 
+Every event reaches both `editor.on(name, fn)` listeners and the matching `on<Name>` option callback (e.g. `paste` → `onPaste`).
+
 | Name | Payload | Description |
 |---|---|---|
 | `change` | `html: string` | Fired after every content mutation. Debounced internally. |
 | `focus` | `context` | Editor gained focus. |
 | `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, 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. |
+| `paste` | `{ text, html }` | Fired on every paste, before the editor inserts anything. Return `false` to cancel the paste, or an HTML string to insert instead (it is sanitised). |
 | `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. |
 | `destroy` | `context` | Fired just before the editor is destroyed. |
 | `charLimitReached` | `context` | Fired when `maxChars` is hit. |
 | `wordLimitReached` | `context` | Fired when `maxWords` is hit. |
+| `autoSave` | `{ key, html, savedAt }` | Fired after an auto-save write. |
+| `autoSaveError` | `{ key, error }` | Fired when an auto-save write fails. |
+| `autoSaveRestore` | `html, context` | Fired after the user restores a draft from the restore banner. |
+| `optionsChange` | `overrides` | Fired after `updateOptions()`. |
+| `beforeCommand` | `{ name, value?, source, event? }` | Fired before a command runs from the toolbar, a shortcut, the context menu or the bubble toolbar (`source`). Return `false` to cancel it — e.g. to gate features by plan or log usage. |
+
+Image uploads are not an event: they go to the `onImageUpload` handler, whose return value the editor uses.
 
 ---
 
@@ -587,6 +601,7 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `maxHeight` | `number` | `0` | Maximum resizable height in pixels. `0` = unlimited. |
 | `focus` | `boolean` | `false` | Automatically focus the editor on creation. |
 | `resizable` | `boolean` | `true` | Show the resize handle at the bottom of the editor. |
+| `statusbar` | `boolean` | `true` | Show the statusbar (word/char count, resize handle). Set `false` to hide it, e.g. for a read-only viewer. `getWordCount()`/`getCharCount()` keep working. |
 | `toolbar` | `Array[]` | all buttons | Toolbar layout. See [Toolbar Customisation](#toolbar-customisation). |
 | `toolbarOverflow` | `string` | `'wrap'` | Toolbar overflow strategy: `'wrap'` or `'scroll'`. |
 | `useBootstrap` | `boolean` | `false` | Apply Bootstrap CSS classes to toolbar buttons. |
@@ -606,14 +621,24 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `defaultFontFamily` | `string` | `'Arial'` | Font shown by default in the font-family dropdown. |
 | `defaultFontSize` | `string` | `'14px'` | Default font size applied to new content. |
 | `fontFamilies` | `string[]` | 10 fonts | Font families available in the font-family dropdown. |
+| `fontSizes` | `string[]` | `8px`–`72px` | Sizes in the font-size dropdown. |
+| `lineHeights` | `string[]` | `'1.0'`–`'3.0'` | Values in the line-height dropdown. |
+| `paragraphStyles` | `{ value, label }[]` | Normal, H1–H6, Quote, Code | Block formats in the paragraph-style dropdown (`value` is a block tag). |
+| `icons` | `object` | `null` | Per-editor icon overrides keyed by button or icon name — SVG markup, or a CSS class list. See [Icons](#icons). |
+| `buttons` | `object \| array` | `null` | Per-editor button definitions, usable by name in `toolbar`. |
+| `keyMap` | `object` | `null` | Keyboard shortcut overrides merged over the defaults. See [Keyboard Shortcuts](#keyboard-shortcuts). |
 | `stickyToolbar` | `boolean` | `false` | Pin the toolbar to the viewport top when the page is scrolled. |
 | `stickyToolbarOffset` | `number` | `0` | Top offset in pixels for the sticky toolbar (e.g. height of a fixed nav bar). |
-| `theme` | `string` | `'light'` | Colour theme: `'light'`, `'dark'`, or `'auto'` (follows system preference). |
+| `theme` | `string` | `'light'` | Colour theme: `'light'`, `'dark'`, or `'auto'` (follows system preference). Changeable at runtime. |
+| `themeVars` | `object` | `null` | Design-token overrides for this editor, e.g. `{ primary: '#f97316', radius: '10px' }`. See [Theming](#theming). |
+| `zIndexOffset` | `number` | `0` | Added to the z-index of every floating layer (tooltips, popovers, dialogs, fullscreen), e.g. to sit above a host modal. |
+| `popupContainer` | `string \| Element \| ShadowRoot` | `null` | Where dialogs, tooltips and menus mount (default `document.body`). Use inside a focus-trapping modal or a shadow root. The element must not set `transform`, `filter` or `contain`. |
 | `readOnly` | `boolean` | `false` | Start the editor in non-editable (read-only) mode with toolbar hidden. |
 | `spellcheck` | `boolean` | `true` | Enable browser spellcheck in the editable area. |
 | `direction` | `string` | `'ltr'` | Text direction: `'ltr'` or `'rtl'`. |
 | `autoSave` | `boolean` | `false` | Persist content to `localStorage` on every change. |
 | `autoSaveKey` | `string` | `'autumnnote-autosave'` | `localStorage` key used when `autoSave` is enabled. |
+| `autoSaveDelay` | `number` | `400` | Debounce in ms between the last change and the auto-save write. |
 | `maxChars` | `number` | `0` | Maximum character count. `0` = unlimited. Shows warning in statusbar. |
 | `maxWords` | `number` | `0` | Maximum word count. `0` = unlimited. Shows warning in statusbar. |
 | `tableHeaderRow` | `boolean` | `false` | Insert a `<thead>` header row when creating new tables. |
@@ -622,7 +647,12 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `cspNonce` | `string` | `''` | CSP nonce applied to dynamically injected Prism and Font Awesome assets. |
 | `externalAssetCrossOrigin` | `string` | `'anonymous'` | `crossorigin` value for optional external assets; set `''` to omit it. |
 | `externalAssetReferrerPolicy` | `string` | `'no-referrer'` | Referrer policy for optional external assets; set `''` to omit it. |
-| `colorSwatches` | `string[]` | `[]` | Custom brand colour swatches prepended to the colour picker palette. |
+| `colorSwatches` | `string[]` | `[]` | Custom brand colour swatches prepended to the colour palette (toolbar, bubble toolbar, context menu). |
+| `colorPalette` | `string[]` | `null` | Replaces the built-in 24-colour palette in the toolbar, bubble toolbar and context menu. |
+| `linkDefaults` | `object` | `{ openInNewTab: false, rel: 'noopener noreferrer', defaultProtocol: 'https://' }` | Link dialog defaults. `openInNewTab` pre-ticks the checkbox; `rel` is used for new-tab links (`noopener` is always added); `defaultProtocol` prefixes bare domains (`''` disables). Relative links (`/path`, `#id`, `?q`) are never prefixed. |
+| `videoProviders` | `array` | `null` | Extra video sources for the video dialog: `[{ name, match: RegExp, embed: (match, url) => embedUrl }]`, tried before YouTube/Vimeo. The embed host must be built in or in `iframeHosts`. |
+| `iframeHosts` | `string[]` | `null` | Extra hostnames whose iframes survive sanitisation (exact hostnames, HTTPS only), e.g. `['player.twitch.tv']`. Every listed host can render arbitrary content in the document — list only hosts you trust. |
+| `onBeforeCommand` | `function` | `null` | See the `beforeCommand` event. |
 | `focusColor` | `string` | `null` | Custom focus ring colour (any valid CSS colour). Overrides the default blue. |
 | `lang` | `string \| object` | `'en'` | UI display language. `'en'` is built in; other codes must be registered first — see [Languages](#languages). Pass a partial locale object for custom overrides. |
 | `markdownShortcuts` | `boolean` | `true` | Convert Markdown-style syntax typed in the editor to HTML in real time (block and inline rules). |
@@ -634,13 +664,22 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 | `maxPasteSize` | `number` | `5242880` | Maximum paste payload size in bytes (default 5 MB). Pastes larger than this are silently dropped. |
 | `minImageSize` | `number` | `20` | Minimum image dimension in px during resize (width and height). |
 | `mention` | `object` | `null` | @mention configuration object. Set `mention.onSearch` to activate. See [Mentions](#mentions). |
+| `contextMenu` | `object` | `null` | Right-click menu override. `contextMenu.items` replaces the built-in list; see `ContextMenuItem` in the type definitions. |
+| `slashMenu` | `boolean` | `true` | Show the `/` command palette when `/` is typed at the start of an empty line. |
+| `slashCommands` | `object[]` | `[]` | Extra entries appended to the `/` command palette. |
+| `historyMaxBytes` | `number` | `10485760` | Combined character budget for the undo/redo snapshot stack (default 10 MB). The oldest snapshots are dropped past it. |
+| `blockIds` | `boolean` | `false` | Add stable `data-an-block-id` attributes to top-level blocks, so an external adapter can address them. |
+| `documentAdapters` | `object` | `{}` | Import/export adapters keyed by format name. |
+| `collaborationAdapter` | `object` | `null` | Bridge notified of local HTML changes. |
+| `autoSaveAdapter` | `object` | `null` | Async persistence for auto-save (`save`, `load`, `remove`) instead of `localStorage`. May be a class instance. |
+| `imageProcessor` | `function` | `null` | `(file, { context }) => dataUrl` — transforms pasted/dropped images before insertion (e.g. compress in a Web Worker). |
 | `onChange` | `Function` | `null` | `(html: string) => void` — called on every content change. |
 | `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, { 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. |
+| `onPaste` | `Function` | `null` | `({ text, html }) => void \| false \| string` — called on every paste, before insertion. Return `false` to cancel it or an HTML string to insert instead. See the `paste` event. |
 | `onPasteError` | `Function` | `null` | `({ message, size?, maxBytes? }) => void` — called when pasted or dropped content cannot be processed. |
 | `onSelectionChange` | `Function` | `null` | `(context) => void` — called when cursor or selection changes. |
 | `onDestroy` | `Function` | `null` | `(context) => void` — called just before the editor is destroyed. |
@@ -649,9 +688,108 @@ See the [full Plugin API docs →](https://autumn.konexforge.com/docs.html#plugi
 
 ---
 
+## Theming
+
+Every colour, radius and font the editor uses is a CSS custom property with a built-in fallback, so you can theme it without a Sass build.
+
+| Token | Light default | Used for |
+|---|---|---|
+| `--an-primary` | `#3b82f6` | Accent: active buttons, links, focus ring, selections |
+| `--an-primary-hover` | `#2563eb` | Accent hover |
+| `--an-border` | `#d1d5db` | Borders and separators |
+| `--an-bg` | `#ffffff` | Editor and dialog background |
+| `--an-bg-toolbar` | `#f9fafb` | Toolbar background |
+| `--an-bg-btn-hover` | `#f3f4f6` | Button hover |
+| `--an-bg-btn-active` | `#dbeafe` | Active (pressed) button |
+| `--an-text` | `#111827` | Text |
+| `--an-muted` | `#6b7280` | Secondary text, placeholders |
+| `--an-statusbar-bg` | `#f9fafb` | Statusbar background |
+| `--an-radius` / `--an-radius-sm` | `6px` / `4px` | Corner radii |
+| `--an-font-family` / `--an-font-size` / `--an-line-height` | system UI / `14px` / `1.6` | Editor UI typography |
+| `--an-focus-color` | `--an-primary` | Focus ring (also the `focusColor` option) |
+| `--an-z-offset` | `0` | Added to floating z-indexes (also the `zIndexOffset` option) |
+
+Three ways to set them, from broadest to narrowest:
+
+```css
+/* 1. Every editor on the page */
+:root { --an-primary: #f97316; --an-radius: 10px; }
+
+/* 2. Dark mode only (theme: 'dark', or 'auto' when the OS is dark) */
+.an-theme-dark { --an-bg: #0b1020; }
+@media (prefers-color-scheme: dark) { .an-theme-auto { --an-bg: #0b1020; } }
+```
+
+```js
+// 3. One editor, including its dialogs and tooltips; changeable at runtime
+const editor = AutumnNote.create('#editor', {
+  themeVars: { primary: '#f97316', 'bg-toolbar': '#fff7ed' },
+});
+editor.updateOptions({ themeVars: null });          // drop all overrides
+editor.updateOptions({ themeVars: { primary: '#10b981' } });
+```
+
+Each editor mounts its dialogs, tooltips and menus in its own portal element (`.an-portal`), which carries the editor's theme class and `themeVars`. Use `popupContainer` to put that portal somewhere other than `document.body`.
+
 ## Toolbar Customisation
 
-The `toolbar` option accepts an array of **groups**. Each group is an array of button definition objects exported from the package:
+The `toolbar` option accepts an array of **groups**. Each group lists buttons by **name** — plain strings, so the config can come from JSON, framework props or the UMD build:
+
+```js
+AutumnNote.create('#editor', {
+  toolbar: [
+    ['paragraphStyle', 'fontSize'],
+    ['bold', 'italic', 'underline', 'strikethrough'],
+    ['ul', 'ol', 'checklist'],
+    ['link', 'image', 'table'],
+    ['undo', 'redo'],
+  ],
+});
+```
+
+Built-in names: `paragraphStyle`, `fontFamily`, `fontSize`, `lineHeight`, `undo`, `redo`, `bold`, `italic`, `underline`, `strikethrough`, `inlineCode`, `superscript`, `subscript`, `foreColor`, `backColor`, `alignLeft`, `alignCenter`, `alignRight`, `alignJustify`, `ul`, `ol`, `checklist`, `indent`, `outdent`, `hr`, `link`, `image`, `video`, `table`, `emoji`, `icon`, `removeFormat`, `direction`, `codeview`, `fullscreen`, `find`, `findReplace`, `print`, `shortcuts`.
+
+### Buttons for one editor
+
+`buttons` defines buttons for a single editor, without touching the global registry — two editors can each have their own `save`:
+
+```js
+AutumnNote.create('#editor', {
+  toolbar: [['bold', 'italic'], ['save']],
+  buttons: {
+    save: { icon: '<svg viewBox="0 0 24 24">…</svg>', tooltip: 'Save', action: (ctx) => save(ctx.getHTML()) },
+  },
+});
+```
+
+### Dropdown lists and colours
+
+```js
+AutumnNote.create('#editor', {
+  fontSizes: ['12px', '14px', '16px', '20px'],
+  lineHeights: ['1.2', '1.5', '2'],
+  paragraphStyles: [{ value: 'p', label: 'Body' }, { value: 'h2', label: 'Title' }],
+  colorPalette: ['#0f172a', '#f97316', '#10b981'], // replaces the 24 defaults
+  colorSwatches: ['#7c3aed'],                       // prepended to the palette
+});
+```
+
+### Icons
+
+Buttons use built-in SVG icons (or Font Awesome when the page loads it). Override any of them per editor with `icons`, or for every editor with `AutumnNote.registerIcon()`. A value starting with `<` is markup; anything else is a CSS class list:
+
+```js
+AutumnNote.registerIcon('bold', 'bi bi-type-bold');            // Bootstrap Icons, all editors
+AutumnNote.create('#editor', {
+  icons: { italic: '<svg viewBox="0 0 24 24">…</svg>', table: 'ti ti-table' },
+});
+```
+
+Keys are button names (`bold`) or icon ids (`list-ul`). The per-editor option wins over `registerIcon()`.
+
+### Button objects
+
+Button definition objects are also exported, for building your own or wrapping a built-in one:
 
 ```js
 import AutumnNote, {
@@ -756,12 +894,40 @@ Object.assign(AutumnNote.defaults, {
 | `Ctrl + B` | Bold |
 | `Ctrl + I` | Italic |
 | `Ctrl + U` | Underline |
+| `Ctrl + K` | Insert / edit link |
+| ``Ctrl + ` `` | Inline code |
+| `Ctrl + Shift + V` | Paste as plain text |
 | `Ctrl + F` | Open Find dialog |
 | `Ctrl + H` | Open Find & Replace dialog |
+| `Ctrl + Shift + /` | Open Keyboard Shortcuts dialog |
 | `Shift + Enter` | Insert line break |
 | `Tab` | Insert spaces / indent list item |
 | `Shift + Tab` | Outdent list item |
-| `Shift + ?` | Open Keyboard Shortcuts dialog |
+
+`Ctrl` is `Cmd` on macOS.
+
+### Changing shortcuts
+
+`keyMap` is merged over the defaults. Combos are written `Mod+B` (`Mod` = Ctrl or Cmd), `Ctrl+Alt+1`, `Mod+Shift+Z`; Shift and Alt must match exactly, so AltGr characters never trigger a Ctrl shortcut. A value can be:
+
+- `false` — disable the default (e.g. give `Ctrl+F` back to the browser)
+- a command name — `undo`, `redo`, `bold`, `italic`, `underline`, `inlineCode`, `link`, `find`, `findReplace`, `shortcuts`, `pastePlainText`, **or any toolbar button name**
+- a function `(context, event) => {}` — return `false` to let the key through
+- `{ run, description }` — a function plus the label the shortcuts dialog shows
+
+```js
+AutumnNote.create('#editor', {
+  keyMap: {
+    'Mod+F': false,                       // browser find
+    'Mod+H': false,
+    'Mod+Shift+F': 'find',                // editor find moves here
+    'Mod+Shift+X': 'strikethrough',       // any toolbar button
+    'Mod+Alt+1': { run: (ctx) => ctx.invoke('editor.formatBlock', 'h1'), description: 'Heading 1' },
+  },
+});
+```
+
+The shortcuts dialog (`Ctrl + Shift + /`) reflects the keyMap: disabled shortcuts disappear and custom ones are listed under *Custom*. Shortcuts need Ctrl, Cmd or Alt; plain keys belong to typing.
 
 > The number of spaces inserted by `Tab` is controlled by the `tabSize` option.
 
@@ -889,7 +1055,7 @@ autumn-note-ce/
 
 ### Development commands
 
-Development and package usage require Node 20.19+ and pnpm 11.1.3.
+Development and package usage require Node 22 LTS (22.22.2+) or Node 24.15+ (newer releases included) and pnpm 11.1.3.
 
 ```bash
 pnpm install                           # install all workspace packages