@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/ui/ExpandModal.tsx

@@ -1,14 +1,15 @@
 import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
-import { createPortal } from "react-dom";
-import { AnimatePresence, motion, useSpring } from "framer-motion";
+import { Modal } from "./Modal";
+import { useSpring } from "framer-motion";
 import { Icon } from "./Icon";
 import { IconButton } from "./IconButton";
 import { Kbd } from "./Kbd";
-import { TRANSITIONS, VARIANTS } from "../motion";
+import { TRANSITIONS } from "../motion";
 
 export interface ExpandModalProps {
 	open: boolean;
 	onClose: () => void;
+	onExitComplete?: () => void;
 	/** Lucide icon shown before the title. */
 	icon: string;
 	title: string;
@@ -114,13 +115,14 @@ function resizeFromCentre(
 export function ExpandModal({
 	open,
 	onClose,
+	onExitComplete,
 	icon,
 	title,
 	hint,
 	actions,
 	children,
 }: ExpandModalProps) {
-	const panelRef = useRef<HTMLDivElement>(null);
+	const panelRef = useRef<HTMLDialogElement>(null);
 	// Whether the reader has taken over the size; the springs below hold it.
 	const [custom, setCustom] = useState(false);
 	const [dragging, setDragging] = useState<Edge | null>(null);
@@ -137,35 +139,14 @@ export function ExpandModal({
 		grab: Point;
 	} | null>(null);
 
-	// Document-level so Escape works wherever focus landed (a pan surface or
-	// chart is a plain element and never holds focus itself). A control in the
-	// header that already consumed the key (the layout menu closing itself)
-	// marks the event default-prevented, and that Escape must not also close
-	// the modal.
 	useEffect(() => {
 		if (!open) return;
-		function onKeyDown(event: KeyboardEvent) {
-			if (event.key === "Escape" && !event.defaultPrevented) {
-				event.preventDefault();
-				onClose();
-			}
-		}
-		document.addEventListener("keydown", onKeyDown);
-		// Wheel-zooming the content must not also scroll the document behind the scrim.
-		const previousOverflow = document.body.style.overflow;
-		document.body.style.overflow = "hidden";
 		return () => {
-			document.removeEventListener("keydown", onKeyDown);
-			document.body.style.overflow = previousOverflow;
-			// A drag interrupted by closing (Escape, scrim click, unmount) never sees
-			// pointerup, so release its global state here: otherwise text selection
-			// stays disabled page-wide and the next open treats a hover over a handle
-			// as an in-progress drag.
 			drag.current = null;
 			setDragging(null);
 			document.body.style.userSelect = "";
 		};
-	}, [open, onClose]);
+	}, [open]);
 
 	// A custom size lasts for one viewing: reopening starts from the default inset.
 	const resetSize = useCallback(() => {
@@ -174,7 +155,7 @@ export function ExpandModal({
 	}, []);
 
 	useEffect(() => {
-		if (!open) resetSize();
+		if (open) resetSize();
 	}, [open, resetSize]);
 
 	// Keep a custom size inside the window if the window shrinks underneath it.
@@ -260,83 +241,61 @@ export function ExpandModal({
 		document.body.style.userSelect = "";
 	}, []);
 
-	// The SSR entry renders the same component tree; never touch `document` at
-	// render time there (the modal is only ever opened client-side anyway).
-	if (typeof document === "undefined") return null;
-
-	// Portal to <body>: callers sit inside the route wrapper, whose fadeRise
-	// transform would otherwise turn `fixed` into "fixed to the column" and let
-	// the scrim miss the top bar and sidebar.
-	return createPortal(
-		<AnimatePresence>
-			{open ? (
-				<motion.div
-					key="scrim"
-					onClick={onClose}
-					{...VARIANTS.scrim}
-					className="fixed inset-0 z-[var(--z-modal)] flex items-center justify-center bg-[var(--scrim)] p-4 backdrop-blur-sm sm:p-8"
+	return (
+		<Modal
+			open={open}
+			onClose={onClose}
+			onExitComplete={onExitComplete}
+			panelRef={panelRef}
+			aria-label={`Expanded ${title.toLowerCase()}`}
+			// A dragged panel takes an explicit size; auto margins keep it centered.
+			style={
+				custom
+					? { width: widthSpring, height: heightSpring, maxWidth: "none", flex: "none" }
+					: undefined
+			}
+			className="flex h-[calc(100dvh-32px)] w-[min(1600px,calc(100vw-32px))] flex-col overflow-visible sm:h-[calc(100dvh-64px)] sm:w-[min(1600px,calc(100vw-64px))]"
+		>
+			<div className="flex shrink-0 items-center gap-2 rounded-t-xl border-b border-border-subtle px-3 py-2">
+				<Icon name={icon} size="md" className="text-text-muted" />
+				<span className="font-sans font-semibold text-text-heading text-[length:var(--size-sm)]">
+					{title}
+				</span>
+				<span className="hidden items-center gap-1.5 font-sans text-[length:var(--size-xs)] text-text-subtle sm:flex">
+					{hint ? <>{hint} · </> : null}
+					drag an edge to resize · <Kbd>esc</Kbd> to close
+				</span>
+				<div className="ml-auto flex items-center gap-2">
+					{actions}
+					<IconButton icon="x" label="Close" size="md" autoFocus onClick={onClose} />
+				</div>
+			</div>
+			<div className="min-h-0 flex-1 overflow-hidden rounded-b-xl">{children}</div>
+			{EDGE_HANDLES.map(({ edge, className, bar }) => (
+				<div
+					key={edge}
+					role="separator"
+					aria-label={`Resize ${edge} edge`}
+					className={"group absolute z-10 " + className}
+					onPointerDown={(event) => onHandleDown(edge, event)}
+					onPointerMove={onHandleMove}
+					onPointerUp={onHandleUp}
+					onPointerCancel={onHandleUp}
+					onDoubleClick={resetSize}
 				>
-					<motion.div
-						ref={panelRef}
-						onClick={(event) => event.stopPropagation()}
-						{...VARIANTS.pop}
-						role="dialog"
-						aria-modal="true"
-						aria-label={`Expanded ${title.toLowerCase()}`}
-						// Once an edge has been dragged the panel takes an explicit size and stays
-						// centred by the scrim's flex box; until then it fills the padded area
-						// (capped for very wide windows).
-						style={
-							custom
-								? { width: widthSpring, height: heightSpring, maxWidth: "none", flex: "none" }
-								: undefined
-						}
-						className="relative flex h-full w-full max-w-[1600px] flex-col rounded-xl border border-border-default bg-surface-raised shadow-lg"
-					>
-						<div className="flex shrink-0 items-center gap-2 rounded-t-xl border-b border-border-subtle px-3 py-2">
-							<Icon name={icon} size="md" className="text-text-muted" />
-							<span className="font-sans font-semibold text-text-heading text-[length:var(--size-sm)]">
-								{title}
-							</span>
-							<span className="hidden items-center gap-1.5 font-sans text-[length:var(--size-xs)] text-text-subtle sm:flex">
-								{hint ? <>{hint} · </> : null}
-								drag an edge to resize · <Kbd>esc</Kbd> to close
-							</span>
-							<div className="ml-auto flex items-center gap-2">
-								{actions}
-								<IconButton icon="x" label="Close" size="md" autoFocus onClick={onClose} />
-							</div>
-						</div>
-						<div className="min-h-0 flex-1 overflow-hidden rounded-b-xl">{children}</div>
-						{EDGE_HANDLES.map(({ edge, className, bar }) => (
-							<div
-								key={edge}
-								role="separator"
-								aria-label={`Resize ${edge} edge`}
-								className={"group absolute z-10 " + className}
-								onPointerDown={(event) => onHandleDown(edge, event)}
-								onPointerMove={onHandleMove}
-								onPointerUp={onHandleUp}
-								onPointerCancel={onHandleUp}
-								onDoubleClick={resetSize}
-							>
-								{bar ? (
-									<span
-										className={
-											"absolute rounded-full transition-opacity " +
-											bar +
-											(dragging === edge
-												? " bg-surface-accent opacity-100"
-												: " bg-border-default opacity-0 group-hover:opacity-100")
-										}
-									/>
-								) : null}
-							</div>
-						))}
-					</motion.div>
-				</motion.div>
-			) : null}
-		</AnimatePresence>,
-		document.body,
+					{bar ? (
+						<span
+							className={
+								"absolute rounded-full transition-opacity " +
+								bar +
+								(dragging === edge
+									? " bg-surface-accent opacity-100"
+									: " bg-border-default opacity-0 group-hover:opacity-100")
+							}
+						/>
+					) : null}
+				</div>
+			))}
+		</Modal>
 	);
 }

package/client/ui/Modal.tsx

@@ -0,0 +1,123 @@
+import { useEffect, useRef, type Ref } from "react";
+import { createPortal } from "react-dom";
+import { AnimatePresence, motion, useIsPresent, type HTMLMotionProps } from "framer-motion";
+import { VARIANTS } from "../motion";
+
+type ModalProps = Omit<HTMLMotionProps<"dialog">, "onClose" | "onCancel" | "ref" | "open"> & {
+	open: boolean;
+	onClose?: () => void;
+	onExitComplete?: () => void;
+	/** Disable Escape and backdrop dismissal while an operation is pending. */
+	dismissible?: boolean;
+	dismissOnBackdrop?: boolean;
+	/** Override backdrop dismissal, for example to protect an unsaved draft. */
+	onBackdropClick?: () => void;
+	placement?: "top" | "center";
+	panelRef?: Ref<HTMLDialogElement>;
+	initialFocus?: string;
+};
+
+// A parent and its nested modal can unmount in either order.
+const scrollLocks = new WeakMap<Document, { count: number; overflow: string }>();
+
+/**
+ * Native modality supplies focus containment, focus return and nested top-layer ordering.
+ * Toggle `open` to close, or wrap a conditionally mounted owner in AnimatePresence.
+ * Exit propagation keeps the native dialog open until its panel has finished fading.
+ */
+export function Modal({ open, onExitComplete, ...props }: ModalProps) {
+	if (typeof document === "undefined") return null;
+	return createPortal(
+		<AnimatePresence propagate onExitComplete={onExitComplete}>
+			{open && <ModalSurface key="modal" {...props} />}
+		</AnimatePresence>,
+		document.body,
+	);
+}
+
+function ModalSurface({
+	onClose,
+	dismissible = true,
+	dismissOnBackdrop = true,
+	onBackdropClick,
+	placement = "center",
+	panelRef,
+	initialFocus,
+	className = "",
+	children,
+	onKeyDown,
+	...props
+}: Omit<ModalProps, "open">) {
+	const present = useIsPresent();
+	const dialogRef = useRef<HTMLDialogElement>(null);
+	const backdropPress = useRef(false);
+	useEffect(() => {
+		const dialog = dialogRef.current!;
+		const previousFocus = document.activeElement;
+		const scrollLock = scrollLocks.get(document) ?? {
+			count: 0,
+			overflow: document.body.style.overflow,
+		};
+		scrollLock.count += 1;
+		scrollLocks.set(document, scrollLock);
+		dialog.showModal();
+		if (initialFocus) dialog.querySelector<HTMLElement>(initialFocus)?.focus();
+		document.body.style.overflow = "hidden";
+		return () => {
+			dialog.close();
+			scrollLock.count -= 1;
+			if (scrollLock.count === 0) {
+				document.body.style.overflow = scrollLock.overflow;
+				scrollLocks.delete(document);
+			}
+			if (previousFocus instanceof HTMLElement && previousFocus.isConnected) previousFocus.focus();
+		};
+	}, [initialFocus]);
+
+	function isBackdrop(event: React.MouseEvent<HTMLDialogElement>) {
+		const bounds = event.currentTarget.getBoundingClientRect();
+		return (
+			event.target === event.currentTarget &&
+			(event.clientX < bounds.left ||
+				event.clientX > bounds.right ||
+				event.clientY < bounds.top ||
+				event.clientY > bounds.bottom)
+		);
+	}
+
+	return (
+		<motion.dialog
+			{...VARIANTS.pop}
+			{...props}
+			ref={(dialog) => {
+				dialogRef.current = dialog;
+				if (typeof panelRef === "function") return panelRef(dialog);
+				if (panelRef) panelRef.current = dialog;
+			}}
+			aria-modal="true"
+			data-exiting={!present || undefined}
+			className={`modal modal--${placement} ${className}`}
+			onCancel={(event) => {
+				event.preventDefault();
+				event.stopPropagation();
+				if (present && dismissible) onClose?.();
+			}}
+			onKeyDown={(event) => {
+				onKeyDown?.(event);
+				event.stopPropagation();
+			}}
+			onPointerDown={(event) => {
+				backdropPress.current = isBackdrop(event);
+			}}
+			onClick={(event) => {
+				event.stopPropagation();
+				const outside = backdropPress.current && isBackdrop(event);
+				backdropPress.current = false;
+				if (present && outside && dismissible && dismissOnBackdrop)
+					(onBackdropClick ?? onClose)?.();
+			}}
+		>
+			{children}
+		</motion.dialog>
+	);
+}

package/client/ui/ResizeHandle.tsx

@@ -178,7 +178,7 @@ export function ResizeHandle({
 			onPointerCancel={onPointerUp}
 			style={{ width: HANDLE_ZONE, ...zoneStyle }}
 			className={
-				"absolute inset-y-0 z-10 flex cursor-col-resize " +
+				"absolute inset-y-0 z-10 hidden md:flex cursor-col-resize " +
 				(anchored
 					? "items-center " + (side === "right" ? "justify-center" : "justify-end")
 					: // A column so the sticky pill can slide along the zone's full height.

package/client/ui/SearchDialog.tsx

@@ -1,3 +1,4 @@
+import { Modal } from "./Modal";
 import {
 	useEffect,
 	useState,
@@ -5,10 +6,10 @@ import {
 	type KeyboardEvent,
 	type ReactNode,
 } from "react";
-import { AnimatePresence, motion, type MotionProps } from "framer-motion";
+import { motion, type MotionProps } from "framer-motion";
 import { Icon } from "./Icon";
 import { Kbd } from "./Kbd";
-import { TRANSITIONS, VARIANTS } from "../motion";
+import { TRANSITIONS } from "../motion";
 
 export interface SearchResult {
 	title: ReactNode;
@@ -49,7 +50,7 @@ function highlight(text: ReactNode, terms: string[] | undefined): ReactNode {
 // React still types on `HTMLAttributes`); `Omit` it, along with the
 // motion.div-owned event props, before extending.
 export interface SearchDialogProps extends Omit<
-	HTMLAttributes<HTMLDivElement>,
+	HTMLAttributes<HTMLDialogElement>,
 	"results" | "onSelect" | keyof MotionProps
 > {
 	open?: boolean;
@@ -79,7 +80,7 @@ export function SearchDialog({
 		setHighlighted(0);
 	}, [query, results, open]);
 
-	function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+	function handleKeyDown(event: KeyboardEvent<HTMLDialogElement>) {
 		if (event.key === "ArrowDown") {
 			event.preventDefault();
 			setHighlighted((current) => Math.min(current + 1, Math.max(results.length - 1, 0)));
@@ -92,96 +93,88 @@ export function SearchDialog({
 				event.preventDefault();
 				onSelect?.(result);
 			}
-		} else if (event.key === "Escape") {
-			event.preventDefault();
-			onClose?.();
 		}
 	}
 
 	return (
-		<AnimatePresence>
-			{open ? (
-				<motion.div
-					key="scrim"
+		<Modal
+			open={open}
+			onClose={onClose}
+			placement="top"
+			aria-label="Search docs"
+			className={"w-[560px] max-w-[calc(100vw-2rem)] overflow-hidden " + (className ?? "")}
+			onKeyDown={handleKeyDown}
+			{...rest}
+		>
+			<div className="flex h-12 items-center gap-3 border-b border-border-subtle px-4">
+				<Icon name="search" size="md" className="text-text-subtle" />
+				<input
+					autoFocus
+					data-bare-focus
+					value={query}
+					onChange={(event) => onQueryChange?.(event.target.value)}
+					placeholder="Search docs"
+					aria-label="Search docs"
+					className="min-w-0 flex-1 border-0 bg-transparent text-[18px] font-normal text-text-body outline-none placeholder:text-text-subtle"
+				/>
+				<button
+					type="button"
+					aria-label="Close search"
 					onClick={onClose}
-					{...VARIANTS.scrim}
-					className="fixed inset-0 z-[var(--z-modal)] flex justify-center bg-[var(--scrim)] pt-[10vh] backdrop-blur-sm"
+					className="flex h-11 w-11 shrink-0 cursor-pointer items-center justify-center rounded-md text-text-subtle md:hidden"
 				>
-					<motion.div
-						onClick={(event) => event.stopPropagation()}
-						onKeyDown={handleKeyDown}
-						{...VARIANTS.pop}
-						className={
-							"w-[560px] max-w-[92vw] self-start overflow-hidden rounded-xl border border-border-default bg-surface-raised shadow-lg" +
-							(className ? " " + className : "")
-						}
-						{...rest}
-					>
-						<div className="flex h-12 items-center gap-3 border-b border-border-subtle px-4">
-							<Icon name="search" size="md" className="text-text-subtle" />
-							<input
-								autoFocus
-								data-bare-focus
-								value={query}
-								onChange={(event) => onQueryChange?.(event.target.value)}
-								placeholder="Search docs"
-								className="flex-1 border-0 bg-transparent text-[18px] font-normal text-text-body outline-none placeholder:text-text-subtle"
-							/>
-							<Kbd>esc</Kbd>
-						</div>
-						<motion.div
-							layout
-							transition={TRANSITIONS.glide}
-							className="max-h-80 overflow-y-auto p-2"
-						>
-							{results.length === 0 ? (
-								<div className="p-6 text-center text-[13px] leading-normal font-medium text-text-subtle">
-									No matches
+					<Icon name="x" size="sm" />
+				</button>
+				<span className="hidden md:contents">
+					<Kbd>esc</Kbd>
+				</span>
+			</div>
+			<motion.div layout transition={TRANSITIONS.glide} className="max-h-80 overflow-y-auto p-2">
+				{results.length === 0 ? (
+					<div className="p-6 text-center text-[13px] leading-normal font-medium text-text-subtle">
+						No matches
+					</div>
+				) : (
+					results.map((result, index) => {
+						const active = index === highlighted;
+						return (
+							<motion.div
+								key={(result.path ?? "") + index}
+								layout
+								initial={{ opacity: 0, y: 4 }}
+								animate={{ opacity: 1, y: 0 }}
+								transition={{
+									...TRANSITIONS.glide,
+									delay: Math.min(index, STAGGER_CAP - 1) * 0.02,
+								}}
+								onMouseEnter={() => setHighlighted(index)}
+								onClick={() => onSelect?.(result)}
+								className={
+									"flex cursor-pointer items-start gap-3 rounded-md p-2.5 " +
+									(active ? "bg-surface-hover" : "bg-transparent")
+								}
+							>
+								<Icon name="file-text" size="sm" className="mt-0.5 text-text-subtle" />
+								<div className="min-w-0 flex-1">
+									{result.label ? (
+										<div className="overflow-hidden text-ellipsis whitespace-nowrap font-mono text-[length:var(--size-2xs)] text-text-subtle">
+											{highlight(result.label, result.terms)}
+										</div>
+									) : null}
+									<div className="text-[13px] leading-normal font-semibold text-text-heading">
+										{highlight(result.title, result.terms)}
+									</div>
+									{result.excerpt ? (
+										<div className="mt-px overflow-hidden text-ellipsis whitespace-nowrap text-[12px] font-normal text-text-muted">
+											{highlight(result.excerpt, result.terms)}
+										</div>
+									) : null}
 								</div>
-							) : (
-								results.map((result, index) => {
-									const active = index === highlighted;
-									return (
-										<motion.div
-											key={(result.path ?? "") + index}
-											layout
-											initial={{ opacity: 0, y: 4 }}
-											animate={{ opacity: 1, y: 0 }}
-											transition={{
-												...TRANSITIONS.glide,
-												delay: Math.min(index, STAGGER_CAP - 1) * 0.02,
-											}}
-											onMouseEnter={() => setHighlighted(index)}
-											onClick={() => onSelect?.(result)}
-											className={
-												"flex cursor-pointer items-start gap-3 rounded-md p-2.5 " +
-												(active ? "bg-surface-hover" : "bg-transparent")
-											}
-										>
-											<Icon name="file-text" size="sm" className="mt-0.5 text-text-subtle" />
-											<div className="min-w-0 flex-1">
-												{result.label ? (
-													<div className="overflow-hidden text-ellipsis whitespace-nowrap font-mono text-[length:var(--size-2xs)] text-text-subtle">
-														{highlight(result.label, result.terms)}
-													</div>
-												) : null}
-												<div className="text-[13px] leading-normal font-semibold text-text-heading">
-													{highlight(result.title, result.terms)}
-												</div>
-												{result.excerpt ? (
-													<div className="mt-px overflow-hidden text-ellipsis whitespace-nowrap text-[12px] font-normal text-text-muted">
-														{highlight(result.excerpt, result.terms)}
-													</div>
-												) : null}
-											</div>
-										</motion.div>
-									);
-								})
-							)}
-						</motion.div>
-					</motion.div>
-				</motion.div>
-			) : null}
-		</AnimatePresence>
+							</motion.div>
+						);
+					})
+				)}
+			</motion.div>
+		</Modal>
 	);
 }

package/client/ui/modal.css

@@ -0,0 +1,42 @@
+.modal {
+	position: fixed;
+	inset: 0;
+	margin: auto;
+	padding: 0;
+	max-width: calc(100vw - 32px);
+	max-height: calc(100dvh - 32px);
+	border: 1px solid var(--border-default);
+	border-radius: var(--radius-xl, 12px);
+	background: var(--surface-raised);
+	color: var(--text-body);
+	box-shadow: 0 28px 100px #0006;
+}
+.modal::backdrop {
+	background: var(--scrim);
+	backdrop-filter: blur(4px);
+	animation: modal-backdrop-in var(--dur-fast) var(--ease-standard) both;
+}
+.modal--top {
+	margin-top: 10vh;
+	max-height: 80dvh;
+}
+
+.modal[data-exiting]::backdrop {
+	animation-name: modal-backdrop-out;
+}
+@keyframes modal-backdrop-in {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}
+@keyframes modal-backdrop-out {
+	from {
+		opacity: 1;
+	}
+	to {
+		opacity: 0;
+	}
+}