@canvist/react 0.0.0-stage → 0.2.0

package/dist/mod.d.ts

@@ -0,0 +1,90 @@
+/**
+ * React bindings for the canvist canvas editor.
+ *
+ * `CanvistEditor` renders an editor; `useCanvistEditor` gives you the
+ * editor itself, and `useEditorState` re-renders a component when
+ * something it reads from the editor changes. `BubbleMenu` and
+ * `FloatingMenu` keep their children next to the selection. Commands, queries, and
+ * plugin APIs are typed from the extensions and plugins you pass, as in
+ * `@canvist/web`.
+ *
+ * ```tsx
+ * function Notes() {
+ * 	const { ref, editor } = useCanvistEditor({
+ * 		content: { format: "markdown", input: "Hello **world**" },
+ * 	});
+ * 	const bold = useEditorState(editor, (current) => current.can.toggleBold(), false);
+ *
+ * 	return (
+ * 		<>
+ * 			<button disabled={!bold} onClick={() => editor?.commands.toggleBold()}>Bold</button>
+ * 			<div ref={ref} />
+ * 		</>
+ * 	);
+ * }
+ * ```
+ *
+ * @module
+ */
+import { type Editor, type EditorOptions, type Extensions, type Plugins, type StarterKit } from "@canvist/web";
+import { type MenuOptions } from "@canvist/web/menus";
+import { type CSSProperties, type ReactElement, type ReactNode, type RefCallback } from "react";
+/** What {@link useCanvistEditor} returns. */
+export interface CanvistEditorHandle<E extends Extensions, P extends Plugins> {
+    /** Attach to the element the editor renders into. */
+    readonly ref: RefCallback<HTMLElement>;
+    /** The editor, once it has loaded; `null` before that and after unmounting. */
+    readonly editor: Editor<E, P> | null;
+}
+/**
+ * Create an editor in the element `ref` is attached to, and destroy it
+ * when the element goes away. `options` are read when the editor is
+ * created; later changes to them have no effect.
+ */
+export declare function useCanvistEditor<const E extends Extensions = StarterKit, const P extends Plugins = []>(options?: EditorOptions<E, P>): CanvistEditorHandle<E, P>;
+/**
+ * Read `select(editor)` and re-render whenever it changes, after any edit
+ * or selection change. `select` must return a primitive or a value that
+ * stays the same object while nothing changed, as with
+ * `useSyncExternalStore`. Until the editor exists, the value is
+ * `fallback`.
+ */
+export declare function useEditorState<E extends Extensions, P extends Plugins, T>(editor: Editor<E, P> | null, select: (editor: Editor<E, P>) => T, fallback: T): T;
+/**
+ * Props for {@link CanvistEditor}: the editor's options, read once except
+ * `editable` and `placeholder`, which follow the props, and the element's.
+ */
+export interface CanvistEditorProps<E extends Extensions, P extends Plugins> extends EditorOptions<E, P> {
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /**
+     * Server-rendered HTML (`.cv-doc` markup from canvist's renderer) to
+     * show until the editor takes over. The editor reads the document from
+     * it when `content` is not given.
+     */
+    readonly html?: string;
+    /** Called once the editor has loaded. */
+    readonly onReady?: (editor: Editor<E, P>) => void;
+    /** Called after every change to the document or selection. */
+    readonly onUpdate?: (editor: Editor<E, P>) => void;
+}
+/** A canvist editor. Give it a width; without a height it grows with its document. */
+export declare function CanvistEditor<const E extends Extensions = StarterKit, const P extends Plugins = []>(props: CanvistEditorProps<E, P>): ReactElement;
+/** Props for {@link BubbleMenu} and {@link FloatingMenu}. */
+export interface MenuProps<E extends Extensions, P extends Plugins> extends MenuOptions<E, P> {
+    /** The editor to follow; the menu stays hidden while it is `null`. */
+    readonly editor: Editor<E, P> | null;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly children?: ReactNode;
+}
+/**
+ * A menu over selected text, as `bubbleMenu` from `@canvist/web/menus`
+ * places it. Pressing inside it keeps the editor's focus and selection.
+ */
+export declare function BubbleMenu<E extends Extensions, P extends Plugins>(props: MenuProps<E, P>): ReactElement;
+/**
+ * A menu beside the caret on an empty line, as `floatingMenu` from
+ * `@canvist/web/menus` places it.
+ */
+export declare function FloatingMenu<E extends Extensions, P extends Plugins>(props: MenuProps<E, P>): ReactElement;

package/dist/mod.js

