@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/ui/ConfirmDeleteDialog.tsx

@@ -0,0 +1,113 @@
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+import { AnimatePresence, motion } from "framer-motion";
+import { formatModified, formatSize } from "../format";
+import Button from "../builtins/Button";
+import type { ListingEntry } from "../router";
+import { Icon } from "./Icon";
+import { VARIANTS } from "../motion";
+
+export function ConfirmDeleteDialog({
+	open,
+	files,
+	pending,
+	onCancel,
+	onConfirm,
+}: {
+	open: boolean;
+	/** Selected file entries, in listing order. */
+	files: ListingEntry[];
+	pending: boolean;
+	onCancel: () => void;
+	onConfirm: () => void;
+}) {
+	// Document-level, not panel-level: while a delete is pending both buttons
+	// are disabled and the browser drops focus to <body>, so a panel onKeyDown
+	// would stop hearing Escape (e.g. after a failed request leaves the dialog
+	// open).
+	useEffect(() => {
+		if (!open) return;
+		function onKeyDown(event: KeyboardEvent) {
+			if (event.key === "Escape" && !pending) {
+				event.preventDefault();
+				onCancel();
+			}
+		}
+		document.addEventListener("keydown", onKeyDown);
+		return () => document.removeEventListener("keydown", onKeyDown);
+	}, [open, pending, onCancel]);
+
+	// Portal to <body>: this renders 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={pending ? undefined : onCancel}
+					{...VARIANTS.scrim}
+					className="fixed inset-0 z-[var(--z-modal)] flex justify-center bg-[var(--scrim)] pt-[10vh] backdrop-blur-sm"
+				>
+					<motion.div
+						onClick={(event) => event.stopPropagation()}
+						{...VARIANTS.pop}
+						role="alertdialog"
+						aria-modal="true"
+						aria-labelledby="confirm-delete-title"
+						className="w-[560px] max-w-[92vw] self-start overflow-hidden rounded-xl border border-border-default bg-surface-raised shadow-lg"
+					>
+						<div className="flex items-center gap-2 border-b border-border-subtle px-4 py-3">
+							<Icon name="trash-2" size="md" className="text-status-danger-fg" />
+							<div className="flex flex-col">
+								<span
+									id="confirm-delete-title"
+									className="font-sans font-semibold text-text-heading text-[length:var(--size-md)]"
+								>
+									Delete {files.length} {files.length === 1 ? "file" : "files"}?
+								</span>
+								<span className="font-sans text-[length:var(--size-sm)] text-text-muted">
+									They&rsquo;ll be moved to the system Trash — this can be undone from there.
+								</span>
+							</div>
+						</div>
+						<div className="max-h-72 overflow-y-auto p-2">
+							{files.map((file) => (
+								<div key={file.name} className="flex items-center gap-2 rounded-md px-2 py-1.5">
+									<Icon name="file-text" size="sm" className="shrink-0 text-text-subtle" />
+									<span className="truncate font-mono text-[length:var(--size-sm)]">
+										{file.name}
+									</span>
+									<span className="ml-auto flex shrink-0 gap-4 pl-4 font-mono text-[length:var(--size-xs)] text-text-subtle tabular-nums">
+										{typeof file.mtime === "number" ? (
+											<span>{formatModified(file.mtime)}</span>
+										) : null}
+										{typeof file.size === "number" ? (
+											<span className="w-16 text-right">{formatSize(file.size)}</span>
+										) : null}
+									</span>
+								</div>
+							))}
+						</div>
+						<div className="flex justify-end gap-2 border-t border-border-subtle px-4 py-3">
+							{/* Start keyboard focus on the safe action. */}
+							<Button variant="secondary" size="sm" autoFocus disabled={pending} onClick={onCancel}>
+								Cancel
+							</Button>
+							<Button
+								variant="danger"
+								size="sm"
+								icon="trash-2"
+								disabled={pending}
+								onClick={onConfirm}
+							>
+								{pending ? "Moving…" : "Move to Trash"}
+							</Button>
+						</div>
+					</motion.div>
+				</motion.div>
+			) : null}
+		</AnimatePresence>,
+		document.body,
+	);
+}

package/client/ui/ExpandModal.tsx

