@meowdown/react 0.4.0 → 0.5.0

package/README.md

@@ -32,9 +32,27 @@ The Markdown editor component. Renders inside a `div.meowdown` wrapper that fill
   - `'source'`: raw Markdown source with syntax highlighting.
 - `initialMarkdown?: string`: first render only.
 - `onDocChange?: VoidFunction`: called on every document change.
-- `onTagSearch?: (query: string) => string[] | Promise<string[]>`: enables the tag menu, which opens when typing `#` followed by text in a rich mode; returns the tags to show for a query (lowercased, punctuation stripped). Omit to disable.
-- `onWikilinkSearch?: (query: string) => string[] | Promise<string[]>`: enables the wikilink menu, which opens as soon as `[[` is typed in a rich mode; returns the note names to show for a query (lowercased, punctuation stripped, may be empty). Selecting a note inserts `[[Note Name]]`. Omit to disable.
+- `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.
+- `resolveImageUrl?: (src: string) => string | undefined`: maps an image `src` to a displayable URL (or `undefined` to skip). Enables inline image rendering: `![alt](src)` stays literal text and the image renders beneath its line. Pass a stable function. Ignored in source mode.
+- `onImagePaste?: (file: File) => Promise<string | undefined>`: persists a pasted or dropped image file and returns its markdown `src` (or `undefined` to decline). Pass a stable function. Ignored in source mode.
+- `onImageSaveError?: (error: Error, file: File) => void`: called when `onImagePaste` throws. Defaults to `console.error`. Ignored in source mode.
+- `placeholder?: string | ((state) => string)`: placeholder text shown in an empty block. Pass a stable function. Ignored in source mode.
+- `readOnly?: boolean`: makes the editor read-only, in both the rich and source modes.
+- `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>`
+- `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`
+
+Re-exported from `@prosekit/react`. Call it from a component passed as `children` to read the live editor instance.
+
+### `checkRoundTrip`
+
+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.
 
 ### `EditorHandle`
 
@@ -48,6 +66,7 @@ Imperative handle for the editor, attached via `ref`.
 - `setSelection(selection: SelectionJSON | 'start' | 'end'): void`: restores a selection with the same hint semantics as `setState`.
 - `focus(): void`: focuses the editor.
 - `scrollIntoView(): void`: scrolls the selection into view.
+- `editor: TypedEditor | undefined`: escape hatch for the underlying ProseKit editor, `undefined` in source mode. No stability guarantees beyond what `@meowdown/core` exports.
 
 Selection positions are in the mounted editor's coordinate space: ProseMirror document positions in the rich modes, character offsets in source mode. They round-trip within one mode but are not portable across a mode switch.
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { Ref } from "react";
-import { MarkMode, MarkMode as MarkMode$1, TypedEditor } from "@meowdown/core";
+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 { SelectionJSON, SelectionJSON as SelectionJSON$1 } from "@prosekit/core";
+import { useEditor } from "@prosekit/react";
 
 //#region src/components/types.d.ts
 /** A selection to restore: an exact JSON selection, or a document edge. */
@@ -36,19 +37,44 @@ interface EditorHandle {
   focus: () => void;
   /** Scrolls the selection into view. */
   scrollIntoView: () => void;
+  /** Escape hatch: the underlying ProseKit editor, or `undefined` in source mode. */
+  readonly editor: TypedEditor$1 | undefined;
+}
+/**
+/** One row in the tag menu. The host ranks the rows; the menu does not re-sort. */
+interface TagItem {
+  /** Inserted as `#tag `. */
+  tag: string;
+  /** Display text; defaults to `#tag`. */
+  label?: string;
+  /** Secondary text shown beside the label. */
+  detail?: string;
+  /** Side effect run after the tag is inserted (e.g. create the tag). */
+  onSelect?: () => void;
 }
 /**
  * Searches tags for the tag menu. Receives the query typed after `#`
- * (lowercased, punctuation stripped) and returns the tags to show, either
+ * (lowercased, punctuation stripped) and returns the rows to show, either
  * synchronously or as a promise.
  */
