@meowdown/react 0.30.1 → 0.32.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode, Ref } from "react";
-import { ExitBoundaryHandler, ImageClickHandler, ImageOptions, LinkClickHandler, LinkCopyHandler, MarkMode, PlaceholderOptions, TagClickHandler, TypedEditor, WikilinkClickHandler } from "@meowdown/core";
+import { AcceptPendingReplacementOptions, ExitBoundaryHandler, FileClickHandler, FileLinkResolver, FilePasteOptions, FileViewOptions, ImageClickHandler, ImageOptions, LinkClickHandler, LinkCopyHandler, MarkMode, PendingReplacement, PendingReplacementOutcome, PlaceholderOptions, StartPendingReplacementOptions, TagClickHandler, TypedEditor, WikilinkClickHandler } from "@meowdown/core";
 import { SelectionJSON, SelectionJSON as SelectionJSON$1 } from "@prosekit/core";
 import { useEditor, useExtension, useKeymap } from "@prosekit/react";
 
@@ -22,6 +22,15 @@ interface EditorHandle {
   getMarkdown: () => string;
   /** Replaces the whole document as a single undoable edit. */
   setMarkdown: (markdown: string) => void;
+  /**
+   * Parses `markdown` and inserts it at the current selection as a single
+   * undoable edit, replacing any selected content. A lone paragraph is
+   * inserted inline at the cursor; anything else is inserted as blocks. The
+   * cursor lands at the end of the inserted content. An empty or
+   * whitespace-only string is a no-op. Unlike `setMarkdown`, it fires
+   * `onDocChange`: the host cannot know the resulting document.
+   */
+  insertMarkdown: (markdown: string) => void;
   /** Returns the current Markdown and selection. */
   getState: () => EditorStateSnapshot;
   /**
@@ -39,13 +48,56 @@ interface EditorHandle {
   focus: () => void;
   /** Scrolls the selection into view. */
   scrollIntoView: () => void;
+  /**
+   * The current selection as Markdown: block structure (list markers,
+   * headings) is serialized, and inline syntax is already literal text. A
+   * selection inside one textblock comes back as its bare text.
+   */
+  getSelectedText: () => string;
+  /**
+   * Opens the selection menu over the current selection. A no-op when the
+   * selection is empty or `onSelectionMenuSearch` is not set.
+   */
+  openSelectionMenu: () => void;
+  /**
+   * Stages a pending replacement over a document range. Returns `false` when
+   * the range is invalid. Calling it again resets the accumulated text, which
+   * is how a retry starts.
+   */
+  startPendingReplacement: (options: StartPendingReplacementOptions) => boolean;
+  /** Appends streamed text to the staged replacement. */
+  appendPendingReplacementText: (text: string) => void;
+  /**
+   * Applies the staged replacement to the document as a single edit. Pass a
+   * `mode` to override the staged placement for this accept (e.g. "Insert
+   * below" on a replace stage).
+   */
+  acceptPendingReplacement: (options?: AcceptPendingReplacementOptions) => void;
+  /** Clears the staged replacement without touching the document. */
+  discardPendingReplacement: () => void;
   /**
    * Escape hatch: the underlying ProseKit editor, or `undefined` when the
    * handle does not wrap one.
    */
   readonly editor: TypedEditor | undefined;
 }