@@ -0,0 +1,342 @@
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { AnimatePresence, motion, useSpring } from "framer-motion";
+import { Icon } from "./Icon";
+import { IconButton } from "./IconButton";
+import { Kbd } from "./Kbd";
+import { TRANSITIONS, VARIANTS } from "../motion";
+
+export interface ExpandModalProps {
+	open: boolean;
+	onClose: () => void;
+	/** Lucide icon shown before the title. */
+	icon: string;
+	title: string;
+	/** Short interaction hint after the title, e.g. "Drag to pan · scroll to zoom". */
+	hint?: ReactNode;
+	/** Controls shown at the right of the header, before the close button. */
+	actions?: ReactNode;
+	/** Fills the panel below the header; render it `h-full` to take the whole area. */
+	children: ReactNode;
+}
+
+/** Explicit panel size once the reader has dragged an edge; null = the default inset. */
+interface PanelSize {
+	width: number;
+	height: number;
+}
+
+type Edge = "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
+
+const MIN_WIDTH = 480;
+const MIN_HEIGHT = 320;
+/** Smallest gap kept between the panel and the viewport while resizing. */
+const MARGIN = 16;
+
+// Grab strips are 10px wide, straddling the edge (5px out, 5px in); corners are 16px squares.
+// Written as literal class strings so Tailwind's scanner can see them.
+const EDGE_HANDLES: { edge: Edge; className: string; bar?: string }[] = [
+	{
+		edge: "n",
+		className: "top-[-5px] right-4 left-4 h-[10px] cursor-ns-resize",
+		bar: "top-[4px] right-0 left-0 h-[2px]",
+	},
+	{
+		edge: "s",
+		className: "bottom-[-5px] right-4 left-4 h-[10px] cursor-ns-resize",
+		bar: "bottom-[4px] right-0 left-0 h-[2px]",
+	},
+	{
+		edge: "e",
+		className: "top-4 right-[-5px] bottom-4 w-[10px] cursor-ew-resize",
+		bar: "top-0 right-[4px] bottom-0 w-[2px]",
+	},
+	{
+		edge: "w",
+		className: "top-4 bottom-4 left-[-5px] w-[10px] cursor-ew-resize",
+		bar: "top-0 bottom-0 left-[4px] w-[2px]",
+	},
+	{ edge: "nw", className: "top-[-5px] left-[-5px] h-4 w-4 cursor-nwse-resize" },
+	{ edge: "se", className: "right-[-5px] bottom-[-5px] h-4 w-4 cursor-nwse-resize" },
+	{ edge: "ne", className: "top-[-5px] right-[-5px] h-4 w-4 cursor-nesw-resize" },
+	{ edge: "sw", className: "bottom-[-5px] left-[-5px] h-4 w-4 cursor-nesw-resize" },
+];
+
+function clampSize(size: PanelSize, viewport: { width: number; height: number }): PanelSize {
+	// The minimum is capped by what's available: on a window narrower or shorter
+	// than the minimum the panel has to fit the viewport rather than overflow it
+	// (which would push the close control off screen).
+	const availableWidth = Math.max(0, viewport.width - MARGIN * 2);
+	const availableHeight = Math.max(0, viewport.height - MARGIN * 2);
+	const width = Math.min(Math.max(size.width, Math.min(MIN_WIDTH, availableWidth)), availableWidth);
+	const height = Math.min(
+		Math.max(size.height, Math.min(MIN_HEIGHT, availableHeight)),
+		availableHeight,
+	);
+	return { width: Math.round(width), height: Math.round(height) };
+}
+
+/** A viewport coordinate, in CSS pixels — the same x/y the DOM's own rects use. */
+interface Point {
+	x: number;
+	y: number;
+}
+
+/**
+ * The panel stays centred while it resizes, so moving one edge by `d` changes
+ * that dimension by `2d`. Each dimension is solved from the pointer's distance
+ * to the panel centre (minus where on the strip it was grabbed) rather than
+ * accumulated deltas, so a long drag can't drift.
+ */
+function resizeFromCentre(
+	edge: Edge,
+	pointer: Point,
+	centre: Point,
+	grab: Point,
+	current: PanelSize,
+	viewport: { width: number; height: number },
+): PanelSize {
+	let { width, height } = current;
+	if (edge.includes("e")) width = 2 * (pointer.x - centre.x - grab.x);
+	if (edge.includes("w")) width = 2 * (centre.x - pointer.x - grab.x);
+	if (edge.includes("s")) height = 2 * (pointer.y - centre.y - grab.y);
+	if (edge.includes("n")) height = 2 * (centre.y - pointer.y - grab.y);
+	return clampSize({ width, height }, viewport);
+}
+
+/**
+ * Near-full-screen modal for exploring a diagram or chart at a larger scale.
+ * The panel takes the viewport minus a small inset by default; dragging any
+ * edge or corner resizes it symmetrically so it stays centred (double-click a
+ * handle, or reopen, to reset), and
+ * `children` get the whole area under a slim header (icon, title, hint, close).
+ */
+export function ExpandModal({
+	open,
+	onClose,
+	icon,
+	title,
+	hint,
+	actions,
+	children,
+}: ExpandModalProps) {
+	const panelRef = useRef<HTMLDivElement>(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);
+	// glide, not snap (as for the sidebar/toc widths): the panel trails the
+	// cursor slightly so the spring is felt as it settles into shape.
+	const widthSpring = useSpring(0, TRANSITIONS.glide);
+	const heightSpring = useSpring(0, TRANSITIONS.glide);
+	/** Latest un-animated target, so clamping on window resize starts from the real size. */
+	const target = useRef<PanelSize | null>(null);
+	const drag = useRef<{
+		edge: Edge;
+		centre: Point;
+		/** Pointer distance past the grabbed edge at press time, so the edge doesn't snap under the cursor. */
+		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]);
+
+	// A custom size lasts for one viewing: reopening starts from the default inset.
+	const resetSize = useCallback(() => {
+		target.current = null;
+		setCustom(false);
+	}, []);
+
+	useEffect(() => {
+		if (!open) resetSize();
+	}, [open, resetSize]);
+
+	// Keep a custom size inside the window if the window shrinks underneath it.
+	useEffect(() => {
+		if (!custom) return;
+		function onResize() {
+			if (!target.current) return;
+			const next = clampSize(target.current, {
+				width: window.innerWidth,
+				height: window.innerHeight,
+			});
+			target.current = next;
+			widthSpring.set(next.width);
+			heightSpring.set(next.height);
+		}
+		window.addEventListener("resize", onResize);
+		return () => window.removeEventListener("resize", onResize);
+	}, [custom, widthSpring, heightSpring]);
+
+	const onHandleDown = useCallback(
+		(edge: Edge, event: React.PointerEvent<HTMLDivElement>) => {
+			const panel = panelRef.current;
+			if (!panel) return;
+			event.preventDefault();
+			const bounds = panel.getBoundingClientRect();
+			const centre = { x: bounds.left + bounds.width / 2, y: bounds.top + bounds.height / 2 };
+			const grab = {
+				x: edge.includes("e")
+					? event.clientX - bounds.right
+					: edge.includes("w")
+						? bounds.left - event.clientX
+						: 0,
+				y: edge.includes("s")
+					? event.clientY - bounds.bottom
+					: edge.includes("n")
+						? bounds.top - event.clientY
+						: 0,
+			};
+			drag.current = { edge, centre, grab };
+			// Land the springs on what's on screen (no animating up from 0) before
+			// the panel switches to the explicit, spring-driven size.
+			target.current = { width: bounds.width, height: bounds.height };
+			widthSpring.jump(bounds.width);
+			heightSpring.jump(bounds.height);
+			setCustom(true);
+			setDragging(edge);
+			try {
+				event.currentTarget.setPointerCapture(event.pointerId);
+			} catch {
+				// Not a live pointer (synthetic event); the drag still works while the cursor stays on the handle.
+			}
+			document.body.style.userSelect = "none";
+		},
+		[widthSpring, heightSpring],
+	);
+
+	const onHandleMove = useCallback(
+		(event: React.PointerEvent<HTMLDivElement>) => {
+			const current = drag.current;
+			if (!current) return;
+			const next = resizeFromCentre(
+				current.edge,
+				{ x: event.clientX, y: event.clientY },
+				current.centre,
+				current.grab,
+				target.current ?? { width: MIN_WIDTH, height: MIN_HEIGHT },
+				{ width: window.innerWidth, height: window.innerHeight },
+			);
+			target.current = next;
+			widthSpring.set(next.width);
+			heightSpring.set(next.height);
+		},
+		[widthSpring, heightSpring],
+	);
+
+	const onHandleUp = useCallback((event: React.PointerEvent<HTMLDivElement>) => {
+		if (!drag.current) return;
+		drag.current = null;
+		setDragging(null);
+		if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+			event.currentTarget.releasePointerCapture(event.pointerId);
+		}
+		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"
+				>
+					<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,
+	);
+}

