@richscripts/richtexteditor 2.14.1 → 2.15.0

package/README.md

@@ -60,7 +60,7 @@ A full collaborative-document workspace, not just a textarea replacement:
 - **Smart link paste** *(2.2.4)* &mdash; pasting a URL or email while text is selected wraps the selection in `<a href>` instead of replacing it. Matches Google Docs / Notion / TipTap / ProseMirror behavior. Opt-out via `smartLinkPaste: false`.
 - **Mobile toolbar mode**, **classic toolbar customization**, **plugins**, **localization**, **image editing**, **PDF export**, **paste-from-Word fidelity**, **find & replace**, **autosave**, **draft recovery**.
 - **Configurable empty-editor placeholders** &mdash; set `placeholder`, `placeholderShowOnlyWhenEditable`, and `placeholderColor` to match the guided empty-state UX offered by current Tiptap and TinyMCE setups.
-- **TypeScript declarations** &mdash; 487-line `index.d.ts` with typed signatures for all 31 documented editor instance methods, the `RichTextEditorCommand` string-literal union (50+ built-in commands), event-handler signatures, and the `RichTextEditorConfig` interface.
+- **TypeScript declarations** &mdash; typed editor methods, commands, event handlers, plugin namespaces, and configuration interfaces, with strict integration compilation tests.
 
 The structured content bridge now returns a semantic document model while still carrying compatibility HTML and plain text:
 
@@ -214,6 +214,8 @@ Pass `file` to skip the built-in file picker, or use `mode: "insert"` to insert
 ## React
 
 ```jsx
+"use client"; // Required for your own state/callback wrapper in Next.js App Router.
+
 import { useState } from "react";
 import { RichTextEditorReact } from "@richscripts/richtexteditor/react";
 
@@ -231,6 +233,18 @@ export default function EditorPage() {
 }
 ```
 
+The `/react` ESM entry declares its own client boundary. A Next.js App Router
+Server Component may render `<RichTextEditorReact value="<p>Hello</p>" />` with
+serializable props. Put `useState`, `onChange`, refs and function-valued editor
+configuration in your own `"use client"` wrapper, as above; do not pass ordinary
+callbacks across the server/client boundary. Copy the runtime to `public/richtexteditor`
+as in the installation steps. Server-side HTML/Markdown conversion belongs in
+`@richscripts/richtexteditor/server`, not in the React client entry.
+
+CommonJS `require("@richscripts/richtexteditor/react")` remains available with
+the same named API. No `ssr: false` workaround is needed just to render the wrapper;
+the browser-only editor is created after the component mounts.
+
 ## Vue
 
 ```js
@@ -268,7 +282,9 @@ const app = createApp({
 
 ## Angular
 
-Angular apps can now use the packaged standalone wrapper component:
+Angular 20.3+ apps can use the packaged standalone wrapper component. The public
+entry point is precompiled partial-Ivy ESM, with generated Angular component
+metadata; consumers do not need to compile the wrapper's TypeScript source:
 
 ```ts
 import { Component } from "@angular/core";