+/** One row of host items in the slash menu. The host ranks the rows; the menu does not re-sort. */
+interface SlashMenuItem {
+  /** Stable row key; defaults to `label`. */
+  id?: string;
+  /** Display text, matched against the typed query like the built-in items. */
+  label: string;
+  /** Secondary text shown beside the label. */
+  detail?: string;
+  /** Runs after the menu closes and the typed `/query` text is removed. */
+  onSelect: () => void;
+}
 /**
+ * Searches host items for the slash menu. Receives the query typed after `/`
+ * (lowercased, punctuation stripped; may be empty) and returns the rows to
+ * show after the built-in items, either synchronously or as a promise.
+ */
+type SlashMenuSearchHandler = (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
 /** One row in the tag menu. The host ranks the rows; the menu does not re-sort. */
 interface TagItem {
   /** Inserted as `#tag `. */
@@ -81,6 +133,34 @@ interface WikilinkItem {
  * a promise.
  */
 type WikilinkSearchHandler = (query: string) => WikilinkItem[] | Promise<WikilinkItem[]>;
+/** The selection the selection menu was opened over. */
+interface SelectionMenuContext {
+  /** The selected text, with block boundaries as blank lines. */
+  selectedText: string;
+  /** Start of the selection. */
+  from: number;
+  /** End of the selection. */
+  to: number;
+}
+/** One row in the selection menu. The host ranks the rows; the menu does not re-sort. */
+interface SelectionMenuItem {
+  /** Stable identity for the row. */
+  id: string;
+  /** Display text. */
+  label: string;
+  /** Secondary text shown beside the label. */
+  detail?: string;
+  /** Runs when the row is picked, with the selection the menu was opened over. */
+  onSelect: (context: SelectionMenuContext) => void;
+}
+/**
+ * Searches commands for the selection menu. Receives the filter text typed in
+ * the menu (may be empty) and the selection the menu was opened over, and
+ * returns the rows to show, either synchronously or as a promise.
+ */
+type SelectionMenuSearchHandler = (query: string, context: SelectionMenuContext) => SelectionMenuItem[] | Promise<SelectionMenuItem[]>;
+/** Reports how a pending replacement ended and its final staged value. */
+type PendingReplacementResolveHandler = (outcome: PendingReplacementOutcome, pending: PendingReplacement) => void;
 //#endregion
 //#region src/components/editor.d.ts
 type EditorMode = MarkMode;
@@ -100,6 +180,16 @@ interface EditorProps {
    * `setState` on the handle do not fire it.
    */
   onDocChange?: VoidFunction;
+  /**
+   * Searches host items for the slash menu, which opens when typing `/`.
+   * Receives the query (lowercased, punctuation stripped, may be empty) and
+   * returns the items to show after the built-in ones, synchronously or as a
+   * promise. Selecting an item removes the typed `/query` text before its
+   * `onSelect` runs, so `onSelect` can insert at the cursor (e.g. via the
+   * handle's `insertMarkdown`). Pass a stable function (e.g. from
+   * `useCallback`). Omit to show only the built-in items.
+   */
+  onSlashMenuSearch?: SlashMenuSearchHandler;
   /**
    * Searches tags for the tag menu, which opens when typing `#` followed by
    * text. Receives the query (lowercased, punctuation stripped) and returns the
@@ -116,13 +206,42 @@ interface EditorProps {
    */
   onWikilinkSearch?: WikilinkSearchHandler;
   /**
-   * Called with the link target on click of a rendered wiki link. Pass a stable
-   * function (e.g. from `useCallback`).
+   * Searches commands for the selection menu, which opens over a non-empty
+   * selection via `EditorHandle.openSelectionMenu()` or the selection
+   * affordance. Receives the filter text typed in the menu (may be empty) and
+   * the selection the menu was opened over, and returns the rows to show,
+   * synchronously or as a promise. The host ranks the rows; the menu does not
+   * re-sort. Pass a stable function (e.g. from `useCallback`). Omit to disable
+   * the selection menu.
+   */
+  onSelectionMenuSearch?: SelectionMenuSearchHandler;
+  /**
+   * Shows a small floating button on a non-empty text selection that opens the
+   * selection menu. On by default; only relevant when `onSelectionMenuSearch`
+   * is set. Ignored when `readOnly` is set.
+   */
+  selectionMenuAffordance?: boolean;
+  /**
+   * Extra controls rendered in the pending-replacement preview footer, next to
+   * the built-in Accept and Discard buttons (e.g. a retry button).
+   */
+  pendingReplacementActions?: ReactNode;
+  /**
+   * Called when a pending replacement ends, with the outcome ('accepted' or
+   * 'discarded') and the final staged value. Use it to stop a stream that is
+   * still appending. Pass a stable function (e.g. from `useCallback`).
+   */
+  onPendingReplacementResolve?: PendingReplacementResolveHandler;
+  /**
+   * Called with the link target on click of a rendered wiki link, or on
+   * `Mod-Enter` with the caret on one. Pass a stable function (e.g. from
+   * `useCallback`).
    */
   onWikilinkClick?: WikilinkClickHandler;
   /**
    * Called with the link `href` on click of a rendered Markdown link
-   * (`[text](url)`). Pass a stable function (e.g. from `useCallback`).
+   * (`[text](url)`), or on `Mod-Enter` with the caret on one. Pass a stable
+   * function (e.g. from `useCallback`).
    */
   onLinkClick?: LinkClickHandler;
   /**
@@ -132,7 +251,8 @@ interface EditorProps {
   onLinkCopy?: LinkCopyHandler;
   /**
    * Called with the tag name (without the leading `#`) on click of a rendered
-   * `#tag`. Pass a stable function (e.g. from `useCallback`).
+   * `#tag`, or on `Mod-Enter` with the caret on one. Pass a stable function
+   * (e.g. from `useCallback`).
    */
   onTagClick?: TagClickHandler;
   /**
@@ -152,12 +272,37 @@ interface EditorProps {
    */
   resolveImageUrl?: ImageOptions['resolveImageUrl'];
   /**
-   * Persists a pasted/dropped image file and returns its markdown `src`. Pass a
-   * stable function.
+   * Claims a `[label](url)` link as a file: a claimed link renders as an
+   * inline pill (file icon, name, size) instead of a link, behaves as one
+   * caret unit, and reports clicks through `onFileClick` instead of
+   * `onLinkClick`. The markdown text is untouched. Must be pure (same link,
+   * same answer). Read once when the editor is created: later identity
+   * changes are ignored, like `initialMarkdown`.
+   */
+  resolveFileLink?: FileLinkResolver;
+  /**
+   * Resolves the metadata (file size in bytes) shown on a file pill, directly
+   * or as a promise; the pill renders immediately and fills the size in when
+   * the promise settles. May be called repeatedly for the same `href`, so
+   * cache in the host when resolving is expensive. Pass a stable function
+   * (e.g. from `useCallback`).
+   */
+  resolveFileInfo?: FileViewOptions['resolveFileInfo'];
+  /**
+   * Called when the user clicks a rendered file pill (or presses `Mod-Enter`
+   * with the caret on one), with its `href`, `name`, and the originating
+   * event. The host decides what a click does (e.g. open the file in the OS
+   * default app). Pass a stable function (e.g. from `useCallback`).
+   */
+  onFileClick?: FileClickHandler;
+  /**
+   * Persists a pasted/dropped file and returns its markdown destination,
+   * inserted as `![](src)` for an image and as a `[name](src)` link for any
+   * other file. Return `undefined` to decline. Pass a stable function.
    */
-  onImagePaste?: ImageOptions['onImagePaste'];
-  /** Called when persisting a pasted/dropped image throws. */
-  onImageSaveError?: ImageOptions['onImageSaveError'];
+  onFilePaste?: FilePasteOptions['onFilePaste'];
+  /** Called when persisting a pasted/dropped file throws. */
+  onFileSaveError?: FilePasteOptions['onFileSaveError'];
   /**
    * Called when the user clicks a rendered image, with its markdown `src`,
    * `alt`, and the originating `MouseEvent`. Pass a stable function (e.g. from
@@ -215,16 +360,24 @@ declare function MeowdownEditor({
   mode,
   initialMarkdown,
   onDocChange,
+  onSlashMenuSearch,
   onTagSearch,
   onWikilinkSearch,
+  onSelectionMenuSearch,
+  selectionMenuAffordance,
+  pendingReplacementActions,
+  onPendingReplacementResolve,
   onWikilinkClick,
   onLinkClick,
   onLinkCopy,
   onTagClick,
   onExitBoundary,
   resolveImageUrl,
-  onImagePaste,
-  onImageSaveError,
+  resolveFileLink,
+  resolveFileInfo,
+  onFileClick,
+  onFilePaste,
+  onFileSaveError,
   onImageClick,
   embedPaste,
   bulletAfterHeading,
@@ -281,4 +434,4 @@ declare function MarkdownView({
   className
 }: MarkdownViewProps): ReactElement;
 //#endregion
-export { type EditorHandle, type EditorMode, type EditorProps, type EditorStateSnapshot, MarkdownView, type MarkdownViewProps, MeowdownEditor, type SelectionHint, type SelectionJSON, type TagItem, type TagSearchHandler, type TimeFormat, type WikilinkItem, type WikilinkSearchHandler, useEditor, useExtension, useKeymap };
+export { type EditorHandle, type EditorMode, type EditorProps, type EditorStateSnapshot, MarkdownView, type MarkdownViewProps, MeowdownEditor, type PendingReplacementResolveHandler, type SelectionHint, type SelectionJSON, type SelectionMenuContext, type SelectionMenuItem, type SelectionMenuSearchHandler, type SlashMenuItem, type SlashMenuSearchHandler, type TagItem, type TagSearchHandler, type TimeFormat, type WikilinkItem, type WikilinkSearchHandler, useEditor, useExtension, useKeymap };

package/dist/index.js

@@ -1,12 +1,12 @@
 import { clsx } from "clsx/lite";
 import { Fragment, createElement, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { codeBlockLanguages, defaultResolveImageUrl, defineBulletAfterHeading, defineEditorExtension, defineEmbedPaste, defineExitBoundaryHandler, defineHTMLPaste, defineImage, defineImageClickHandler, defineLinkClickHandler, defineLinkEditKeymap, defineLinkHoverHandler, defineMarkMode, defineMarkdownCopy, definePlaceholder, defineReadonly, defineSpellCheckPlugin, defineTagClickHandler, defineWikilinkClickHandler, defineWikilinkTrigger, docToMarkdown, getCodeTokens, getMarkBuilders, getVirtualElementFromRange, inlineTextToMarkChunks, isSelectionInTableCell, listenForTweetHeight, markdownToDoc, matchEmbed } from "@meowdown/core";
+import { codeBlockLanguages, defaultResolveImageUrl, defineBulletAfterHeading, defineEditorExtension, defineEmbedPaste, defineExitBoundaryHandler, defineFileClickHandler, defineFilePaste, defineFileView, defineFollowLinkHandler, defineHTMLPaste, defineImage, defineImageClickHandler, defineLinkClickHandler, defineLinkEditKeymap, defineLinkHoverHandler, defineMarkMode, defineMarkdownCopy, definePendingReplacementHandler, definePlaceholder, defineReadonly, defineSpellCheckPlugin, defineTagClickHandler, defineWikilinkClickHandler, defineWikilinkTrigger, docToMarkdown, getCodeTokens, getMarkBuilders, getPendingReplacement, getSelectedText, getVirtualElementFromRange, inlineTextToMarkChunks, isSelectionInTableCell, listenForTweetHeight, markdownToDoc, matchEmbed } from "@meowdown/core";
 import { clamp } from "@ocavue/utils";
-import { canUseRegexLookbehind, createEditor, defineDocChangeHandler, union } from "@prosekit/core";
+import { canUseRegexLookbehind, createEditor, defineDocChangeHandler, defineUpdateHandler, isTextSelection, union } from "@prosekit/core";
 import { Selection, TextSelection } from "@prosekit/pm/state";
 import { ProseKit, defineReactNodeView, useEditor, useEditor as useEditor$1, useEditorDerivedValue, useExtension, useExtension as useExtension$1, useKeymap } from "@prosekit/react";
 import { Combobox } from "@base-ui/react/combobox";
-import { CheckIcon, ChevronsUpDownIcon, CopyIcon, GripHorizontalIcon, GripVerticalIcon, PencilIcon, UnlinkIcon } from "lucide-react";
+import { CheckIcon, ChevronsUpDownIcon, CopyIcon, GripHorizontalIcon, GripVerticalIcon, PencilIcon, SparklesIcon, UnlinkIcon } from "lucide-react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { BlockHandleDraggable, BlockHandlePopup, BlockHandlePositioner, BlockHandleRoot } from "@prosekit/react/block-handle";
 import { DropIndicator } from "@prosekit/react/drop-indicator";
@@ -216,7 +216,7 @@ function DropIndicator$1() {
 
 //#endregion
 //#region src/components/editor-extensions.tsx
-function EditorExtensions({ markMode, onDocChange, onWikilinkClick, onLinkClick, onTagClick, onExitBoundary, resolveImageUrl, onImagePaste, onImageSaveError, onImageClick, embedPaste, bulletAfterHeading, placeholder, readOnly, wikilinkEnabled, spellCheck }) {
+function EditorExtensions({ markMode, onDocChange, onWikilinkClick, onLinkClick, onTagClick, onExitBoundary, resolveImageUrl, resolveFileInfo, onFileClick, onFilePaste, onFileSaveError, onImageClick, embedPaste, bulletAfterHeading, placeholder, readOnly, wikilinkEnabled, spellCheck }) {
 	useExtension$1(useMemo(() => {
 		return defineMarkMode(markMode);
 	}, [markMode]));
@@ -235,20 +235,37 @@ function EditorExtensions({ markMode, onDocChange, onWikilinkClick, onLinkClick,
 	useExtension$1(useMemo(() => {
 		return onTagClick ? defineTagClickHandler(onTagClick) : null;
 	}, [onTagClick]));
+	useExtension$1(useMemo(() => {
+		return onWikilinkClick || onTagClick || onFileClick || onLinkClick ? defineFollowLinkHandler({
+			onWikilinkClick,
+			onTagClick,
+			onFileClick,
+			onLinkClick
+		}) : null;
+	}, [
+		onWikilinkClick,
+		onTagClick,
+		onFileClick,
+		onLinkClick
+	]));
 	useExtension$1(useMemo(() => {
 		return onExitBoundary ? defineExitBoundaryHandler(onExitBoundary) : null;
 	}, [onExitBoundary]));
 	useExtension$1(useMemo(() => {
-		return defineImage({
-			resolveImageUrl,
-			onImagePaste,
-			onImageSaveError
-		});
-	}, [
-		resolveImageUrl,
-		onImagePaste,
-		onImageSaveError
-	]));
+		return defineImage({ resolveImageUrl });
+	}, [resolveImageUrl]));
+	useExtension$1(useMemo(() => {
+		return defineFileView({ resolveFileInfo });
+	}, [resolveFileInfo]));
+	useExtension$1(useMemo(() => {
+		return onFileClick ? defineFileClickHandler(onFileClick) : null;
+	}, [onFileClick]));
+	useExtension$1(useMemo(() => {
+		return onFilePaste ? defineFilePaste({
+			onFilePaste,
+			onFileSaveError
+		}) : null;
+	}, [onFilePaste, onFileSaveError]));
 	useExtension$1(useMemo(() => {
 		return onImageClick ? defineImageClickHandler(onImageClick) : null;
 	}, [onImageClick]));
@@ -542,6 +559,299 @@ function LinkMenu({ onLinkClick, onLinkCopy }) {
 	return null;
 }
 
+//#endregion
+//#region src/components/pending-replacement-preview.module.css
+var pending_replacement_preview_module_default = {
+	"AcceptButton": "meow_AcceptButton_DPJ5ia",
+	"Button": "meow_Button_DPJ5ia",
+	"Footer": "meow_Footer_DPJ5ia",
+	"Popup": "meow_Popup_DPJ5ia",
+	"Positioner": "meow_Positioner_DPJ5ia",
+	"Spacer": "meow_Spacer_DPJ5ia",
+	"Text": "meow_Text_DPJ5ia",
+	"Waiting": "meow_Waiting_DPJ5ia"
+};
+
+//#endregion
+//#region src/components/pending-replacement-preview.tsx
+/**
+* The preview for a staged (pending) replacement: a popover anchored to the
+* source range showing the accumulated text, with Accept and Discard controls
+* plus a host-provided `actions` slot. Dismissing the popover (Escape or an
+* outside press) discards the stage; the document is only touched on accept.
+*/
+function PendingReplacementPreview({ actions, onResolve }) {
+	const editor = useEditor$1();
+	const [pending, setPending] = useState(null);
+	useExtension$1(useMemo(() => {
+		return definePendingReplacementHandler((event) => {
+			if (event.type === "update") setPending(event.pending);
+			else {
+				setPending(null);
+				onResolve?.(event.outcome, event.pending);
+			}
+		});
+	}, [onResolve]));
+	const from = pending?.from;
+	const to = pending?.to;
+	const anchor = useMemo(() => {
+		if (from == null || to == null) return;
+		return getVirtualElementFromRange(editor.view, {
+			from,
+			to
+		});
+	}, [
+		from,
+		to,
+		editor
+	]);
+	if (!pending) return null;
+	const discard = () => {
+		editor.commands.discardPendingReplacement();
+		editor.focus();
+	};
+	const accept = () => {
+		editor.commands.acceptPendingReplacement();
+		editor.focus();
+	};
+	return /* @__PURE__ */ jsx(Popover.Root, {
+		open: true,
+		onOpenChange: (next) => {
+			if (!next) discard();
+		},
+		children: /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(Popover.Positioner, {
+			anchor,
+			side: "bottom",
+			sideOffset: 8,
+			className: pending_replacement_preview_module_default.Positioner,
+			children: /* @__PURE__ */ jsxs(Popover.Popup, {
+				className: pending_replacement_preview_module_default.Popup,
+				"data-testid": "pending-replacement",
+				initialFocus: false,
+				finalFocus: false,
+				children: [/* @__PURE__ */ jsx("div", {
+					className: pending_replacement_preview_module_default.Text,
+					"data-testid": "pending-replacement-text",
+					children: pending.text || /* @__PURE__ */ jsx("span", {
+						className: pending_replacement_preview_module_default.Waiting,
+						children: "Waiting for text..."
+					})
+				}), /* @__PURE__ */ jsxs("div", {
+					className: pending_replacement_preview_module_default.Footer,
+					children: [
+						actions,
+						/* @__PURE__ */ jsx("span", { className: pending_replacement_preview_module_default.Spacer }),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							className: pending_replacement_preview_module_default.Button,
+							"data-testid": "pending-replacement-discard",
+							onClick: discard,
+							children: "Discard"
+						}),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							className: pending_replacement_preview_module_default.AcceptButton,
+							"data-testid": "pending-replacement-accept",
+							disabled: !pending.text.trim(),
+							onClick: accept,
+							children: "Accept"
+						})
+					]
+				})]
+			})
+		}) })
+	});
+}
+
+//#endregion
+//#region src/components/selection-menu.module.css
+var selection_menu_module_default = {
+	"AffordanceButton": "meow_AffordanceButton_2_4Zjq",
+	"AffordancePopup": "meow_AffordancePopup_2_4Zjq",
+	"AffordancePositioner": "meow_AffordancePositioner_2_4Zjq",
+	"Detail": "meow_Detail_2_4Zjq",
+	"Empty": "meow_Empty_2_4Zjq",
+	"Input": "meow_Input_2_4Zjq",
+	"Item": "meow_Item_2_4Zjq",
+	"Label": "meow_Label_2_4Zjq",
+	"List": "meow_List_2_4Zjq",
+	"Popup": "meow_Popup_2_4Zjq",
+	"Positioner": "meow_Positioner_2_4Zjq"
+};
+
+//#endregion
+//#region src/components/selection-menu.tsx
+/**
+* A command menu over the current selection: a popover with a filter input and
+* host-supplied rows, anchored to the selected range. Opened imperatively (via
+* `EditorHandle.openSelectionMenu`) or from the selection affordance, a small
+* floating button that appears on a non-empty selection.
+*/
+function SelectionMenu({ onSelectionMenuSearch, context, onOpen, onClose, affordance = true }) {
+	const editor = useEditor$1();
+	const [selection, setSelection] = useState();
+	useExtension$1(useMemo(() => {
+		return defineUpdateHandler((view) => {
+			const { from, to, empty } = view.state.selection;
+			const anchorable = !empty && isTextSelection(view.state.selection) && !getPendingReplacement(view.state);
+			setSelection((previous) => {
+				if (previous?.from === from && previous?.to === to && previous?.anchorable === anchorable) return previous;
+				return {
+					from,
+					to,
+					anchorable
+				};
+			});
+		});
+	}, []));
+	const close = useCallback(() => {
+		onClose();
+		editor.focus();
+	}, [onClose, editor]);
+	const menuAnchor = useMemo(() => {
+		if (!context) return;
+		return getVirtualElementFromRange(editor.view, {
+			from: context.from,
+			to: context.to
+		});
+	}, [context, editor]);
+	const showAffordance = affordance && !!!context && !!selection?.anchorable;
+	const affordanceVisible = useDelayedFlag(showAffordance, 250, 0);
+	const affordanceAnchor = useMemo(() => {
+		if (!showAffordance || !selection) return;
+		return getVirtualElementFromRange(editor.view, {
+			from: selection.to,
+			to: selection.to
+		});
+	}, [
+		showAffordance,
+		selection,
+		editor
+	]);
+	if (context) return /* @__PURE__ */ jsx(Popover.Root, {
+		open: true,
+		onOpenChange: (next) => {
+			if (!next) close();
+		},
+		children: /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(Popover.Positioner, {
+			anchor: menuAnchor,
+			side: "bottom",
+			sideOffset: 8,
+			className: selection_menu_module_default.Positioner,
+			children: /* @__PURE__ */ jsx(Popover.Popup, {
+				className: selection_menu_module_default.Popup,
+				"data-testid": "selection-menu",
+				finalFocus: false,
+				children: /* @__PURE__ */ jsx(SelectionMenuPopup, {
+					onSelectionMenuSearch,
+					context,
+					onClose: close
+				})
+			})
+		}) })
+	});
+	if (affordanceVisible && showAffordance) return /* @__PURE__ */ jsx(Popover.Root, {
+		open: true,
+		onOpenChange: () => {},
+		children: /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(Popover.Positioner, {
+			anchor: affordanceAnchor,
+			side: "bottom",
+			sideOffset: 4,
+			className: selection_menu_module_default.AffordancePositioner,
+			children: /* @__PURE__ */ jsx(Popover.Popup, {
+				className: selection_menu_module_default.AffordancePopup,
+				"data-testid": "selection-menu-affordance",
+				initialFocus: false,
+				finalFocus: false,
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: selection_menu_module_default.AffordanceButton,
+					title: "Selection commands",
+					"aria-label": "Selection commands",
+					onPointerDown: (event) => event.preventDefault(),
+					onClick: onOpen,
+					children: /* @__PURE__ */ jsx(SparklesIcon, {})
+				})
+			})
+		}) })
+	});
+	return null;
+}
+/** The menu content. Mounted only while the menu is open, so its filter state
+*  resets naturally on close. */
+function SelectionMenuPopup({ onSelectionMenuSearch, context, onClose }) {
+	const [query, setQuery] = useState("");
+	const [items, setItems] = useState([]);
+	const [loading, setLoading] = useState(false);
+	const [activeIndex, setActiveIndex] = useState(0);
+	const fetchItems = useCallback(async (query, signal) => {
+		if (signal.aborted) return;
+		setLoading(true);
+		const result = await onSelectionMenuSearch(query, context);
+		if (signal.aborted) return;
+		setItems(result);
+		setActiveIndex(0);
+		setLoading(false);
+	}, [onSelectionMenuSearch, context]);
+	useEffect(() => {
+		const controller = new AbortController();
+		queueMicrotask(() => {
+			fetchItems(query, controller.signal);
+		});
+		return () => {
+			controller.abort();
+		};
+	}, [query, fetchItems]);
+	const selectItem = useCallback((item) => {
+		onClose();
+		item.onSelect(context);
+	}, [context, onClose]);
+	function onInputKeyDown(event) {
+		if (event.key === "ArrowDown") {
+			event.preventDefault();
+			setActiveIndex((index) => Math.min(index + 1, Math.max(items.length - 1, 0)));
+		} else if (event.key === "ArrowUp") {
+			event.preventDefault();
+			setActiveIndex((index) => Math.max(index - 1, 0));
+		} else if (event.key === "Enter") {
+			event.preventDefault();
+			const item = items[activeIndex];
+			if (item) selectItem(item);
+		}
+	}
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("input", {
+		autoFocus: true,
+		className: selection_menu_module_default.Input,
+		value: query,
+		placeholder: "Filter commands...",
+		"data-testid": "selection-menu-input",
+		onChange: (event) => setQuery(event.target.value),
+		onKeyDown: onInputKeyDown
+	}), /* @__PURE__ */ jsxs("div", {
+		role: "listbox",
+		className: selection_menu_module_default.List,
+		children: [items.map((item, index) => /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			role: "option",
+			"aria-selected": index === activeIndex,
+			className: selection_menu_module_default.Item,
+			"data-active": index === activeIndex || void 0,
+			onPointerEnter: () => setActiveIndex(index),
+			onClick: () => selectItem(item),
+			children: [/* @__PURE__ */ jsx("span", {
+				className: selection_menu_module_default.Label,
+				children: item.label
+			}), item.detail ? /* @__PURE__ */ jsx("span", {
+				className: selection_menu_module_default.Detail,
+				children: item.detail
+			}) : null]
+		}, item.id)), items.length === 0 ? /* @__PURE__ */ jsx("div", {
+			className: selection_menu_module_default.Empty,
+			children: loading ? "Loading..." : "No commands"
+		}) : null]
+	})] });
+}
+
 //#endregion
 //#region src/utils/date-format.ts
 /** Formats the current wall-clock time for the `/now` slash command. */
