@meowdown/react 0.3.0 → 0.5.0

package/README.md

@@ -32,15 +32,43 @@ 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`
 
 Imperative handle for the editor, attached via `ref`.
 
 - `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.
+- `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.
+- `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.
 
 ## Keyboard shortcuts
 
@@ -55,13 +83,7 @@ In the rich modes (`focus` / `show` / `hide`), these toggle inline formatting on
 
 ## Styling
 
-`@meowdown/react/style.css` includes the default theme from [`@meowdown/core`](https://www.npmjs.com/package/@meowdown/core). Colors follow the page's `color-scheme`; customize via the `--meowdown-*` CSS variables documented there. The editor reserves a horizontal gutter (`--meowdown-gutter`) so the block handle has room to the left of the hovered block.
-
-Selection colors are standalone variables (independent from `--meowdown-accent`):
-
-- `--meowdown-node-outline`: outline of a selected node (e.g. a block grabbed by its handle).
-- `--meowdown-node-selection`: background wash of a selected node.
-- `--meowdown-selection`: text `::selection` background.
+`@meowdown/react/style.css` includes the default theme from [`@meowdown/core`](https://www.npmjs.com/package/@meowdown/core).
 
 ## License
 

package/dist/index.d.ts

@@ -1,26 +1,80 @@
-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. */
+type SelectionHint = SelectionJSON$1 | 'start' | 'end';
+/**
+ * The current Markdown and selection. Selection positions are in the mounted
+ * editor's coordinate space: ProseMirror positions in the rich modes,
+ * character offsets in source mode. Not portable across a mode switch.
+ */
+type EditorStateSnapshot = [markdown: string, selection: SelectionJSON$1];
 interface EditorHandle {
   /**
    * Serializes the current document to Markdown. Can be expensive on large
    * documents; call it on demand (e.g. throttled) instead of on every change.
    */
   getMarkdown: () => string;
+  /** Replaces the whole document as a single undoable edit. */
+  setMarkdown: (markdown: string) => void;
+  /** Returns the current Markdown and selection. */
+  getState: () => EditorStateSnapshot;
+  /**
+   * 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. Without a selection, the current one
+   * is mapped through the change.
+   */
+  setState: (markdown?: string, selection?: SelectionHint) => void;
+  /** Returns the current selection. */
+  getSelection: () => SelectionJSON$1;
+  /** Restores a selection with the same hint semantics as `setState`. */
+  setSelection: (selection: SelectionHint) => void;
+  /** Focuses the editor. */
+  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';
@@ -56,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,
@@ -65,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 MarkMode, 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 };