@dojo-ng/rich-text 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @dojo-ng/rich-text
+
+`<dj-rich-text>` — A form-associated WYSIWYG editor built on the Lexical core.
+
+Part of [Dojo NG](../../README.md), a framework-agnostic web component library built on Lit. BSD-3-Clause.
+
+A form-associated WYSIWYG editor built on the Lexical core. The editable region renders in LIGHT DOM (Lexical's selection handling is not reliable inside a shadow root yet), so this component overrides `createRenderRoot`; theming still works because `--dj-*` tokens cascade in light DOM. The editor is a PLUGIN HOST: bold/italic/underline and undo/redo ship as the default plugin set (`default-plugins.ts`) and flow through the same {@link RichTextPlugin} API third-party plugins use. Foundational behavior (`registerRichText`, value sync, root-element setup) stays as core. Toolbar controls, node registration, and output formats all come from plugins. Constraint: Lexical needs node classes at creation, so a `plugins` change after creation rebuilds the editor (serialize → recreate → deserialize). Value is HTML by default; the `format` property selects an alternate serializer contributed by a plugin. Event: `dj-change`.
+
+> Pasted HTML is sanitized against an allowlist by default (scripts, styles, event handlers, inline styles, and unsafe `javascript:`/`data:` URLs are stripped; unknown tags are unwrapped, keeping their text) — a security and consistency hook, not a nicety. Set `sanitizePaste = false` in JS to turn it off, or supply your own `pasteSanitizer(html) => html`. Plain-text pastes bypass it. The exported `sanitizeHtml(html)` is the default and can be reused. Formatting, headings/lists/links, and other node types come from plugins; setting `plugins` replaces the default set, so spread `...defaultPlugins` to keep the basics.
+
+## Install
+
+```bash
+npm install @dojo-ng/rich-text
+```
+
+## Usage
+
+Import the package to register the custom element, then use the tag.
+
+Lexical-based; set and read `value` (HTML).
+
+```html
+<dj-rich-text id="rt" label="Description"></dj-rich-text>
+<script type="module">
+  import "@dojo-ng/rich-text";
+  document.getElementById("rt").value = "<p>Hello <strong>world</strong></p>";
+</script>
+```
+
+## Properties
+
+`↻` marks an attribute reflected to the DOM; a dash means the property is set in JavaScript only.
+
+| Property | Attribute | Type | Default |
+|---|---|---|---|
+| `value` | value | `string` | `""` |
+| `name` | name ↻ | `string` | — |
+| `label` | label | `string` | — |
+| `placeholder` | placeholder | `string` | `""` |
+| `disabled` | disabled ↻ | `boolean` | `false` |
+| `plugins` | — | `RichTextPlugin[]` | `[]` |
+| `format` | format ↻ | `string` | `"html"` |
+| `sanitizePaste` | — | `boolean` | `true` |
+| `pasteSanitizer` | — | `(html: string) => string` | — |
+
+**Events:** `dj-change`
+
+**Methods:** `checkValidity(): boolean`, `focus(o: FocusOptions)`, `setHtml(htmlString: string)` (Replace the document with the given HTML (regardless of the active `format`).)
+
+## Theming
+
+Styled with Dojo NG `--dj-*` design tokens and exposes `::part()` hooks for targeted overrides.
+
+## Accessibility and i18n
+
+Follows the project's WCAG 2.2 AA and localization conventions.
+
+## More
+
+Live, interactive examples are in the playground (`playground/index.html`). For the full API reference, theming, accessibility, and localization guides, see the [Dojo NG documentation](../../README.md).

package/dist/default-plugins.d.ts

@@ -0,0 +1,8 @@
+import { type RichTextPlugin } from "./plugin.js";
+/** Bold / italic / underline. Commands are handled by the component's core `registerRichText`; this
+ *  plugin only contributes toolbar controls and reflects active state. */
+export declare const formattingPlugin: RichTextPlugin;
+/** Undo / redo. `setup` installs Lexical's history listener and returns its disposer. */
+export declare const historyPlugin: RichTextPlugin;
+/** The default plugin set applied when the component's `plugins` property is left empty. */
+export declare const defaultPlugins: RichTextPlugin[];

package/dist/default-plugins.js

@@ -0,0 +1,54 @@
+import { html } from "lit";
+import { FORMAT_TEXT_COMMAND, UNDO_COMMAND, REDO_COMMAND, } from "lexical";
+import { registerHistory, createEmptyHistoryState } from "@lexical/history";
+import { defineRichTextPlugin } from "./plugin.js";
+/**
+ * Default plugin set for `<dj-rich-text>`: the bold/italic/underline formatting controls and the
+ * undo/redo history. These ship as plugins (not hard-coded into the component) so the basics flow
+ * through the same API third-party plugins use, and so a consumer can replace or omit them by
+ * passing their own `plugins` array. Foundational rich-text behavior (`registerRichText`, the
+ * value-sync listener, root-element setup) stays in the component as core, not as a plugin.
+ */
+const glyph = (text, style) => html `<span style=${style}>${text}</span>`;
+/** Bold / italic / underline. Commands are handled by the component's core `registerRichText`; this
+ *  plugin only contributes toolbar controls and reflects active state. */
+export const formattingPlugin = defineRichTextPlugin({
+    name: "formatting",
+    toolbar: [
+        {
+            id: "bold", group: "format", order: 1, label: "Bold",
+            icon: glyph("B", "font-weight:700"),
+            isActive: (ctx) => ctx.activeFormats().has("bold"),
+            run: (ctx) => ctx.command(FORMAT_TEXT_COMMAND, "bold"),
+        },
+        {
+            id: "italic", group: "format", order: 2, label: "Italic",
+            icon: glyph("I", "font-style:italic"),
+            isActive: (ctx) => ctx.activeFormats().has("italic"),
+            run: (ctx) => ctx.command(FORMAT_TEXT_COMMAND, "italic"),
+        },
+        {
+            id: "underline", group: "format", order: 3, label: "Underline",
+            icon: glyph("U", "text-decoration:underline"),
+            isActive: (ctx) => ctx.activeFormats().has("underline"),
+            run: (ctx) => ctx.command(FORMAT_TEXT_COMMAND, "underline"),
+        },
+    ],
+});
+/** Undo / redo. `setup` installs Lexical's history listener and returns its disposer. */
+export const historyPlugin = defineRichTextPlugin({
+    name: "history",
+    setup: (ctx) => registerHistory(ctx.editor, createEmptyHistoryState(), 1000),
+    toolbar: [
+        {
+            id: "undo", group: "history", order: 1, label: "Undo", icon: "↶",
+            run: (ctx) => ctx.command(UNDO_COMMAND, undefined),
+        },
+        {
+            id: "redo", group: "history", order: 2, label: "Redo", icon: "↷",
+            run: (ctx) => ctx.command(REDO_COMMAND, undefined),
+        },
+    ],
+});
+/** The default plugin set applied when the component's `plugins` property is left empty. */
+export const defaultPlugins = [formattingPlugin, historyPlugin];

package/dist/dj-rich-text.d.ts

@@ -0,0 +1,67 @@
+import { type TemplateResult } from "lit";
+import DojoElement, { DojoFormControl } from "@dojo-ng/dojo-element";
+import "@dojo-ng/button";
+import { type LexicalEditor } from "lexical";
+import { type RichTextPlugin } from "./plugin.js";
+declare const DjRichText_base: typeof DojoElement & (abstract new (...args: any[]) => import("@dojo-ng/dojo-element").FormControlMixinInterface);
+/**
+ * `<dj-rich-text>` — a form-associated WYSIWYG editor built on the Lexical core. The editable
+ * region renders in LIGHT DOM (Lexical's selection handling is not reliable inside a shadow root
+ * yet), so this component overrides `createRenderRoot`; theming still works because `--dj-*` tokens
+ * cascade in light DOM.
+ *
+ * The editor is a PLUGIN HOST: bold/italic/underline and undo/redo ship as the default plugin set
+ * (`default-plugins.ts`) and flow through the same {@link RichTextPlugin} API third-party plugins
+ * use. Foundational behavior (`registerRichText`, value sync, root-element setup) stays as core.
+ * Toolbar controls, node registration, and output formats all come from plugins.
+ *
+ * Constraint: Lexical needs node classes at creation, so a `plugins` change after creation rebuilds
+ * the editor (serialize → recreate → deserialize). Value is HTML by default; the `format` property
+ * selects an alternate serializer contributed by a plugin. Event: `dj-change`.
+ */
+export declare class DjRichText extends DjRichText_base implements Partial<DojoFormControl> {
+    #private;
+    static version: string;
+    static focusable: boolean;
+    static formAssociated: boolean;
+    protected createRenderRoot(): this;
+    private editable;
+    value: string;
+    name?: string;
+    label?: string;
+    placeholder: string;
+    disabled: boolean;
+    /** Plugin set. Set in JavaScript (rich data). The default set is used when this is empty. */
+    plugins: RichTextPlugin[];
+    /** Output format; selects which serializer the value getter/setter uses. `"html"` is built in. */
+    format: string;
+    /** Sanitize pasted HTML against an allowlist (on by default). Set in JS to disable. */
+    sanitizePaste: boolean;
+    /** Custom paste sanitizer `(html) => html`; defaults to the built-in allowlist `sanitizeHtml`. */
+    pasteSanitizer?: (html: string) => string;
+    /** Bumped on every selection change to re-render the toolbar's active state. */
+    private selVersion;
+    /** Becomes true once the editor is built; gates toolbar rendering so plugin toolbar items that
+     *  read the editor (block-type select, list state) never run before the editor exists. */
+    private ready;
+    constructor();
+    /** Read-only access to the live Lexical editor, so export code outside a plugin can reach it.
+     *  The editor is REPLACED when `plugins` changes (serialize → recreate → deserialize) — do not
+     *  cache the returned instance across a rebuild. `undefined` until the first update completes. */
+    get editor(): LexicalEditor | undefined;
+    get validity(): ValidityState;
+    checkValidity(): boolean;
+    focus(o?: FocusOptions): void;
+    formResetCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(c: Map<PropertyKey, unknown>): void;
+    /** Replace the document with the given HTML (regardless of the active `format`). */
+    setHtml(htmlString: string): void;
+    render(): TemplateResult<1>;
+}
+export default DjRichText;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        "dj-change": CustomEvent<Record<string, never>>;
+    }
+}

