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

package/README.md

@@ -1,11 +1,43 @@
 # @rathkit/rte-react
 
-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-react is in alpha. Install the alpha with the `next` tag:
+The editor for React: a component and hooks over the headless layer. A component re-renders only when the value it reads changes. No editor or accessibility logic lives here.
+
+## Install
 
 ```sh
-npm install @rathkit/rte-react@next
+npm install @rathkit/rte-react@next @rathkit/rte-core@next @rathkit/rte-headless@next
+```
+
+This package has no dependencies of its own. It works with `@rathkit/rte-core`, `@rathkit/rte-headless`, `react` (peer dependencies, all optional so that npm installs nothing you did not ask for), so install the ones you use alongside it; `react` comes from your own project.
+
+## Example
+
+```jsx
+import { RteEditor, useCommand } from "@rathkit/rte-react";
+import { useState } from "react";
+
+function Bold({ editor }) {
+  const bold = useCommand(editor, "format.bold");
+  return <button aria-pressed={bold.active} onClick={() => editor.commands.run("format.bold")}>Bold</button>;
+}
+
+export function Field() {
+  const [editor, setEditor] = useState();
+  return (
+    <>
+      <Bold editor={editor} />
+      <RteEditor label="Body" defaultValue="<p>Hello</p>" onReady={setEditor} onChange={(html) => console.log(html)} />
+    </>
+  );
+}
 ```
 
-About the project: https://rathkit.com
+## 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/editor.d.ts

@@ -0,0 +1,22 @@
+import type { Editor } from "@rathkit/rte-core/dom";
+import { type StandardOptions } from "@rathkit/rte-core/standard";
+export type RteOptions = Omit<StandardOptions, "element" | "html" | "readOnly">;
+export interface RteEditorProps extends RteOptions {
+    /** The starting HTML. Later changes to this prop are ignored: call `editor.setHtml` to replace the document. */
+    defaultValue?: string;
+    readOnly?: boolean;
+    /** The name screen readers announce for the editing surface. Required: an unnamed editor is an accessibility fault. */
+    label: string;
+    className?: string;
+    /** Called with the HTML after each change that alters it. */
+    onChange?: (html: string) => void;
+    /** Called once the editor exists, with the editor to run commands on and subscribe to. */
+    onReady?: (editor: Editor) => void;
+}
+/** The hook behind `RteEditor`, for those who draw their own surface: give `ref` to one element. */
+export declare function useRteEditor(props: Omit<RteEditorProps, "label" | "className">): {
+    ref: (element: HTMLElement | null) => void;
+    editor: Editor | undefined;
+};
+/** The editing surface as a component. */
+export declare function RteEditor(props: RteEditorProps): unknown;

package/dist/editor.js

@@ -0,0 +1,36 @@
+import { createElement, useEffect, useRef, useState } from "react";
+import { createEditor } from "@rathkit/rte-core/standard";
+export function useRteEditor(props) {
+    const [element, ref] = useState(null);
+    const [editor, setEditor] = useState(undefined);
+    const latest = useRef(props);
+    latest.current = props;
+    useEffect(() => {
+        if (!element)
+            return;
+        const { defaultValue, readOnly, onChange: _c, onReady: _r, ...options } = latest.current;
+        const made = createEditor({ ...options, element, html: defaultValue ?? "", readOnly: readOnly ?? false });
+        let last = made.getHtml();
+        const stop = made.subscribe(() => {
+            const html = made.getHtml();
+            if (html === last)
+                return;
+            last = html;
+            latest.current.onChange?.(html);
+        });
+        setEditor(made);
+        latest.current.onReady?.(made);
+        return () => {
+            stop();
+            made.destroy();
+            setEditor(undefined);
+        };
+    }, [element]);
+    useEffect(() => { editor?.setReadOnly(props.readOnly ?? false); }, [editor, props.readOnly]);
+    return { ref, editor };
+}
+export function RteEditor(props) {
+    const { label, className, ...rest } = props;
+    const { ref } = useRteEditor(rest);
+    return createElement("div", { ref, "aria-label": label, className, "data-rk-surface": "" });
+}

package/dist/hooks.d.ts

@@ -0,0 +1,11 @@
+import { type ExternalStore, type HeadlessEditor } from "@rathkit/rte-headless";
+import type { CommandState, EditorSnapshot } from "@rathkit/rte-core";
+/** Reads an external store (any of `commandStore`, `selectStore`, `snapshotStore`) as React state. */
+export declare function useStore<T>(store: ExternalStore<T>): T;
+/** One command's state: whether it can run, whether it is on, its value. Before the editor exists it is off and disabled. */
+export declare function useCommand(editor: HeadlessEditor | undefined, name: string): CommandState;
+/**
+ * One value worked out from the editor state, such as a word count. The component re-renders only when that value changes. Give a
+ * stable `selector` (declare it outside the component or wrap it in `useCallback`), or the store is rebuilt on every render.
+ */
+export declare function useSelector<T>(editor: HeadlessEditor | undefined, selector: (snapshot: EditorSnapshot) => T, equals?: (a: T, b: T) => boolean): T | undefined;

package/dist/hooks.js

@@ -0,0 +1,15 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { commandStore, selectStore } from "@rathkit/rte-headless";
+const idle = Object.freeze({ enabled: false, active: false, value: undefined });
+const nothing = { subscribe: () => () => undefined, getSnapshot: () => undefined };
+export function useStore(store) {
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+export function useCommand(editor, name) {
+    const store = useMemo(() => (editor ? commandStore(editor, name) : { subscribe: nothing.subscribe, getSnapshot: () => idle }), [editor, name]);
+    return useStore(store);
+}
+export function useSelector(editor, selector, equals) {
+    const store = useMemo(() => (editor ? selectStore(editor, selector, equals) : { subscribe: nothing.subscribe, getSnapshot: () => undefined }), [editor, selector, equals]);
+    return useStore(store);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { useCommand, useSelector, useStore } from "./hooks.ts";
+export { RteEditor, useRteEditor, type RteEditorProps, type RteOptions } from "./editor.ts";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { useCommand, useSelector, useStore } from "./hooks.js";
+export { RteEditor, useRteEditor } from "./editor.js";

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@rathkit/rte-react",
-  "version": "0.0.0",
-  "description": "Placeholder. @rathkit/rte-react is in alpha: install it with the next tag.",
+  "version": "0.1.0-alpha.3",
+  "description": "The editor for React: a component and hooks over the headless layer, with no editor or accessibility logic of its own.",
+  "keywords": [
+    "rich-text",
+    "editor",
+    "wysiwyg",
+    "contenteditable",
+    "zero-dependencies",
+    "typescript",
+    "react",
+    "hooks"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://rathkit.com",
   "repository": {
@@ -12,7 +22,59 @@
   "bugs": {
     "url": "https://github.com/rathkit/rte/issues"
   },
+  "type": "module",
+  "sideEffects": false,
+  "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"
+    }
+  },
+  "peerDependencies": {
+    "@rathkit/rte-core": ">=0.1.0-alpha.3 <0.2.0",
+    "@rathkit/rte-headless": ">=0.1.0-alpha.3 <0.2.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@rathkit/rte-core": {
+      "optional": true
+    },
+    "@rathkit/rte-headless": {
+      "optional": true
+    },
+    "react": {
+      "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 --import ./test/register.mjs --test \"src/**/*.test.ts\""
+  },
+  "rathkit": {
+    "budgets": [
+      {
+        "name": "react",
+        "entry": "dist/index.js",
+        "gzipKB": 2
+      }
+    ]
   }
 }