@karimsa/mdxserve 0.0.0-stage → 0.2.0

package/client/MdSection.tsx

@@ -0,0 +1,234 @@
+import {
+	lazy,
+	startTransition,
+	Suspense,
+	useContext,
+	useEffect,
+	useState,
+	type MouseEvent,
+	type ReactNode,
+} from "react";
+import { useAtom } from "jotai";
+import { trpcClient } from "./api";
+import { DocContext } from "./DocContext";
+import { openSectionAtom } from "./state";
+import { IconButton } from "./ui/IconButton";
+import { pushToast } from "./ui/Toast";
+
+// The Tiptap editor (~300 KB of ProseMirror) must never be part of a doc
+// module's own bundle, and must never be evaluated by the SSR render worker
+// (client/ssr-entry.tsx), which only ever renders sections in read mode. A
+// module-scope `lazy()` call is safe in both places: it just builds a
+// component descriptor around a loader, and the loader only actually runs
+// when React commits the "edit" branch below, which SSR never reaches.
+const loadEditor = () => import("./MdSectionEditor");
+const MdSectionEditor = lazy(loadEditor);
+
+// Warm the editor chunk as soon as a pointer lands on any section, so by the
+// time the user has double-clicked or reached the pencil the lazy import is
+// already cached and the switch into edit mode doesn't wait on the network.
+let editorPreloaded = false;
+function preloadEditor(): void {
+	if (editorPreloaded) return;
+	editorPreloaded = true;
+	void loadEditor();
+}
+
+export interface MdSectionProps {
+	/** 0-based order among a doc's sections, as a string (mdxJsxFlowElement attributes are always strings). */
+	index: string;
+	/** 1-based, inclusive source line numbers, as strings. */
+	startLine: string;
+	endLine: string;
+	children: ReactNode;
+}
+
+/**
+ * MDXProvider registration (see client/mdx-components.ts) for the synthetic
+ * `<MdSection>` element the server's remark-sections compiler plugin wraps
+ * around every maximal run of pure-markdown top-level nodes. In read mode
+ * it's invisible — same children, same DOM — until hovered, when a pencil
+ * appears to swap it into an inline Tiptap editor seeded from the raw file.
+ *
+ * This outer component only resolves `path` and re-keys the inner `Section`
+ * on `path:startLine:endLine`. That key matters after a save: Vite's HMR
+ * re-executes the doc module and React Fast Refresh re-renders this
+ * component in place with *new* startLine/endLine props (the edited range
+ * shifted). Without the key, Fast Refresh would preserve `Section`'s local
+ * state across that update and leave it holding an editor pointed at
+ * now-stale line numbers; keying on the range forces a clean remount back to
+ * read mode instead.
+ */
+export function MdSection({ index, startLine, endLine, children }: MdSectionProps) {
+	const ctxPath = useContext(DocContext)?.path;
+	// MdSection also renders inside the SSR worker (client/ssr-entry.tsx, used
+	// by the `mdxserve validate` render check via renderToString), which has no
+	// router and so no DocContext provider — and no `location` global at all.
+	// Read mode never needs `path`, so falling back to "" there is fine.
+	const path =
+		ctxPath ?? (typeof location !== "undefined" ? decodeURIComponent(location.pathname) : "");
+
+	return (
+		<Section
+			key={`${path}:${startLine}:${endLine}`}
+			path={path}
+			index={index}
+			startLine={Number(startLine)}
+			endLine={Number(endLine)}
+		>
+			{children}
+		</Section>
+	);
+}
+
+function Section({
+	path,
+	index,
+	startLine,
+	endLine,
+	children,
+}: {
+	path: string;
+	index: string;
+	startLine: number;
+	endLine: number;
+	children: ReactNode;
+}) {
+	const [mode, setMode] = useState<"read" | "loading" | "edit">("read");
+	const [source, setSource] = useState("");
+	const [version, setVersion] = useState("");
+	const [openSection, setOpenSection] = useAtom(openSectionAtom);
+	const key = `${path}:${startLine}:${endLine}`;
+
+	// Only one section edits (or loads) at a time. The atom is claimed the
+	// moment a section starts opening, so if a different section claims it
+	// while this one is mid-fetch or mid-edit, this one drops back to read
+	// mode and discards whatever it had — no confirmation, matching the
+	// "explicit Save / Esc cancels, no autosave" model. Claiming up front
+	// (rather than when the fetch lands) is what makes a slow earlier click
+	// lose to a faster later one instead of clobbering it.
+	useEffect(() => {
+		if (mode !== "read" && openSection !== key) setMode("read");
+	}, [openSection, key, mode]);
+
+	// If this section unmounts while it owns the atom — a navigation away, or
+	// the HMR remount after another section's save shifted our line range —
+	// release it, or DocView would keep the doc's resize handles hidden.
+	useEffect(() => {
+		return () => {
+			setOpenSection((current) => (current === key ? null : current));
+		};
+	}, [key, setOpenSection]);
+
+	async function startEdit() {
+		// Double-click and the pencil can both fire while a fetch is in flight.
+		if (mode !== "read") return;
+		setOpenSection(key);
+		setMode("loading");
+		try {
+			// The vanilla client, not the query cache: the source must be exactly
+			// what is on disk at this moment, never a cached copy.
+			const data = await trpcClient.getDocSource.query({ path });
+			// Functional update so a response that lands after another section
+			// took the atom (the effect above has already reset us to "read")
+			// is dropped rather than resurrecting this section's editor.
+			const lines = data.text.split(/\r?\n/);
+			const sliced = lines.slice(startLine - 1, endLine).join("\n");
+			setMode((current) => {
+				if (current !== "loading") return current;
+				setSource(sliced);
+				setVersion(data.version);
+				return current;
+			});
+			// A transition, so React keeps the read-mode DOM on screen until the
+			// lazy editor chunk has resolved and MdSectionEditor can commit in
+			// one go — instead of swapping in the Suspense fallback first and
+			// then the editor, which read as a flash.
+			startTransition(() => {
+				setMode((current) => (current === "loading" ? "edit" : current));
+			});
+		} catch {
+			pushToast({ tone: "danger", text: "Couldn't open section for editing" });
+			setMode((current) => (current === "loading" ? "read" : current));
+			setOpenSection((current) => (current === key ? null : current));
+		}
+	}
+
+	// Called by MdSectionEditor on both Save-success and Cancel — this section
+	// is (by construction — see the effect above) still the open one whenever
+	// its own editor is what's calling this, so clearing unconditionally is safe.
+	function finishEdit() {
+		// Only release the atom if it is still ours: a slow save can resolve
+		// after another section has claimed it, and clearing unconditionally
+		// would close that newer editor and discard its unsaved edits.
+		setOpenSection((current) => (current === key ? null : current));
+		setMode("read");
+	}
+
+	// MdSectionEditor renders its own `.mdx-section[data-editing]` wrapper (it
+	// needs to be the direct parent of `.ProseMirror` for the prose rhythm
+	// rules in client/design/base/prose.css to reach it), so this branch adds
+	// nothing around it — a second `.mdx-section` here would double-nest and
+	// throw off the `:is(.mdx-prose, .mdx-section, …) > * + *` selectors.
+	//
+	// The fallback is the read-mode content itself, not a skeleton: with the
+	// transition in startEdit this branch normally never suspends visibly, and
+	// if it ever does (chunk evicted, slow network) the section simply stays
+	// as it was until the editor is ready.
+	if (mode === "edit") {
+		return (
+			<Suspense
+				fallback={
+					<div className="mdx-section" data-md-section={index}>
+						{children}
+					</div>
+				}
+			>
+				<MdSectionEditor
+					source={source}
+					version={version}
+					path={path}
+					startLine={startLine}
+					endLine={endLine}
+					onDone={finishEdit}
+				/>
+			</Suspense>
+		);
+	}
+
+	// Double-clicking prose is the fast path into the editor. It has to stay
+	// out of the way where a double-click already means something: following/
+	// selecting a link, a button (code copy, tabs), a task checkbox, selecting a
+	// word inside a code block, and svg-pan-zoom's double-click zoom on a
+	// mermaid diagram (client/Mermaid.tsx `dblClickZoomEnabled`).
+	function onDoubleClick(event: MouseEvent<HTMLDivElement>) {
+		const target = event.target as Element | null;
+		if (target?.closest("a, button, input, select, textarea, summary, pre, svg")) return;
+		event.preventDefault();
+		void startEdit();
+	}
+
+	return (
+		<div
+			className="mdx-section group"
+			data-md-section={index}
+			onDoubleClick={onDoubleClick}
+			onPointerEnter={preloadEditor}
+		>
+			{children}
+			{/* Floats over the section's top-right corner rather than in the left
+			    gutter, which is where DocView's left ResizeHandle lives — the two
+			    hover affordances were fighting for the same strip of pixels. */}
+			<IconButton
+				icon="pencil"
+				label="Edit section"
+				size="sm"
+				variant="outline"
+				data-print-hide
+				disabled={mode === "loading"}
+				onClick={startEdit}
+				className="absolute -top-3 right-0 z-20 opacity-0 shadow-sm transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
+			/>
+		</div>
+	);
+}