@@ -0,0 +1,162 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React bindings for the canvist canvas editor.
+ *
+ * `CanvistEditor` renders an editor; `useCanvistEditor` gives you the
+ * editor itself, and `useEditorState` re-renders a component when
+ * something it reads from the editor changes. `BubbleMenu` and
+ * `FloatingMenu` keep their children next to the selection. Commands, queries, and
+ * plugin APIs are typed from the extensions and plugins you pass, as in
+ * `@canvist/web`.
+ *
+ * ```tsx
+ * function Notes() {
+ * 	const { ref, editor } = useCanvistEditor({
+ * 		content: { format: "markdown", input: "Hello **world**" },
+ * 	});
+ * 	const bold = useEditorState(editor, (current) => current.can.toggleBold(), false);
+ *
+ * 	return (
+ * 		<>
+ * 			<button disabled={!bold} onClick={() => editor?.commands.toggleBold()}>Bold</button>
+ * 			<div ref={ref} />
+ * 		</>
+ * 	);
+ * }
+ * ```
+ *
+ * @module
+ */
+import { createEditor, } from "@canvist/web";
+import { bubbleMenu, floatingMenu, } from "@canvist/web/menus";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, } from "react";
+/**
+ * Create an editor in the element `ref` is attached to, and destroy it
+ * when the element goes away. `options` are read when the editor is
+ * created; later changes to them have no effect.
+ */
+export function useCanvistEditor(options = {}) {
+    const [element, setElement] = useState(null);
+    const [editor, setEditor] = useState(null);
+    const initial = useRef(options);
+    useEffect(() => {
+        if (element === null) {
+            return;
+        }
+        const mount = { live: true, editor: null };
+        void create(element, initial.current, mount, setEditor);
+        return () => {
+            mount.live = false;
+            mount.editor?.destroy();
+            setEditor(null);
+        };
+    }, [element]);
+    return { ref: setElement, editor };
+}
+/**
+ * Read `select(editor)` and re-render whenever it changes, after any edit
+ * or selection change. `select` must return a primitive or a value that
+ * stays the same object while nothing changed, as with
+ * `useSyncExternalStore`. Until the editor exists, the value is
+ * `fallback`.
+ */
+export function useEditorState(editor, select, fallback) {
+    const subscribe = useCallback((listener) => editor?.subscribe(listener) ?? noop, [editor]);
+    return useSyncExternalStore(subscribe, () => editor === null ? fallback : select(editor), () => fallback);
+}
+/** A canvist editor. Give it a width; without a height it grows with its document. */
+export function CanvistEditor(props) {
+    const { className, style, html, onReady, onUpdate, ...options } = props;
+    const { ref, editor } = useCanvistEditor(options);
+    const callbacks = useRef({ onReady, onUpdate });
+    const { editable = true, placeholder = "" } = options;
+    useEffect(() => {
+        editor?.setEditable(editable);
+    }, [editor, editable]);
+    useEffect(() => {
+        editor?.setPlaceholder(placeholder);
+    }, [editor, placeholder]);
+    useEffect(() => {
+        callbacks.current = { onReady, onUpdate };
+    });
+    useEffect(() => {
+        if (editor === null) {
+            return;
+        }
+        callbacks.current.onReady?.(editor);
+        return editor.subscribe(() => callbacks.current.onUpdate?.(editor));
+    }, [editor]);
+    return (_jsx("div", { ref: ref, className: className, style: style, 
+        // Set once: React leaves the editor's elements alone afterwards.
+        dangerouslySetInnerHTML: html === undefined
+            ? undefined
+            : { __html: html } }));
+}
+/**
+ * A menu over selected text, as `bubbleMenu` from `@canvist/web/menus`
+ * places it. Pressing inside it keeps the editor's focus and selection.
+ */
+export function BubbleMenu(props) {
+    return _jsx(FollowingMenu, { ...props, attach: bubbleMenu });
+}
+/**
+ * A menu beside the caret on an empty line, as `floatingMenu` from
+ * `@canvist/web/menus` places it.
+ */
+export function FloatingMenu(props) {
+    return _jsx(FollowingMenu, { ...props, attach: floatingMenu });
+}
+function FollowingMenu(props) {
+    const { editor, attach, className, style, children, ...options } = props;
+    const element = useRef(null);
+    const menu = useRef(null);
+    // The latest rule, without re-attaching each time a new closure renders.
+    const shouldShow = useRef(options.shouldShow);
+    shouldShow.current = options.shouldShow;
+    const custom = options.shouldShow !== undefined;
+    const { placement, offset, padding } = options;
+    useEffect(() => {
+        if (editor === null || element.current === null) {
+            return;
+        }
+        const attached = attach(editor, element.current, {
+            ...(placement === undefined ? {} : { placement }),
+            ...(offset === undefined ? {} : { offset }),
+            ...(padding === undefined ? {} : { padding }),
+            ...(custom
+                ? { shouldShow: (current) => shouldShow.current?.(current) ?? false }
+                : {}),
+        });
+        menu.current = attached;
+        return () => {
+            attached.destroy();
+            menu.current = null;
+        };
+    }, [editor, attach, placement, offset, padding, custom]);
+    // A re-render can change what `shouldShow` or the children decide.
+    useEffect(() => {
+        menu.current?.update();
+    });
+    return (_jsx("div", { ref: element, className: className, style: style, hidden: true, children: children }));
+}
+/**
+ * Create the editor for `mount`. An effect cleaned up while the module
+ * loaded (as React's Strict Mode does once) destroys what arrives late.
+ */
+async function create(element, options, mount, created) {
+    try {
+        const editor = await createEditor(element, options);
+        if (!mount.live) {
+            editor.destroy();
+            return;
+        }
+        mount.editor = editor;
+        created(editor);
+    }
+    catch (error) {
+        if (mount.live) {
+            reportError(error);
+        }
+    }
+}
+function noop() { }

