autumnnote 1.3.0 → 1.4.0

package/README.md

@@ -16,7 +16,7 @@ A modern, lightweight WYSIWYG rich-text editor built with vanilla JavaScript (ES
 
 > Write rich text. No dependencies. No drama.
 
-[Live Demo](https://cmm-cmm.github.io/Autumn-Note/)
+[Live Demo](https://cmm-cmm.github.io/Autumn-Note/) · [Docs](https://cmm-cmm.github.io/Autumn-Note/docs.html) · [Playground](https://cmm-cmm.github.io/Autumn-Note/playground.html)
 
 <p align="center"><img src="demo/Screenshot.png" alt="AutumnNote Screenshot"/></p>
 
@@ -27,14 +27,15 @@ A modern, lightweight WYSIWYG rich-text editor built with vanilla JavaScript (ES
 1. [Features](#features)
 2. [Installation](#installation)
 3. [Quick Start](#quick-start)
-4. [API](#api)
-5. [Options](#options)
-6. [Toolbar Customisation](#toolbar-customisation)
-7. [Keyboard Shortcuts](#keyboard-shortcuts)
-8. [Mentions](#mentions)
-9. [Project Structure](#project-structure)
-10. [Comparison](#comparison)
-11. [License](#license)
+4. [Plugin API](#plugin-api)
+5. [API](#api)
+6. [Options](#options)
+7. [Toolbar Customisation](#toolbar-customisation)
+8. [Keyboard Shortcuts](#keyboard-shortcuts)
+9. [Mentions](#mentions)
+10. [Project Structure](#project-structure)
+11. [Comparison](#comparison)
+12. [License](#license)
 
 ---
 
@@ -109,7 +110,7 @@ Right-click inside the editor opens a context menu with: **Undo**, **Redo**, **C
 - **No jQuery** — pure vanilla ES2022, zero runtime dependencies
 - **Bootstrap friendly** — optional Bootstrap 4/5 styling (`useBootstrap: true`)
 - **FontAwesome ready** — auto-detects FA on the page; falls back to built-in SVG icons
-- **Plugin-ready** — register custom modules via `AutumnNote.defaults`
+- **Plugin API** — first-class plugin system: `AutumnNote.use(plugin)`, `context.getPlugin(name)`, global button registry (`registerButton`), per-instance installation, `AsnPlugin<T>` TypeScript interface
 - **Tree-shakeable** — ES module build; all core utilities individually exported
 - **TypeScript definitions** — bundled `types/index.d.ts` with full JSDoc coverage
 - **@mention autocomplete** — type `@` (or any custom trigger) to open a floating dropdown backed by a user-supplied `onSearch` function; inserts a non-editable mention chip; customisable chip HTML via `onInsert`
@@ -269,6 +270,61 @@ const editor = AutumnNote.create('#my-editor', {
 
 ---
 
+## Plugin API
+
+Plugins package editor extensions — custom modules, toolbar buttons, and event handlers — into a reusable, distributable object.
+
+```js
+import AutumnNote from 'autumnnote';
+
+const WordCountPlugin = {
+  name: 'word-count',
+  version: '1.0.0',
+  // Buttons registered BEFORE create() — usable by name in toolbar config
+  buttons: [{
+    name: 'wordCountBtn',
+    icon: 'hashtag',
+    tooltip: 'Word count',
+    action: (ctx) => alert(`${ctx.getWordCount()} words`),
+  }],
+  // Called after all built-in modules initialise
+  install(ctx, options) {
+    ctx.on('change', () => console.log('words:', ctx.getWordCount()));
+    return { getMax: () => options.maxWords };
+  },
+  uninstall(ctx) { /* cleanup */ },
+};
+
+// Global — applied to every future editor instance
+AutumnNote.use(WordCountPlugin, { maxWords: 500 });
+
+const editor = AutumnNote.create('#editor', {
+  toolbar: [['bold', 'italic', 'wordCountBtn']], // 'wordCountBtn' resolved from registry
+});
+
+editor.getPlugin('word-count').getMax(); // → 500
+```
+
+**Per-instance installation:**
+
+```js
+const editor = AutumnNote.create('#editor');
+editor.use(WordCountPlugin, { maxWords: 200 });
+editor.invoke('toolbar.rebuild'); // re-render toolbar with new buttons
+```
+
+| Method | Description |
+|---|---|
+| `AutumnNote.use(plugin, opts?)` | Install globally. Buttons registered immediately; `install()` called after modules init. |
+| `AutumnNote.hasPlugin(name)` | Returns `true` if plugin registered globally. |
+| `AutumnNote.registerButton(def)` | Register a single button globally by name. |
+| `context.use(plugin, opts?)` | Install on this instance only. |
+| `context.getPlugin<T>(name)` | Returns the public API from `plugin.install()`. |
+
+See the [full Plugin API docs →](https://cmm-cmm.github.io/Autumn-Note/docs.html#plugin-api)
+
+---
+
 ## API
 
 ### Factory

package/dist/autumnnote.es.js

@@ -1089,6 +1089,34 @@ function btn(name, icon, tooltip, action, isActive, isDisabled) {
 		isDisabled
 	};
 }
+/**
+* Global registry for custom buttons registered via AutumnNote.registerButton()
+* or via a plugin's `buttons` array. Toolbar resolves string names from here.
+* @type {Map<string, object>}
+*/
+var _buttonRegistry = /* @__PURE__ */ new Map();
+/**
+* Registers a button definition in the global registry so it can be referenced
+* by string name in toolbar configuration: `toolbar: [['myBtn', boldBtn]]`.
+* @param {object} btnDef - Any ToolbarItemDef-compatible object with a `name` string.
+*/
+function registerButton(btnDef) {
+	if (!btnDef || typeof btnDef.name !== "string") {
+		console.warn("[AutumnNote] registerButton: btnDef must have a string `name` property.");
+		return;
+	}
+	if (_buttonRegistry.has(btnDef.name)) console.warn(`[AutumnNote] registerButton: overwriting existing button "${btnDef.name}".`);
+	_buttonRegistry.set(btnDef.name, btnDef);
+}
+/**
+* Looks up a button definition by name from the global registry.
+* Returns undefined when not found.
+* @param {string} name
+* @returns {object|undefined}
+*/
+function getButton(name) {
+	return _buttonRegistry.get(name);
+}
 var boldBtn = btn("bold", "bold", "Bold (Ctrl+B)", () => bold(), () => document.queryCommandState("bold"));
 var italicBtn = btn("italic", "italic", "Italic (Ctrl+I)", () => italic(), () => document.queryCommandState("italic"));
 var underlineBtn = btn("underline", "underline", "Underline (Ctrl+U)", () => underline(), () => {
@@ -5797,6 +5825,8 @@ var Editor = class {
 * Toolbar.js - Builds and manages the editor toolbar UI
 * Inspired by Summernote's Toolbar module — rewritten without jQuery
 */
+/** Resolve a toolbar item: string → registry lookup, object → pass-through. */
+var _resolveBtn = (item) => typeof item === "string" ? getButton(item) : item;
 var _faPageLevelReady = null;
 var _S$1 = "stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"";
 var _svgWrap = (paths) => `<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" ${_S$1} style="display:block">${paths}</svg>`;
@@ -5893,7 +5923,7 @@ var Toolbar = class {
 		this.el = createElement("div", { class: "an-toolbar" });
 		this._faReady = this._detectFontAwesome();
 		this._buildButtons();
-		this._btnMap = new Map((this.options.toolbar || []).flat().map((b) => [b.name, b]));
+		this._btnMap = new Map((this.options.toolbar || []).flat().map(_resolveBtn).filter(Boolean).map((b) => [b.name, b]));
 		return this;
 	}
 	destroy() {
@@ -5909,7 +5939,12 @@ var Toolbar = class {
 		const fragment = document.createDocumentFragment();
 		toolbar.forEach((group) => {
 			const groupEl = createElement("div", { class: "an-btn-group" });
-			group.forEach((btnDef) => {
+			group.forEach((item) => {
+				const btnDef = _resolveBtn(item);
+				if (!btnDef) {
+					console.warn(`[AutumnNote] Toolbar: button "${item}" not found in registry. Skipped.`);
+					return;
+				}
 				let el;
 				if (btnDef.type === "select") el = this._createSelect(btnDef);
 				else if (btnDef.type === "grid") el = this._createGridPicker(btnDef);
@@ -6329,6 +6364,24 @@ var Toolbar = class {
 	hide() {
 		if (this.el) this.el.style.display = "none";
 	}
+	/**
+	* Tears down and re-renders the toolbar in-place.
+	* Call after registering new buttons post-create via context.use(plugin)
+	* or AutumnNote.registerButton() to make them appear in the toolbar.
+	*/
+	rebuild() {
+		if (this._refreshRaf) {
+			cancelAnimationFrame(this._refreshRaf);
+			this._refreshRaf = null;
+		}
+		this._disposers.forEach((d) => d());
+		this._disposers = [];
+		if (this.el) this.el.innerHTML = "";
+		this._faReady = this._detectFontAwesome();
+		this._buildButtons();
+		this._btnMap = new Map((this.options.toolbar || []).flat().map(_resolveBtn).filter(Boolean).map((b) => [b.name, b]));
+		this.refresh();
+	}
 };
 //#endregion
 //#region src/js/module/Statusbar.js
@@ -15776,6 +15829,8 @@ var Mention = class {
 */
 /** Module registry shared across all Context instances (populated via AutumnNote.registerModule). */
 var _customModules = /* @__PURE__ */ new Map();
+/** Global plugin registry (populated via AutumnNote.use()). Applied to every new Context. */
+var _globalPlugins = /* @__PURE__ */ new Map();
 var Context = class {
 	/**
 	* @param {HTMLElement} targetEl - The element to replace with the editor
@@ -15792,6 +15847,8 @@ var Context = class {
 		this._listeners = /* @__PURE__ */ new Map();
 		/** @type {Map<string, object>} */
 		this._modules = /* @__PURE__ */ new Map();
+		/** @type {Map<string, { plugin: object, publicApi: * }>} */
+		this._plugins = /* @__PURE__ */ new Map();
 		this._disposers = [];
 		this._alive = false;
 	}
@@ -15814,6 +15871,7 @@ var Context = class {
 		if (this.options.focus) editable.focus();
 		this._alive = true;
 		this.invoke("toolbar.refresh");
+		this._applyGlobalPlugins();
 		if (typeof this.options.onInit === "function") this.options.onInit(this);
 		return this;
 	}
@@ -15865,6 +15923,46 @@ var Context = class {
 		this._modules.set(name, instance);
 		return this;
 	}
+	/**
+	* Installs a plugin on this editor instance.
+	* If called after create(), buttons are registered immediately but the toolbar
+	* must be rebuilt via ctx.invoke('toolbar.rebuild') to render new buttons.
+	* @param {object} plugin - { name, version?, buttons?, install?, uninstall? }
+	* @param {object} [options] - Forwarded to plugin.install(context, options)
+	* @returns {this}
+	*/
+	use(plugin, options = {}) {
+		if (Array.isArray(plugin.buttons)) plugin.buttons.forEach((b) => registerButton(b));
+		this._installPlugin(plugin, options);
+		return this;
+	}
+	/**
+	* Returns the public API returned by plugin.install(), or null.
+	* @param {string} name
+	* @returns {*}
+	*/
+	getPlugin(name) {
+		return this._plugins.get(name)?.publicApi ?? null;
+	}
+	_installPlugin(plugin, pluginOptions = {}) {
+		const { name } = plugin;
+		if (!name || typeof name !== "string") {
+			console.warn("[AutumnNote] Plugin must have a string `name` property.");
+			return;
+		}
+		if (this._plugins.has(name)) {
+			console.warn(`[AutumnNote] Plugin "${name}" already installed on this instance. Skipping.`);
+			return;
+		}
+		const publicApi = typeof plugin.install === "function" ? plugin.install(this, pluginOptions) ?? null : null;
+		this._plugins.set(name, {
+			plugin,
+			publicApi
+		});
+	}
+	_applyGlobalPlugins() {
+		for (const { plugin, options } of _globalPlugins.values()) this._installPlugin(plugin, options);
+	}
 	_bindEditorEvents(editable) {
 		const d0 = on(editable, "input", () => this._syncToTarget());
 		const d1 = on(editable, "focus", () => {
@@ -16115,6 +16213,10 @@ var Context = class {
 			if (typeof module.destroy === "function") module.destroy();
 		});
 		this._modules.clear();
+		for (const { plugin } of this._plugins.values()) if (typeof plugin.uninstall === "function") try {
+			plugin.uninstall(this);
+		} catch (_) {}
+		this._plugins.clear();
 		this._disposers.forEach((d) => d());
 		this._disposers = [];
 		const container = this.layoutInfo.container;
@@ -16301,7 +16403,27 @@ var AutumnNote = {
 	registerModule(name, ModuleClass) {
 		_customModules.set(name, ModuleClass);
 	},
-	version: "1.1.1"
+	use(plugin, options = {}) {
+		if (!plugin || typeof plugin.name !== "string") throw new TypeError("[AutumnNote] AutumnNote.use: plugin must have a string `name` property.");
+		if (_globalPlugins.has(plugin.name)) {
+			console.warn(`[AutumnNote] Plugin "${plugin.name}" already registered globally. Skipping.`);
+			return this;
+		}
+		if (Array.isArray(plugin.buttons)) plugin.buttons.forEach((b) => registerButton(b));
+		_globalPlugins.set(plugin.name, {
+			plugin,
+			options
+		});
+		return this;
+	},
+	hasPlugin(name) {
+		return _globalPlugins.has(name);
+	},
+	registerButton(btnDef) {
+		registerButton(btnDef);
+		return this;
+	},
+	version: "1.4.0"
 };
 /**
 * @param {string|Element|NodeList|Element[]} selector
@@ -16314,6 +16436,6 @@ function resolveElements(selector) {
 	return [];
 }
 //#endregion
-export { Context, ELEMENT_NODE, TEXT_NODE, WrappedRange, alignCenterBtn, alignJustifyBtn, alignLeftBtn, alignRightBtn, all, ancestors, any, backColorBtn, boldBtn, checklistBtn, children, chunk, clamp, closest, closestPara, codeviewBtn, collapsedRange, compose, createElement, currentRange, debounce, AutumnNote as default, defaultOptions, defaultToolbar, directionBtn, emojiBtn, env, findBtn, findReplaceBtn, first, flatten, fontFamilyBtn, fontSizeBtn, foreColorBtn, fromNativeRange, fullscreenBtn, groupBy, hrBtn, iconBtn, identity, imageBtn, indentBtn, initial, inlineCodeBtn, insertAfter, isAnchor, isEditable, isElement, isEmpty, isFunction, isImage, isInline, isInsideEditable, isKey, isLi, isList, isModifier, isNil, isPara, isPlainObject, isSelectionInside, isString, isTable, isText, isVoid, italicBtn, key, last, lineHeightBtn, linkBtn, locales, mergeDeep, nextElement, nodeValue, olBtn, on, outdentBtn, outerHtml, paragraphStyleBtn, placeCaret, prevElement, printBtn, rangeFromElement, rect2bnd, redoBtn, remove, removeFormatBtn, resolveLocale, sanitiseHTML, sanitiseUrl, shortcutsBtn, splitText, strikeBtn, subscriptBtn, superscriptBtn, tableBtn, tail, throttle, trapFocus, ulBtn, underlineBtn, undoBtn, unique, unwrap, videoBtn, withSavedRange, wrap };
+export { Context, ELEMENT_NODE, TEXT_NODE, WrappedRange, _buttonRegistry, alignCenterBtn, alignJustifyBtn, alignLeftBtn, alignRightBtn, all, ancestors, any, backColorBtn, boldBtn, checklistBtn, children, chunk, clamp, closest, closestPara, codeviewBtn, collapsedRange, compose, createElement, currentRange, debounce, AutumnNote as default, defaultOptions, defaultToolbar, directionBtn, emojiBtn, env, findBtn, findReplaceBtn, first, flatten, fontFamilyBtn, fontSizeBtn, foreColorBtn, fromNativeRange, fullscreenBtn, getButton, groupBy, hrBtn, iconBtn, identity, imageBtn, indentBtn, initial, inlineCodeBtn, insertAfter, isAnchor, isEditable, isElement, isEmpty, isFunction, isImage, isInline, isInsideEditable, isKey, isLi, isList, isModifier, isNil, isPara, isPlainObject, isSelectionInside, isString, isTable, isText, isVoid, italicBtn, key, last, lineHeightBtn, linkBtn, locales, mergeDeep, nextElement, nodeValue, olBtn, on, outdentBtn, outerHtml, paragraphStyleBtn, placeCaret, prevElement, printBtn, rangeFromElement, rect2bnd, redoBtn, registerButton, remove, removeFormatBtn, resolveLocale, sanitiseHTML, sanitiseUrl, shortcutsBtn, splitText, strikeBtn, subscriptBtn, superscriptBtn, tableBtn, tail, throttle, trapFocus, ulBtn, underlineBtn, undoBtn, unique, unwrap, videoBtn, withSavedRange, wrap };
 
 //# sourceMappingURL=autumnnote.es.js.map