package/client/MdSectionEditor.tsx

@@ -0,0 +1,233 @@
+import { useEffect, useState, type KeyboardEvent, type MouseEvent } from "react";
+import type { Editor } from "@tiptap/core";
+import type { Mark } from "@tiptap/pm/model";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { StarterKit } from "@tiptap/starter-kit";
+import { TaskItem, TaskList } from "@tiptap/extension-list";
+import { TableKit } from "@tiptap/extension-table";
+import { Image } from "@tiptap/extension-image";
+import { Markdown } from "@tiptap/markdown";
+import { motion } from "framer-motion";
+import { isTRPCClientError } from "@trpc/client";
+import { trpcClient } from "./api";
+import { TRANSITIONS } from "./motion";
+import { isApplePlatform } from "./platform";
+import { modifiedLinkHref } from "./editor-link";
+import { Kbd } from "./ui/Kbd";
+import { pushToast } from "./ui/Toast";
+
+// The two hints enter together, each springing a few px rightwards while it
+// fades in, the second a beat after the first.
+const hintStack = { animate: { transition: { staggerChildren: 0.05 } } };
+const hint = {
+	initial: { opacity: 0, x: -10 },
+	animate: { opacity: 1, x: 0, transition: TRANSITIONS.glide },
+};
+
+export interface MdSectionEditorProps {
+	/** Raw markdown for exactly [startLine, endLine], sliced by MdSection.tsx. */
+	source: string;
+	/** Version token for the whole file at the moment `source` was fetched — the save's stale-write guard. */
+	version: string;
+	path: string;
+	startLine: number;
+	endLine: number;
+	/** Called after a successful save, or on Cancel — either way the section returns to read mode. */
+	onDone: () => void;
+}
+
+/**
+ * Markdown soft line breaks (a hard-wrapped paragraph in the source) survive
+ * @tiptap/markdown's parse as literal "\n" inside text nodes, and `.ProseMirror`
+ * renders with `white-space: pre-wrap`, so a paragraph wrapped at 80 columns
+ * on disk would show up in the editor broken across lines mid-sentence. Turn
+ * them into spaces up front — exactly what every Markdown renderer does with a
+ * soft break — leaving code blocks alone, where "\n" is real content. Text
+ * nodes are rebuilt with their own marks so bold/italic/link spans that
+ * happened to straddle a wrap keep their formatting. The edited paragraph is
+ * therefore written back as one line on save.
+ */
+function unwrapSoftBreaks(editor: Editor): void {
+	if (editor.isDestroyed) return;
+	const { state } = editor;
+	const edits: { from: number; to: number; text: string; marks: readonly Mark[] }[] = [];
+	state.doc.descendants((node, pos, parent) => {
+		if (!node.isText || !node.text?.includes("\n")) return;
+		if (parent?.type.name === "codeBlock") return;
+		edits.push({
+			from: pos,
+			to: pos + node.nodeSize,
+			text: node.text.replace(/\n/g, " "),
+			marks: node.marks,
+		});
+	});
+	if (edits.length === 0) return;
+	const tr = state.tr;
+	// Apply back to front so earlier positions stay valid.
+	for (const edit of edits.reverse()) {
+		tr.replaceWith(edit.from, edit.to, state.schema.text(edit.text, edit.marks));
+	}
+	editor.view.dispatch(tr.setMeta("addToHistory", false));
+}
+
+/**
+ * The Tiptap editing surface for one `MdSection`. This is the module
+ * `client/MdSection.tsx` lazy-loads on click, so its ~300 KB of ProseMirror
+ * never ships with a doc's own bundle and is never touched by the SSR render
+ * worker (which only ever renders sections in read mode).
+ *
+ * `StarterKit` 3.29 bundles Link, Underline and Strike itself (confirmed in
+ * node_modules/@tiptap/starter-kit/src/starter-kit.ts), so no separate
+ * `@tiptap/extension-link` install is needed to configure `link`.
+ */
+export default function MdSectionEditor({
+	source,
+	version,
+	path,
+	startLine,
+	endLine,
+	onDone,
+}: MdSectionEditorProps) {
+	const [saving, setSaving] = useState(false);
+	// Drives the hints' entrance. Not framer's `initial`/`animate` on mount:
+	// this component mounts through Suspense inside a transition, and its
+	// first commit can happen while the subtree is still hidden, so a
+	// mount-time animation has already finished by the time it's on screen.
+	// Flipping state in the post-mount effect below starts the spring on the
+	// visible commit instead.
+	const [entered, setEntered] = useState(false);
+
+	const editor = useEditor({
+		extensions: [
+			StarterKit.configure({
+				heading: { levels: [1, 2, 3, 4, 5, 6] },
+				link: { openOnClick: false },
+			}),
+			TaskList,
+			TaskItem.configure({ nested: true }),
+			TableKit,
+			Image,
+			Markdown,
+		],
+		content: source,
+		contentType: "markdown",
+		onCreate: ({ editor: created }) => unwrapSoftBreaks(created),
+		editorProps: { attributes: { class: "mdx-editor", "aria-label": "Section editor" } },
+	});
+
+	// Not `autofocus`: useEditor creates the editor before <EditorContent>
+	// below has attached its view to the DOM, so focusing at creation time is
+	// a no-op. This effect runs after the child's effects, i.e. once the view
+	// is mounted, for both the pencil and the double-click entry paths.
+	//
+	// The `isDestroyed` guard is load-bearing: this component mounts through
+	// React.lazy + Suspense, and useEditor can hand the first committed render
+	// an instance it has already torn down and is about to replace. Reading
+	// `.commands` on a destroyed Editor dereferences a null commandManager and
+	// throws; the replacement instance re-runs this effect and focuses.
+	useEffect(() => {
+		if (!editor || editor.isDestroyed) return;
+		editor.commands.focus("start");
+		setEntered(true);
+	}, [editor]);
+
+	async function save() {
+		if (!editor || saving) return;
+		setSaving(true);
+		try {
+			await trpcClient.saveDocSection.mutate({
+				path,
+				startLine,
+				endLine,
+				version,
+				markdown: editor.getMarkdown(),
+			});
+			// The write lands on disk, chokidar → Vite HMR re-executes the doc
+			// module, and Fast Refresh re-renders this section's MdSection
+			// wrapper with fresh line numbers — no need to do anything here
+			// beyond leaving edit mode.
+			onDone();
+		} catch (error) {
+			const code = isTRPCClientError(error) ? error.data?.code : undefined;
+			if (code === "CONFLICT") {
+				pushToast({ tone: "warn", text: "File changed on disk — reopen the section" });
+			} else if (code === "UNPROCESSABLE_CONTENT") {
+				console.error(error);
+				pushToast({ tone: "danger", text: "Couldn't save — the markdown doesn't compile" });
+			} else {
+				console.error(error);
+				pushToast({ tone: "danger", text: "Couldn't save section" });
+			}
+		} finally {
+			setSaving(false);
+		}
+	}
+
+	// Cmd/ctrl+click follows a link (client/editor-link.ts says why the
+	// browser's own new-tab gesture is inert inside a contenteditable). A DOM
+	// `click` listener rather than ProseMirror's `handleClick` prop: that one
+	// only fires when ProseMirror's own mousedown→mouseup tracking survives,
+	// and it bails on a few pixels of pointer drift. The opener is a detached
+	// `target=_blank` anchor rather than `window.open`, which Chrome turns into
+	// a popup window as soon as a feature string (even `noopener`) is passed;
+	// `noopener` because the target may be any site the doc links to.
+	function onClick(event: MouseEvent<HTMLDivElement>) {
+		const anchor = (event.target as Element | null)?.closest("a");
+		if (!anchor) return;
+		// The raw attribute, not `anchor.href`: an empty target (`[label]()`)
+		// resolves to the current page and would open a duplicate tab.
+		const href = modifiedLinkHref(event, anchor.getAttribute("href"));
+		if (!href) return;
+		event.preventDefault();
+		const opener = document.createElement("a");
+		opener.href = href;
+		opener.target = "_blank";
+		opener.rel = "noopener noreferrer";
+		opener.click();
+	}
+
+	function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+		if ((event.metaKey || event.ctrlKey) && event.key === "s") {
+			event.preventDefault();
+			void save();
+			return;
+		}
+		if (event.key === "Escape") {
+			// Cancel discards immediately — no confirmation, matching the
+			// no-autosave model: nothing was ever written until Save.
+			event.preventDefault();
+			onDone();
+		}
+	}
+
+	// Editor construction is synchronous but not instant on first mount;
+	// render nothing rather than a half-built surface.
+	if (!editor) return null;
+
+	return (
+		<div className="mdx-section" data-editing onClick={onClick} onKeyDown={onKeyDown}>
+			<EditorContent editor={editor} />
+			{/* Keyboard is the only way out of edit mode (no buttons), so the hints
+			    float in the right gutter beside the frame, out of the text flow —
+			    the section keeps its read-mode box exactly. pointer-events-none so
+			    the right ResizeHandle underneath still works. */}
+			<motion.div
+				aria-hidden="true"
+				className="pointer-events-none absolute top-0 left-[calc(100%+var(--space-8))] z-20 flex w-max flex-col gap-1.5 text-[length:var(--size-xs)] text-text-subtle"
+				variants={hintStack}
+				initial="initial"
+				animate={entered ? "animate" : "initial"}
+			>
+				<motion.span variants={hint} className="flex items-center gap-1.5">
+					<Kbd>{isApplePlatform() ? "⌘S" : "Ctrl S"}</Kbd> to save
+				</motion.span>
+				<motion.span variants={hint} className="flex items-center gap-1.5">
+					<Kbd>Esc</Kbd> to cancel
+				</motion.span>
+				<motion.span variants={hint} className="flex items-center gap-1.5">
+					<Kbd>{isApplePlatform() ? "⌘" : "Ctrl"}</Kbd> click to follow a link
+				</motion.span>
+			</motion.div>
+		</div>
+	);
+}