@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/MdSectionEditor.tsx

@@ -1,4 +1,21 @@
-import { useEffect, useState, type KeyboardEvent, type MouseEvent } from "react";
+import {
+	findDiagram,
+	replaceDiagram,
+	mermaidEditButtons,
+	type DiagramEditTarget,
+} from "./diagrams/edit-block";
+import type { ExistingDiagram } from "./diagrams/edit-context";
+import { mermaidSlash } from "./diagrams/slash";
+import { MermaidDialog } from "./diagrams/Dialog";
+import type { Range } from "@tiptap/core";
+import {
+	useEffect,
+	useState,
+	useRef,
+	useCallback,
+	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";
@@ -7,7 +24,7 @@ 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 { AnimatePresence, motion } from "framer-motion";
 import { isTRPCClientError } from "@trpc/client";
 import { trpcClient } from "./api";
 import { TRANSITIONS } from "./motion";
@@ -25,6 +42,7 @@ const hint = {
 };
 
 export interface MdSectionEditorProps {
+	initialDiagram?: ExistingDiagram;
 	/** 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. */
@@ -81,6 +99,7 @@ function unwrapSoftBreaks(editor: Editor): void {
  * `@tiptap/extension-link` install is needed to configure `link`.
  */
 export default function MdSectionEditor({
+	initialDiagram,
 	source,
 	version,
 	path,
@@ -89,6 +108,39 @@ export default function MdSectionEditor({
 	onDone,
 }: MdSectionEditorProps) {
 	const [saving, setSaving] = useState(false);
+	const diagramEnabled = useRef(false);
+	const [diagramReady, setDiagramReady] = useState(false);
+	const [editTarget, setEditTarget] = useState<DiagramEditTarget | null>(null);
+	const openedDiagram = useRef(false);
+	const [diagramRange, setDiagramRange] = useState<Range | null>(null);
+	const openDiagram = useRef<(range: Range) => void>(() => {});
+	openDiagram.current = setDiagramRange;
+	useEffect(() => {
+		let active = true;
+		const refresh = () => {
+			void trpcClient.getDiagramPreferences
+				.query({})
+				.then((settings) => {
+					if (active) {
+						diagramEnabled.current = settings.agent !== "disabled";
+						setDiagramReady(diagramEnabled.current);
+						if (!diagramEnabled.current) {
+							setDiagramRange(null);
+							setEditTarget(null);
+						}
+					}
+				})
+				.catch(() => {
+					diagramEnabled.current = false;
+				});
+		};
+		refresh();
+		window.addEventListener("mdxserve-diagram-preferences", refresh);
+		return () => {
+			active = false;
+			window.removeEventListener("mdxserve-diagram-preferences", refresh);
+		};
+	}, []);
 	// 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
@@ -99,6 +151,11 @@ export default function MdSectionEditor({
 
 	const editor = useEditor({
 		extensions: [
+			mermaidEditButtons(() => diagramEnabled.current, setEditTarget),
+			mermaidSlash(
+				() => diagramEnabled.current,
+				(range) => openDiagram.current(range),
+			),
 			StarterKit.configure({
 				heading: { levels: [1, 2, 3, 4, 5, 6] },
 				link: { openOnClick: false },
@@ -131,6 +188,44 @@ export default function MdSectionEditor({
 		setEntered(true);
 	}, [editor]);
 
+	useEffect(() => {
+		if (!editor || editor.isDestroyed || !initialDiagram || openedDiagram.current) return;
+		openedDiagram.current = true;
+		const target = findDiagram(editor, initialDiagram);
+		if (target) setEditTarget(target);
+		else
+			pushToast({
+				tone: "warn",
+				text: "Diagram changed on disk. Reopen the section before editing.",
+			});
+	}, [editor, initialDiagram]);
+
+	useEffect(() => {
+		if (!editor || editor.isDestroyed || !diagramReady || openedDiagram.current) return;
+		openedDiagram.current = true;
+		const document = editor.state.doc;
+		const block = document.firstChild;
+		// Tiptap adds an empty trailing paragraph after a code block.
+		const onlyDiagram =
+			document.childCount === 1 ||
+			(document.childCount === 2 &&
+				document.lastChild?.type.name === "paragraph" &&
+				document.lastChild.content.size === 0);
+		if (onlyDiagram && block?.type.name === "codeBlock" && block.attrs.language === "mermaid") {
+			setEditTarget({ range: { from: 0, to: block.nodeSize }, source: block.textContent });
+		}
+	}, [editor, diagramReady]);
+
+	useEffect(() => {
+		if (editor && !editor.isDestroyed) editor.view.dispatch(editor.state.tr);
+	}, [editor, diagramReady]);
+
+	const closeDiagram = useCallback(() => {
+		setDiagramRange(null);
+		setEditTarget(null);
+		editor?.commands.focus();
+	}, [editor]);
+
 	async function save() {
 		if (!editor || saving) return;
 		setSaving(true);
@@ -187,6 +282,7 @@ export default function MdSectionEditor({
 	}
 
 	function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+		if (diagramRange || editTarget) return;
 		if ((event.metaKey || event.ctrlKey) && event.key === "s") {
 			event.preventDefault();
 			void save();
@@ -207,6 +303,57 @@ export default function MdSectionEditor({
 	return (
 		<div className="mdx-section" data-editing onClick={onClick} onKeyDown={onKeyDown}>
 			<EditorContent editor={editor} />
+			<AnimatePresence>
+				{(diagramRange || editTarget) && (
+					<MermaidDialog
+						initialSource={editTarget?.source}
+						onClose={closeDiagram}
+						onInsert={(source) => {
+							if (editTarget) {
+								if (!replaceDiagram(editor, editTarget, source)) {
+									pushToast({
+										tone: "warn",
+										text: "Diagram changed. Reopen it before applying changes.",
+									});
+									return;
+								}
+								closeDiagram();
+								return;
+							}
+							if (!diagramRange) return;
+							if (diagramRange.to > editor.state.doc.content.size) {
+								closeDiagram();
+								return;
+							}
+							const from = editor.state.doc.resolve(diagramRange.from);
+							if (
+								from.parent.type.name !== "paragraph" ||
+								from.parent.textContent !==
+									editor.state.doc.textBetween(diagramRange.from, diagramRange.to)
+							) {
+								pushToast({
+									tone: "warn",
+									text: "Insertion location changed. Close the dialog and choose a new block.",
+								});
+								return;
+							}
+							editor
+								.chain()
+								.focus()
+								.insertContentAt(
+									{ from: from.before(), to: from.after() },
+									{
+										type: "codeBlock",
+										attrs: { language: "mermaid" },
+										content: [{ type: "text", text: source }],
+									},
+								)
+								.run();
+							closeDiagram();
+						}}
+					/>
+				)}
+			</AnimatePresence>
 			{/* 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

package/client/Mermaid.tsx

@@ -131,7 +131,17 @@ function useThemeTick(): number {
  * mirrored into the expanded modal's header so view controls that live in the
  * code frame (the flow-direction toggle) stay reachable at full size.
  */
-export function MermaidDiagram({ source, toolbar }: { source: string; toolbar?: ReactNode }) {
+export function MermaidDiagram({
+	source,
+	toolbar,
+	onRender,
+	fill = false,
+}: {
+	source: string;
+	toolbar?: ReactNode;
+	onRender?: (source: string, valid: boolean) => void;
+	fill?: boolean;
+}) {
 	// Seeded from the source so a chart-diagram fence never shows the
 	// "Rendering diagram…" placeholder — there is nothing to load for it.
 	const [state, setState] = useState<State>(() => {
@@ -177,7 +187,10 @@ export function MermaidDiagram({ source, toolbar }: { source: string; toolbar?:
 				return mermaid.render(renderId, source);
 			})
 			.then(({ svg }) => {
-				if (!cancelled) setState({ kind: "ok", svg });
+				if (!cancelled) {
+					setState({ kind: "ok", svg });
+					onRender?.(source, true);
+				}
 			})
 			.catch((error: unknown) => {
 				// mermaid.render() draws into a temporary `<div id="d<renderId>">` it
@@ -191,11 +204,12 @@ export function MermaidDiagram({ source, toolbar }: { source: string; toolbar?:
 				if (cancelled) return;
 				const message = error instanceof Error ? error.message : String(error);
 				setState({ kind: "error", message });
+				onRender?.(source, false);
 			});
 		return () => {
 			cancelled = true;
 		};
-	}, [source, id, themeTick]);
+	}, [source, id, themeTick, onRender]);
 
 	return (
 		<AnimatePresence mode="wait" initial={false}>
@@ -230,8 +244,12 @@ export function MermaidDiagram({ source, toolbar }: { source: string; toolbar?:
 					</DiagramNoticeBody>
 				</motion.div>
 			) : (
-				<motion.div key="ok" {...VARIANTS.fade}>
-					<ExpandableDiagram svg={state.svg} toolbar={toolbar} />
+				<motion.div key="ok" {...VARIANTS.fade} className={fill ? "h-full w-full" : undefined}>
+					{fill ? (
+						<PanZoomSvg svg={state.svg} viewportClassName="h-full" />
+					) : (
+						<ExpandableDiagram svg={state.svg} toolbar={toolbar} />
+					)}
 				</motion.div>
 			)}
 		</AnimatePresence>
@@ -384,6 +402,7 @@ function PanZoomSvg({
  */
 function ExpandableDiagram({ svg, toolbar }: { svg: string; toolbar?: ReactNode }) {
 	const [expanded, setExpanded] = useState(false);
+	const [closing, setClosing] = useState(false);
 	return (
 		<>
 			{/* Only one copy of the markup is live at a time. Mermaid doesn't namespace
@@ -392,7 +411,7 @@ function ExpandableDiagram({ svg, toolbar }: { svg: string; toolbar?: ReactNode
 			    SVG — the one svg-pan-zoom has already wrapped and transformed. The
 			    card sits behind the scrim while expanded, so the placeholder that
 			    holds its height never shows. */}
-			{expanded ? (
+			{expanded || closing ? (
 				<div className="h-96 w-full" aria-hidden="true" />
 			) : (
 				<PanZoomSvg svg={svg} viewportClassName="h-96" onExpand={() => setExpanded(true)} />
@@ -401,7 +420,11 @@ function ExpandableDiagram({ svg, toolbar }: { svg: string; toolbar?: ReactNode
 				open={expanded}
 				svg={svg}
 				toolbar={toolbar}
-				onClose={() => setExpanded(false)}
+				onClose={() => {
+					setClosing(true);
+					setExpanded(false);
+				}}
+				onExitComplete={() => setClosing(false)}
 			/>
 		</>
 	);
@@ -412,16 +435,19 @@ function DiagramModal({
 	svg,
 	toolbar,
 	onClose,
+	onExitComplete,
 }: {
 	open: boolean;
 	svg: string;
 	toolbar?: ReactNode;
 	onClose: () => void;
+	onExitComplete: () => void;
 }) {
 	return (
 		<ExpandModal
 			open={open}
 			onClose={onClose}
+			onExitComplete={onExitComplete}
 			icon="image"
 			title="Diagram"
 			hint="Drag to pan · scroll to zoom"

package/client/Settings.css

@@ -0,0 +1,17 @@
+@media (max-width: 639px) {
+	.diagram-settings .diagram-settings-body section {
+		padding: 20px;
+	}
+
+	.diagram-settings .diagram-setting-row {
+		flex-direction: column;
+		align-items: stretch;
+		gap: 10px;
+	}
+
+	.diagram-settings .diagram-setting-row .diagram-agent-select,
+	.diagram-settings .diagram-setting-row select {
+		width: 100%;
+		min-width: 0;
+	}
+}

package/client/Settings.tsx

@@ -0,0 +1,132 @@
+import { useAtom } from "jotai";
+import { useState, type ReactNode } from "react";
+import ChevronDown from "lucide-react/dist/esm/icons/chevron-down.mjs";
+import Network from "lucide-react/dist/esm/icons/network.mjs";
+import PanelsTopLeft from "lucide-react/dist/esm/icons/panels-top-left.mjs";
+import SettingsIcon from "lucide-react/dist/esm/icons/settings.mjs";
+import CloseIcon from "lucide-react/dist/esm/icons/x.mjs";
+import { contentLayoutAtom, tocVisibleAtom, type ContentLayout } from "./state";
+import { Modal } from "./ui/Modal";
+
+export function Settings({
+	onClose,
+	diagrams,
+	status,
+	saving = false,
+}: {
+	onClose: () => void;
+	diagrams?: ReactNode;
+	status?: ReactNode;
+	saving?: boolean;
+}) {
+	const [category, setCategory] = useState<"diagrams" | "layout">(diagrams ? "diagrams" : "layout");
+	const [layout, setLayout] = useAtom(contentLayoutAtom);
+	const [tocVisible, setTocVisible] = useAtom(tocVisibleAtom);
+	return (
+		<Modal
+			open
+			onClose={onClose}
+			dismissible={!saving}
+			className="diagram-dialog diagram-settings"
+			aria-label="Settings"
+		>
+			<header className="diagram-navbar">
+				<div className="diagram-title">
+					<SettingsIcon size={17} />
+					<h2>Settings</h2>
+				</div>
+				<button
+					type="button"
+					className="diagram-icon-button"
+					aria-label="Close settings"
+					disabled={saving}
+					onClick={onClose}
+				>
+					<CloseIcon size={18} />
+				</button>
+			</header>
+			<div className="diagram-settings-body">
+				<aside>
+					<button
+						type="button"
+						className="diagram-settings-category"
+						aria-pressed={category === "layout"}
+						onClick={() => setCategory("layout")}
+					>
+						<PanelsTopLeft size={15} />
+						Layout
+					</button>
+					{diagrams && (
+						<button
+							type="button"
+							className="diagram-settings-category"
+							aria-pressed={category === "diagrams"}
+							onClick={() => setCategory("diagrams")}
+						>
+							<Network size={15} />
+							Diagrams
+						</button>
+					)}
+				</aside>
+				{category === "layout" ? (
+					<section>
+						<h3>Layout</h3>
+						<p>Choose how content fills the available space.</p>
+						<label className="diagram-setting-row" htmlFor="content-layout">
+							<span>
+								<strong>Content layout</strong>
+								<small>
+									{layout === "flexible"
+										? "Drag the bars to resize content."
+										: "Content automatically fills the available width."}
+								</small>
+							</span>
+							<span className="diagram-agent-select">
+								<select
+									id="content-layout"
+									value={layout}
+									onChange={(event) => setLayout(event.target.value as ContentLayout)}
+								>
+									<option value="flexible">Flexible</option>
+									<option value="full-width">Full width</option>
+								</select>
+								<ChevronDown size={14} aria-hidden="true" />
+							</span>
+						</label>
+						<label className="diagram-setting-row" htmlFor="toc-visibility">
+							<span>
+								<strong>Table of contents</strong>
+								<small>Show the “On this page” navigation beside documents.</small>
+							</span>
+							<span className="diagram-agent-select">
+								<select
+									id="toc-visibility"
+									value={tocVisible ? "visible" : "hidden"}
+									onChange={(event) => setTocVisible(event.target.value === "visible")}
+								>
+									<option value="visible">Visible</option>
+									<option value="hidden">Hidden</option>
+								</select>
+								<ChevronDown size={14} aria-hidden="true" />
+							</span>
+						</label>
+					</section>
+				) : (
+					diagrams
+				)}
+			</div>
+			<footer className="diagram-settings-footer">
+				<span>
+					{category === "layout" ? (
+						"Saved in this browser."
+					) : (
+						<>
+							Also available through <code>mdxserve setup</code>
+						</>
+					)}
+				</span>
+				{status ?? <span role="status">Settings save automatically.</span>}
+			</footer>
+		</Modal>
+	);
+}

package/client/Table.tsx

@@ -1,14 +1,2 @@
-import type { TableHTMLAttributes } from "react";
-
-/**
- * MDXProvider `table` override. Tables with long cells (paths, code) can't
- * shrink below their content, so without this they'd overflow the prose column
- * and run under the TOC rail. Each table scrolls inside its own container.
- */
-export function Table(props: TableHTMLAttributes<HTMLTableElement>) {
-	return (
-		<div className="mdx-table-scroll">
-			<table {...props} />
-		</div>
-	);
-}
+// Compatibility export; native Markdown tables use the shared DataTable renderer.
+export { MarkdownTable as Table } from "./MarkdownTable";