@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/shell/TocRail.tsx

@@ -0,0 +1,53 @@
+import { useAtom } from "jotai";
+import { useRef } from "react";
+import { ResizeHandle } from "../ui/ResizeHandle";
+import { TocList } from "../ui/TocList";
+import { TOC_MAX_WIDTH, TOC_MIN_WIDTH, tocWidthAtom } from "../state";
+import { useToc } from "./useToc";
+
+function clampWidth(px: number): number {
+	return Math.min(TOC_MAX_WIDTH, Math.max(TOC_MIN_WIDTH, Math.round(px)));
+}
+
+/** "On this page" rail. Hidden entirely when the doc has no h2s. */
+export function TocRail({ path, version }: { path: string; version: number }) {
+	const { items, activeId, setActiveId } = useToc(path, version);
+	const [width, setWidth] = useAtom(tocWidthAtom);
+	const railRef = useRef<HTMLDivElement>(null);
+	const hasH2 = items.some((item) => item.level === 2);
+	if (!hasH2) return null;
+
+	function handleSelect(id: string) {
+		setActiveId(id);
+		history.replaceState(null, "", `#${id}`);
+		document.getElementById(id)?.scrollIntoView({ block: "start" });
+	}
+
+	return (
+		<div
+			ref={railRef}
+			data-print-hide
+			className="hidden xl:block shrink-0 self-start ml-10 sticky top-[calc(var(--topbar-height)+40px)]"
+			style={{ width: clampWidth(width) }}
+		>
+			{/* The rail is flush against the main column's right edge, so the
+			    handle sits on its left and the drag maps 1:1 to the width. It's a
+			    sibling of the scroller, not inside it, so overflow-y-auto can't clip it. */}
+			<ResizeHandle
+				side="left"
+				anchored
+				container={railRef}
+				onResize={setWidth}
+				label="Resize table of contents"
+				minWidth={TOC_MIN_WIDTH}
+				maxWidth={TOC_MAX_WIDTH}
+			/>
+			{/* Capped to the viewport (less the sticky offset and matching bottom
+			    margin) so a long list scrolls here instead of running below the fold,
+			    and the handle's resting pill stays centred in what's visible. */}
+			<div className="max-h-[calc(100vh-var(--topbar-height)-80px)] overflow-y-auto">
+				<TocList items={items} activeId={activeId} onSelect={handleSelect} />
+			</div>
+		</div>
+	);
+}

package/client/shell/TopBar.tsx

