@meowdown/react 0.44.2 → 0.45.0

package/README.md

@@ -56,12 +56,33 @@ See the full API reference [here](https://npmx.dev/package-docs/@meowdown%2Freac
 
 Slash menu host items can include `keywords` to match hidden terms without changing the displayed label.
 
+### Wiki-link hover cards
+
+Mount `WikilinkHoverCard` inside `MeowdownEditor` and render host-owned preview
+content from the hovered wiki link's `target`. Returning `null` renders no
+card.
+
+```tsx
+<MeowdownEditor initialMarkdown="See [[Project plan]]">
+  <WikilinkHoverCard>
+    {(hit) => <LocalNotePreview key={hit.target} target={hit.target} />}
+  </WikilinkHoverCard>
+</MeowdownEditor>
+```
+
+For local-only passive preview content, render Markdown with interaction
+disabled: the tree contains no anchors or focusable controls, and recognized
+tweet and YouTube embeds are omitted before any image resolver runs. Supply a
+resolver that accepts only trusted local image sources.
+
+```tsx
+<MarkdownView markdown={markdown} interactive={false} resolveImageUrl={resolveLocalImageUrl} />
+```
+
 ## Styling
 
 Import both stylesheets: `@meowdown/core/style.css` (the editor theme and variables) and `@meowdown/react/style.css` (the component layout). The core theme is documented in [`@meowdown/core`](https://www.npmjs.com/package/@meowdown/core).
 
-Math (`$E=mc^2$` inline, `$$` blocks, and ` ```math ` fences) is compiled by KaTeX to native MathML.
-
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode, Ref } from "react";
-import { AcceptPendingReplacementOptions, ExitBoundaryHandler, FileClickHandler, FileLinkResolver, FilePasteOptions, FileViewOptions, ImageClickHandler, ImageOptions, LinkClickHandler, LinkCopyHandler, ListMarker, MarkMode, PendingReplacement, PendingReplacementOutcome, PlaceholderOptions, StartPendingReplacementOptions, TagClickHandler, TypedEditor, WikilinkClickHandler } from "@meowdown/core";
+import { AcceptPendingReplacementOptions, ExitBoundaryHandler, FileClickHandler, FileLinkResolver, FilePasteOptions, FileViewOptions, ImageClickHandler, ImageOptions, LinkClickHandler, LinkCopyHandler, ListMarker, MarkMode, PendingReplacement, PendingReplacementOutcome, PlaceholderOptions, StartPendingReplacementOptions, TagClickHandler, TypedEditor, WikilinkClickHandler, WikilinkHoverHit } from "@meowdown/core";
 import { SelectionJSON, SelectionJSON as SelectionJSON$1 } from "@prosekit/core";
 import { useEditor, useExtension, useKeymap } from "@prosekit/react";
 //#region src/utils/date-format.d.ts
@@ -408,9 +408,16 @@ interface MarkdownViewProps {
   markMode?: MarkMode;
   /** Peel a leading YAML frontmatter block before rendering. Off by default. */
   frontmatter?: boolean;
+  /**
+   * Whether rendered links, images, and task checkboxes can be activated.
+   * Defaults to `true`. When `false`, callbacks are ignored, the rendered tree
+   * contains no anchors or focusable task controls, and recognized tweet and
+   * YouTube embeds are omitted before any image resolver runs.
+   */
+  interactive?: boolean;
   /** Map an image `src` to a displayable URL, or `undefined` to skip it. */
   resolveImageUrl?: (src: string) => string | undefined;
-  /** Called when a rendered wiki link is clicked. Pass a stable function. */
+  /** Called when a rendered wikilink is clicked. Pass a stable function. */
   onWikilinkClick?: WikilinkClickHandler;
   /** Called when a rendered Markdown link is clicked. Pass a stable function. */
   onLinkClick?: LinkClickHandler;
@@ -423,7 +430,7 @@ interface MarkdownViewProps {
 }
 /**
  * Render Markdown to a read-only React tree that looks exactly like the editor
- * in `hide` mark mode: inline marks, wiki-link chips, images, tweet/YouTube
+ * in `hide` mark mode: inline marks, wikilink chips, images, tweet/YouTube
  * embeds, and syntax-highlighted code. No editor, no ProseMirror view; just a
  * walk over `markdownToDoc`'s document reusing meowdown's own parse, mark logic,
  * and CSS (the root carries `ProseMirror` + `data-mark-mode` so the existing
@@ -432,6 +439,22 @@ interface MarkdownViewProps {
  * Callbacks (`onWikilinkClick`, etc.) should be stable; pass them via
  * `useCallback` to avoid re-rendering the whole tree.
  */
-declare function MarkdownView({ markdown, markMode, frontmatter, resolveImageUrl, onWikilinkClick, onLinkClick, onImageClick, onTaskClick, className }: MarkdownViewProps): ReactElement;
+declare function MarkdownView({ markdown, markMode, frontmatter, interactive, resolveImageUrl, onWikilinkClick, onLinkClick, onImageClick, onTaskClick, className }: MarkdownViewProps): ReactElement;
+//#endregion
+//#region src/components/wikilink-hover-card.d.ts
+/** Props for {@link WikilinkHoverCard}. */
+interface WikilinkHoverCardProps {
+  /**
+   * Render the card body from the hovered wiki link. Returning `null` renders
+   * no card.
+   */
+  readonly children: (hit: WikilinkHoverHit) => ReactNode;
+  /** Optional class applied to the popup, after the default card surface. */
+  readonly className?: string;
+}
+/**
+ * Show host-rendered content after a 300ms dwell over a rendered wiki link.
+ */
+declare function WikilinkHoverCard({ children, className }: WikilinkHoverCardProps): ReactNode;
 //#endregion
-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 TaskClickHandler, type TaskClickPayload, 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 TaskClickHandler, type TaskClickPayload, type TimeFormat, WikilinkHoverCard, type WikilinkHoverCardProps, type WikilinkItem, type WikilinkSearchHandler, useEditor, useExtension, useKeymap };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { clsx } from "clsx/lite";
 import { Fragment, cloneElement, createElement, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { buildFileMarkdown, codeBlockLanguages, defaultResolveImageUrl, defineBulletAfterHeading, defineCodeBlockPreviewPlugin, defineEditorExtension, defineEmbedPaste, defineExitBoundaryHandler, defineFileClickHandler, defineFilePaste, defineFileView, defineFollowLinkHandler, defineHTMLPaste, defineImage, defineImageClickHandler, defineLinkClickHandler, defineLinkEditKeymap, defineLinkHoverHandler, defineLinkPaste, defineMarkdownCopy, definePendingReplacementHandler, definePlaceholder, defineReadonly, defineSpellCheckPlugin, defineTagClickHandler, defineWikilinkClickHandler, defineWikilinkTrigger, docToMarkdown, getCodeTokens, getMarkBuilders, getPendingReplacement, getSelectedText, getTableColumnAlign, getVirtualElementFromRange, inlineTextToMarkChunks, isCodeBlockPreviewHiddenDecoration, isSelectionInTableCell, listenForTweetHeight, loadKaTeX, markdownToDoc, matchEmbed, renderMathInto } from "@meowdown/core";
+import { buildFileMarkdown, codeBlockLanguages, defaultResolveImageUrl, defineBulletAfterHeading, defineCodeBlockPreviewPlugin, defineEditorExtension, defineEmbedPaste, defineExitBoundaryHandler, defineFileClickHandler, defineFilePaste, defineFileView, defineFollowLinkHandler, defineHTMLPaste, defineImage, defineImageClickHandler, defineLinkClickHandler, defineLinkEditKeymap, defineLinkHoverHandler, defineLinkPaste, defineMarkdownCopy, definePendingReplacementHandler, definePlaceholder, defineReadonly, defineSpellCheckPlugin, defineTagClickHandler, defineWikilinkClickHandler, defineWikilinkHoverHandler, defineWikilinkTrigger, docToMarkdown, getCodeTokens, getMarkBuilders, getPendingReplacement, getSelectedText, getTableColumnAlign, getVirtualElementFromRange, inlineTextToMarkChunks, isCodeBlockPreviewHiddenDecoration, isSelectionInTableCell, listenForTweetHeight, loadKaTeX, markdownToDoc, matchEmbed, renderMathInto } from "@meowdown/core";
 import { clamp } from "@ocavue/utils";
 import { canUseRegexLookbehind, createEditor, defineDocChangeHandler, defineUpdateHandler, isTextSelection, union } from "@prosekit/core";
 import { Selection, TextSelection } from "@prosekit/pm/state";
@@ -16,6 +16,7 @@ import { MenuItem, MenuPopup, MenuPositioner } from "@prosekit/react/menu";
 import { TableHandleColumnMenuRoot, TableHandleColumnMenuTrigger, TableHandleColumnPopup, TableHandleColumnPositioner, TableHandleDragPreview, TableHandleDropIndicator, TableHandleRoot, TableHandleRowMenuRoot, TableHandleRowMenuTrigger, TableHandleRowPopup, TableHandleRowPositioner } from "@prosekit/react/table-handle";
 import { Mark } from "@prosekit/pm/model";
 import { BOOLEAN, OVERLOADED_BOOLEAN, getPropertyInfo, possibleStandardNames } from "react-property";
+import { PreviewCard } from "@base-ui/react/preview-card";
 
 //#region src/hooks/use-katex.ts
 /**
@@ -381,16 +382,16 @@ function EditorExtensions({ markMode, onDocChange, onWikilinkClick, onLinkClick,
 //#endregion
 //#region src/hooks/use-delayed-flag.ts
 /** Delay before the flag opens, in ms. */
-const OPEN_DELAY = 400;
+const OPEN_DELAY$1 = 400;
 /** Grace before the flag closes, in ms. The window lets a pointer travel from
 *  the hovered link onto the popover it anchors. */
-const CLOSE_DELAY = 300;
+const CLOSE_DELAY$1 = 300;
 /**
 * Mirrors `value` into a boolean that flips true `openDelay`ms after `value`
 * becomes true and false `closeDelay`ms after it becomes false, cancelling any
 * pending flip on each change.
 */
-function useDelayedFlag(value, openDelay = OPEN_DELAY, closeDelay = CLOSE_DELAY) {
+function useDelayedFlag(value, openDelay = OPEN_DELAY$1, closeDelay = CLOSE_DELAY$1) {
 	const [flag, setFlag] = useState(false);
 	const timerRef = useRef(void 0);
 	useEffect(() => {
@@ -1942,7 +1943,13 @@ function outputSpecToReact(spec, content, context) {
 	const [tag, attrs, rest] = normalized;
 	const reactProps = { ...attributesToProps(attrs, tag) };
 	reactProps.key = `${key} ${JSON.stringify(attrs)}`;
-	if (tag === "input" && attrs?.["type"] === "checkbox") reactProps.readOnly = true;
+	if (tag === "input" && attrs?.["type"] === "checkbox") {
+		reactProps.readOnly = true;
+		if (!context.interactive) {
+			reactProps.disabled = true;
+			reactProps.tabIndex = -1;
+		}
+	}
 	return createElement(tag, reactProps, ...rest.map((child) => outputSpecToReact(child, content, context)));
 }
 function WikilinkChip(props) {
@@ -1994,9 +2001,9 @@ function EmbedFrame({ embed }) {
 	});
 }
 function ImagePreview(props) {
-	const { src, alt, width, resolveImageUrl, onImageClick } = props;
+	const { src, alt, width, resolveImageUrl, onImageClick, interactive } = props;
 	const embed = matchEmbed(src);
-	if (embed) return /* @__PURE__ */ jsx(EmbedFrame, { embed });
+	if (embed) return interactive ? /* @__PURE__ */ jsx(EmbedFrame, { embed }) : null;
 	const url = (resolveImageUrl ?? defaultResolveImageUrl)(src);
 	if (!url) return null;
 	return /* @__PURE__ */ jsx("span", {
@@ -2025,7 +2032,8 @@ function ImageView(props) {
 			alt,
 			width,
 			resolveImageUrl: context.resolveImageUrl,
-			onImageClick: context.onImageClick
+			onImageClick: context.onImageClick,
+			interactive: context.interactive
 		}), /* @__PURE__ */ jsx("span", {
 			className: "md-image-view-content md-atom-view-content",
 			children
@@ -2142,6 +2150,10 @@ function wrapMark(mark, children, context) {
 		}
 		case "mdLinkText": {
 			const attrs = mark.attrs;
+			if (!context.interactive) return /* @__PURE__ */ jsx("span", {
+				className: "md-link",
+				children
+			});
 			const handleClick = context.onLinkClick ? (event) => context.onLinkClick?.({
 				href: attrs.href,
 				event: event.nativeEvent
@@ -2239,7 +2251,7 @@ function renderBlock(node, context) {
 }
 /**
 * Render Markdown to a read-only React tree that looks exactly like the editor
-* in `hide` mark mode: inline marks, wiki-link chips, images, tweet/YouTube
+* in `hide` mark mode: inline marks, wikilink chips, images, tweet/YouTube
 * embeds, and syntax-highlighted code. No editor, no ProseMirror view; just a
 * walk over `markdownToDoc`'s document reusing meowdown's own parse, mark logic,
 * and CSS (the root carries `ProseMirror` + `data-mark-mode` so the existing
@@ -2248,15 +2260,16 @@ function renderBlock(node, context) {
 * Callbacks (`onWikilinkClick`, etc.) should be stable; pass them via
 * `useCallback` to avoid re-rendering the whole tree.
 */
-function MarkdownView({ markdown, markMode = "hide", frontmatter = false, resolveImageUrl, onWikilinkClick, onLinkClick, onImageClick, onTaskClick, className }) {
+function MarkdownView({ markdown, markMode = "hide", frontmatter = false, interactive = true, resolveImageUrl, onWikilinkClick, onLinkClick, onImageClick, onTaskClick, className }) {
 	const content = useMemo(() => {
 		const doc = markdownToDoc(markdown, { frontmatter });
 		const context = {
+			interactive,
 			resolveImageUrl,
-			onWikilinkClick,
-			onLinkClick,
-			onImageClick,
-			onTaskClick,
+			onWikilinkClick: interactive ? onWikilinkClick : void 0,
+			onLinkClick: interactive ? onLinkClick : void 0,
+			onImageClick: interactive ? onImageClick : void 0,
+			onTaskClick: interactive ? onTaskClick : void 0,
 			taskCounter: { value: 0 },
 			keyCounter: { value: 0 }
 		};
@@ -2264,6 +2277,7 @@ function MarkdownView({ markdown, markMode = "hide", frontmatter = false, resolv
 	}, [
 		markdown,
 		frontmatter,
+		interactive,
 		resolveImageUrl,
 		onWikilinkClick,
 		onLinkClick,
@@ -2278,4 +2292,77 @@ function MarkdownView({ markdown, markMode = "hide", frontmatter = false, resolv
 }
 
 //#endregion
-export { MarkdownView, MeowdownEditor, useEditor, useExtension, useKeymap };
+//#region src/components/wikilink-hover-card.module.css
+var wikilink_hover_card_module_default = {
+	"Popup": "meow_Popup_HMEwgW",
+	"Positioner": "meow_Positioner_HMEwgW",
+	"Viewport": "meow_Viewport_HMEwgW"
+};
+
+//#endregion
+//#region src/components/wikilink-hover-card.tsx
+const OPEN_DELAY = 300;
+const CLOSE_DELAY = 200;
+/**
+* Show host-rendered content after a 300ms dwell over a rendered wiki link.
+*/
+function WikilinkHoverCard({ children, className }) {
+	const [hit, setHit] = useState();
+	const lastRectRef = useRef(null);
+	const [displayed, setDisplayed] = useState();
+	const [open, setOpen] = useState(false);
+	const [hoverExtension] = useState(() => {
+		return defineWikilinkHoverHandler((nextHit) => setHit(nextHit));
+	});
+	useExtension$1(hoverExtension);
+	const getRect = useCallback(() => {
+		const rect = hit?.element?.getBoundingClientRect();
+		if (rect && rect.width > 0 && rect.height > 0) lastRectRef.current = rect;
+		return lastRectRef.current || new DOMRect(0, 0, 0, 0);
+	}, [hit]);
+	const anchor = useMemo(() => {
+		return { getBoundingClientRect: getRect };
+	}, [getRect]);
+	const hasDisplayed = !!displayed;
+	useEffect(() => {
+		if (!hit) {
+			const timer = setTimeout(() => setOpen(false), CLOSE_DELAY);
+			return () => clearTimeout(timer);
+		}
+		const timer = setTimeout(() => {
+			setDisplayed(hit);
+			setOpen(true);
+		}, hasDisplayed ? 0 : OPEN_DELAY);
+		return () => clearTimeout(timer);
+	}, [hit, hasDisplayed]);
+	const body = displayed ? children(displayed) : null;
+	return /* @__PURE__ */ jsx(PreviewCard.Root, {
+		open: open && body != null,
+		onOpenChange: (nextOpen) => {
+			if (!nextOpen) setOpen(false);
+		},
+		onOpenChangeComplete: (nextOpen) => {
+			if (!nextOpen) setDisplayed(void 0);
+		},
+		children: body != null && /* @__PURE__ */ jsx(PreviewCard.Portal, { children: /* @__PURE__ */ jsx(PreviewCard.Positioner, {
+			anchor,
+			side: "bottom",
+			sideOffset: 8,
+			collisionPadding: 8,
+			className: wikilink_hover_card_module_default.Positioner,
+			"data-testid": "wikilink-hover-positioner",
+			children: /* @__PURE__ */ jsx(PreviewCard.Popup, {
+				inert: true,
+				className: clsx(wikilink_hover_card_module_default.Popup, className),
+				"data-testid": "wikilink-hover-card",
+				children: /* @__PURE__ */ jsx(PreviewCard.Viewport, {
+					className: wikilink_hover_card_module_default.Viewport,
+					children: body
+				})
+			})
+		}) })
+	});
+}
+
+//#endregion
+export { MarkdownView, MeowdownEditor, WikilinkHoverCard, useEditor, useExtension, useKeymap };

package/dist/style.css

@@ -764,6 +764,53 @@
     display: block;
   }
 }
+.meow_Positioner_HMEwgW {
+  z-index: 50;
+  pointer-events: none;
+  max-width: calc(100vw - 1rem);
+  max-height: calc(100vh - 1rem);
+  transition-property: top, left, right, bottom, transform;
+  transition-duration: .35s;
+  transition-timing-function: cubic-bezier(.22, 1, .36, 1);
+}
+
+.meow_Popup_HMEwgW {
+  box-sizing: border-box;
+  pointer-events: none;
+  border: 1px solid var(--meowdown-border);
+  background: var(--meowdown-popover-bg);
+  width: min(20rem, 100vw - 1rem);
+  max-height: min(12rem, 100vh - 1rem);
+  transform-origin: var(--transform-origin);
+  border-radius: .75rem;
+  outline: none;
+  transition: opacity .15s, transform .15s;
+  display: flex;
+  box-shadow: 0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a;
+}
+
+.meow_Popup_HMEwgW[data-closed] {
+  transition: opacity .1s, transform .1s;
+}
+
+.meow_Popup_HMEwgW[data-starting-style], .meow_Popup_HMEwgW[data-ending-style] {
+  opacity: 0;
+  transform: scale(.96);
+}
+
+.meow_Viewport_HMEwgW {
+  border-radius: inherit;
+  flex: 1;
+  min-width: 0;
+  position: relative;
+  overflow: clip;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .meow_Positioner_HMEwgW, .meow_Popup_HMEwgW {
+    transition: none;
+  }
+}
 .meowdown {
   flex-direction: column;
   flex: 1 0 auto;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meowdown/react",
   "type": "module",
-  "version": "0.44.2",
+  "version": "0.45.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
     "react-property": "^2.0.2",
-    "@meowdown/core": "0.44.2"
+    "@meowdown/core": "0.45.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",