package/package.json

@@ -1,6 +1,41 @@
 {
-  "name": "@canvist/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@canvist/react",
+	"version": "0.2.0",
+	"description": "React bindings for the canvist canvas editor: a component, and hooks typed from the extensions you register.",
+	"license": "Unlicense",
+	"homepage": "https://github.com/canvist/canvist/tree/main/packages/canvist-react#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/canvist/canvist.git",
+		"directory": "packages/canvist-react"
+	},
+	"bugs": {
+		"url": "https://github.com/canvist/canvist/issues",
+		"email": "support@canvist.dev"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"default": "./dist/mod.js"
+		}
+	},
+	"files": ["dist"],
+	"sideEffects": false,
+	"scripts": {
+		"check:types": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"@canvist/web": "^0.2.0"
+	},
+	"peerDependencies": {
+		"react": "^18.3.0 || ^19.0.0"
+	},
+	"devDependencies": {
+		"@types/react": "^19.0.0",
+		"react": "^19.0.0",
+		"typescript": "^7.0.2"
+	}
+}

package/readme.md

@@ -0,0 +1,61 @@
+<p align="center">
+  <a href="https://github.com/canvist/canvist">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup-dark.svg">
+      <img width="220" src="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup.svg" alt="canvist" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/quick-start/react.md"><strong>Quick start</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/readme.md"><strong>Docs</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/reference/contributing.md"><strong>Contributing</strong></a> ·
+  <a href="https://github.com/canvist/canvist"><strong>canvist</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@canvist/react"><img src="https://img.shields.io/npm/v/%40canvist%2Freact?color=3B2CF5" alt="npm version" /></a>
+  <a href="https://github.com/canvist/canvist/actions/workflows/web.yml"><img src="https://github.com/canvist/canvist/actions/workflows/web.yml/badge.svg?branch=main" alt="web status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/react
+
+React bindings for [`@canvist/web`](../canvist-web), the canvist canvas editor. Commands, queries, and plugin APIs are typed from the extensions and plugins you pass.
+
+```sh
+npm install @canvist/react
+```
+
+```tsx
+import { useCanvistEditor, useEditorState } from "@canvist/react";
+
+function Notes() {
+	const { ref, editor } = useCanvistEditor({ label: "Notes" });
+	const isBold = useEditorState(
+		editor,
+		(current) => current.query.isBold(),
+		false,
+	);
+
+	return (
+		<>
+			<button
+				aria-pressed={isBold}
+				onClick={() => editor?.commands.toggleBold()}
+			>
+				Bold
+			</button>
+			<div ref={ref} />
+		</>
+	);
+}
+```
+
+- `useCanvistEditor(options)` creates the editor in the element `ref` is attached to and destroys it on unmount, Strict Mode included.
+- `useEditorState(editor, select, fallback)` re-renders when `select(editor)` changes, through `useSyncExternalStore`.
+- `<CanvistEditor />` takes the editor's options as props, plus `onReady`, `onUpdate`, and `html` for server-rendered HTML to hydrate. `editable` and `placeholder` follow their props.
+- `<BubbleMenu editor={editor}>` and `<FloatingMenu editor={editor}>` keep their children next to the selection.
+
+See [Quick start: React](../../docs/src/quick-start/react.md).

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.