@meowdown/react 0.5.0 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ React components for Meowdown, a hybrid (live-preview) Markdown editor.
 ## Usage
 
 ```tsx
-import { Editor, type EditorHandle } from '@meowdown/react'
+import { MeowdownEditor, type EditorHandle } from '@meowdown/react'
 import '@meowdown/react/style.css'
 import { useRef, useCallback } from 'react'
 
@@ -15,13 +15,20 @@ export function App() {
     console.log(ref.current?.getMarkdown())
   }, [])
 
-  return <Editor ref={ref} mode="focus" initialMarkdown="# Hello" onDocChange={handleDocChange} />
+  return (
+    <MeowdownEditor
+      handleRef={ref}
+      mode="focus"
+      initialMarkdown="# Hello"
+      onDocChange={handleDocChange}
+    />
+  )
 }
 ```
 
 ## API
 
-### `<Editor>`
+### `<MeowdownEditor>`
 
 The Markdown editor component. Renders inside a `div.meowdown` wrapper that fills a flex parent. In rich modes, typing `/` opens a slash menu for inserting blocks (headings, blockquote, lists, code block, table). Hovering a block shows a handle to its left: the plus button inserts an empty paragraph below the block, and the grip selects the block and can be dragged to move it, with a drop indicator line marking the target.
 
@@ -31,7 +38,7 @@ The Markdown editor component. Renders inside a `div.meowdown` wrapper that fill
   - `'hide'`: Markdown syntax is always hidden.
   - `'source'`: raw Markdown source with syntax highlighting.
 - `initialMarkdown?: string`: first render only.
-- `onDocChange?: VoidFunction`: called on every document change.
+- `onDocChange?: VoidFunction`: called on every user-driven document change. Programmatic `setMarkdown` / `setState` on the handle do not fire it.
 - `onTagSearch?: (query: string) => TagItem[] | Promise<TagItem[]>`: enables the tag menu, which opens when typing `#` followed by text in a rich mode. Returns ranked rows `{ tag, label?, detail?, onSelect? }` (the menu does not re-sort). Selecting a row inserts `#tag ` then runs its `onSelect`. Omit to disable.
 - `onWikilinkSearch?: (query: string) => WikilinkItem[] | Promise<WikilinkItem[]>`: enables the wikilink menu, which opens as soon as `[[` is typed in a rich mode. Returns ranked rows `{ target, label?, detail?, onSelect? }` (the menu does not re-sort). Selecting a row inserts `[[target]]` then runs its `onSelect`. Omit to disable.
 - `onWikilinkClick?: (payload: { target: string; event: MouseEvent }) => void`: called when a rendered wiki link is clicked. A plain click inside a link the caret already sits in just places the caret; `Mod`-click always fires. Pass a stable function (e.g. from `useCallback`). Ignored in source mode.
@@ -43,7 +50,7 @@ The Markdown editor component. Renders inside a `div.meowdown` wrapper that fill
 - `spellCheck?: boolean`: toggles the browser's native spell checking in the rich modes. Defaults to the browser's behavior. Ignored in source mode.
 - `editorClassName?: string`: class on the editable root (the contenteditable). Rich modes only.
 - `wrapperClassName?: string`: class on the outer `div.meowdown` wrapper.
-- `ref?: Ref<EditorHandle>`
+- `handleRef?: Ref<EditorHandle>`
 - `children?: ReactNode`: rendered inside the editor's ProseKit context, so children can call `useEditor()`. Only rendered in the rich modes; source mode ignores them.
 
 ### `useEditor`