package/dist/dj-rich-text.js

@@ -0,0 +1,364 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _DjRichText_instances, _DjRichText_internals, _DjRichText_editor, _DjRichText_applyingValue, _DjRichText_built, _DjRichText_disposers, _DjRichText_active, _DjRichText_selectionSubs, _DjRichText_serializers, _DjRichText_plugins, _DjRichText_ctx, _DjRichText_resolvePlugins, _DjRichText_currentFormat, _DjRichText_buildEditor, _DjRichText_teardown, _DjRichText_serialize, _DjRichText_syncValue, _DjRichText_applyValue, _DjRichText_icon, _DjRichText_renderItem, _DjRichText_toolbarItems;
+import { html, nothing } from "lit";
+import { property, state, query } from "lit/decorators.js";
+import DojoElement, { FormControl } from "@dojo-ng/dojo-element";
+import "@dojo-ng/button";
+import { createEditor, $getRoot, $getSelection, $isRangeSelection, COMMAND_PRIORITY_HIGH, PASTE_COMMAND, } from "lexical";
+import { registerRichText } from "@lexical/rich-text";
+import { $generateHtmlFromNodes, $generateNodesFromDOM } from "@lexical/html";
+import { $insertGeneratedNodes } from "@lexical/clipboard";
+import { mergeRegister } from "@lexical/utils";
+import { defaultPlugins } from "./default-plugins.js";
+import { sanitizeHtml } from "./sanitize-html.js";
+/** Inline text formats inspected for toolbar active state. */
+const TEXT_FORMATS = [
+    "bold", "italic", "underline", "strikethrough", "code", "subscript", "superscript", "highlight",
+];
+/** Built-in HTML serializer. `serialize` runs inside an editor read; `deserialize` inside an update. */
+const HTML_FORMAT = {
+    serialize: (editor) => $generateHtmlFromNodes(editor, null),
+    deserialize: (editor, data) => {
+        const root = $getRoot();
+        root.clear();
+        const dom = new DOMParser().parseFromString(data || "<p></p>", "text/html");
+        for (const node of $generateNodesFromDOM(editor, dom))
+            root.append(node);
+    },
+};
+/**
+ * `<dj-rich-text>` — a form-associated WYSIWYG editor built on the Lexical core. The editable
+ * region renders in LIGHT DOM (Lexical's selection handling is not reliable inside a shadow root
+ * yet), so this component overrides `createRenderRoot`; theming still works because `--dj-*` tokens
+ * cascade in light DOM.
+ *
+ * The editor is a PLUGIN HOST: bold/italic/underline and undo/redo ship as the default plugin set
+ * (`default-plugins.ts`) and flow through the same {@link RichTextPlugin} API third-party plugins
+ * use. Foundational behavior (`registerRichText`, value sync, root-element setup) stays as core.
+ * Toolbar controls, node registration, and output formats all come from plugins.
+ *
+ * Constraint: Lexical needs node classes at creation, so a `plugins` change after creation rebuilds
+ * the editor (serialize → recreate → deserialize). Value is HTML by default; the `format` property
+ * selects an alternate serializer contributed by a plugin. Event: `dj-change`.
+ */
+export class DjRichText extends FormControl(DojoElement) {
+    // Light DOM: required for Lexical selection to work today.
+    createRenderRoot() { return this; }
+    constructor() {
+        super();
+        _DjRichText_instances.add(this);
+        _DjRichText_internals.set(this, void 0);
+        _DjRichText_editor.set(this, void 0);
+        _DjRichText_applyingValue.set(this, false);
+        _DjRichText_built.set(this, false);
+        _DjRichText_disposers.set(this, []);
+        _DjRichText_active.set(this, new Set());
+        _DjRichText_selectionSubs.set(this, new Set());
+        _DjRichText_serializers.set(this, { html: HTML_FORMAT });
+        _DjRichText_plugins.set(this, []);
+        _DjRichText_ctx.set(this, void 0);
+        this.value = "";
+        this.placeholder = "";
+        this.disabled = false;
+        /** Plugin set. Set in JavaScript (rich data). The default set is used when this is empty. */
+        this.plugins = [];
+        /** Output format; selects which serializer the value getter/setter uses. `"html"` is built in. */
+        this.format = "html";
+        /** Sanitize pasted HTML against an allowlist (on by default). Set in JS to disable. */
+        this.sanitizePaste = true;
+        /** Bumped on every selection change to re-render the toolbar's active state. */
+        this.selVersion = 0;
+        /** Becomes true once the editor is built; gates toolbar rendering so plugin toolbar items that
+         *  read the editor (block-type select, list state) never run before the editor exists. */
+        this.ready = false;
+        __classPrivateFieldSet(this, _DjRichText_internals, this.attachInternals(), "f");
+        // Stable context object — safe to read before the editor exists (activeFormats() is empty,
+        // command() is a no-op until then). `editor` is a live getter because rebuilds replace it.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias -- stable context object needs a captured host for its live `editor` getter
+        const host = this;
+        __classPrivateFieldSet(this, _DjRichText_ctx, {
+            get editor() { return __classPrivateFieldGet(host, _DjRichText_editor, "f"); },
+            host,
+            command(type, payload) {
+                __classPrivateFieldGet(host, _DjRichText_editor, "f")?.dispatchCommand(type, payload);
+                host.focus();
+            },
+            onSelectionChange(cb) {
+                __classPrivateFieldGet(host, _DjRichText_selectionSubs, "f").add(cb);
+                return () => __classPrivateFieldGet(host, _DjRichText_selectionSubs, "f").delete(cb);
+            },
+            activeFormats: () => __classPrivateFieldGet(host, _DjRichText_active, "f"),
+            get plugins() { return __classPrivateFieldGet(host, _DjRichText_plugins, "f"); },
+        }, "f");
+    }
+    /** Read-only access to the live Lexical editor, so export code outside a plugin can reach it.
+     *  The editor is REPLACED when `plugins` changes (serialize → recreate → deserialize) — do not
+     *  cache the returned instance across a rebuild. `undefined` until the first update completes. */
+    get editor() { return __classPrivateFieldGet(this, _DjRichText_editor, "f"); }
+    get validity() { return __classPrivateFieldGet(this, _DjRichText_internals, "f").validity; }
+    checkValidity() { return __classPrivateFieldGet(this, _DjRichText_internals, "f").checkValidity(); }
+    focus(o) { this.editable?.focus(o); }
+    formResetCallback() { __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_applyValue).call(this, this.getAttribute("value") ?? "", HTML_FORMAT); }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_teardown).call(this);
+        __classPrivateFieldSet(this, _DjRichText_built, false, "f");
+    }
+    updated(c) {
+        if (!__classPrivateFieldGet(this, _DjRichText_editor, "f")) {
+            __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_buildEditor).call(this);
+        }
+        else if (c.has("plugins") && c.get("plugins") !== undefined) {
+            // Genuine post-creation plugin change: rebuild around the new node set, preserving value.
+            this.value = __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_serialize).call(this);
+            __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_teardown).call(this);
+            __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_buildEditor).call(this);
+        }
+        if (c.has("disabled")) {
+            __classPrivateFieldGet(this, _DjRichText_editor, "f")?.setEditable(!this.isDisabled);
+            if (this.editable)
+                this.editable.contentEditable = this.isDisabled ? "false" : "true";
+        }
+        if (c.has("format") && !c.has("plugins") && __classPrivateFieldGet(this, _DjRichText_built, "f"))
+            __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_syncValue).call(this);
+    }
+    /** Replace the document with the given HTML (regardless of the active `format`). */
+    setHtml(htmlString) { __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_applyValue).call(this, htmlString, HTML_FORMAT); }
+    render() {
+        // Only build toolbar items once the editor exists — plugin items may read ctx.editor.
+        const items = this.ready && __classPrivateFieldGet(this, _DjRichText_editor, "f") ? __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_toolbarItems).call(this) : [];
+        let lastGroup;
+        const toolbar = items.map((item, idx) => {
+            const sep = idx > 0 && item.group !== lastGroup
+                ? html `<span class="dj-rt-sep" role="separator" aria-orientation="vertical"></span>`
+                : nothing;
+            lastGroup = item.group;
+            return html `${sep}${__classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_renderItem).call(this, item)}`;
+        });
+        return html `
+			<style>
+				dj-rich-text { display: block; font-family: var(--dj-font-family, inherit); }
+				dj-rich-text .dj-rt-toolbar { display: flex; align-items: center; gap: .15rem; padding: .25rem; border: 1px solid var(--dj-color-border, #d1d5db); border-bottom: none; border-radius: var(--dj-input-border-radius-medium, .25rem) var(--dj-input-border-radius-medium, .25rem) 0 0; background: var(--dj-color-neutral-50, #f9fafb); }
+				dj-rich-text .dj-rt-sep { align-self: stretch; width: 1px; margin: .15rem .25rem; background: var(--dj-color-border, #d1d5db); }
+				dj-rich-text .dj-rt-editable { min-height: 8rem; padding: var(--dj-spacing-small, .75rem); border: 1px solid var(--dj-color-border, #d1d5db); border-radius: 0 0 var(--dj-input-border-radius-medium, .25rem) var(--dj-input-border-radius-medium, .25rem); outline: none; background: var(--dj-color-background, #fff); color: var(--dj-color-text, #1f2937); }
+				dj-rich-text .dj-rt-editable:focus { border-color: var(--dj-color-primary-600, #2563eb); box-shadow: 0 0 0 1px var(--dj-color-primary-600, #2563eb); }
+				@media (forced-colors: active) { dj-rich-text .dj-rt-editable:focus { outline: 2px solid Highlight; outline-offset: -1px; } }
+				dj-rich-text[disabled] { opacity: .5; }
+				@media print {
+					dj-rich-text .dj-rt-toolbar { display: none; }
+					dj-rich-text .dj-rt-editable { border: none; min-height: 0; padding: 0; }
+				}
+			</style>
+			${this.label ? html `<label style="display:block;margin-bottom:.25rem;color:var(--dj-color-neutral-700,#374151)">${this.label}</label>` : ""}
+			<div class="dj-rt-toolbar" role="toolbar" aria-label="Formatting">${toolbar}</div>
+			<div class="dj-rt-editable" role="textbox" aria-multiline="true" aria-label=${this.label || "Rich text editor"} data-placeholder=${this.placeholder}></div>
+		`;
+    }
+}
+_DjRichText_internals = new WeakMap(), _DjRichText_editor = new WeakMap(), _DjRichText_applyingValue = new WeakMap(), _DjRichText_built = new WeakMap(), _DjRichText_disposers = new WeakMap(), _DjRichText_active = new WeakMap(), _DjRichText_selectionSubs = new WeakMap(), _DjRichText_serializers = new WeakMap(), _DjRichText_plugins = new WeakMap(), _DjRichText_ctx = new WeakMap(), _DjRichText_instances = new WeakSet(), _DjRichText_resolvePlugins = function _DjRichText_resolvePlugins() {
+    return this.plugins.length ? this.plugins : defaultPlugins;
+}, _DjRichText_currentFormat = function _DjRichText_currentFormat() {
+    return __classPrivateFieldGet(this, _DjRichText_serializers, "f")[this.format] ?? HTML_FORMAT;
+}, _DjRichText_buildEditor = function _DjRichText_buildEditor() {
+    const plugins = __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_resolvePlugins).call(this);
+    __classPrivateFieldSet(this, _DjRichText_plugins, plugins, "f"); // expose the resolved set via ctx.plugins (for the slash menu, etc.)
+    // Collect node classes contributed by plugins, de-duplicated. The core registers no nodes of
+    // its own: heading/quote/list nodes come from their plugins, so an editor only pays for what
+    // it loads (an editor without the headings plugin renders pasted headings as paragraphs).
+    const nodes = [...new Set(plugins.flatMap((p) => p.nodes ?? []))];
+    // Build the format-serializer registry from plugin-contributed formats.
+    __classPrivateFieldSet(this, _DjRichText_serializers, { html: HTML_FORMAT }, "f");
+    for (const p of plugins)
+        if (p.formats)
+            Object.assign(__classPrivateFieldGet(this, _DjRichText_serializers, "f"), p.formats);
+    // Merge plugin-contributed HTML import/export overrides (later plugins win on tag collisions).
+    // This is how the color plugin preserves inline color/background on `value` round-trips, which
+    // the default DOM import would otherwise strip.
+    const htmlImport = {};
+    const htmlExport = new Map();
+    for (const p of plugins) {
+        if (p.html?.import)
+            Object.assign(htmlImport, p.html.import);
+        if (p.html?.export)
+            for (const [k, v] of p.html.export)
+                htmlExport.set(k, v);
+    }
+    const editor = createEditor({
+        namespace: "dj-rich-text",
+        nodes,
+        onError: (e) => console.error("[dj-rich-text]", e),
+        html: { import: htmlImport, export: htmlExport },
+    });
+    __classPrivateFieldSet(this, _DjRichText_editor, editor, "f");
+    // Lexical's vanilla setRootElement does NOT make the element editable; we own that.
+    this.editable.contentEditable = this.isDisabled ? "false" : "true";
+    this.editable.spellcheck = true;
+    editor.setRootElement(this.editable);
+    editor.setEditable(!this.isDisabled);
+    __classPrivateFieldSet(this, _DjRichText_disposers, [
+        registerRichText(editor),
+        // Sanitize pasted HTML before Lexical's own paste handler runs (higher priority + return
+        // true stops it). Plain-text pastes (no text/html) fall through to the safe default.
+        editor.registerCommand(PASTE_COMMAND, (event) => {
+            if (!this.sanitizePaste)
+                return false;
+            const cd = event.clipboardData;
+            const raw = cd?.getData("text/html");
+            if (!raw)
+                return false; // no HTML → let the default handle text/plain
+            event.preventDefault();
+            const clean = (this.pasteSanitizer ?? sanitizeHtml)(raw);
+            editor.update(() => {
+                const sel = $getSelection();
+                if (!$isRangeSelection(sel))
+                    return;
+                const dom = new DOMParser().parseFromString(clean || "", "text/html");
+                const nodes = $generateNodesFromDOM(editor, dom);
+                // Route through Lexical's own clipboard-insert command (handled by registerRichText),
+                // not a bare `selection.insertNodes`: block/"shadow-root" nodes like tables are
+                // flattened to their text by the naive path in real browsers, but inserted intact by
+                // the command handler. Falls back to insertNodes when nothing consumes the command.
+                $insertGeneratedNodes(editor, nodes, sel);
+            });
+            return true;
+        }, COMMAND_PRIORITY_HIGH),
+        editor.registerUpdateListener(({ editorState }) => {
+            editorState.read(() => {
+                const sel = $getSelection();
+                __classPrivateFieldSet(this, _DjRichText_active, $isRangeSelection(sel)
+                    ? new Set(TEXT_FORMATS.filter((f) => sel.hasFormat(f)))
+                    : new Set(), "f");
+            });
+            this.selVersion++; // re-render toolbar active state
+            for (const cb of __classPrivateFieldGet(this, _DjRichText_selectionSubs, "f"))
+                cb();
+            if (__classPrivateFieldGet(this, _DjRichText_applyingValue, "f"))
+                return; // programmatic value set: don't echo back
+            __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_syncValue).call(this);
+        }),
+    ], "f");
+    // Run each plugin's setup and compose its disposer.
+    for (const p of plugins) {
+        const dispose = p.setup?.(__classPrivateFieldGet(this, _DjRichText_ctx, "f"));
+        if (dispose)
+            __classPrivateFieldGet(this, _DjRichText_disposers, "f").push(dispose);
+    }
+    __classPrivateFieldSet(this, _DjRichText_built, true, "f");
+    this.ready = true; // re-render so the toolbar shows now that ctx.editor is live
+    if (this.value)
+        __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_applyValue).call(this, this.value, __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_currentFormat).call(this));
+}, _DjRichText_teardown = function _DjRichText_teardown() {
+    mergeRegister(...__classPrivateFieldGet(this, _DjRichText_disposers, "f"))();
+    __classPrivateFieldSet(this, _DjRichText_disposers, [], "f");
+    __classPrivateFieldGet(this, _DjRichText_editor, "f")?.setRootElement(null);
+    __classPrivateFieldSet(this, _DjRichText_editor, undefined, "f");
+    this.ready = false;
+}, _DjRichText_serialize = function _DjRichText_serialize() {
+    const editor = __classPrivateFieldGet(this, _DjRichText_editor, "f");
+    if (!editor)
+        return this.value;
+    const fmt = __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_currentFormat).call(this);
+    return editor.getEditorState().read(() => fmt.serialize(editor));
+}, _DjRichText_syncValue = function _DjRichText_syncValue() {
+    const out = __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_serialize).call(this);
+    if (out !== this.value) {
+        this.value = out;
+        __classPrivateFieldGet(this, _DjRichText_internals, "f").setFormValue(out);
+        this.emit("dj-change");
+    }
+}, _DjRichText_applyValue = function _DjRichText_applyValue(data, fmt) {
+    const editor = __classPrivateFieldGet(this, _DjRichText_editor, "f");
+    if (!editor) {
+        this.value = data;
+        return;
+    }
+    __classPrivateFieldSet(this, _DjRichText_applyingValue, true, "f");
+    editor.update(() => fmt.deserialize(editor, data), {
+        onUpdate: () => { __classPrivateFieldSet(this, _DjRichText_applyingValue, false, "f"); },
+    });
+}, _DjRichText_icon = function _DjRichText_icon(icon) {
+    return icon === undefined ? nothing : typeof icon === "string" ? html `${icon}` : icon;
+}, _DjRichText_renderItem = function _DjRichText_renderItem(item) {
+    if (item.render)
+        return item.render(__classPrivateFieldGet(this, _DjRichText_ctx, "f"));
+    const pressed = item.isActive ? String(item.isActive(__classPrivateFieldGet(this, _DjRichText_ctx, "f"))) : nothing;
+    return html `<dj-button
+			kind="text"
+			aria-pressed=${pressed}
+			?disabled=${item.isDisabled ? item.isDisabled(__classPrivateFieldGet(this, _DjRichText_ctx, "f")) : false}
+			aria-label=${item.label}
+			@click=${() => item.run?.(__classPrivateFieldGet(this, _DjRichText_ctx, "f"))}
+		>${__classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_icon).call(this, item.icon)}</dj-button>`;
+}, _DjRichText_toolbarItems = function _DjRichText_toolbarItems() {
+    const items = [];
+    // Keep plugins in array order; sort only WITHIN each plugin by `order` (a stable sort, so
+    // items without an `order` keep their relative position). Sorting globally would interleave
+    // controls from different plugins.
+    for (const p of __classPrivateFieldGet(this, _DjRichText_instances, "m", _DjRichText_resolvePlugins).call(this)) {
+        const t = typeof p.toolbar === "function" ? p.toolbar(__classPrivateFieldGet(this, _DjRichText_ctx, "f")) : p.toolbar;
+        if (!t)
+            continue;
+        const sorted = t
+            .map((item, i) => ({ item, i }))
+            .sort((a, b) => (a.item.order ?? 0) - (b.item.order ?? 0) || a.i - b.i)
+            .map(({ item }) => item);
+        items.push(...sorted);
+    }
+    return items;
+};
+DjRichText.version = "0.1.0";
+DjRichText.focusable = true;
+DjRichText.formAssociated = true;
+__decorate([
+    query(".dj-rt-editable")
+], DjRichText.prototype, "editable", void 0);
+__decorate([
+    property()
+], DjRichText.prototype, "value", void 0);
+__decorate([
+    property({ reflect: true })
+], DjRichText.prototype, "name", void 0);
+__decorate([
+    property()
+], DjRichText.prototype, "label", void 0);
+__decorate([
+    property()
+], DjRichText.prototype, "placeholder", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], DjRichText.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], DjRichText.prototype, "plugins", void 0);
+__decorate([
+    property({ reflect: true })
+], DjRichText.prototype, "format", void 0);
+__decorate([
+    property({ attribute: false, type: Boolean })
+], DjRichText.prototype, "sanitizePaste", void 0);
+__decorate([
+    property({ attribute: false })
+], DjRichText.prototype, "pasteSanitizer", void 0);
+__decorate([
+    state()
+], DjRichText.prototype, "selVersion", void 0);
+__decorate([
+    state()
+], DjRichText.prototype, "ready", void 0);
+export default DjRichText;

