autumnnote 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autumnnote",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A modern, lightweight WYSIWYG editor — built with vanilla JavaScript, no jQuery required.",
   "main": "dist/autumnnote.umd.js",
   "module": "dist/autumnnote.es.js",

package/src/js/Context.js

@@ -5,6 +5,7 @@
  */
 
 import { mergeDeep } from './core/func.js';
+import { registerButton } from './module/Buttons.js';
 import { defaultOptions } from './settings.js';
 import { resolveLocale } from './i18n/index.js';
 import { renderLayout } from './renderer.js';
@@ -42,6 +43,9 @@ import { Mention } from './module/Mention.js';
 /** Module registry shared across all Context instances (populated via AutumnNote.registerModule). */
 export const _customModules = new Map();
 
+/** Global plugin registry (populated via AutumnNote.use()). Applied to every new Context. */
+export const _globalPlugins = new Map();
+
 export class Context {
   /**
    * @param {HTMLElement} targetEl - The element to replace with the editor
@@ -63,6 +67,9 @@ export class Context {
     /** @type {Map<string, object>} */
     this._modules = new Map();
 
+    /** @type {Map<string, { plugin: object, publicApi: * }>} */
+    this._plugins = new Map();
+
     this._disposers = [];
     this._alive = false;
   }
@@ -106,6 +113,9 @@ export class Context {
     // Initial toolbar sync so dropdowns show the correct font on load
     this.invoke('toolbar.refresh');
 
+    // Apply plugins registered globally via AutumnNote.use()
+    this._applyGlobalPlugins();
+
     if (typeof this.options.onInit === 'function') {
       this.options.onInit(this);
     }
@@ -168,6 +178,53 @@ export class Context {
     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) {
     // Keep the original textarea/input value in sync immediately on every input.
     // This guarantees form.submit() sees fresh data even before debounced change.
@@ -487,6 +544,13 @@ export class Context {
     });
     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 = [];
 

package/src/js/index.js

@@ -10,7 +10,8 @@
  */
 
 import '../styles/autumnnote.scss';
-import { Context, _customModules } from './Context.js';
+import { Context, _customModules, _globalPlugins } from './Context.js';
+import { registerButton } from './module/Buttons.js';
 import { defaultOptions } from './settings.js';
 
 // Snapshot of factory defaults taken at module-load time (before any setDefaults() calls)
@@ -99,8 +100,47 @@ const AutumnNote = {
    */
   registerModule(name, ModuleClass) { _customModules.set(name, ModuleClass); },
 
+  /**
+   * Installs a plugin globally — applied to every future editor instance.
+   * Plugin `buttons` are registered to the global button registry immediately
+   * so they are available when Toolbar initialises inside create().
+   * Plugin `install()` is called after all built-in modules have initialised.
+   * @param {object} plugin - { name, version?, buttons?, install?, uninstall? }
+   * @param {object} [options] - Forwarded to plugin.install(context, options)
+   * @returns {typeof AutumnNote}
+   */
+  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;
+  },
+
+  /**
+   * Returns true if a plugin with the given name has been registered globally.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  hasPlugin(name) { return _globalPlugins.has(name); },
+
+  /**
+   * Registers a single button definition in the global button registry.
+   * After create(), call ctx.invoke('toolbar.rebuild') to render new buttons.
+   * @param {object} btnDef - ButtonDef-compatible object with a `name` string
+   * @returns {typeof AutumnNote}
+   */
+  registerButton(btnDef) { registerButton(btnDef); return this; },
+
   /** Library version */
-  version: '1.1.1',
+  version: '1.4.0',
 };
 
 // ---------------------------------------------------------------------------

package/src/js/module/Buttons.js

@@ -51,6 +51,43 @@ function btn(name, icon, tooltip, action, isActive, isDisabled) {
   return { name, icon, tooltip, action, isActive, isDisabled };
 }
 
+// ---------------------------------------------------------------------------
+// Global button registry
+// ---------------------------------------------------------------------------
+
+/**
+ * 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>}
+ */
+export const _buttonRegistry = 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.
+ */
+export 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}
+ */
+export function getButton(name) {
+  return _buttonRegistry.get(name);
+}
+
 // ---------------------------------------------------------------------------
 // Style buttons
 // ---------------------------------------------------------------------------