@@ -54,12 +61,16 @@ Re-exported from `@prosekit/react`. Call it from a component passed as `children
 
 Re-exported from `@meowdown/core`. `checkRoundTrip(markdown)` returns `'exact' | 'normalizing' | 'lossy'`, for hosts that gate saving markdown files on whether the editor reproduces them faithfully.
 
+### `EDITOR_KEY_BINDINGS`
+
+Re-exported from `@meowdown/core`. A literal (`as const`) object mapping each editor shortcut (e.g. `Mod-b`, `Mod-1`) to its description, for host settings UIs and keybinding-collision checks.
+
 ### `EditorHandle`
 
-Imperative handle for the editor, attached via `ref`.
+Imperative handle for the editor, attached via `handleRef`.
 
 - `getMarkdown(): string`: serializes the current document to Markdown. Can be expensive on large documents; call it on demand (e.g. throttled) instead of on every change.
-- `setMarkdown(markdown: string): void`: replaces the whole document as a single undoable edit.
+- `setMarkdown(markdown: string): void`: replaces the whole document as a single undoable edit. Does not fire `onDocChange`.
 - `getState(): EditorStateSnapshot`: returns `[markdown, selection]`, where `selection` is a `SelectionJSON` (`{ anchor: number, head: number, type: string }`).
 - `setState(markdown?: string, selection?: SelectionJSON | 'start' | 'end'): void`: replaces the document (if `markdown` is given) and restores `selection`: exactly when valid, otherwise clamped to the nearest text selection; out-of-range positions never throw. `'start'` and `'end'` jump to the document edges. Without a selection, the current one is mapped through the change. Restore a snapshot with `handle.setState(...handle.getState())`.
 - `getSelection(): SelectionJSON`: returns the current selection.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, Ref } from "react";
-import { ImageOptions, MarkMode, MarkMode as MarkMode$1, PlaceholderOptions, RoundTripFidelity, TypedEditor, TypedEditor as TypedEditor$1, WikilinkClickHandler, checkRoundTrip } from "@meowdown/core";
+import { EDITOR_KEY_BINDINGS, ImageOptions, MarkMode, MarkMode as MarkMode$1, PlaceholderOptions, RoundTripFidelity, TypedEditor, TypedEditor as TypedEditor$1, WikilinkClickHandler, checkRoundTrip } from "@meowdown/core";
 import { SelectionJSON, SelectionJSON as SelectionJSON$1 } from "@prosekit/core";
 import { useEditor } from "@prosekit/react";
 
@@ -91,7 +91,10 @@ interface EditorProps {
    * first render is used; later changes are ignored.
    */
   initialMarkdown?: string;
-  /** Called on every document change. */
+  /**
+   * Called on every user-driven document change. Programmatic `setMarkdown` and
+   * `setState` on the handle do not fire it.
+   */
   onDocChange?: VoidFunction;
   /**
    * Searches tags for the tag menu, which opens when typing `#` followed by
@@ -144,11 +147,11 @@ interface EditorProps {
   /** Class on the outer `.meowdown` wrapper div. */
   wrapperClassName?: string;
   /** Imperative handle for the editor. */
-  ref?: Ref<EditorHandle>;
+  handleRef?: Ref<EditorHandle>;
   /** Nodes rendered inside the editor's ProseKit context (rich modes only). */
   children?: ReactNode;
 }
