@rathkit/rte-element 0.0.0 → 0.1.0-alpha.3

package/README.md

@@ -1,11 +1,36 @@
 # @rathkit/rte-element
 
-This version is an empty placeholder. It holds no code.
+> **Alpha** (0.1.0-alpha.0). Not for production: the APIs will change between releases. Published to the `next` tag only.
 
-@rathkit/rte-element is in alpha. Install the alpha with the `next` tag:
+The editor as custom elements, `<rk-editor>` and `<rk-toolbar>`, for any page or framework: form-associated (it submits its value, resets, restores), with properties, attributes and events.
+
+## Install
 
 ```sh
-npm install @rathkit/rte-element@next
+npm install @rathkit/rte-element@next @rathkit/rte-core@next @rathkit/rte-headless@next
 ```
 
-About the project: https://rathkit.com
+This package has no dependencies of its own. It works with `@rathkit/rte-core`, `@rathkit/rte-headless` (peer dependencies, all optional so that npm installs nothing you did not ask for), so install the ones you use alongside it.
+
+## Example
+
+```html
+<script type="module">
+  import "@rathkit/rte-element/define";
+</script>
+
+<form>
+  <rk-editor name="body" label="Body"><p>Start here</p></rk-editor>
+</form>
+<script>
+  document.querySelector("rk-editor").addEventListener("rk-change", (e) => console.log(e.detail.html));
+</script>
+```
+
+## More
+
+Documentation: <https://rathkit.com>. Source and issues: <https://github.com/rathkit/rte>. What is checked: [SUPPORT.md](https://github.com/rathkit/rte/blob/main/docs/SUPPORT.md). Changes: [CHANGELOG.md](https://github.com/rathkit/rte/blob/main/CHANGELOG.md). How a release is verified: [VERIFY.md](https://github.com/rathkit/rte/blob/main/docs/VERIFY.md).
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/define.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/define.js

@@ -0,0 +1,2 @@
+import { define } from "./index.js";
+define();

package/dist/editor-element.d.ts

@@ -0,0 +1,51 @@
+import type { Editor } from "@rathkit/rte-core/dom";
+import { type StandardOptions } from "@rathkit/rte-core/standard";
+/** Options an app can only pass as code (functions, plugin lists): everything in the standard editor's options except what attributes control. */
+export type RkEditorOptions = Omit<StandardOptions, "element" | "html" | "readOnly">;
+export declare class RkEditor extends HTMLElement {
+    static formAssociated: boolean;
+    static observedAttributes: string[];
+    private internals;
+    private surface;
+    private current;
+    private html;
+    private defaultHtml;
+    private opts;
+    private stop;
+    private atFocus;
+    private resolveReady;
+    private ready;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
+    get form(): HTMLFormElement | null;
+    get name(): string;
+    set name(value: string);
+    get validity(): ValidityState | undefined;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    /** The document as HTML. Setting it replaces the document and clears the undo history. */
+    get value(): string;
+    set value(html: string);
+    get readOnly(): boolean;
+    set readOnly(value: boolean);
+    /** The editor inside, once it exists: for commands, plugins and subscriptions. */
+    get editor(): Editor | undefined;
+    /** Resolves with the editor once the element is connected and the editor is built. */
+    whenReady(): Promise<Editor>;
+    /** Options only code can give (an upload function, more plugins). Set them before the element is connected. */
+    get options(): RkEditorOptions;
+    set options(options: RkEditorOptions);
+    focus(): void;
+    private changed;
+    private lastSent;
+    /** Brings the form value and validity up to date. */
+    private sync;
+    private isEmpty;
+    private onFocusIn;
+    private onFocusOut;
+}

package/dist/editor-element.js