@@ -308,8 +324,57 @@ export class AppComponent {
 
 The Angular wrapper exposes the same JSON bridge and convenience instance methods as the React and Vue wrappers: `focus()`, `getEditor()`, `getHTMLCode()`, `getJSON()`, `setHTMLCode()`, `setJSON()`, and plugin accessors such as `getAiToolkit()` / `getCollab()` / `getComments()`.
 
+When asset loading fails, show the `(error)` message and offer an explicit retry:
+`await editorComponent.retry()`. It retries a failed initialization while keeping
+the current bound form value. It does not replace an editor that is already ready,
+start a second concurrent load, or revive a destroyed component. Fix missing asset
+paths/CSP permissions before retrying. Asset autoload waits for theme CSS as well
+as core/plugins; failed script or stylesheet requests can be retried without
+refreshing the whole page. Manually preloaded (`autoload=false`) assets remain
+your application's responsibility.
+
 The repo also includes a full Angular starter in `Demos/rte-ng-ts/` that uses the same wrapper pattern.
 
+For maintainers: `npm run build:angular` regenerates the ESM entry point,
+declarations and source/output hash manifest. `npm pack` runs this step through
+`prepack`; the build needs the declared Angular/compiler/TypeScript/esbuild dev
+dependencies (or the installed Angular demo toolchain in a repository checkout).
+The normal test suite rejects stale generated files. Angular dependencies are
+optional peers and are not required by React/Vue/server-only consumers.
+
+### Angular forms
+
+The wrapper implements `ControlValueAccessor`: import `FormsModule` for
+`[(ngModel)]="body"`, or `ReactiveFormsModule` for `[formControl]="bodyControl"`
+and `formControlName`. These modules come from `@angular/forms`; use matching
+Angular core/forms versions. Angular peers are optional for React/Vue users.
+
+```ts
+import { FormControl, ReactiveFormsModule } from "@angular/forms";
+// Add ReactiveFormsModule and RichTextEditorAngularComponent to your imports.
+bodyControl = new FormControl("<p>Hello</p>", {
+  nonNullable: true,
+  updateOn: "blur"
+});
+```
+
+```html
+<rich-text-editor [formControl]="bodyControl"
+  [assetBasePath]="'/assets/richtexteditor'" />
+```
+
+HTML is the default; use `valueFormat="json"` for structured document values.
+External writes do not echo as user changes, null resets clear the editor,
+and `disable()` / `enable()` update read-only state. Pending edits are flushed
+before blur so `updateOn: "blur"` receives the final character. The default
+120 ms change coalescing also applies to form changes; set `[changeDelay]="0"`
+for the shortest quiet period. Do not combine `[value]` with a form binding.
+An explicit `config.readOnly: true` remains read-only after `enable()`.
+
+Use a content-aware required validator: `Validators.required` on the HTML
+string alone accepts empty markup such as `<p><br></p>`. Check outstanding image
+uploads before saving; valid form state is not an upload-completion guarantee.
+
 ## Svelte
 
 `@richscripts/richtexteditor/svelte` ships a plain Svelte **action** &mdash; no compiler coupling,
@@ -324,10 +389,12 @@ controller, leaving the toolbar markup entirely to you.
   let state = {};    // active formats, refreshed as the caret moves
 </script>
 
-<button class:is-active={state.bold}
-        on:mousedown|preventDefault={() => editor.run("bold")}>B</button>
-<button disabled={!state.canUndo}
-        on:mousedown|preventDefault={() => editor.run("undo")}>Undo</button>
+<button disabled={!editor} aria-pressed={!!state.bold} class:is-active={state.bold}
+        on:mousedown|preventDefault={() => {}}
+        on:click={() => editor.run("bold")}>Bold</button>
+<button disabled={!editor || !state.canUndo}
+        on:mousedown|preventDefault={() => {}}
+        on:click={() => editor.run("undo")}>Undo</button>
 
 <div use:richTextEditor={{
        value: "<p>Hello</p>",
@@ -336,12 +403,48 @@ controller, leaving the toolbar markup entirely to you.
      }}></div>
 ```
 
-Use `on:mousedown|preventDefault` on toolbar buttons so the click never steals the caret. Changing
+Prevent the pointer's default mousedown focus change to keep the caret, but run commands
+from `click` so keyboard activation works too. Changing
 the `value` you pass in pushes new content into the editor, so a store can own the document, and
 the action calls `destroy()` for you when the node unmounts. In SvelteKit this is client-only
 code &mdash; keep it in a component that renders in the browser.
 
-Options: `value`, `config`, `assetBasePath`, `onReady`, `onUpdate`, `onChange`, `onError`.
+Options: `value`, `config`, `assetBasePath`, `signal`, `onReady`, `onUpdate`, `onChange`, `onError`.
+
+Updating the action's options replaces callbacks without remounting. Only a
+changed bound `value` replaces the document; an unrelated callback/state update
+does not overwrite typing. Unmounting during asset loading disposes any late
+controller and does not emit ready/error callbacks into a destroyed view.
+
+For Svelte 5 runes, use reactive controller/state variables and the modern event syntax:
+
+```svelte
+<script>
+  import { richTextEditor } from "@richscripts/richtexteditor/svelte";
+  let editor = $state(null);
+  let state = $state({});
+  let html = $state("<p>Hello</p>");
+</script>
+
+<button disabled={!editor} aria-pressed={!!state.bold}
+        onmousedown={event => event.preventDefault()}
+        onclick={() => editor.run("bold")}>Bold</button>
+<div use:richTextEditor={{
+  value: html,
+  onReady: controller => { editor = controller; },
+  onUpdate: next => { state = next; },
+  onChange: function () { html = this.getHTML(); }
+}}></div>
+<textarea aria-label="HTML output" readonly value={html}></textarea>
+```
+
+`onChange` runs with the controller as `this`. On unmount it can synchronously
+deliver a final native edit before the core's deferred change event. Read/save the
+value inside that callback; do not clear your controller reference first. A
+programmatic bound-value update is not emitted again as a final user edit.
+Toolbar controls should have visible names, `aria-pressed` for toggle state and
+disabled state until ready. This is a keyboard-usable starting point, not a
+complete accessibility certification for a custom toolbar.
 
 ## Web component
 
@@ -349,8 +452,12 @@ For pages that use none of the framework bindings above &mdash; Rails, Laravel,
 htmx, plain HTML.
 
 ```html
+<link rel="stylesheet" href="richtexteditor/rte_theme_default.min.css">
+<link rel="stylesheet" href="richtexteditor/rte_mobile.min.css">
 <script src="richtexteditor/rte-config.js"></script>
 <script src="richtexteditor/rte.js"></script>
+<!-- Optional plugins for the full toolbar. Omit unused plugins in a modular build. -->
+<script src="richtexteditor/plugins/all_plugins.min.js"></script>
 <script src="richtexteditor/rte-webcomponent.js"></script>
 
 <form method="post">
@@ -359,8 +466,41 @@ htmx, plain HTML.
 </form>
 ```
 
-That form posts `body=...` with no glue code. The element is form-associated, so `form.reset()`,
-`required` and `form.elements.body` behave the way they do for a `<textarea>`.
+Serve the page and runtime from your local HTTP server, not `file://`. That form
+posts `body=...` with no value-copying glue in browsers supporting form-associated
+custom elements. `required` and `form.elements.body` use `ElementInternals`;
+older-browser hidden-input fallback supports submission, not full native validation.
+Always validate and sanitize the submitted HTML on your server.
+
+React and Vue components commit the latest native input on editor blur, even if
+their normal change callback is coalesced or the core change event is still pending.
+This makes an ordinary editor-to-Save-button interaction safer, but it is not an
+upload-completion or persistence guarantee. For programmatic saves, read fresh
+HTML through the editor ref in the save/submit handler and wait for your image
+upload adapter's pending requests first. A `form.submit()` call skips native
+validation and submit listeners; use `requestSubmit()` when you need that workflow.
+React can still batch a parent state update when code forces focus and clicks Save
+inside one synchronous function. Use the editor ref for that same-turn programmatic
+snapshot; a captured value from the previous parent render is not a fresh document.
+
+The `value` attribute is the default document; alternatively put initial HTML
+between the tags. `form.reset()` restores that initial document. Set the `.value`
+property for application updates, and await readiness before calling editor APIs:
+
+```js
+const field = document.querySelector("rich-text-editor");
+field.value = "<p>Application content</p>"; // also works before first connection
+await field.ready;
+console.log(field.value); // current HTML, not the original value attribute
+const payload = new FormData(field.form); // name="body" participates automatically
+```
+
+`disabled` (including an enclosing disabled `<fieldset>`) disables editing and
+excludes the value from form submission. `readonly` prevents editing but keeps
+the submitted value. Rich-text emptiness ignores whitespace/entities and blank
+paragraphs; images and other media count as content. These client checks are not
+upload validation. Use the image-handling guide for a persistent upload backend
+and wait for pending uploads before saving a document.
 
 Attributes: `value`, `name`, `toolbar`, `height`, `width`, `readonly`, `disabled`, `required`,
 `shadow`, `config` (JSON). Properties: `.value`, `.editor`, `.ready` (a Promise). Events: `input`,
@@ -395,6 +535,29 @@ Block-level formats go through `run("formatblock", "h1")` rather than `run("h1")
 from `/richtexteditor` unless you pass `assetBasePath`; pass `autoload: false` if the page already
 loads them.
 
+Initialization supports `signal: AbortSignal`. Cancel an abandoned view while
+assets load without cancelling other editors that share the same asset request:
+
+```js
+const pending = new AbortController();
+const initialization = createHeadlessEditor("#host", { signal: pending.signal });
+// If the view closes before initialization settles: pending.abort();
+const controller = await initialization;
+// Once mounted, explicitly call controller.destroy() when the view closes.
+```
+
+Cancellation rejects with the signal's reason (`AbortError` by default). It
+does not destroy an already mounted editor. The React/Vue headless bindings and
+Svelte action wire their own pending-initialization cancellation on unmount.
+React headless bindings use the latest `value` and callbacks. For Vue, pass a
+reactive options object if the value should follow application state:
+
+```js
+const options = reactive({ value: "<p>Initial</p>" }); // import reactive from vue
+const { mountRef, editor, state } = useRichTextEditor(options);
+options.value = "<p>Loaded from the application</p>";
+```
+
 ## Classic usage
 
 ```html

package/angular/build-manifest.json

@@ -0,0 +1,23 @@
+{
+  "angularCompiler": "20.3.31",
+  "typescript": "5.9.3",
+  "esbuild": "0.28.1",
+  "sources": {
+    "angular/component.ts": "c20f6c003689c8b931b55fd08232d4da56ca7ab95257bfe82edd2a42b34829f8",
+    "angular/index.ts": "e20427ea679cdac2f9103663089d60b59cc6739d973c3c9d2983b3b9be07a6f5",
+    "integrations/shared.js": "df288497a07fd2f5652fccaf33299ba2d5c6468af7453d801f56013451875f11",
+    "integrations/shared.d.ts": "66e7f7e60f31f4896e902ae562b68e56250ec3bd58ae851027ff77c27e1daf04",
+    "index.d.ts": "87ede19a371082213cda51db0dfc99621f83480f215776f99cf0a9d8619cd503",
+    "scripts/build-angular.mjs": "3e087b5d7f297299ff9d729b4e47c888a11b4e5a72f45f39852a1721159d4313"
+  },
+  "outputs": {
+    "angular/index.mjs": {
+      "bytes": 124323,
+      "sha256": "75093e8ff2410a07cb5a7cb43a20274cd06eada4f7d404a3526f2369fa7ec925"
+    },
+    "angular/index.d.ts": {
+      "bytes": 5009,
+      "sha256": "f533d2ac09f202326cfe3cc256489f0b345c1daba5f4c8ab6e05558f1056a90a"
+    }
+  }
+}

package/angular/index.d.ts

@@ -1,80 +1,75 @@
-import type {
-  RichTextEditorAccessibilityResult,
-  RichTextEditorAiToolkit,
-  RichTextEditorCollab,
-  RichTextEditorComments,
-  RichTextEditorDictation,
-  RichTextEditorDocumentMetrics,
-  RichTextEditorDocumentOutlineItem,
-  RichTextEditorFootnoteItem,
-  RichTextEditorInstance,
-  RichTextEditorMentions,
-  RichTextEditorPageSetup,
-  RichTextEditorReviewLedger,
-  RichTextEditorRevisionHistory,
-  RichTextEditorSlashCommands,
-  RichTextEditorStructuredDocument,
-  RichTextEditorStructuredInput,
-  RichTextEditorTableOfContentsItem,
-  RichTextEditorTableOfContentsOptions,
-  RichTextEditorTextStatistics,
-  RichTextEditorValueFormat
-} from "../index";
-
+import { AfterViewInit, ElementRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from "@angular/core";
+import { type ControlValueAccessor } from "@angular/forms";
+import type { RichTextEditorAccessibilityResult, RichTextEditorAiToolkit, RichTextEditorCollab, RichTextEditorComments, RichTextEditorDictation, RichTextEditorDocumentMetrics, RichTextEditorDocumentOutlineItem, RichTextEditorFootnoteItem, RichTextEditorInstance, RichTextEditorMentions, RichTextEditorPageSetup, RichTextEditorReviewLedger, RichTextEditorRevisionHistory, RichTextEditorSlashCommands, RichTextEditorStructuredDocument, RichTextEditorStructuredInput, RichTextEditorTableOfContentsItem, RichTextEditorTableOfContentsOptions, RichTextEditorTextStatistics, RichTextEditorValueFormat } from "../index";
+import * as i0 from "@angular/core";
 export interface RichTextEditorAngularChangeEvent {
-  editor: RichTextEditorInstance;
-  value: string | RichTextEditorStructuredDocument;
+    editor: RichTextEditorInstance;
+    value: string | RichTextEditorStructuredDocument;
 }
-
-export declare class RichTextEditorAngularComponent {
-  assetBasePath: string;
-  autoload: boolean;
-  config: Record<string, unknown>;
-  value?: RichTextEditorStructuredInput;
-  valueFormat: RichTextEditorValueFormat;
-
-  focus(): void;
-  getEditor(): RichTextEditorInstance | null;
-  getHTMLCode(): string;
-  setHTMLCode(value: string): void;
-  getJSON(): RichTextEditorStructuredDocument | null;
-  setJSON(value: RichTextEditorStructuredInput): void;
-  getTextStatistics(): RichTextEditorTextStatistics | null;
-  getSelectionStatistics(): RichTextEditorTextStatistics | null;
-  getDocumentMetrics(): RichTextEditorDocumentMetrics | null;
-  getDocumentPageSetup(): RichTextEditorPageSetup | null;
-  setDocumentPageSetup(pageSetup: RichTextEditorPageSetup | null): RichTextEditorAngularComponent | null;
-  getDocumentOutline(): RichTextEditorDocumentOutlineItem[];
-  getFootnotes(): RichTextEditorFootnoteItem[];
-  getTableOfContents(options?: RichTextEditorTableOfContentsOptions): RichTextEditorTableOfContentsItem[];
-  syncTableOfContents(options?: RichTextEditorTableOfContentsOptions): RichTextEditorStructuredDocument | null;
-  auditAccessibility(): RichTextEditorAccessibilityResult | null;
-
-  getAiToolkit(): RichTextEditorAiToolkit | null | undefined;
-  getDictation(): RichTextEditorDictation | null | undefined;
-  getRevisionHistory(): RichTextEditorRevisionHistory | null | undefined;
-  getCollab(): RichTextEditorCollab | null | undefined;
-  getSlashCommands(): RichTextEditorSlashCommands | null | undefined;
-  getMentions(): RichTextEditorMentions | null | undefined;
-  getComments(): RichTextEditorComments | null | undefined;
-  getReviewLedger(): RichTextEditorReviewLedger | null | undefined;
+export declare class RichTextEditorAngularComponent implements AfterViewInit, OnChanges, OnDestroy, ControlValueAccessor {
+    assetBasePath: string;
+    autoload: boolean;
+    config: Record<string, unknown>;
+    value?: RichTextEditorStructuredInput;
+    valueFormat: RichTextEditorValueFormat;
+    changeDelay: number;
+    disabled: boolean;
+    change: EventEmitter<RichTextEditorAngularChangeEvent>;
+    error: EventEmitter<Error>;
+    ready: EventEmitter<RichTextEditorInstance>;
+    hostRef: ElementRef<HTMLDivElement>;
+    private changeHandler;
+    private emitChange;
+    private lastEmitted;
+    private editor;
+    private destroyed;
+    private initializing;
+    private writingValue;
+    private lastKnownHtml;
+    private blurHandler;
+    private onModelChange;
+    private onModelTouched;
+    ngAfterViewInit(): Promise<void>;
+    /** Retry a failed initial load; never replace a ready or destroyed instance. */
+    retry(): Promise<void>;
+    ngOnChanges(changes: SimpleChanges): void;
+    writeValue(value: RichTextEditorStructuredInput | null | undefined): void;
+    registerOnChange(fn: (value: string | RichTextEditorStructuredDocument) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(disabled: boolean): void;
+    private applyDisabledState;
+    private emitCurrentValue;
+    ngOnDestroy(): void;
+    private releaseEditor;
+    focus(): void;
+    getEditor(): RichTextEditorInstance | null;
+    getHTMLCode(): string;
+    setHTMLCode(value: string): void;
+    getJSON(): RichTextEditorStructuredDocument | null;
+    setJSON(value: RichTextEditorStructuredInput): void;
+    getTextStatistics(): RichTextEditorTextStatistics | null;
+    getSelectionStatistics(): RichTextEditorTextStatistics | null;
+    getDocumentMetrics(): RichTextEditorDocumentMetrics | null;
+    getDocumentPageSetup(): RichTextEditorPageSetup | null;
+    setDocumentPageSetup(pageSetup: RichTextEditorPageSetup | null): RichTextEditorAngularComponent | null;
+    getDocumentOutline(): RichTextEditorDocumentOutlineItem[];
+    getFootnotes(): RichTextEditorFootnoteItem[];
+    getTableOfContents(options?: RichTextEditorTableOfContentsOptions): RichTextEditorTableOfContentsItem[];
+    syncTableOfContents(options?: RichTextEditorTableOfContentsOptions): RichTextEditorStructuredDocument | null;
+    auditAccessibility(): RichTextEditorAccessibilityResult | null;
+    getAiToolkit(): RichTextEditorAiToolkit | null | undefined;
+    getDictation(): RichTextEditorDictation | null | undefined;
+    getRevisionHistory(): RichTextEditorRevisionHistory | null | undefined;
+    getCollab(): RichTextEditorCollab | null | undefined;
+    getSlashCommands(): RichTextEditorSlashCommands | null | undefined;
+    getMentions(): RichTextEditorMentions | null | undefined;
+    getComments(): RichTextEditorComments | null | undefined;
+    getReviewLedger(): RichTextEditorReviewLedger | null | undefined;
+    private getPluginNamespace;
+    private syncEditor;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RichTextEditorAngularComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RichTextEditorAngularComponent, "rich-text-editor", never, { "assetBasePath": { "alias": "assetBasePath"; "required": false; }; "autoload": { "alias": "autoload"; "required": false; }; "config": { "alias": "config"; "required": false; }; "value": { "alias": "value"; "required": false; }; "valueFormat": { "alias": "valueFormat"; "required": false; }; "changeDelay": { "alias": "changeDelay"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, { "change": "change"; "error": "error"; "ready": "ready"; }, never, never, true, never>;
 }
 
-export {
-  auditAccessibility,
-  createStructuredContent,
-  createStructuredDocument,
-  fromMarkdown,
-  getDocumentPageSetup,
-  getDocumentMetrics,
-  getDocumentOutline,
-  getFootnotes,
-  getTableOfContents,
-  getTextStatistics,
-  loadRichTextEditorAssets,
-  renderHTML,
-  setDocumentPageSetup,
-  syncTableOfContents,
-  toMarkdown,
-  validateStructuredContent
-} from "../integrations/shared";
+
+export { auditAccessibility, auditLinks, createStructuredContent, createStructuredDocument, fromMarkdown, getDocumentPageSetup, getDocumentMetrics, getDocumentOutline, getFootnotes, getTableOfContents, getTextStatistics, loadRichTextEditorAssets, renderHTML, setDocumentPageSetup, syncTableOfContents, toMarkdown, validateStructuredContent } from "../integrations/shared";