autumnnote 1.4.2 → 1.5.0

package/README.md

@@ -26,16 +26,17 @@ A modern WYSIWYG rich-text editor built with vanilla JavaScript (ES2022+) — no
 
 1. [Features](#features)
 2. [Installation](#installation)
-3. [Quick Start](#quick-start)
-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)
+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)
 
 ---
 
@@ -166,6 +167,66 @@ import 'autumnnote/dist/autumnnote.css';
 
 ---
 
+## Framework Wrappers
+
+Official React and Vue 3 wrappers are available as separate packages in this monorepo (managed with pnpm workspaces).
+
+### React
+
+```bash
+npm install autumnnote autumnnote-react
+import 'autumnnote/dist/autumnnote.css';
+```
+
+```jsx
+import { useRef } from 'react';
+import AutumnNoteEditor from 'autumnnote-react';
+
+function MyEditor() {
+  const editorRef = useRef(null);
+
+  return (
+    <AutumnNoteEditor
+      ref={editorRef}
+      options={{ placeholder: 'Start typing…', height: 300, bubbleToolbar: true }}
+    />
+  );
+}
+
+// Access the editor instance:
+editorRef.current.getHTML();
+editorRef.current.invoke('editor.setHTML', '<p>Hello!</p>');
+```
+
+The `ref` is forwarded to the underlying `Context` instance via `useImperativeHandle`. Pass a `key` prop to force remount when options change.
+
+### Vue 3
+
+```bash
+npm install autumnnote autumnnote-vue
+import 'autumnnote/dist/autumnnote.css';
+```
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import AutumnNoteEditor from 'autumnnote-vue';
+
+const editorRef = ref(null);
+</script>
+
+<template>
+  <AutumnNoteEditor
+    ref="editorRef"
+    :options="{ placeholder: 'Start typing…', height: 300 }"
+  />
+</template>
+```
+
+Access the editor instance via `editorRef.value.editor.value` (the `editor` reactive ref exposed by `defineExpose`).
+
+---
+
 ## Quick Start
 
 ### ES Module
@@ -641,16 +702,34 @@ src/
     └── autumnnote.scss       Main stylesheet
 ```
 
+### Monorepo structure
+
+This project uses **pnpm workspaces** to manage the core library alongside official framework wrappers:
+
+```
+autumn-note-ce/
+├── pnpm-workspace.yaml       # workspace root
+├── src/                      # core library source
+├── packages/
+│   ├── react/                # autumnnote-react
+│   │   └── src/index.jsx
+│   └── vue/                  # autumnnote-vue
+│       └── src/AutumnNote.vue
+└── test/                     # Vitest test suite
+```
+
 ### Development commands
 
 ```bash
-npm install          # install dependencies
-npm run dev          # start Vite dev server with HMR
-npm run build        # build ES + UMD + CSS to dist/
-npm test             # run Vitest test suite once
-npm run test:watch   # run tests in watch mode
-npm run lint         # ESLint
-npm run typecheck    # TypeScript type check (tsconfig.json)
+pnpm install                           # install all workspace packages
+npm run dev                            # start Vite dev server with HMR
+npm run build                          # build core ES + UMD + CSS to dist/
+pnpm --filter autumnnote-react build   # build React wrapper
+pnpm --filter autumnnote-vue build     # build Vue wrapper
+npm test                               # run Vitest test suite once
+npm run test:watch                     # run tests in watch mode
+npm run lint                           # ESLint
+npm run typecheck                      # TypeScript type check (tsconfig.json)
 ```
 
 Build output in `dist/`:

package/dist/autumnnote.es.js

@@ -1590,6 +1590,7 @@ var en = {
 		chooseHighlightColor: "Choose highlight color",
 		customColor: "Custom color",
 		insertTableLabel: "Insert Table",
+		/** Map of paragraph-style value → label (only values needing translation) */
 		paragraphItems: {
 			p: "Normal",
 			blockquote: "Quote",
@@ -1632,6 +1633,7 @@ var en = {
 		widthPlaceholder: "560",
 		insertBtn: "Insert",
 		cancelBtn: "Cancel",
+		/** @param {string} type */
 		detected: (type) => `Detected: ${type}`,
 		unknownFormat: "Unknown format — will try direct video embed",
 		invalidUrl: "Invalid URL — please enter a valid video link."
@@ -1794,9 +1796,13 @@ var en = {
 	},
 	statusbar: {
 		resizeHandle: "Resize editor",
+		/** @param {number} n */
 		words: (n) => `Words: ${n}`,
+		/** @param {number} n @param {number} max */
 		wordsLimit: (n, max) => `Words: ${n}/${max}`,
+		/** @param {number} n */
 		chars: (n) => `Chars: ${n}`,
+		/** @param {number} n @param {number} max */
 		charsLimit: (n, max) => `Chars: ${n}/${max}`
 	},
 	tooltips: {
@@ -1869,7 +1875,9 @@ var en = {
 		}
 	},
 	errors: {
+		/** @param {string} type */
 		imageFormat: (type) => `Format "${type}" is not supported for display in web browsers. Please convert to JPEG, PNG, or WebP first.`,
+		/** @param {number} maxSize */
 		imageSize: (maxSize) => `Image file is too large. Maximum allowed size is ${maxSize} MB.`
 	}
 };
@@ -16359,13 +16367,21 @@ function any(arr, predicate) {
 */
 var userAgent = navigator.userAgent;
 var env = {
+	/** True if browser is Chrome */
 	isChrome: /Chrome\//.test(userAgent),
+	/** True if browser is Firefox */
 	isFF: /Firefox\//.test(userAgent),
+	/** True if browser is Safari (not Chrome) */
 	isSafari: /^((?!chrome|android).)*safari/i.test(userAgent),
+	/** True if browser is Edge (Chromium) */
 	isEdge: /Edg\//.test(userAgent),
+	/** True if running on macOS */
 	isMac: /Macintosh/.test(userAgent),
+	/** True if running on mobile */
 	isMobile: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent),
+	/** True if touch is supported */
 	isTouch: "ontouchstart" in window || navigator.maxTouchPoints > 0,
+	/** Modifier key name depending on platform */
 	modifierKey: /Macintosh/.test(userAgent) ? "metaKey" : "ctrlKey"
 };
 //#endregion
@@ -16374,6 +16390,13 @@ var _originalDefaults = { ...defaultOptions };
 /** @type {WeakMap<Element, Context>} */
 var instances = /* @__PURE__ */ new WeakMap();
 var AutumnNote = {
+	/**
+	* Creates (or returns existing) editor instance on one or more elements.
+	*
+	* @param {string|Element|NodeList|Element[]} selector
+	* @param {import('./settings.js').AsnOptions} [options]
+	* @returns {Context|Context[]} single Context or array of Contexts
+	*/
 	create(selector, options = {}) {
 		const ctxs = resolveElements(selector).map((el) => {
 			if (instances.has(el)) return instances.get(el);
@@ -16384,6 +16407,10 @@ var AutumnNote = {
 		});
 		return ctxs.length === 1 ? ctxs[0] : ctxs;
 	},
+	/**
+	* Destroys the editor(s) on the given selector.
+	* @param {string|Element|NodeList|Element[]} selector
+	*/
 	destroy(selector) {
 		resolveElements(selector).forEach((el) => {
 			const ctx = instances.get(el);
@@ -16393,23 +16420,45 @@ var AutumnNote = {
 			}
 		});
 	},
+	/**
+	* Returns the Context instance for a given element (or null).
+	* @param {string|Element} selector
+	* @returns {Context|null}
+	*/
 	getInstance(selector) {
 		const el = typeof selector === "string" ? document.querySelector(selector) : selector;
 		return el ? instances.get(el) || null : null;
 	},
+	/** Returns a shallow copy of the default options (read-only snapshot). */
 	get defaults() {
 		return { ...defaultOptions };
 	},
+	/** Merges properties into the global defaults, applied to all future instances. */
 	setDefaults(overrides) {
 		Object.assign(defaultOptions, overrides);
 	},
+	/** Restores global defaults to their original factory values. */
 	resetDefaults() {
 		Object.keys(defaultOptions).forEach((k) => delete defaultOptions[k]);
 		Object.assign(defaultOptions, _originalDefaults);
 	},
+	/**
+	* Registers a custom module to be included in every new editor instance.
+	* @param {string} name - unique module key used for ctx.invoke() calls
+	* @param {Function} ModuleClass - class with initialize() and optional destroy()
+	*/
 	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)) {
@@ -16423,14 +16472,26 @@ var AutumnNote = {
 		});
 		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;
 	},
-	version: "1.4.2"
+	/** Library version */
+	version: "1.5.0"
 };
 /**
 * @param {string|Element|NodeList|Element[]} selector