package/dist/editor-styles.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Idempotent, document-level style injection for light-DOM rich-text plugins.
+ *
+ * The `dj-rich-text` component renders in the light DOM, so plugin content styles must live as global
+ * selectors (e.g. `dj-rich-text table { ... }`) in `document.head`. Plugins that add editable content
+ * (tables, checklists, mentions, embeds) call `ensureEditorStyles(id, css)` once during `setup`; the
+ * `id` guards against duplicate `<style>` elements when several editors mount.
+ */
+/**
+ * Append a `<style id={id}>` with the given CSS to `document.head`, unless an element with that id
+ * already exists. Safe to call repeatedly with the same id (a no-op after the first call). No-op when
+ * there is no `document` (e.g. a non-DOM environment).
+ */
+export declare function ensureEditorStyles(id: string, css: string): void;

package/dist/editor-styles.js

@@ -0,0 +1,23 @@
+/**
+ * Idempotent, document-level style injection for light-DOM rich-text plugins.
+ *
+ * The `dj-rich-text` component renders in the light DOM, so plugin content styles must live as global
+ * selectors (e.g. `dj-rich-text table { ... }`) in `document.head`. Plugins that add editable content
+ * (tables, checklists, mentions, embeds) call `ensureEditorStyles(id, css)` once during `setup`; the
+ * `id` guards against duplicate `<style>` elements when several editors mount.
+ */
+/**
+ * Append a `<style id={id}>` with the given CSS to `document.head`, unless an element with that id
+ * already exists. Safe to call repeatedly with the same id (a no-op after the first call). No-op when
+ * there is no `document` (e.g. a non-DOM environment).
+ */
+export function ensureEditorStyles(id, css) {
+    if (typeof document === "undefined" || !document.head)
+        return;
+    if (document.getElementById(id))
+        return;
+    const style = document.createElement("style");
+    style.id = id;
+    style.textContent = css;
+    document.head.appendChild(style);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { DjRichText } from "./dj-rich-text.js";
+export * from "./dj-rich-text.js";
+export * from "./plugin.js";
+export * from "./default-plugins.js";
+export { sanitizeHtml } from "./sanitize-html.js";
+export { ensureEditorStyles } from "./editor-styles.js";
+export default DjRichText;
+declare global {
+    interface HTMLElementTagNameMap {
+        "dj-rich-text": DjRichText;
+    }
+}

package/dist/index.js

@@ -0,0 +1,8 @@
+import { DjRichText } from "./dj-rich-text.js";
+export * from "./dj-rich-text.js";
+export * from "./plugin.js";
+export * from "./default-plugins.js";
+export { sanitizeHtml } from "./sanitize-html.js";
+export { ensureEditorStyles } from "./editor-styles.js";
+export default DjRichText;
+DjRichText.define("dj-rich-text", DjRichText);

package/dist/plugin.d.ts

@@ -0,0 +1,102 @@
+import type { LexicalCommand, LexicalEditor, LexicalNode, Klass, DOMConversionMap, DOMExportOutputMap } from "lexical";
+import type { TemplateResult } from "lit";
+/**
+ * Plugin API for `<dj-rich-text>`. A plugin is a plain object (or a factory returning one) that
+ * can contribute Lexical nodes, register commands/transforms/listeners, add toolbar controls, and
+ * supply alternate output formats. The component's own bold/italic/underline and undo/redo ship as
+ * the default plugin set (see `default-plugins.ts`), so even the basics flow through this API.
+ *
+ * KEY CONSTRAINT: Lexical needs its custom node classes at editor-creation time, so a plugin that
+ * contributes `nodes` must be declared before the editor is built. Changing the `plugins` property
+ * after creation rebuilds the editor (serialize → recreate → deserialize).
+ */
+/** What a plugin can see and do. Passed to `setup()` and to toolbar item callbacks. */
+export interface RichTextContext {
+    /** The live Lexical editor. */
+    readonly editor: LexicalEditor;
+    /** The `dj-rich-text` host element (focus, events, requestUpdate). */
+    readonly host: HTMLElement;
+    /** Dispatch a Lexical command, then return focus to the editor. */
+    command<P>(type: LexicalCommand<P>, payload: P): void;
+    /** Subscribe to selection/format changes; returns a disposer. Drives toolbar active state. */
+    onSelectionChange(cb: () => void): () => void;
+    /** The current selection's active inline formats (`bold`, `italic`, …). */
+    activeFormats(): ReadonlySet<string>;
+    /**
+     * The resolved plugin list the editor was built with (empty array before the editor is built).
+     * Used by aggregating plugins such as the slash menu to gather every loaded plugin's `inserts`.
+     */
+    readonly plugins: readonly RichTextPlugin[];
+}
+/**
+ * A block/insert action a plugin exposes to a command menu (the slash menu). Aggregated across all
+ * loaded plugins by `@dojo-ng/rich-text-slash`. When run, the menu has already removed the "/query"
+ * trigger text and the caret sits in that block. `run` executes within the removal `editor.update` so
+ * a block transform keeps the caret's selection (a separate update would lose it); a nested
+ * `editor.update`, a command dispatch, or opening a dialog all work from here.
+ */
+export interface RichTextInsertItem {
+    id: string;
+    label: string;
+    icon?: TemplateResult | string;
+    keywords?: string[];
+    run(ctx: RichTextContext): void;
+}
+/**
+ * A toolbar control contributed by a plugin. Either a simple command button (`run` + optional
+ * `icon`/`isActive`/`isDisabled`) or a fully custom control (`render`). `label` is the accessible
+ * name and is always required so plugins cannot regress accessibility.
+ */
+export interface RichTextToolbarItem {
+    id: string;
+    /** Controls grouping; a separator is rendered between items of differing groups. */
+    group?: string;
+    /** Sort order within the toolbar (ascending; ties keep insertion order). */
+    order?: number;
+    /** Accessible name (required). */
+    label: string;
+    icon?: TemplateResult | string;
+    /** Reflected as `aria-pressed`. Re-evaluated on selection change. */
+    isActive?(ctx: RichTextContext): boolean;
+    isDisabled?(ctx: RichTextContext): boolean;
+    run?(ctx: RichTextContext): void;
+    render?(ctx: RichTextContext): TemplateResult;
+}
+/**
+ * An alternate output format a plugin can add (for example Markdown). The component invokes
+ * `serialize` inside an editor read scope and `deserialize` inside an editor update scope, so
+ * implementations call the `$`-prefixed Lexical helpers directly without their own `read`/`update`.
+ */
+export interface RichTextFormat {
+    serialize(editor: LexicalEditor): string;
+    deserialize(editor: LexicalEditor, data: string): void;
+}
+export interface RichTextPlugin {
+    name: string;
+    /** Custom nodes this plugin needs. Registered at editor creation; see the rebuild note above. */
+    nodes?: Klass<LexicalNode>[];
+    /** Register commands, transforms, and listeners. Return a disposer (or compose with `mergeRegister`). */
+    setup?(ctx: RichTextContext): (() => void) | void;
+    /** Toolbar controls, static or derived from context. */
+    toolbar?: RichTextToolbarItem[] | ((ctx: RichTextContext) => RichTextToolbarItem[]);
+    /** Optional alternate output formats, keyed by name (for example `"markdown"`). */
+    formats?: Record<string, RichTextFormat>;
+    /**
+     * Block/insert actions this plugin exposes to a command menu (the slash menu). Static, or a
+     * function of context so a plugin can vary its offerings. Resolved once per menu open.
+     */
+    inserts?: RichTextInsertItem[] | ((ctx: RichTextContext) => RichTextInsertItem[]);
+    /**
+     * Optional HTML import/export overrides passed to `createEditor`'s `html` config. `import` is a
+     * `DOMConversionMap` merged across plugins (later plugins win on tag collisions); it lets a plugin
+     * preserve markup the default converters drop — for example the color plugin uses it to keep inline
+     * `color`/`background-color` on `value` round-trips (the default DOM import strips them). `export`
+     * is the matching `DOMExportOutputMap`.
+     */
+    html?: {
+        import?: DOMConversionMap;
+        export?: DOMExportOutputMap;
+    };
+}
+/** Identity helper for typing and authoring a plugin. */
+export declare const defineRichTextPlugin: (p: RichTextPlugin) => RichTextPlugin;

package/dist/plugin.js

@@ -0,0 +1,2 @@
+/** Identity helper for typing and authoring a plugin. */
+export const defineRichTextPlugin = (p) => p;

package/dist/sanitize-html.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Allowlist HTML sanitizer for pasted content. Security and consistency hook: strips anything not
+ * on the allowlist so pasted markup can't smuggle scripts, event handlers, inline styles, or unsafe
+ * URLs into the editor, and pastes land as clean structural/formatting HTML.
+ *
+ * It parses with `DOMParser` (which does NOT execute scripts), walks the tree, removes dangerous
+ * elements outright, unwraps other disallowed elements (keeping their text), strips every attribute
+ * not explicitly allowed for a tag, and drops unsafe `href`/`src` URLs. Returns clean HTML.
+ */
+/** Sanitize an HTML string to the allowlist and return clean HTML. */
+export declare function sanitizeHtml(input: string): string;

package/dist/sanitize-html.js

@@ -0,0 +1,75 @@
+/**
+ * Allowlist HTML sanitizer for pasted content. Security and consistency hook: strips anything not
+ * on the allowlist so pasted markup can't smuggle scripts, event handlers, inline styles, or unsafe
+ * URLs into the editor, and pastes land as clean structural/formatting HTML.
+ *
+ * It parses with `DOMParser` (which does NOT execute scripts), walks the tree, removes dangerous
+ * elements outright, unwraps other disallowed elements (keeping their text), strips every attribute
+ * not explicitly allowed for a tag, and drops unsafe `href`/`src` URLs. Returns clean HTML.
+ */
+/** Allowed elements → the attributes each may keep. Everything else is stripped. */
+const ALLOWED = {
+    a: ["href", "title", "target", "rel"],
+    p: [], br: [], hr: [],
+    h1: [], h2: [], h3: [], h4: [], h5: [], h6: [],
+    blockquote: [], pre: [], code: [],
+    ul: [], ol: ["start", "type"], li: [],
+    strong: [], b: [], em: [], i: [], u: [], s: [], strike: [], del: [], ins: [],
+    sub: [], sup: [], mark: [], span: [],
+    table: [], thead: [], tbody: [], tfoot: [], tr: [], caption: [],
+    th: ["colspan", "rowspan"], td: ["colspan", "rowspan"],
+};
+/** Elements removed entirely, content and all (never merely unwrapped). */
+const REMOVE = new Set([
+    "script", "style", "iframe", "object", "embed", "noscript", "template", "link", "meta", "base",
+    "head", "title", "form", "input", "button", "textarea", "select", "option", "svg", "math",
+    "audio", "video", "source", "track", "canvas", "applet", "frame", "frameset",
+]);
+/** True for URLs safe to keep: http(s)/mailto/tel, or relative/anchor. Any other scheme is rejected. */
+function safeUrl(url) {
+    const v = url.trim();
+    if (/^(https?:|mailto:|tel:)/i.test(v))
+        return true;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(v))
+        return false; // some other scheme (javascript:, data:, vbscript:, …)
+    return true; // relative path, query, or #anchor
+}
+function stripAttrs(el, allowed) {
+    for (const attr of Array.from(el.attributes)) {
+        const name = attr.name.toLowerCase();
+        if (!allowed.includes(name)) {
+            el.removeAttribute(attr.name);
+            continue;
+        }
+        if ((name === "href" || name === "src") && !safeUrl(attr.value)) {
+            el.removeAttribute(attr.name);
+        }
+    }
+}
+/** Depth-first: clean descendants, then keep-and-strip (allowed) or unwrap (disallowed) each child. */
+function sanitizeChildren(parent) {
+    for (const child of Array.from(parent.children)) {
+        const tag = child.tagName.toLowerCase();
+        if (REMOVE.has(tag)) {
+            child.remove();
+            continue;
+        }
+        sanitizeChildren(child); // clean the subtree first, so unwrapped children are already clean
+        const allowed = ALLOWED[tag];
+        if (allowed) {
+            stripAttrs(child, allowed);
+        }
+        else {
+            // Unwrap: promote the (already-cleaned) children in place of the disallowed element.
+            while (child.firstChild)
+                parent.insertBefore(child.firstChild, child);
+            child.remove();
+        }
+    }
+}
+/** Sanitize an HTML string to the allowlist and return clean HTML. */
+export function sanitizeHtml(input) {
+    const doc = new DOMParser().parseFromString(input ?? "", "text/html");
+    sanitizeChildren(doc.body);
+    return doc.body.innerHTML;
+}

package/package.json

@@ -0,0 +1,5 @@
+{ "name": "@dojo-ng/rich-text", "version": "0.1.0", "license": "BSD-3-Clause", "description": "Dojo NG rich-text (WYSIWYG) web component on Lexical", "type": "module",
+  "main": "./dist/index.js", "module": "./dist/index.js", "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json", "clean": "rm -rf dist" },
+  "dependencies": { "@dojo-ng/dojo-element": "^0.1.0", "@dojo-ng/button": "^0.1.0", "lexical": "^0.21.0", "@lexical/rich-text": "^0.21.0", "@lexical/history": "^0.21.0", "@lexical/html": "^0.21.0", "@lexical/clipboard": "^0.21.0", "@lexical/utils": "^0.21.0", "lit": "^3.3.0" } }