@@ -0,0 +1,117 @@
+import type { ExportFormat } from "../../src/export/service";
+import Dropdown from "../builtins/Dropdown";
+import { Icon } from "../ui/Icon";
+import { IconButton } from "../ui/IconButton";
+import { Kbd } from "../ui/Kbd";
+import type { Theme } from "../theme";
+import { isApplePlatform } from "../platform";
+
+// The export formats the viewer offers; the server's `exportDoc` validates
+// against the same `EXPORT_FORMATS` list (src/export/service.ts).
+const EXPORT_FORMAT_OPTIONS: { value: ExportFormat; label: string; description: string }[] = [
+	{
+		value: "html",
+		label: "HTML",
+		description: "One self-contained page; diagrams load from a CDN",
+	},
+];
+
+function Wordmark({ href }: { href?: string }) {
+	const content = (
+		<>
+			<span className="font-extrabold text-text-heading">mdx</span>
+			<span className="font-normal text-text-accent">serve</span>
+		</>
+	);
+	if (!href) {
+		return <span className="flex shrink-0 items-baseline gap-px text-[15px]">{content}</span>;
+	}
+	return (
+		<a
+			href={href}
+			className="flex shrink-0 items-baseline gap-px text-[15px] no-underline [letter-spacing:var(--tracking-tight)]"
+		>
+			{content}
+		</a>
+	);
+}
+
+export function TopBar({
+	homeHref,
+	hostLabel,
+	sidebar,
+	search,
+	exportDoc,
+	theme,
+	onToggleTheme,
+}: {
+	/** Wordmark's link target; undefined renders it as a plain (non-link) span. */
+	homeHref?: string;
+	/** Host chip shown next to the wordmark; omitted when undefined. */
+	hostLabel?: string;
+	/** Sidebar toggle button; omitted when undefined. */
+	sidebar?: { open: boolean; onToggle: () => void };
+	/** Search button; omitted when undefined. */
+	search?: { onOpen: () => void };
+	/** Export menu (doc pages, same-machine viewers only); omitted when undefined. */
+	exportDoc?: { pending: boolean; onExport: (format: ExportFormat) => void };
+	theme: Theme;
+	onToggleTheme: () => void;
+}) {
+	const mac = isApplePlatform();
+
+	return (
+		<header
+			data-print-hide
+			className="sticky top-0 z-10 flex h-topbar shrink-0 items-center gap-3 border-b border-border-subtle px-4"
+			style={{
+				background: "color-mix(in oklab, var(--surface-page) 82%, transparent)",
+				backdropFilter: "var(--blur-chrome)",
+			}}
+		>
+			{sidebar ? (
+				<IconButton
+					icon="panel-left"
+					label="Toggle sidebar"
+					size="sm"
+					active={sidebar.open}
+					onClick={sidebar.onToggle}
+				/>
+			) : null}
+			<Wordmark href={homeHref} />
+			{hostLabel ? (
+				<span className="rounded-sm border border-border-default px-1.5 py-0.5 font-mono text-[length:var(--size-2xs)] text-text-subtle">
+					{hostLabel}
+				</span>
+			) : null}
+			<span className="flex-1" />
+			{search ? (
+				<button
+					type="button"
+					onClick={search.onOpen}
+					className="flex h-[30px] w-60 items-center gap-2 rounded-md border border-border-default bg-surface-card px-2.5 text-[13px] text-text-subtle shadow-xs cursor-pointer"
+				>
+					<Icon name="search" size="sm" />
+					<span className="flex-1 text-left">Search docs</span>
+					<Kbd>{mac ? "⌘K" : "Ctrl K"}</Kbd>
+				</button>
+			) : null}
+			{exportDoc ? (
+				<Dropdown
+					icon="download"
+					label="Export page"
+					size="sm"
+					disabled={exportDoc.pending}
+					options={EXPORT_FORMAT_OPTIONS}
+					onChange={(format) => exportDoc.onExport(format as ExportFormat)}
+				/>
+			) : null}
+			<IconButton
+				icon={theme === "dark" ? "sun" : "moon"}
+				label={theme === "dark" ? "Light mode" : "Dark mode"}
+				size="sm"
+				onClick={onToggleTheme}
+			/>
+		</header>
+	);
+}

package/client/shell/use-doc-width.ts

@@ -0,0 +1,61 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { useSpring } from "framer-motion";
+import { TRANSITIONS } from "../motion";
+import { DOC_MAX_WIDTH, DOC_MIN_WIDTH } from "../state";
+
+/**
+ * Width of the content area (the flex column holding the route wrapper),
+ * tracked with a ResizeObserver so widths follow window/sidebar/toc resizes.
+ * A layout effect so the first paint already has a real measurement.
+ */
+export function useContentWidth(ref: React.RefObject<HTMLElement | null>) {
+	const [width, setWidth] = useState(0);
+
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const measure = () => setWidth(el.clientWidth);
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [ref]);
+
+	return width;
+}
+
+/**
+ * Spring-animated max-width for doc pages, or null while the user hasn't
+ * dragged one — the wrapper keeps its default `max-w-prose` then. The spring
+ * jumps (not animates) when a drag first activates it, so the page doesn't
+ * lurch from a stale value to the grabbed width.
+ */
+export function useDocMaxWidth(contentWidth: number, stored: number | null) {
+	// glide, not snap: the width trails the drag slightly so the spring is felt.
+	const spring = useSpring(0, TRANSITIONS.glide);
+	const active = useRef(false);
+	// Whether the applied target used a real content-area measurement. The first
+	// effect run can see contentWidth === 0 (measurement lands one render later);
+	// keep jumping until a measured target is applied so a stored width doesn't
+	// animate down to its clamp on load.
+	const measured = useRef(false);
+
+	useLayoutEffect(() => {
+		if (stored === null) {
+			active.current = false;
+			measured.current = false;
+			return;
+		}
+		const target = Math.min(
+			DOC_MAX_WIDTH,
+			contentWidth > 0 ? contentWidth : DOC_MAX_WIDTH,
+			Math.max(DOC_MIN_WIDTH, stored),
+		);
+		if (active.current && measured.current) spring.set(target);
+		else spring.jump(target);
+		active.current = true;
+		measured.current = contentWidth > 0;
+	}, [contentWidth, stored, spring]);
+
+	return stored === null ? null : spring;
+}