-declare function Editor({
+declare function MeowdownEditor({
   mode,
   initialMarkdown,
   onDocChange,
@@ -163,8 +166,8 @@ declare function Editor({
   spellCheck,
   editorClassName,
   wrapperClassName,
-  ref,
+  handleRef,
   children
 }: EditorProps): import("react").JSX.Element;
 //#endregion
-export { Editor, type EditorHandle, type EditorMode, type EditorProps, type EditorStateSnapshot, type MarkMode, type RoundTripFidelity, type SelectionHint, type SelectionJSON, type TagItem, type TagSearchHandler, type TypedEditor, type WikilinkItem, type WikilinkSearchHandler, checkRoundTrip, useEditor };
+export { EDITOR_KEY_BINDINGS, type EditorHandle, type EditorMode, type EditorProps, type EditorStateSnapshot, type MarkMode, MeowdownEditor, type RoundTripFidelity, type SelectionHint, type SelectionJSON, type TagItem, type TagSearchHandler, type TypedEditor, type WikilinkItem, type WikilinkSearchHandler, checkRoundTrip, useEditor };

package/dist/index.js

@@ -7,7 +7,7 @@ import { Compartment, EditorSelection, EditorState } from "@codemirror/state";
 import { EditorView, keymap } from "@codemirror/view";
 import { clamp } from "@ocavue/utils";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { checkRoundTrip, codeBlockLanguages, defineEditorExtension, defineImages, defineMarkMode, definePlaceholder, defineReadonly, defineWikilinkClickHandler, docToMarkdown, markdownToDoc } from "@meowdown/core";
+import { EDITOR_KEY_BINDINGS, checkRoundTrip, codeBlockLanguages, defineEditorExtension, defineImages, defineMarkMode, definePlaceholder, defineReadonly, defineWikilinkClickHandler, docToMarkdown, markdownToDoc } from "@meowdown/core";
 import { canUseRegexLookbehind, createEditor, defineDocChangeHandler, union } from "@prosekit/core";
 import { Selection, TextSelection } from "@prosekit/pm/state";
 import { ProseKit, defineReactNodeView, useEditor, useEditor as useEditor$1, useExtension } from "@prosekit/react";
@@ -26,6 +26,7 @@ function CodeMirrorEditor({ initialMarkdown, onDocChange, readOnly, ref }) {
 	const containerRef = useRef(null);
 	const viewRef = useRef(null);
 	const readOnlyCompartmentRef = useRef(new Compartment());
+	const suppressDocChangeRef = useRef(false);
 	const onDocChangeRef = useRef(onDocChange);
 	useLayoutEffect(() => {
 		onDocChangeRef.current = onDocChange;
@@ -55,15 +56,20 @@ function CodeMirrorEditor({ initialMarkdown, onDocChange, readOnly, ref }) {
 			}
 			if (markdown == null && !selection) return;
 			const docLength = markdown == null ? view.state.doc.length : markdown.length;
-			view.dispatch({
-				changes: markdown == null ? void 0 : {
-					from: 0,
-					to: view.state.doc.length,
-					insert: markdown
-				},
-				selection: selection ? resolveSelection$1(selection, docLength) : void 0,
-				scrollIntoView: true
-			});
+			suppressDocChangeRef.current = true;
+			try {
+				view.dispatch({
+					changes: markdown == null ? void 0 : {
+						from: 0,
+						to: view.state.doc.length,
+						insert: markdown
+					},
+					selection: selection ? resolveSelection$1(selection, docLength) : void 0,
+					scrollIntoView: true
+				});
+			} finally {
+				suppressDocChangeRef.current = false;
+			}
 		}
 		function setMarkdown(markdown) {
 			setState(markdown);
@@ -104,7 +110,7 @@ function CodeMirrorEditor({ initialMarkdown, onDocChange, readOnly, ref }) {
 					EditorView.lineWrapping,
 					readOnlyCompartmentRef.current.of(EditorState.readOnly.of(initialReadOnlyRef.current)),
 					EditorView.updateListener.of((update) => {
-						if (!update.docChanged) return;
+						if (!update.docChanged || suppressDocChangeRef.current) return;
 						onDocChangeRef.current?.();
 					})
 				]
@@ -429,22 +435,31 @@ function DropIndicator$1() {
 //#endregion
 //#region src/components/editor-extensions.tsx
 function EditorExtensions({ markMode, onDocChange, onWikilinkClick, resolveImageUrl, onImagePaste, onImageSaveError, placeholder, readOnly }) {
-	useExtension(useMemo(() => defineMarkMode(markMode), [markMode]));
-	useExtension(useMemo(() => readOnly ? defineReadonly() : null, [readOnly]));
-	useExtension(useMemo(() => onDocChange ? defineDocChangeHandler(onDocChange) : null, [onDocChange]));
-	useExtension(useMemo(() => onWikilinkClick ? defineWikilinkClickHandler(onWikilinkClick) : null, [onWikilinkClick]));
-	useExtension(useMemo(() => resolveImageUrl ? defineImages({
-		resolveImageUrl,
-		onImagePaste,
-		onImageSaveError
-	}) : null, [
+	useExtension(useMemo(() => {
+		return defineMarkMode(markMode);
+	}, [markMode]));
+	useExtension(useMemo(() => {
+		return readOnly ? defineReadonly() : null;
+	}, [readOnly]));
+	useExtension(useMemo(() => {
+		return onDocChange ? defineDocChangeHandler(onDocChange) : null;
+	}, [onDocChange]));
+	useExtension(useMemo(() => {
+		return onWikilinkClick ? defineWikilinkClickHandler(onWikilinkClick) : null;
+	}, [onWikilinkClick]));
+	useExtension(useMemo(() => {
+		return resolveImageUrl ? defineImages({
+			resolveImageUrl,
+			onImagePaste,
+			onImageSaveError
+		}) : null;
+	}, [
 		resolveImageUrl,
 		onImagePaste,
 		onImageSaveError
 	]));
 	useExtension(useMemo(() => {
-		if (!placeholder) return null;
-		return definePlaceholder({ placeholder });
+		return placeholder ? definePlaceholder({ placeholder }) : null;
 	}, [placeholder]));
 	return null;
 }
@@ -686,6 +701,7 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 		if (initialMarkdown) editor.setContent(markdownToDoc(editor, initialMarkdown));
 		return editor;
 	});
+	const suppressDocChangeRef = useRef(false);
 	useImperativeHandle(ref, () => {
 		function getMarkdown() {
 			return docToMarkdown(editor.state.doc);
@@ -704,7 +720,12 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 				transaction.replaceWith(0, transaction.doc.content.size, doc.content);
 			}
 			if (selection) transaction.setSelection(resolveSelection(transaction.doc, selection)).scrollIntoView();
-			editor.view.dispatch(transaction);
+			suppressDocChangeRef.current = true;
+			try {
+				editor.view.dispatch(transaction);
+			} finally {
+				suppressDocChangeRef.current = false;
+			}
 		}
 		function setMarkdown(markdown) {
 			setState(markdown);
@@ -730,6 +751,13 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 			editor
 		};
 	}, [editor]);
+	const handleDocChange = useMemo(() => {
+		if (!onDocChange) return void 0;
+		return () => {
+			if (suppressDocChangeRef.current) return;
+			onDocChange();
+		};
+	}, [onDocChange]);
 	return /* @__PURE__ */ jsxs(ProseKit, {
 		editor,
 		children: [
@@ -740,7 +768,7 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 			}),
 			/* @__PURE__ */ jsx(EditorExtensions, {
 				markMode,
-				onDocChange,
+				onDocChange: handleDocChange,
 				onWikilinkClick,
 				resolveImageUrl,
 				onImagePaste,
@@ -760,9 +788,9 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 
 //#endregion
 //#region src/components/editor.tsx
-function Editor({ mode = "focus", initialMarkdown, onDocChange, onTagSearch, onWikilinkSearch, onWikilinkClick, resolveImageUrl, onImagePaste, onImageSaveError, placeholder, readOnly, spellCheck, editorClassName, wrapperClassName, ref, children }) {
+function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onTagSearch, onWikilinkSearch, onWikilinkClick, resolveImageUrl, onImagePaste, onImageSaveError, placeholder, readOnly, spellCheck, editorClassName, wrapperClassName, handleRef, children }) {
 	const childRef = useRef(null);
-	useImperativeHandle(ref, () => {
+	useImperativeHandle(handleRef, () => {
 		function getMarkdown() {
 			return childRef.current?.getMarkdown() ?? "";
 		}
@@ -838,4 +866,4 @@ function Editor({ mode = "focus", initialMarkdown, onDocChange, onTagSearch, onW
 }
 
 //#endregion
-export { Editor, checkRoundTrip, useEditor };
+export { EDITOR_KEY_BINDINGS, MeowdownEditor, checkRoundTrip, useEditor };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meowdown/react",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@prosekit/pm": "^0.1.18",
     "@prosekit/react": "^0.8.0-beta.0",
     "clsx": "^2.1.1",
-    "@meowdown/core": "0.4.0"
+    "@meowdown/core": "0.5.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -43,7 +43,7 @@
     }
   },
   "devDependencies": {
-    "@css-modules-kit/codegen": "^1.2.0",
+    "@css-modules-kit/codegen": "^1.3.0",
     "@ocavue/tsconfig": "^0.7.1",
     "@tsdown/css": "^0.22.2",
     "@types/react": "^19.2.17",