@@ -572,21 +882,57 @@ var autocomplete_menu_module_default = {
 //#endregion
 //#region src/components/slash-menu.tsx
 const regex$2 = canUseRegexLookbehind() ? /(?<!\S)\/(\S.*)?$/u : /\/(\S.*)?$/u;
-function SlashMenuItem({ label, kbd, onSelect }) {
+function SlashMenuItem({ label, detail, kbd, onSelect }) {
 	return /* @__PURE__ */ jsxs(AutocompleteItem, {
+		value: label,
 		className: autocomplete_menu_module_default.Item,
 		onSelect,
-		children: [/* @__PURE__ */ jsx("span", { children: label }), kbd && /* @__PURE__ */ jsx("kbd", { children: kbd })]
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: detail ? autocomplete_menu_module_default.Label : void 0,
+				children: label
+			}),
+			detail ? /* @__PURE__ */ jsx("span", {
+				className: autocomplete_menu_module_default.Detail,
+				children: detail
+			}) : null,
+			kbd && /* @__PURE__ */ jsx("kbd", { children: kbd })
+		]
 	});
 }
 function selectionInTableCell(editor) {
 	return isSelectionInTableCell(editor.state);
 }
-function SlashMenu({ timeFormat = "12" }) {
+function SlashMenu({ timeFormat = "12", onSlashMenuSearch }) {
 	const editor = useEditor$1();
 	const inTableCell = useEditorDerivedValue(selectionInTableCell);
+	const [open, setOpen] = useState(false);
+	const [query, setQuery] = useState("");
+	const [hostItems, setHostItems] = useState([]);
+	const fetchHostItems = useCallback(async (query, signal) => {
+		if (!onSlashMenuSearch || signal.aborted) return;
+		const result = await onSlashMenuSearch(query);
+		if (signal.aborted) return;
+		setHostItems(result);
+	}, [onSlashMenuSearch]);
+	useEffect(() => {
+		if (!open) return;
+		const controller = new AbortController();
+		queueMicrotask(() => {
+			fetchHostItems(query, controller.signal);
+		});
+		return () => {
+			controller.abort();
+		};
+	}, [
+		open,
+		query,
+		fetchHostItems
+	]);
 	return /* @__PURE__ */ jsx(AutocompleteRoot, {
 		regex: regex$2,
+		onOpenChange: (event) => setOpen(event.detail),
+		onQueryChange: (event) => setQuery(event.detail),
 		children: /* @__PURE__ */ jsx(AutocompletePositioner, {
 			className: autocomplete_menu_module_default.Positioner,
 			children: /* @__PURE__ */ jsxs(AutocompletePopup, {
@@ -657,6 +1003,11 @@ function SlashMenu({ timeFormat = "12" }) {
 						label: "Now",
 						onSelect: () => editor.commands.insertText({ text: formatNowTime(timeFormat) })
 					}),
+					hostItems.map((item) => /* @__PURE__ */ jsx(SlashMenuItem, {
+						label: item.label,
+						detail: item.detail,
+						onSelect: item.onSelect
+					}, item.id ?? item.label)),
 					/* @__PURE__ */ jsx(AutocompleteEmpty, {
 						className: autocomplete_menu_module_default.Item,
 						children: "No results"
@@ -977,9 +1328,9 @@ function resolveSelection(doc, selection) {
 		return TextSelection.between(doc.resolve(anchor), doc.resolve(head));
 	}
 }
-function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTagSearch, onWikilinkSearch, onWikilinkClick, onLinkClick, onLinkCopy, onTagClick, onExitBoundary, resolveImageUrl, onImagePaste, onImageSaveError, onImageClick, embedPaste, bulletAfterHeading, frontmatter = false, blockHandle = true, placeholder, readOnly, spellCheck, timeFormat, editorClassName, ref, children }) {
+function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onSlashMenuSearch, onTagSearch, onWikilinkSearch, onSelectionMenuSearch, selectionMenuAffordance = true, pendingReplacementActions, onPendingReplacementResolve, onWikilinkClick, onLinkClick, onLinkCopy, onTagClick, onExitBoundary, resolveImageUrl, resolveFileLink, resolveFileInfo, onFileClick, onFilePaste, onFileSaveError, onImageClick, embedPaste, bulletAfterHeading, frontmatter = false, blockHandle = true, placeholder, readOnly, spellCheck, timeFormat, editorClassName, ref, children }) {
 	const [editor] = useState(() => {
-		const editor = createEditor({ extension: union(defineEditorExtension(), defineCodeBlockView()) });
+		const editor = createEditor({ extension: union(defineEditorExtension({ resolveFileLink }), defineCodeBlockView()) });
 		if (initialMarkdown) editor.setContent(markdownToDoc(initialMarkdown, {
 			nodes: editor.nodes,
 			frontmatter
@@ -987,6 +1338,21 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 		return editor;
 	});
 	const suppressDocChangeRef = useRef(false);
+	const [selectionMenuContext, setSelectionMenuContext] = useState();
+	const hasSelectionMenu = !!onSelectionMenuSearch;
+	const openSelectionMenu = useCallback(() => {
+		const { state } = editor;
+		const { from, to, empty } = state.selection;
+		if (empty) return;
+		setSelectionMenuContext({
+			selectedText: getSelectedText(state),
+			from,
+			to
+		});
+	}, [editor]);
+	const closeSelectionMenu = useCallback(() => {
+		setSelectionMenuContext(void 0);
+	}, []);
 	useImperativeHandle(ref, () => {
 		function getMarkdown() {
 			return docToMarkdown(editor.state.doc, { frontmatter });
@@ -1018,6 +1384,9 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 		function setMarkdown(markdown) {
 			setState(markdown);
 		}
+		function insertMarkdown(markdown) {
+			editor.commands.insertMarkdown(markdown);
+		}
 		function setSelection(selection) {
 			setState(void 0, selection);
 		}
@@ -1027,18 +1396,49 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 		function scrollIntoView() {
 			editor.view.dispatch(editor.state.tr.scrollIntoView());
 		}
+		function getSelectedTextFromState() {
+			return getSelectedText(editor.state);
+		}
+		function openSelectionMenuFromHandle() {
+			if (!hasSelectionMenu) return;
+			openSelectionMenu();
+		}
+		function startPendingReplacement(options) {
+			return editor.commands.startPendingReplacement(options);
+		}
+		function appendPendingReplacementText(text) {
+			editor.commands.appendPendingReplacementText(text);
+		}
+		function acceptPendingReplacement(options) {
+			editor.commands.acceptPendingReplacement(options ?? {});
+		}
+		function discardPendingReplacement() {
+			editor.commands.discardPendingReplacement();
+		}
 		return {
 			getMarkdown,
 			setMarkdown,
+			insertMarkdown,
 			getState,
 			setState,
 			getSelection,
 			setSelection,
 			focus,
 			scrollIntoView,
+			getSelectedText: getSelectedTextFromState,
+			openSelectionMenu: openSelectionMenuFromHandle,
+			startPendingReplacement,
+			appendPendingReplacementText,
+			acceptPendingReplacement,
+			discardPendingReplacement,
 			editor
 		};
-	}, [editor, frontmatter]);
+	}, [
+		editor,
+		frontmatter,
+		hasSelectionMenu,
+		openSelectionMenu
+	]);
 	const handleDocChange = useMemo(() => {
 		if (!onDocChange) return;
 		return () => {
@@ -1061,8 +1461,10 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 				onTagClick,
 				onExitBoundary,
 				resolveImageUrl,
-				onImagePaste,
-				onImageSaveError,
+				resolveFileInfo,
+				onFileClick,
+				onFilePaste,
+				onFileSaveError,
 				onImageClick,
 				embedPaste,
 				bulletAfterHeading,
@@ -1074,13 +1476,27 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 			blockHandle && !readOnly && /* @__PURE__ */ jsx(BlockHandle, {}),
 			!readOnly && /* @__PURE__ */ jsx(TableHandle, {}),
 			blockHandle && !readOnly && /* @__PURE__ */ jsx(DropIndicator$1, {}),
-			/* @__PURE__ */ jsx(SlashMenu, { timeFormat }),
+			/* @__PURE__ */ jsx(SlashMenu, {
+				timeFormat,
+				onSlashMenuSearch
+			}),
 			!readOnly && /* @__PURE__ */ jsx(LinkMenu, {
 				onLinkClick,
 				onLinkCopy
 			}),
 			onTagSearch && /* @__PURE__ */ jsx(TagMenu, { onTagSearch }),
 			onWikilinkSearch && /* @__PURE__ */ jsx(WikilinkMenu, { onWikilinkSearch }),
+			onSelectionMenuSearch && !readOnly && /* @__PURE__ */ jsx(SelectionMenu, {
+				onSelectionMenuSearch,
+				context: selectionMenuContext,
+				onOpen: openSelectionMenu,
+				onClose: closeSelectionMenu,
+				affordance: selectionMenuAffordance
+			}),
+			!readOnly && /* @__PURE__ */ jsx(PendingReplacementPreview, {
+				actions: pendingReplacementActions,
+				onResolve: onPendingReplacementResolve
+			}),
 			children
 		]
 	});
@@ -1088,7 +1504,7 @@ function ProseKitEditor({ markMode = "focus", initialMarkdown, onDocChange, onTa
 
 //#endregion
 //#region src/components/editor.tsx
-function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onTagSearch, onWikilinkSearch, onWikilinkClick, onLinkClick, onLinkCopy, onTagClick, onExitBoundary, resolveImageUrl, onImagePaste, onImageSaveError, onImageClick, embedPaste = true, bulletAfterHeading = false, frontmatter = false, blockHandle = true, placeholder, readOnly, spellCheck, timeFormat, editorClassName, wrapperClassName, handleRef, children }) {
+function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onSlashMenuSearch, onTagSearch, onWikilinkSearch, onSelectionMenuSearch, selectionMenuAffordance = true, pendingReplacementActions, onPendingReplacementResolve, onWikilinkClick, onLinkClick, onLinkCopy, onTagClick, onExitBoundary, resolveImageUrl, resolveFileLink, resolveFileInfo, onFileClick, onFilePaste, onFileSaveError, onImageClick, embedPaste = true, bulletAfterHeading = false, frontmatter = false, blockHandle = true, placeholder, readOnly, spellCheck, timeFormat, editorClassName, wrapperClassName, handleRef, children }) {
 	const childRef = useRef(null);
 	useImperativeHandle(handleRef, () => {
 		function getMarkdown() {
@@ -1097,6 +1513,9 @@ function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onTagSea
 		function setMarkdown(markdown) {
 			childRef.current?.setMarkdown(markdown);
 		}
+		function insertMarkdown(markdown) {
+			childRef.current?.insertMarkdown(markdown);
+		}
 		function getState() {
 			return childRef.current?.getState() ?? ["", {
 				type: "text",
@@ -1123,15 +1542,40 @@ function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onTagSea
 		function scrollIntoView() {
 			childRef.current?.scrollIntoView();
 		}
+		function getSelectedText() {
+			return childRef.current?.getSelectedText() ?? "";
+		}
+		function openSelectionMenu() {
+			childRef.current?.openSelectionMenu();
+		}
+		function startPendingReplacement(options) {
+			return childRef.current?.startPendingReplacement(options) ?? false;
+		}
+		function appendPendingReplacementText(text) {
+			childRef.current?.appendPendingReplacementText(text);
+		}
+		function acceptPendingReplacement(options) {
+			childRef.current?.acceptPendingReplacement(options);
+		}
+		function discardPendingReplacement() {
+			childRef.current?.discardPendingReplacement();
+		}
 		return {
 			getMarkdown,
 			setMarkdown,
+			insertMarkdown,
 			getState,
 			setState,
 			getSelection,
 			setSelection,
 			focus,
 			scrollIntoView,
+			getSelectedText,
+			openSelectionMenu,
+			startPendingReplacement,
+			appendPendingReplacementText,
+			acceptPendingReplacement,
+			discardPendingReplacement,
 			get editor() {
 				return childRef.current?.editor;
 			}
@@ -1144,16 +1588,24 @@ function MeowdownEditor({ mode = "focus", initialMarkdown, onDocChange, onTagSea
 			markMode: mode,
 			initialMarkdown,
 			onDocChange,
+			onSlashMenuSearch,
 			onTagSearch,
 			onWikilinkSearch,
+			onSelectionMenuSearch,
+			selectionMenuAffordance,
+			pendingReplacementActions,
+			onPendingReplacementResolve,
 			onWikilinkClick,
 			onLinkClick,
 			onLinkCopy,
 			onTagClick,
 			onExitBoundary,
 			resolveImageUrl,
-			onImagePaste,
-			onImageSaveError,
+			resolveFileLink,
+			resolveFileInfo,
+			onFileClick,
+			onFilePaste,
+			onFileSaveError,
 			onImageClick,
 			embedPaste,
 			bulletAfterHeading,

package/dist/style.css

@@ -344,6 +344,187 @@
     outline-offset: -1px;
   }
 }
+.meow_Positioner_DPJ5ia {
+  z-index: 50;
+  width: min(24rem, 100vw - 1rem);
+  display: block;
+}
+
+.meow_Popup_DPJ5ia {
+  box-sizing: border-box;
+  border: 1px solid var(--meowdown-border);
+  background: var(--meowdown-popover-bg);
+  border-radius: .75rem;
+  flex-direction: column;
+  width: 100%;
+  font-size: .875rem;
+  display: flex;
+  box-shadow: 0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a;
+}
+
+.meow_Text_DPJ5ia {
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+  max-height: 14rem;
+  color: var(--meowdown-text);
+  padding: .625rem .75rem;
+  overflow-y: auto;
+}
+
+.meow_Waiting_DPJ5ia {
+  color: var(--meowdown-muted);
+}
+
+.meow_Footer_DPJ5ia {
+  border-top: 1px solid var(--meowdown-border);
+  align-items: center;
+  gap: .25rem;
+  padding: .375rem;
+  display: flex;
+}
+
+.meow_Spacer_DPJ5ia {
+  flex: 1;
+}
+
+.meow_Button_DPJ5ia {
+  color: var(--meowdown-text);
+  cursor: pointer;
+  border-radius: .5rem;
+  align-items: center;
+  padding: .25rem .625rem;
+  display: inline-flex;
+
+  &:hover {
+    background: var(--meowdown-popover-hover-bg);
+  }
+}
+
+.meow_AcceptButton_DPJ5ia {
+  color: var(--meowdown-popover-bg);
+  background: var(--meowdown-accent);
+  cursor: pointer;
+  border-radius: .5rem;
+  align-items: center;
+  padding: .25rem .625rem;
+  display: inline-flex;
+
+  &:hover {
+    filter: brightness(1.05);
+  }
+
+  &:disabled {
+    opacity: .5;
+    cursor: default;
+  }
+}
+.meow_Positioner_2_4Zjq {
+  z-index: 50;
+  width: min(18rem, 100vw - 1rem);
+  display: block;
+}
+
+.meow_Popup_2_4Zjq {
+  box-sizing: border-box;
+  border: 1px solid var(--meowdown-border);
+  background: var(--meowdown-popover-bg);
+  border-radius: .75rem;
+  flex-direction: column;
+  width: 100%;
+  padding: .25rem;
+  font-size: .875rem;
+  display: flex;
+  box-shadow: 0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a;
+}
+
+.meow_Input_2_4Zjq {
+  box-sizing: border-box;
+  width: 100%;
+  font: inherit;
+  color: var(--meowdown-text);
+  border: 1px solid var(--meowdown-border);
+  background: none;
+  border-radius: .5rem;
+  margin-bottom: .25rem;
+  padding: .375rem .5rem;
+
+  &:focus {
+    outline: 2px solid var(--meowdown-accent);
+    outline-offset: -1px;
+  }
+}
+
+.meow_List_2_4Zjq {
+  flex-direction: column;
+  max-height: 16rem;
+  display: flex;
+  overflow-y: auto;
+}
+
+.meow_Item_2_4Zjq {
+  text-align: left;
+  color: var(--meowdown-text);
+  cursor: pointer;
+  border-radius: .5rem;
+  align-items: baseline;
+  gap: .5rem;
+  padding: .375rem .5rem;
+  display: flex;
+
+  &[data-active] {
+    background: var(--meowdown-popover-hover-bg);
+  }
+}
+
+.meow_Label_2_4Zjq {
+  flex: none;
+}
+
+.meow_Detail_2_4Zjq {
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  min-width: 0;
+  color: var(--meowdown-muted);
+  flex: 1;
+  font-size: .8125rem;
+  overflow: hidden;
+}
+
+.meow_Empty_2_4Zjq {
+  color: var(--meowdown-muted);
+  padding: .375rem .5rem;
+}
+
+.meow_AffordancePositioner_2_4Zjq {
+  z-index: 40;
+  display: block;
+}
+
+.meow_AffordancePopup_2_4Zjq {
+  display: flex;
+}
+
+.meow_AffordanceButton_2_4Zjq {
+  color: var(--meowdown-muted);
+  background: var(--meowdown-popover-bg);
+  border: 1px solid var(--meowdown-border);
+  cursor: pointer;
+  border-radius: .5rem;
+  justify-content: center;
+  align-items: center;
+  padding: .25rem;
+  display: inline-flex;
+
+  &:hover {
+    color: var(--meowdown-accent);
+    background: var(--meowdown-popover-hover-bg);
+  }
+
+  & svg {
+    width: .875rem;
+    height: .875rem;
+  }
+}
 .meow_Positioner_Dqll0G {
   z-index: 50;
   width: min(24rem, 100vw - 1rem);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meowdown/react",
   "type": "module",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "@prosekit/react": "^0.8.0-beta.15",
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
-    "@meowdown/core": "0.30.1"
+    "@meowdown/core": "0.32.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",