package/src/js/module/Toolbar.js

@@ -4,6 +4,10 @@
  */
 
 import { createElement, on } from '../core/dom.js';
+import { getButton } from './Buttons.js';
+
+/** Resolve a toolbar item: string → registry lookup, object → pass-through. */
+const _resolveBtn = (item) => (typeof item === 'string') ? getButton(item) : item;
 
 // Module-level cache for FontAwesome detection.
 // Evaluated once per page load so all Toolbar instances on the same page agree
@@ -129,7 +133,10 @@ export class Toolbar {
     // for every button rendered.
     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;
   }
 
@@ -155,7 +162,12 @@ export class Toolbar {
     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);
@@ -714,4 +726,23 @@ export class Toolbar {
   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();
+  }
 }

package/types/index.d.ts

@@ -21,7 +21,7 @@ export interface AsnOptions {
   /** Show the resize handle in the statusbar. */
   resizable?: boolean;
   /** Toolbar button group configuration. */
-  toolbar?: Array<Array<ToolbarItemDef>>;
+  toolbar?: Array<Array<ToolbarItemDef | string>>;
   /** Use Bootstrap button classes on toolbar buttons. */
   useBootstrap?: boolean;
   /** CSS class(es) applied to Bootstrap toolbar buttons. */
@@ -234,6 +234,31 @@ export interface DropdownDef {
 
 export type ToolbarItemDef = ButtonDef | DropdownDef | GridButtonDef | ColorPickerDef;
 
+// ---------------------------------------------------------------------------
+// Plugin API
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin descriptor passed to `AutumnNote.use()` or `context.use()`.
+ * `T` is the shape of the public API returned by `install()`, accessible
+ * via `context.getPlugin<T>(name)`.
+ */
+export interface AsnPlugin<T = unknown> {
+  /** Unique plugin identifier. */
+  name: string;
+  /** Semantic version string (informational only). */
+  version?: string;
+  /** Button definitions to register in the global button registry. */
+  buttons?: ToolbarItemDef[];
+  /**
+   * Called after all built-in modules have initialised.
+   * Return an object to expose it as the plugin's public API.
+   */
+  install?: (context: Context, options: Record<string, unknown>) => T | null | void;
+  /** Called when the editor instance is destroyed. */
+  uninstall?: (context: Context) => void;
+}
+
 // ---------------------------------------------------------------------------
 // Entry-point re-exports
 // ---------------------------------------------------------------------------
@@ -394,6 +419,18 @@ export declare class Context {
    */
   registerModule(name: string, ModuleClass: new (ctx: Context) => object): this;
 
+  /**
+   * Installs a plugin on this editor instance.
+   * If called after create(), call `ctx.invoke('toolbar.rebuild')` to render new buttons.
+   */
+  use<T = unknown>(plugin: AsnPlugin<T>, options?: Record<string, unknown>): this;
+
+  /**
+   * Returns the public API returned by `plugin.install()`, or null.
+   * Cast to your plugin's return type: `ctx.getPlugin<MyPluginApi>('my-plugin')`.
+   */
+  getPlugin<T = unknown>(name: string): T | null;
+
   /** Completely removes the editor and restores the original element. */
   destroy(): void;
 }
@@ -476,6 +513,22 @@ export interface AutumnNoteStatic {
    */
   registerModule(name: string, ModuleClass: new (ctx: Context) => object): void;
 
+  /**
+   * Installs a plugin globally — applied to every future editor instance.
+   * Plugin `buttons` are registered immediately so Toolbar can resolve them by name.
+   * Plugin `install()` is called after all built-in modules have initialised.
+   */
+  use<T = unknown>(plugin: AsnPlugin<T>, options?: Record<string, unknown>): this;
+
+  /** Returns true if a plugin with the given name has been registered globally. */
+  hasPlugin(name: string): boolean;
+
+  /**
+   * Registers a single button in the global button registry so it can be
+   * referenced by string name in toolbar configuration.
+   */
+  registerButton(btnDef: ToolbarItemDef): this;
+
   /** Library version string. */
   readonly version: string;
 }