package/client/ui/Icon.tsx

@@ -0,0 +1,114 @@
+// The explicit .mjs extension matters: this module is also reachable from
+// scripts/build-registry.ts under plain Node, whose ESM resolver (unlike
+// Vite's) requires a real extension since lucide-react's package.json has no
+// "exports" map for this subpath.
+import dynamicIconImports from "lucide-react/dynamicIconImports.mjs";
+import type { LucideIcon, LucideProps } from "lucide-react";
+import { useEffect, useState, type CSSProperties } from "react";
+import { staticIcons } from "./icon-set";
+
+const SIZES = { sm: 14, md: 16, lg: 20, xl: 24 } as const;
+
+export type IconSize = keyof typeof SIZES | number;
+
+export interface IconProps extends Omit<LucideProps, "size" | "strokeWidth" | "ref"> {
+	/** Lucide icon name in kebab-case, e.g. "search", "chevron-right", "file-text". */
+	name: string;
+	/** 14 / 16 / 20 / 24 px, or an explicit pixel number. Default "md". */
+	size?: IconSize;
+	/** "light" dims the glyph to 75% for secondary chrome. */
+	strokeWidth?: "light";
+	style?: CSSProperties;
+}
+
+type DynamicIconName = keyof typeof dynamicIconImports;
+
+function isDynamicIconName(name: string): name is DynamicIconName {
+	return Object.hasOwn(dynamicIconImports, name);
+}
+
+// Module-level so every Icon instance sharing a name shares one load: a
+// resolved glyph (or `null` for a name that turned out to have no default
+// export) sits in `resolved`, an in-flight import sits in `pending` until it
+// settles.
+const resolved = new Map<string, LucideIcon | null>();
+const pending = new Map<string, Promise<LucideIcon | null>>();
+
+function loadDynamicIcon(name: DynamicIconName): Promise<LucideIcon | null> {
+	const cached = resolved.get(name);
+	if (cached !== undefined) return Promise.resolve(cached);
+	const inFlight = pending.get(name);
+	if (inFlight) return inFlight;
+
+	const promise = dynamicIconImports[name]()
+		.then((mod) => mod.default ?? null)
+		.catch(() => null)
+		.then((glyph) => {
+			resolved.set(name, glyph);
+			pending.delete(name);
+			return glyph;
+		});
+	pending.set(name, promise);
+	return promise;
+}
+
+/**
+ * Lucide (stroke 1.75) is mdxserve's icon set. Components that show icons take a
+ * Lucide *name string* so MDX authors can write `icon="rocket"`; this is the one
+ * place that turns the name into a glyph. Unknown names render nothing rather
+ * than throwing, so a typo in a doc never breaks the page.
+ *
+ * Two tiers: `staticIcons` (client/ui/icon-set.ts) covers the ~30 names
+ * mdxserve's own chrome uses, resolved synchronously with no import at all.
+ * Any other name is looked up in lucide-react's `dynamicIconImports` map and
+ * loaded on demand — this is how MDX authors can write `icon="anything-in-
+ * lucide"` without every one of lucide's 2,022 icons shipping in the bundle.
+ * While a dynamic icon is loading, a same-size empty placeholder holds its
+ * layout so nothing shifts once the glyph lands.
+ */
+export function Icon({ name, size = "md", strokeWidth, style, ...rest }: IconProps) {
+	const px = typeof size === "number" ? size : SIZES[size];
+	const opacity = strokeWidth === "light" ? 0.75 : undefined;
+
+	const StaticGlyph = staticIcons[name];
+	const dynamic = !StaticGlyph && isDynamicIconName(name);
+	const [DynamicGlyph, setDynamicGlyph] = useState<LucideIcon | null>(() =>
+		dynamic ? (resolved.get(name) ?? null) : null,
+	);
+
+	useEffect(() => {
+		if (!dynamic) return;
+		if (resolved.has(name)) {
+			setDynamicGlyph(resolved.get(name) ?? null);
+			return;
+		}
+		let cancelled = false;
+		loadDynamicIcon(name).then((glyph) => {
+			if (!cancelled) setDynamicGlyph(glyph);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [dynamic, name]);
+
+	const Glyph = StaticGlyph ?? (dynamic ? DynamicGlyph : null);
+
+	if (!StaticGlyph && !dynamic) return null;
+
+	if (!Glyph) {
+		// Unresolved dynamic icon: still loading. Same footprint as the glyph
+		// it will become so nothing reflows once it lands.
+		return <svg aria-hidden="true" width={px} height={px} style={{ flex: "0 0 auto", ...style }} />;
+	}
+
+	return (
+		<Glyph
+			aria-hidden="true"
+			data-icon={name}
+			size={px}
+			strokeWidth={1.75}
+			style={{ flex: "0 0 auto", opacity, ...style }}
+			{...rest}
+		/>
+	);
+}

package/client/ui/IconButton.tsx

@@ -0,0 +1,63 @@
+import { forwardRef, type ButtonHTMLAttributes } from "react";
+import { motion, type MotionProps } from "framer-motion";
+import { Icon } from "./Icon";
+import { TRANSITIONS } from "../motion";
+
+const BOX: Record<"sm" | "md" | "lg", string> = {
+	sm: "h-[26px] w-[26px]",
+	md: "h-8 w-8",
+	lg: "h-[38px] w-[38px]",
+};
+
+// `motion.button` redefines a handful of DOM event props (onAnimationStart,
+// onDrag*…) with its own signatures; omitting their DOM versions here is what
+// lets `{...rest}` below flow straight onto it without a type clash.
+export interface IconButtonProps extends Omit<
+	ButtonHTMLAttributes<HTMLButtonElement>,
+	keyof MotionProps
+> {
+	/** Lucide icon name. */
+	icon: string;
+	size?: "sm" | "md" | "lg";
+	variant?: "ghost" | "outline";
+	/** Sticky pressed state, e.g. an enabled sidebar toggle. */
+	active?: boolean;
+	/** Accessible name — also used as the native tooltip. */
+	label?: string;
+}
+
+/** Small square control for chrome: sidebar toggle, code copy, diagram zoom. */
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
+	{ icon, size = "md", variant = "ghost", active, label, disabled, className, ...rest },
+	ref,
+) {
+	const bordered = variant === "outline";
+	return (
+		<motion.button
+			ref={ref}
+			type="button"
+			aria-label={label}
+			title={label}
+			disabled={disabled}
+			whileTap={disabled ? undefined : { scale: 0.92 }}
+			transition={TRANSITIONS.snap}
+			className={
+				"inline-flex items-center justify-center rounded-md cursor-pointer transition-colors " +
+				"disabled:cursor-not-allowed disabled:opacity-45 " +
+				BOX[size] +
+				" " +
+				(bordered ? "border border-border-default" : "border border-transparent") +
+				" " +
+				(active
+					? "bg-surface-active text-text-heading"
+					: bordered
+						? "bg-surface-card text-text-muted hover:bg-surface-hover"
+						: "text-text-muted hover:bg-surface-hover") +
+				(className ? " " + className : "")
+			}
+			{...rest}
+		>
+			<Icon name={icon} size={size === "sm" ? "sm" : "md"} />
+		</motion.button>
+	);
+});

package/client/ui/Kbd.tsx

@@ -0,0 +1,17 @@
+import type { HTMLAttributes } from "react";
+
+export interface KbdProps extends HTMLAttributes<HTMLElement> {}
+
+/** A single keycap, e.g. inside SearchDialog's "esc" hint. */
+export function Kbd({ className, ...rest }: KbdProps) {
+	return (
+		<kbd
+			className={
+				"inline-flex h-5 min-w-5 items-center justify-center rounded-sm border border-b-2 border-border-default " +
+				"bg-surface-card px-[5px] font-mono text-[length:var(--size-2xs)] font-medium text-text-muted" +
+				(className ? " " + className : "")
+			}
+			{...rest}
+		/>
+	);
+}