@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/CrossFade.tsx

@@ -0,0 +1,72 @@
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { motion } from "framer-motion";
+import { enterTransition, fadeSwapTransition } from "./motion";
+
+export interface CrossFadePane {
+	key: string;
+	node: ReactNode;
+	/** Extra props for the pane wrapper (e.g. role="tabpanel", ids). */
+	props?: Record<string, unknown>;
+}
+
+/**
+ * Cross-fades between panes that all stay mounted. Panes are stacked in a
+ * single grid cell and the container's height tweens to the active pane's
+ * height, so switching never collapses or jumps the layout. Inactive panes
+ * are inert and hidden from assistive tech.
+ */
+export function CrossFade({
+	active,
+	panes,
+	className,
+}: {
+	active: string;
+	panes: CrossFadePane[];
+	className?: string;
+}) {
+	const refs = useRef(new Map<string, HTMLDivElement>());
+	const [height, setHeight] = useState<number | null>(null);
+
+	useLayoutEffect(() => {
+		const el = refs.current.get(active);
+		if (!el) return;
+		const measure = () => setHeight(el.offsetHeight);
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [active, panes.length]);
+
+	return (
+		<motion.div
+			className={`grid grid-cols-[minmax(0,1fr)] overflow-hidden ${className ?? ""}`}
+			initial={false}
+			animate={height === null ? undefined : { height }}
+			transition={enterTransition}
+			style={height === null ? undefined : { height }}
+		>
+			{panes.map((pane) => {
+				const isActive = pane.key === active;
+				return (
+					<motion.div
+						key={pane.key}
+						ref={(el) => {
+							if (el) refs.current.set(pane.key, el);
+							else refs.current.delete(pane.key);
+						}}
+						className="min-w-0 [grid-area:1/1] self-start"
+						initial={false}
+						animate={{ opacity: isActive ? 1 : 0 }}
+						transition={fadeSwapTransition}
+						style={{ pointerEvents: isActive ? "auto" : "none" }}
+						inert={!isActive}
+						aria-hidden={!isActive}
+						{...pane.props}
+					>
+						{pane.node}
+					</motion.div>
+				);
+			})}
+		</motion.div>
+	);
+}

package/client/DocContext.ts

@@ -0,0 +1,14 @@
+import { createContext } from "react";
+
+/**
+ * The absolute on-disk path of the doc currently rendering. Provided by
+ * `DocView` around the compiled MDX module's `<Content/>`, so any
+ * `MdSection` inside it (including nested ones re-imported via HMR) can
+ * reach the path without threading it through every builtin's props.
+ *
+ * `null` outside a doc render — e.g. `MdSection` also has to work when the
+ * SSR worker (`client/ssr-entry.tsx`) renders a doc module directly for
+ * `validate_doc`, which has no router and thus no provider above it. See the
+ * `location`-based fallback in `client/MdSection.tsx`.
+ */
+export const DocContext = createContext<{ path: string } | null>(null);

package/client/DocView.tsx

@@ -0,0 +1,107 @@
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { useAtomValue, useSetAtom } from "jotai";
+import { DocContext } from "./DocContext";
+import { ErrorBox } from "./ErrorBox";
+import { RenderErrorBoundary } from "./RenderErrorBoundary";
+import type { DocModuleState } from "./doc-module-cache";
+import { ResizeHandle } from "./ui/ResizeHandle";
+import { DOC_MAX_WIDTH, DOC_MIN_WIDTH, docWidthAtom, openSectionAtom } from "./state";
+
+// Each Component a re-import produces (including an HMR re-import after a
+// fix) is a distinct function identity, so this assigns it a stable, unique
+// key the RenderErrorBoundary below can be keyed on to reset itself.
+const moduleKeys = new WeakMap<object, number>();
+let nextModuleKey = 0;
+function keyForComponent(Component: object): number {
+	let key = moduleKeys.get(Component);
+	if (key === undefined) {
+		key = nextModuleKey++;
+		moduleKeys.set(Component, key);
+	}
+	return key;
+}
+
+export function DocView({
+	path,
+	module,
+	onRendered,
+}: {
+	path: string;
+	/**
+	 * The cached module for `path` (client/doc-module-cache.ts), read
+	 * by the caller rather than here: keeping this component's own import
+	 * graph free of router.ts (and the tRPC/react-query it pulls in) is what
+	 * lets client/standalone-entry.tsx reuse it without either.
+	 */
+	module: DocModuleState | undefined;
+	/**
+	 * Fired once the article for the *current* cached module is on the page —
+	 * keyed on the cached entry's identity (not just route.path) so it fires
+	 * exactly once per resolved module, including the async case where the
+	 * initial server-rendered route's module is still importing on mount (see
+	 * the bootstrap effect in client/router.ts). Lets TocRail/useToc know when
+	 * it's safe to re-scan the DOM for headings.
+	 */
+	onRendered?: () => void;
+}) {
+	const cached = module;
+	const setWidth = useSetAtom(docWidthAtom);
+	// While a section is being edited the page width is pinned: a drag would
+	// reflow the editor under the caret, and the handles' hover strips sit
+	// exactly where the frame's glow and hints live.
+	const editing = useAtomValue(openSectionAtom) !== null;
+	const container = useRef<HTMLDivElement>(null);
+	// Every `MdSection` inside `<Content/>` reads the doc's path off this
+	// context (see client/DocContext.ts) instead of a prop, since MDX content
+	// components render through the MDXProvider map and never see route props
+	// directly. Memoized on the path so identity-sensitive children (none
+	// currently, but cheap insurance) don't see a new object every render.
+	const docContext = useMemo(() => ({ path }), [path]);
+
+	useLayoutEffect(() => {
+		if (cached?.status === "ok") onRendered?.();
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [cached, onRendered]);
+
+	// The router always resolves the module before setting a "doc" route (see
+	// client/router.ts loadRoute / the initial-route bootstrap effect), so this
+	// is only ever transiently empty on the very first render after boot.
+	if (!cached) return null;
+
+	if (cached.status === "error") {
+		return <ErrorBox message={cached.message} />;
+	}
+
+	const Content = cached.Component;
+	return (
+		<div ref={container} className="relative">
+			{!editing && (
+				<>
+					<ResizeHandle
+						side="left"
+						container={container}
+						onResize={setWidth}
+						label="Resize page"
+						minWidth={DOC_MIN_WIDTH}
+						maxWidth={DOC_MAX_WIDTH}
+					/>
+					<ResizeHandle
+						side="right"
+						container={container}
+						onResize={setWidth}
+						label="Resize page"
+						minWidth={DOC_MIN_WIDTH}
+						maxWidth={DOC_MAX_WIDTH}
+					/>
+				</>
+			)}
+			<article className="mdx-prose min-w-0 max-w-full">
+				<DocContext value={docContext}>
+					<RenderErrorBoundary key={keyForComponent(Content)}>
+						<Content />
+					</RenderErrorBoundary>
+				</DocContext>
+			</article>
+		</div>
+	);
+}

package/client/ErrorBox.tsx

@@ -0,0 +1,23 @@
+import { motion } from "framer-motion";
+import { fadeRise } from "./motion";
+
+/**
+ * Shown in place of a doc's content when it fails to render — either a
+ * dynamic import error (DocView) or a render-time throw caught by
+ * RenderErrorBoundary. Lives in its own file (not DocView.tsx) so
+ * RenderErrorBoundary can import it without importing DocView, which would
+ * otherwise cycle back through client/router.ts and client/api.ts.
+ */
+export function ErrorBox({ message }: { message: string }) {
+	return (
+		<motion.div
+			variants={fadeRise}
+			initial="initial"
+			animate="enter"
+			className="rounded border border-red-200 bg-red-50 p-4 text-sm text-red-800 dark:border-red-900 dark:bg-red-950 dark:text-red-200"
+		>
+			<p className="mb-2 font-semibold">Failed to render this page</p>
+			<pre className="whitespace-pre-wrap break-words font-mono text-xs">{message}</pre>
+		</motion.div>
+	);
+}

package/client/Heading.tsx

@@ -0,0 +1,31 @@
+import type { ComponentPropsWithoutRef, ElementType } from "react";
+
+/**
+ * MDXProvider `h2`/`h3`/`h4` overrides. `rehype-slug` (see client/entry.tsx)
+ * stamps an `id` on every heading it compiles; this factory adds the hover
+ * affordance that links to it (`.mdx-anchor`, styled + positioned by
+ * client/design/base/prose.css — it only shows up on heading hover or focus).
+ * A heading with no `id` (hand-written JSX without rehype-slug) renders
+ * without the anchor rather than linking to nothing.
+ */
+function makeHeading<Level extends "h2" | "h3" | "h4">(tag: Level) {
+	// JSX can't use a generic type parameter directly as a tag name; narrow it
+	// to `ElementType` once here so `<Tag>` below type-checks as an intrinsic element.
+	const Tag = tag as ElementType;
+	return function Heading({ id, children, ...rest }: ComponentPropsWithoutRef<Level>) {
+		return (
+			<Tag id={id} {...rest}>
+				{children}
+				{id ? (
+					<a className="mdx-anchor" href={"#" + id} aria-label="Link to this section">
+						#
+					</a>
+				) : null}
+			</Tag>
+		);
+	};
+}
+
+export const H2 = makeHeading("h2");
+export const H3 = makeHeading("h3");
+export const H4 = makeHeading("h4");

package/client/HomeEmptyState.tsx

@@ -0,0 +1,101 @@
+import { useState } from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import { Icon } from "./ui/Icon";
+import { TRANSITIONS } from "./motion";
+
+/** What the Copy control puts on the clipboard: the command up to where the path goes. */
+const COMMAND_PREFIX = "mdxserve roots add ";
+
+/**
+ * The home page when nothing is mounted. The server is up and this page
+ * already re-renders itself on `mdxserve:roots-changed`, so the whole view
+ * is framed as a server waiting for a folder rather than as an error: one
+ * command to run, a quieter agent alternative, and a live status line that
+ * says where the server is listening.
+ */
+export function HomeEmptyState() {
+	const [copied, setCopied] = useState(false);
+	const host = typeof window === "undefined" ? "" : window.location.host;
+
+	async function copyCommand() {
+		try {
+			await navigator.clipboard.writeText(COMMAND_PREFIX);
+			setCopied(true);
+			setTimeout(() => setCopied(false), 1500);
+		} catch {
+			// clipboard unavailable (insecure context, permissions); the text is still selectable
+		}
+	}
+
+	// Layout is all container gaps, no element margins: reset.css zeroes
+	// h1/p margins outside any cascade layer, so a `mt-*` utility on them is
+	// a no-op while the same class on a div works.
+	return (
+		<section aria-labelledby="home-empty-heading" className="flex flex-col gap-10 pt-6">
+			<div className="flex flex-col gap-2">
+				<div className="mb-3 flex h-10 w-10 items-center justify-center rounded-md bg-surface-accent-soft text-text-accent">
+					<Icon name="folder-plus" size="lg" />
+				</div>
+				<h1
+					id="home-empty-heading"
+					className="font-sans font-bold leading-[1.2] text-[length:var(--size-2xl)] text-text-heading"
+				>
+					No folders are mounted
+				</h1>
+				<p className="max-w-[52ch] font-sans leading-relaxed text-[length:var(--size-md)] text-text-muted">
+					The server is up and waiting. Mount a folder of Markdown and it appears here on its own,
+					no reload needed.
+				</p>
+			</div>
+
+			<div className="flex flex-col gap-3">
+				<div className="flex items-center gap-3 rounded-md border border-code-border bg-code-bg py-2.5 pr-2 pl-3.5 font-mono text-[length:var(--size-sm)] text-code-fg">
+					<span aria-hidden="true" className="select-none text-text-subtle">
+						$
+					</span>
+					<code className="min-w-0 flex-1 truncate">
+						{COMMAND_PREFIX}
+						<span className="text-text-subtle">&lt;dir&gt;</span>
+					</code>
+					<motion.button
+						type="button"
+						onClick={copyCommand}
+						whileTap={{ scale: 0.94 }}
+						transition={TRANSITIONS.snap}
+						className={
+							"inline-flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-sm px-2 font-sans text-[length:var(--size-xs)] font-medium leading-none transition-colors " +
+							(copied ? "text-text-accent" : "text-text-subtle hover:text-text-heading")
+						}
+					>
+						<AnimatePresence mode="wait" initial={false}>
+							<motion.span
+								key={copied ? "done" : "idle"}
+								initial={{ opacity: 0, y: -3 }}
+								animate={{ opacity: 1, y: 0 }}
+								exit={{ opacity: 0, y: 3 }}
+								transition={TRANSITIONS.fast}
+								className="inline-flex items-center gap-1.5"
+							>
+								<Icon name={copied ? "check" : "copy"} size={13} />
+								{copied ? "Copied" : "Copy"}
+							</motion.span>
+						</AnimatePresence>
+					</motion.button>
+				</div>
+				<p className="font-sans text-[length:var(--size-xs)] leading-relaxed text-text-subtle">
+					An agent with the mdxserve skill can run this for you.
+				</p>
+			</div>
+
+			<p className="flex items-center gap-2.5 font-mono text-[length:var(--size-xs)] text-text-subtle">
+				<span aria-hidden="true" className="relative flex h-2 w-2">
+					<span className="absolute inline-flex h-full w-full rounded-pill bg-status-ok-fg opacity-60 motion-safe:animate-ping" />
+					<span className="relative inline-flex h-2 w-2 rounded-pill bg-status-ok-fg" />
+				</span>
+				<span>
+					Waiting on <span className="text-text-muted">{host}</span>
+				</span>
+			</p>
+		</section>
+	);
+}

package/client/HomeView.tsx

@@ -0,0 +1,78 @@
+import { motion } from "framer-motion";
+import { shortenHome } from "./format";
+import { stagger } from "./motion";
+import { Icon } from "./ui/Icon";
+import { HomeEmptyState } from "./HomeEmptyState";
+import { useTree, type Route, type TreeNode } from "./router";
+
+function countDocs(nodes: TreeNode[] | null): number {
+	if (!nodes) return 0;
+	let count = 0;
+	for (const node of nodes) {
+		if (node.isDoc) count++;
+		if (node.children) count += countDocs(node.children);
+	}
+	return count;
+}
+
+const rowVariants = {
+	initial: { opacity: 0, y: 4 },
+	enter: { opacity: 1, y: 0 },
+};
+
+/**
+ * Landing page listing every mounted root; the server serves this at "/"
+ * whenever the root count isn't exactly one (zero mounted roots, or more
+ * than one — a single root redirects straight to its listing instead).
+ */
+export function HomeView({ route }: { route: Extract<Route, { kind: "home" }> }) {
+	const { roots: liveRoots } = useTree();
+	// Roots can be added/removed at runtime; once the tree query has loaded,
+	// trust it over the route's own snapshot so the page updates without a
+	// reload. Before that first load, fall back to what the server embedded
+	// so the list doesn't flash empty.
+	const roots = liveRoots ?? route.roots;
+	const treeByDir = new Map((liveRoots ?? []).map((root) => [root.dir, root.tree]));
+
+	if (roots.length === 0) return <HomeEmptyState />;
+
+	return (
+		<motion.div
+			variants={stagger}
+			initial="initial"
+			animate="enter"
+			className="divide-y divide-border-subtle border-y border-border-subtle"
+		>
+			{roots.map((root) => {
+				const docCount = countDocs(treeByDir.get(root.dir) ?? null);
+				return (
+					<motion.div
+						key={root.dir}
+						variants={rowVariants}
+						className="group flex items-center rounded-md hover:bg-surface-hover"
+					>
+						{/* Plain <a>: the router's global click delegation (client/router.ts)
+						    intercepts this for client-side navigation. */}
+						<a
+							href={`${root.dir}/`}
+							className="flex min-w-0 flex-1 items-center gap-2 py-2 pr-3 pl-2"
+						>
+							<Icon name="folder" size="md" className="shrink-0 text-text-subtle" />
+							<span className="flex min-w-0 flex-col">
+								<span className="truncate font-sans font-medium leading-normal text-[length:var(--size-md)]">
+									{root.name}
+								</span>
+								<span className="truncate font-mono font-normal leading-normal text-[length:var(--size-xs)] text-text-subtle">
+									{shortenHome(root.dir)}
+								</span>
+							</span>
+							<span className="ml-auto flex shrink-0 items-center gap-4 pl-4 font-mono font-normal leading-[1.62] text-[length:var(--size-xs)] text-text-subtle tabular-nums">
+								{docCount} {docCount === 1 ? "doc" : "docs"}
+							</span>
+						</a>
+					</motion.div>
+				);
+			})}
+		</motion.div>
+	);
+}