package/client/shell/useToc.ts

@@ -0,0 +1,77 @@
+import { useLayoutEffect, useRef, useState } from "react";
+
+export interface TocEntry {
+	id: string;
+	label: string;
+	level: 2 | 3;
+}
+
+/** Strips the trailing `#` from the Heading.tsx anchor link (see client/Heading.tsx). */
+function stripAnchorGlyph(text: string): string {
+	return text.replace(/#\s*$/, "").trim();
+}
+
+function collectHeadings(): { entries: TocEntry[]; elements: HTMLElement[] } {
+	const article = document.querySelector("article.mdx-prose");
+	if (!article) return { entries: [], elements: [] };
+
+	const elements = Array.from(article.querySelectorAll<HTMLElement>("h2, h3")).filter(
+		(el) => el.id,
+	);
+	const entries: TocEntry[] = elements.map((el) => ({
+		id: el.id,
+		label: stripAnchorGlyph(el.textContent ?? ""),
+		level: el.tagName === "H3" ? 3 : 2,
+	}));
+	return { entries, elements };
+}
+
+/**
+ * "On this page" data for the current doc. Re-scans `article.mdx-prose` for
+ * h2/h3 elements whenever `path` or `version` changes (`version` is bumped by
+ * DocView.onRendered — see client/shell/TocRail.tsx — because the article for
+ * a given `path` can render asynchronously after this effect first runs, e.g.
+ * the initial server-rendered route's module is still importing on mount).
+ */
+export function useToc(path: string, version: number) {
+	const [items, setItems] = useState<TocEntry[]>([]);
+	const [activeId, setActiveId] = useState<string | undefined>(undefined);
+	const observerRef = useRef<IntersectionObserver | null>(null);
+
+	useLayoutEffect(() => {
+		function collect() {
+			const { entries, elements } = collectHeadings();
+			setItems(entries);
+
+			observerRef.current?.disconnect();
+			observerRef.current = null;
+			if (elements.length === 0) return;
+
+			const observer = new IntersectionObserver(
+				(observed) => {
+					for (const entry of observed) {
+						if (entry.isIntersecting) {
+							setActiveId(entry.target.id);
+							break;
+						}
+					}
+				},
+				{ root: null, rootMargin: "-60px 0px -70% 0px" },
+			);
+			for (const el of elements) observer.observe(el);
+			observerRef.current = observer;
+		}
+
+		collect();
+
+		const hot = import.meta.hot;
+		hot?.on("vite:afterUpdate", collect);
+		return () => {
+			observerRef.current?.disconnect();
+			observerRef.current = null;
+			hot?.off?.("vite:afterUpdate", collect);
+		};
+	}, [path, version]);
+
+	return { items, activeId, setActiveId };
+}

package/client/ssr-entry.tsx

@@ -0,0 +1,22 @@
+import type { ComponentType } from "react";
+import { renderToString } from "react-dom/server";
+import { MDXProvider } from "@mdx-js/react";
+import { mdxComponents } from "./mdx-components";
+
+/**
+ * Server-side render of a compiled MDX document's default export, using the
+ * exact same `MDXProvider` component map as the browser (`client/entry.tsx`).
+ * Used by `src/rendering/render.ts` to catch render-time errors (e.g. a bare identifier
+ * from a stray MDX expression) that static analysis can't see.
+ *
+ * No `MotionConfig` here: it only affects animation defaults, which don't
+ * matter for a render that's discarded immediately, and dropping it keeps
+ * this entry's dependency surface smaller for SSR.
+ */
+export function renderDoc(Content: ComponentType): string {
+	return renderToString(
+		<MDXProvider components={mdxComponents}>
+			<Content />
+		</MDXProvider>,
+	);
+}

package/client/standalone-entry.tsx

@@ -0,0 +1,51 @@
+import { createRoot } from "react-dom/client";
+import { MDXProvider } from "@mdx-js/react";
+import { MotionConfig } from "framer-motion";
+import type { ComponentType } from "react";
+import { mdxComponentsBase } from "./mdx-components-base";
+import { docModuleCache } from "./doc-module-cache";
+import { StandaloneShell } from "./shell/StandaloneShell";
+
+/**
+ * What `mdxserve export` embeds as `#__mdxserve_route` JSON, read back by
+ * readMeta() below. `mtime` is omitted when the source file's mtime is
+ * unavailable at build time.
+ */
+export interface StandaloneMeta {
+	/** An opaque key (the file name, never an absolute path — the file gets shared) for docModuleCache/TOC/DocContext. */
+	path: string;
+	label: string;
+	mtime?: number;
+}
+
+/** Parses the `#__mdxserve_route` script tag the same way entry.tsx does. */
+export function readMeta(): StandaloneMeta {
+	const el = document.getElementById("__mdxserve_route");
+	try {
+		return JSON.parse(el?.textContent ?? "{}") as StandaloneMeta;
+	} catch {
+		return { path: "", label: document.title };
+	}
+}
+
+/**
+ * Entry point for a `mdxserve export` output. The bundler's virtual entry
+ * plugin (src/rendering/bundle.ts) generates a module that imports the
+ * compiled doc component and calls `mount(Doc, readMeta())` — keep both
+ * export names and this signature stable, since that generated import is not
+ * type-checked against this file.
+ */
+export function mount(Doc: ComponentType, meta: StandaloneMeta): void {
+	const rootEl = document.getElementById("root");
+	if (!rootEl) return;
+	// DocView reads the module from the router's cache; seed it with the doc
+	// that was compiled into this file so it renders synchronously.
+	docModuleCache.set(meta.path, { status: "ok", Component: Doc });
+	createRoot(rootEl).render(
+		<MotionConfig reducedMotion="user">
+			<MDXProvider components={mdxComponentsBase}>
+				<StandaloneShell meta={meta} />
+			</MDXProvider>
+		</MotionConfig>,
+	);
+}

package/client/state.ts

@@ -0,0 +1,90 @@
+import { atom } from "jotai";
+import { atomWithStorage, createJSONStorage } from "jotai/utils";
+
+export type SortKey = "name" | "modified";
+
+function isSortKey(value: unknown): value is SortKey {
+	return value === "name" || value === "modified";
+}
+
+// The pre-jotai code stored the sort as a bare string (`modified`), which
+// jotai's JSON storage can't parse. Accept both forms so an existing choice
+// survives the upgrade; writes go through the JSON storage as usual.
+const sortStorage = createJSONStorage<SortKey>(() => localStorage);
+const legacyAwareSortStorage = {
+	...sortStorage,
+	getItem(key: string, initialValue: SortKey): SortKey {
+		try {
+			const raw = localStorage.getItem(key);
+			if (raw === null) return initialValue;
+			try {
+				const parsed: unknown = JSON.parse(raw);
+				return isSortKey(parsed) ? parsed : initialValue;
+			} catch {
+				return isSortKey(raw) ? raw : initialValue;
+			}
+		} catch {
+			return initialValue;
+		}
+	},
+};
+
+/** Folder listing sort order. */
+export const listingSortAtom = atomWithStorage<SortKey>(
+	"mdxserve.listing.sort",
+	"name",
+	legacyAwareSortStorage,
+	{ getOnInit: true },
+);
+
+export const SIDEBAR_MIN_WIDTH = 200;
+export const SIDEBAR_MAX_WIDTH = 560;
+export const SIDEBAR_DEFAULT_WIDTH = 264;
+
+/** Docked sidebar width in px; dragged via the resize handle. */
+export const sidebarWidthAtom = atomWithStorage<number>(
+	"mdxserve.sidebar.width",
+	SIDEBAR_DEFAULT_WIDTH,
+	undefined,
+	{ getOnInit: true },
+);
+
+export const TOC_MIN_WIDTH = 160;
+export const TOC_MAX_WIDTH = 420;
+export const TOC_DEFAULT_WIDTH = 220;
+
+/** "On this page" rail width in px; dragged via the resize handle. */
+export const tocWidthAtom = atomWithStorage<number>(
+	"mdxserve.toc.width",
+	TOC_DEFAULT_WIDTH,
+	undefined,
+	{ getOnInit: true },
+);
+
+export const LISTING_MIN_WIDTH = 360;
+export const LISTING_MAX_WIDTH = 1600;
+
+/** Folder listing width in px, or null for the default prose width. */
+export const listingWidthAtom = atomWithStorage<number | null>(
+	"mdxserve.listing.width",
+	null,
+	undefined,
+	{ getOnInit: true },
+);
+
+export const DOC_MIN_WIDTH = 480;
+export const DOC_MAX_WIDTH = 1600;
+
+/** Doc page width in px, or null for the default prose width. */
+export const docWidthAtom = atomWithStorage<number | null>("mdxserve.doc.width", null, undefined, {
+	getOnInit: true,
+});
+
+/**
+ * The key (`${path}:${startLine}:${endLine}`) of the `MdSection` currently in
+ * edit mode, or null. Plain in-memory atom — not persisted, since an open
+ * editor holding unsaved edits should never survive a reload. Only one
+ * section edits at a time: a `Section` that isn't this atom's value drops
+ * back to read mode, discarding whatever it had open (see client/MdSection.tsx).
+ */
+export const openSectionAtom = atom<string | null>(null);

package/client/theme.ts

@@ -0,0 +1,65 @@
+import { useCallback, useEffect, useState } from "react";
+
+export type Theme = "light" | "dark";
+
+const STORAGE_KEY = "mdxserve-theme";
+const MEDIA = "(prefers-color-scheme: dark)";
+
+function systemTheme(): Theme {
+	return window.matchMedia(MEDIA).matches ? "dark" : "light";
+}
+
+function storedTheme(): Theme | null {
+	try {
+		const value = localStorage.getItem(STORAGE_KEY);
+		return value === "light" || value === "dark" ? value : null;
+	} catch {
+		return null;
+	}
+}
+
+function applyTheme(theme: Theme): void {
+	document.documentElement.setAttribute("data-theme", theme);
+}
+
+/**
+ * The page theme. `src/http/html.ts` sets `data-theme` on `<html>` before the
+ * stylesheet loads (same rules as here) so there is no flash; this hook keeps
+ * that attribute, localStorage, and React state in sync afterwards.
+ *
+ * An explicit choice is persisted; "follow the system" is represented by the
+ * absence of a stored value, so the OS setting keeps working until the reader
+ * picks a side.
+ */
+export function useTheme(): { theme: Theme; toggle: () => void; set: (theme: Theme) => void } {
+	const [theme, setTheme] = useState<Theme>(() => storedTheme() ?? systemTheme());
+
+	useEffect(() => {
+		applyTheme(theme);
+	}, [theme]);
+
+	// Follow OS changes only while the reader has not chosen explicitly.
+	useEffect(() => {
+		const mql = window.matchMedia(MEDIA);
+		const onChange = () => {
+			if (storedTheme() === null) setTheme(systemTheme());
+		};
+		mql.addEventListener("change", onChange);
+		return () => mql.removeEventListener("change", onChange);
+	}, []);
+
+	const set = useCallback((next: Theme) => {
+		try {
+			localStorage.setItem(STORAGE_KEY, next);
+		} catch {
+			// private mode / storage disabled: the choice just won't persist
+		}
+		setTheme(next);
+	}, []);
+
+	const toggle = useCallback(() => {
+		set(theme === "dark" ? "light" : "dark");
+	}, [theme, set]);
+
+	return { theme, toggle, set };
+}

package/client/ui/Breadcrumb.tsx

@@ -0,0 +1,49 @@
+import { Fragment, type HTMLAttributes, type ReactNode } from "react";
+import { Icon } from "./Icon";
+
+export interface BreadcrumbItem {
+	label: ReactNode;
+	href?: string;
+}
+
+export interface BreadcrumbProps extends HTMLAttributes<HTMLElement> {
+	items?: BreadcrumbItem[];
+}
+
+/** Path trail above the prose column. */
+export function Breadcrumb({ items = [], className, ...rest }: BreadcrumbProps) {
+	return (
+		<nav
+			className={
+				"flex flex-wrap items-center gap-1.5 text-[13px] leading-normal font-medium text-text-subtle" +
+				(className ? " " + className : "")
+			}
+			{...rest}
+		>
+			{items.map((item, index) => {
+				const last = index === items.length - 1;
+				const label =
+					last || !item.href ? (
+						<span
+							className={last ? "font-semibold text-text-body" : "font-medium text-text-subtle"}
+						>
+							{item.label}
+						</span>
+					) : (
+						<a
+							href={item.href}
+							className="font-medium text-text-subtle no-underline hover:text-text-heading"
+						>
+							{item.label}
+						</a>
+					);
+				return (
+					<Fragment key={index}>
+						{index > 0 ? <Icon name="chevron-right" size={12} className="text-n-300" /> : null}
+						{label}
+					</Fragment>
+				);
+			})}
+		</nav>
+	);
+}