@@ -0,0 +1,139 @@
+import { createEditor } from "@rathkit/rte-core/standard";
+export class RkEditor extends HTMLElement {
+    static formAssociated = true;
+    static observedAttributes = ["value", "readonly", "disabled", "label", "required", "placeholder"];
+    internals;
+    surface;
+    current;
+    html = "";
+    defaultHtml = "";
+    opts = {};
+    stop;
+    atFocus = "";
+    resolveReady;
+    ready = new Promise((resolve) => { this.resolveReady = resolve; });
+    constructor() {
+        super();
+        this.internals = typeof this.attachInternals === "function" ? this.attachInternals() : undefined;
+    }
+    connectedCallback() {
+        if (this.current)
+            return;
+        if (this.html === "" && !this.hasAttribute("value"))
+            this.html = this.innerHTML.trim();
+        else if (this.html === "")
+            this.html = this.getAttribute("value") ?? "";
+        if (this.defaultHtml === "")
+            this.defaultHtml = this.hasAttribute("value") ? (this.getAttribute("value") ?? "") : this.html;
+        this.replaceChildren();
+        const surface = document.createElement("div");
+        surface.setAttribute("data-rk-surface", "");
+        this.appendChild(surface);
+        this.surface = surface;
+        const label = this.getAttribute("label");
+        if (label)
+            surface.setAttribute("aria-label", label);
+        else if (!this.hasAttribute("aria-label") && !this.hasAttribute("aria-labelledby"))
+            console.warn("[rte] <rk-editor> has no name: give it a label attribute.");
+        const maxLength = Number.parseInt(this.getAttribute("maxlength") ?? "", 10);
+        const spellcheck = this.getAttribute("spellcheck");
+        const editor = createEditor({
+            ...this.opts, element: surface, html: this.html, readOnly: this.hasAttribute("readonly") || this.hasAttribute("disabled"),
+            ...(this.hasAttribute("placeholder") ? { placeholder: this.getAttribute("placeholder") ?? "" } : {}),
+            ...(Number.isFinite(maxLength) && maxLength >= 0 ? { maxLength } : {}),
+            ...(spellcheck === "true" || spellcheck === "false" ? { spellcheck: spellcheck === "true" } : {}),
+            ...(this.hasAttribute("autofocus") ? { autofocus: true } : {}),
+        });
+        this.current = editor;
+        this.stop = editor.subscribe(() => this.changed());
+        surface.addEventListener("focusin", this.onFocusIn);
+        surface.addEventListener("focusout", this.onFocusOut);
+        this.sync();
+        this.resolveReady?.(editor);
+        this.dispatchEvent(new CustomEvent("rk-ready", { bubbles: true, composed: true, detail: { editor } }));
+    }
+    disconnectedCallback() {
+        const editor = this.current;
+        if (!editor)
+            return;
+        this.html = editor.getHtml();
+        this.stop?.();
+        editor.destroy();
+        this.surface?.removeEventListener("focusin", this.onFocusIn);
+        this.surface?.removeEventListener("focusout", this.onFocusOut);
+        this.current = undefined;
+        this.surface = undefined;
+        this.ready = new Promise((resolve) => { this.resolveReady = resolve; });
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (name === "value") {
+            if (value !== null && value !== this.value)
+                this.value = value;
+        }
+        else if (name === "readonly" || name === "disabled") {
+            this.current?.setReadOnly(this.hasAttribute("readonly") || this.hasAttribute("disabled"));
+        }
+        else if (name === "placeholder") {
+            this.current?.setPlaceholder(value ?? "");
+        }
+        else if (name === "label") {
+            if (value)
+                this.surface?.setAttribute("aria-label", value);
+        }
+        else if (name === "required") {
+            this.sync();
+        }
+    }
+    formResetCallback() { this.value = this.defaultHtml; }
+    formDisabledCallback(disabled) { this.current?.setReadOnly(disabled || this.hasAttribute("readonly")); }
+    formStateRestoreCallback(state) { if (typeof state === "string")
+        this.value = state; }
+    get form() { return this.internals?.form ?? null; }
+    get name() { return this.getAttribute("name") ?? ""; }
+    set name(value) { this.setAttribute("name", value); }
+    get validity() { return this.internals?.validity; }
+    checkValidity() { return this.internals?.checkValidity() ?? true; }
+    reportValidity() { return this.internals?.reportValidity() ?? true; }
+    get value() { return this.current ? this.current.getHtml() : this.html; }
+    set value(html) {
+        this.html = html;
+        if (this.current)
+            this.current.setHtml(html);
+        else
+            this.defaultHtml ||= html;
+        this.sync();
+    }
+    get readOnly() { return this.hasAttribute("readonly"); }
+    set readOnly(value) { this.toggleAttribute("readonly", value); }
+    get editor() { return this.current; }
+    whenReady() { return this.ready; }
+    get options() { return this.opts; }
+    set options(options) {
+        if (this.current)
+            console.warn("[rte] <rk-editor> options set after it was connected have no effect.");
+        this.opts = options;
+    }
+    focus() { this.current?.focus(); }
+    changed() {
+        const html = this.value;
+        if (html === this.lastSent)
+            return;
+        this.lastSent = html;
+        this.sync();
+        this.dispatchEvent(new CustomEvent("rk-change", { bubbles: true, composed: true, detail: { html } }));
+        this.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+    }
+    lastSent = "";
+    sync() {
+        const html = this.value;
+        this.internals?.setFormValue(html);
+        if (this.hasAttribute("required") && this.isEmpty(html))
+            this.internals?.setValidity({ valueMissing: true }, "Please fill in this field.", this.surface);
+        else
+            this.internals?.setValidity({});
+    }
+    isEmpty(html) { return html.replace(/<[^>]*>/g, "").replace(/&nbsp;/g, "").trim() === "" && !html.includes("<img"); }
+    onFocusIn = () => { this.atFocus = this.value; };
+    onFocusOut = () => { if (this.value !== this.atFocus)
+        this.dispatchEvent(new Event("change", { bubbles: true })); };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { RkEditor, type RkEditorOptions } from "./editor-element.ts";
+import { RkToolbar } from "./toolbar-element.ts";
+export { RkEditor, RkToolbar, type RkEditorOptions };
+/** Registers the elements. Safe to call more than once. */
+export declare function define(names?: {
+    readonly editor?: string;
+    readonly toolbar?: string;
+}): void;

package/dist/index.js

@@ -0,0 +1,11 @@
+import { RkEditor } from "./editor-element.js";
+import { RkToolbar } from "./toolbar-element.js";
+export { RkEditor, RkToolbar };
+export function define(names = {}) {
+    const editor = names.editor ?? "rk-editor";
+    const toolbar = names.toolbar ?? "rk-toolbar";
+    if (!customElements.get(editor))
+        customElements.define(editor, RkEditor);
+    if (!customElements.get(toolbar))
+        customElements.define(toolbar, RkToolbar);
+}

package/dist/toolbar-element.d.ts

@@ -0,0 +1,14 @@
+export declare class RkToolbar extends HTMLElement {
+    static observedAttributes: string[];
+    private toolbar;
+    private unbind;
+    private unwatch;
+    private building;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** The editor this toolbar belongs to: the element named by `for`, else the nearest <rk-editor> beside or around it. */
+    private target;
+    private teardown;
+    private build;
+}

package/dist/toolbar-element.js

@@ -0,0 +1,70 @@
+import { createToolbar } from "@rathkit/rte-headless";
+export class RkToolbar extends HTMLElement {
+    static observedAttributes = ["for", "label", "slot-name"];
+    toolbar;
+    unbind;
+    unwatch;
+    building = 0;
+    connectedCallback() { void this.build(); }
+    disconnectedCallback() { this.teardown(); }
+    attributeChangedCallback() { if (this.isConnected)
+        void this.build(); }
+    target() {
+        const id = this.getAttribute("for");
+        if (id)
+            return this.ownerDocument.getElementById(id);
+        return (this.parentElement?.querySelector("rk-editor") ?? this.closest("rk-editor"));
+    }
+    teardown() {
+        this.unwatch?.();
+        this.unbind?.();
+        this.toolbar?.destroy();
+        this.toolbar = undefined;
+    }
+    async build() {
+        const ticket = ++this.building;
+        this.teardown();
+        const host = this.target();
+        if (!host)
+            return;
+        await customElements.whenDefined("rk-editor");
+        const editor = await host.whenReady();
+        if (ticket !== this.building || !this.isConnected)
+            return;
+        const toolbar = createToolbar(editor, { label: this.getAttribute("label") ?? "Formatting", slot: this.getAttribute("slot-name") ?? "toolbar.main" });
+        this.toolbar = toolbar;
+        const draw = () => {
+            this.unbind?.();
+            const controls = [];
+            for (const item of toolbar.items) {
+                if (item.kind === "separator") {
+                    const s = document.createElement("span");
+                    s.setAttribute("role", "separator");
+                    controls.push(s);
+                }
+                else if (item.kind === "select") {
+                    const select = document.createElement("select");
+                    select.setAttribute("data-rk-item", item.id);
+                    for (const o of item.options) {
+                        const option = document.createElement("option");
+                        option.value = String(o.value);
+                        option.textContent = o.label;
+                        select.appendChild(option);
+                    }
+                    controls.push(select);
+                }
+                else if (item.kind !== "menu") {
+                    const button = document.createElement("button");
+                    button.type = "button";
+                    button.setAttribute("data-rk-item", item.id);
+                    button.textContent = toolbar.state(item.id)?.label ?? item.id;
+                    controls.push(button);
+                }
+            }
+            this.replaceChildren(...controls);
+            this.unbind = toolbar.bind(this, { onOpen: (item, control) => this.dispatchEvent(new CustomEvent("rk-open", { bubbles: true, composed: true, detail: { item, control } })) });
+        };
+        draw();
+        this.unwatch = editor.ui.subscribe(this.getAttribute("slot-name") ?? "toolbar.main", draw);
+    }
+}

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@rathkit/rte-element",
-  "version": "0.0.0",
-  "description": "Placeholder. @rathkit/rte-element is in alpha: install it with the next tag.",
+  "version": "0.1.0-alpha.3",
+  "description": "The editor as a custom element, <rk-editor>, for any page or framework: form-associated, with properties, attributes and events.",
+  "keywords": [
+    "rich-text",
+    "editor",
+    "wysiwyg",
+    "contenteditable",
+    "zero-dependencies",
+    "typescript",
+    "web-components",
+    "custom-element"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://rathkit.com",
   "repository": {
@@ -12,7 +22,61 @@
   "bugs": {
     "url": "https://github.com/rathkit/rte/issues"
   },
+  "type": "module",
+  "sideEffects": [
+    "./dist/define.js"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "files": [
+    "dist",
+    "NOTICE",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "default": "./dist/define.js"
+    }
+  },
+  "peerDependencies": {
+    "@rathkit/rte-core": ">=0.1.0-alpha.3 <0.2.0",
+    "@rathkit/rte-headless": ">=0.1.0-alpha.3 <0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@rathkit/rte-core": {
+      "optional": true
+    },
+    "@rathkit/rte-headless": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rathkit/rte-core": "workspace:*",
+    "@rathkit/rte-headless": "workspace:*"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsc -p tsconfig.build.js.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node -e \"process.exit(0)\""
+  },
+  "rathkit": {
+    "budgets": [
+      {
+        "name": "element",
+        "entry": "dist/index.js",
+        "gzipKB": 4
+      }
+    ]
   }
 }