-type TagSearchHandler = (query: string) => string[] | Promise<string[]>;
+type TagSearchHandler = (query: string) => TagItem[] | Promise<TagItem[]>;
+/** One row in the wikilink menu. The host ranks the rows; the menu does not re-sort. */
+interface WikilinkItem {
+  /** Inserted as `[[target]]`. */
+  target: string;
+  /** Display text; defaults to `target`. */
+  label?: string;
+  /** Secondary text shown beside the label. */
+  detail?: string;
+  /** Side effect run after the link is inserted (e.g. create the note). */
+  onSelect?: () => void;
+}
 /**
  * Searches notes for the wikilink menu. Receives the query typed after
  * `[[` (lowercased, punctuation stripped, may be empty or contain spaces)
- * and returns the note names to show, either synchronously or as a promise.
+ * and returns the rows to show, either synchronously or as a promise.
  */
-type WikilinkSearchHandler = (query: string) => string[] | Promise<string[]>;
+type WikilinkSearchHandler = (query: string) => WikilinkItem[] | Promise<WikilinkItem[]>;
 //#endregion
 //#region src/components/editor.d.ts
 type EditorMode = MarkMode$1 | 'source';
@@ -84,8 +110,43 @@ interface EditorProps {
    * mode.
    */
   onWikilinkSearch?: WikilinkSearchHandler;
+  /**
+   * Called with the link target on click of a rendered wiki link. Pass a stable
+   * function (e.g. from `useCallback`). Ignored in source mode.
+   */
+  onWikilinkClick?: WikilinkClickHandler;
+  /**
+   * Maps an image `src` to a displayable URL (or `undefined` to skip). Enables
+   * inline image rendering. Pass a stable function. Ignored in source mode.
+   */
+  resolveImageUrl?: ImageOptions['resolveImageUrl'];
+  /**
+   * Persists a pasted/dropped image file and returns its markdown `src`. Pass a
+   * stable function. Ignored in source mode.
+   */
+  onImagePaste?: ImageOptions['onImagePaste'];
+  /** Called when persisting a pasted/dropped image throws. Ignored in source mode. */
+  onImageSaveError?: ImageOptions['onImageSaveError'];
+  /**
+   * Placeholder text shown in an empty block. A function receives the editor
+   * state. Pass a stable function. Ignored in source mode.
+   */
+  placeholder?: PlaceholderOptions['placeholder'];
+  /** Makes the editor read-only, in both the rich and source modes. */
+  readOnly?: boolean;
+  /**
+   * Enables the browser's native spell checking in the rich modes. Defaults
+   * to the browser's behavior. Ignored in source mode.
+   */
+  spellCheck?: boolean;
+  /** Class on the editable root (the contenteditable). Rich modes only. */
+  editorClassName?: string;
+  /** Class on the outer `.meowdown` wrapper div. */
+  wrapperClassName?: string;
   /** Imperative handle for the editor. */
   ref?: Ref<EditorHandle>;
+  /** Nodes rendered inside the editor's ProseKit context (rich modes only). */
+  children?: ReactNode;
 }
 declare function Editor({
   mode,
@@ -93,7 +154,17 @@ declare function Editor({
   onDocChange,
   onTagSearch,
   onWikilinkSearch,
-  ref
+  onWikilinkClick,
+  resolveImageUrl,
+  onImagePaste,
+  onImageSaveError,
+  placeholder,
+  readOnly,
+  spellCheck,
+  editorClassName,
+  wrapperClassName,
+  ref,
+  children
 }: EditorProps): import("react").JSX.Element;
 //#endregion
-export { Editor, type EditorHandle, type EditorMode, type EditorProps, type EditorStateSnapshot, type MarkMode, type SelectionHint, type SelectionJSON, type TagSearchHandler, type TypedEditor, type WikilinkSearchHandler };
+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 };