@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/builtins/Screenshot.tsx

@@ -0,0 +1,209 @@
+import { useCallback, useEffect, useRef, useState, type PointerEvent } from "react";
+import { motion } from "framer-motion";
+import { z } from "zod";
+import { TRANSITIONS } from "../motion";
+import { IconButton } from "../ui/IconButton";
+import { ExpandModal } from "../ui/ExpandModal";
+
+export const screenshotProps = z.object({
+	src: z.string().describe("Image URL, relative to the document like a Markdown image."),
+	alt: z.string().default("").describe("Accessible description of the image."),
+	title: z
+		.string()
+		.optional()
+		.describe("Window title shown centred in the title bar, e.g. the app or page name."),
+	caption: z.string().optional().describe("Caption shown below the image on a hairline rule."),
+	width: z
+		.union([z.number(), z.string()])
+		.optional()
+		.describe("Max width of the window (px or any CSS length); defaults to the full column."),
+});
+
+export type ScreenshotProps = z.infer<typeof screenshotProps>;
+
+// macOS traffic-light colours; the same in both themes, like the real thing.
+const TRAFFIC_LIGHTS = ["#ff5f57", "#febc2e", "#28c840"];
+
+const MIN_SCALE = 0.25;
+const MAX_SCALE = 8;
+/** Zoom factor per +/− press; wheel zoom scales continuously with the delta. */
+const ZOOM_STEP = 1.25;
+
+interface View {
+	scale: number;
+	x: number;
+	y: number;
+}
+
+const FIT_VIEW: View = { scale: 1, x: 0, y: 0 };
+
+function clampScale(scale: number): number {
+	return Math.min(MAX_SCALE, Math.max(MIN_SCALE, scale));
+}
+
+/**
+ * Zoom `view` by `factor` keeping the viewport point `focus` (relative to
+ * the viewport centre) fixed under the cursor. The image is translated then
+ * scaled about its centre, so a point `p` on it lands at `x + scale * p`.
+ */
+function zoomAt(view: View, factor: number, focus: { x: number; y: number }): View {
+	const scale = clampScale(view.scale * factor);
+	const ratio = scale / view.scale;
+	return {
+		scale,
+		x: focus.x - (focus.x - view.x) * ratio,
+		y: focus.y - (focus.y - view.y) * ratio,
+	};
+}
+
+/**
+ * Fills its parent with the image fitted to the available area at rest;
+ * drag to pan, wheel to zoom about the cursor, double-click to reset, with
+ * +/−/reset controls in the corner like the mermaid diagram viewport.
+ */
+function PanZoomImage({ src, alt }: { src: string; alt: string }) {
+	const hostRef = useRef<HTMLDivElement>(null);
+	const [view, setView] = useState<View>(FIT_VIEW);
+	const dragRef = useRef<{
+		pointerId: number;
+		startX: number;
+		startY: number;
+		origin: View;
+	} | null>(null);
+
+	const reset = useCallback(() => setView(FIT_VIEW), []);
+	const zoomBy = useCallback(
+		(factor: number) => setView((current) => zoomAt(current, factor, { x: 0, y: 0 })),
+		[],
+	);
+
+	// Wheel zoom has to preventDefault so the page behind the modal doesn't
+	// scroll, and React registers wheel listeners as passive — so attach it by
+	// hand.
+	useEffect(() => {
+		const host = hostRef.current;
+		if (!host) return;
+		const onWheel = (event: WheelEvent) => {
+			event.preventDefault();
+			const rect = host.getBoundingClientRect();
+			const focus = {
+				x: event.clientX - (rect.left + rect.width / 2),
+				y: event.clientY - (rect.top + rect.height / 2),
+			};
+			const factor = Math.exp(-event.deltaY * 0.002);
+			setView((current) => zoomAt(current, factor, focus));
+		};
+		host.addEventListener("wheel", onWheel, { passive: false });
+		return () => host.removeEventListener("wheel", onWheel);
+	}, []);
+
+	const onPointerDown = (event: PointerEvent<HTMLDivElement>) => {
+		if (event.button !== 0) return;
+		event.currentTarget.setPointerCapture(event.pointerId);
+		dragRef.current = {
+			pointerId: event.pointerId,
+			startX: event.clientX,
+			startY: event.clientY,
+			origin: view,
+		};
+	};
+	const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
+		const drag = dragRef.current;
+		if (!drag || drag.pointerId !== event.pointerId) return;
+		setView({
+			scale: drag.origin.scale,
+			x: drag.origin.x + (event.clientX - drag.startX),
+			y: drag.origin.y + (event.clientY - drag.startY),
+		});
+	};
+	const onPointerUp = (event: PointerEvent<HTMLDivElement>) => {
+		if (dragRef.current?.pointerId !== event.pointerId) return;
+		dragRef.current = null;
+		event.currentTarget.releasePointerCapture(event.pointerId);
+	};
+
+	return (
+		<div className="relative h-full bg-surface-sunken">
+			<div
+				ref={hostRef}
+				className="flex h-full w-full cursor-grab touch-none select-none items-center justify-center overflow-hidden active:cursor-grabbing"
+				onPointerDown={onPointerDown}
+				onPointerMove={onPointerMove}
+				onPointerUp={onPointerUp}
+				onPointerCancel={onPointerUp}
+				onDoubleClick={reset}
+			>
+				<img
+					src={src}
+					alt={alt}
+					draggable={false}
+					className="max-h-full max-w-full"
+					style={{
+						transform: `translate(${view.x}px, ${view.y}px) scale(${view.scale})`,
+						transformOrigin: "center",
+					}}
+				/>
+			</div>
+			<motion.div
+				initial={{ opacity: 0 }}
+				animate={{ opacity: 1 }}
+				transition={{ ...TRANSITIONS.base, delay: 0.1 }}
+				className="absolute right-3 bottom-3 flex flex-col divide-y divide-border-subtle overflow-hidden rounded-md border border-border-default bg-surface-card shadow-xs"
+			>
+				<IconButton icon="plus" label="Zoom in" size="sm" onClick={() => zoomBy(ZOOM_STEP)} />
+				<IconButton icon="maximize" label="Reset view" size="sm" onClick={reset} />
+				<IconButton icon="minus" label="Zoom out" size="sm" onClick={() => zoomBy(1 / ZOOM_STEP)} />
+			</motion.div>
+		</div>
+	);
+}
+
+export default function Screenshot({ src, alt = "", title, caption, width }: ScreenshotProps) {
+	const [expanded, setExpanded] = useState(false);
+
+	return (
+		<figure
+			className="not-prose mx-auto overflow-hidden rounded-lg border border-border-default bg-surface-card shadow-md"
+			style={width === undefined ? undefined : { maxWidth: width }}
+		>
+			<div className="relative flex h-[34px] items-center border-b border-border-subtle bg-surface-raised px-3">
+				<div className="flex items-center gap-2" aria-hidden="true">
+					{TRAFFIC_LIGHTS.map((color) => (
+						<span
+							key={color}
+							className="block size-3 rounded-full border border-black/10"
+							style={{ backgroundColor: color }}
+						/>
+					))}
+				</div>
+				{title ? (
+					<span className="pointer-events-none absolute inset-x-16 truncate text-center font-sans font-medium leading-[1.62] text-[length:var(--size-xs)] text-text-subtle">
+						{title}
+					</span>
+				) : null}
+				<IconButton
+					icon="expand"
+					label="Expand screenshot"
+					size="sm"
+					className="-mr-1 ml-auto"
+					onClick={() => setExpanded(true)}
+				/>
+			</div>
+			<img src={src} alt={alt} className="block w-full" />
+			{caption ? (
+				<figcaption className="border-t border-border-subtle px-4 py-2.5 font-sans font-medium leading-normal text-[length:var(--size-xs)] text-text-subtle">
+					{caption}
+				</figcaption>
+			) : null}
+			<ExpandModal
+				open={expanded}
+				onClose={() => setExpanded(false)}
+				icon="image"
+				title={title || alt || "Screenshot"}
+				hint="Drag to pan · scroll to zoom"
+			>
+				<PanZoomImage src={src} alt={alt} />
+			</ExpandModal>
+		</figure>
+	);
+}

package/client/builtins/Sparkline.tsx

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+export const sparklineProps = z.object({
+	values: z.array(z.number()).describe("Series to plot; at least two numbers."),
+	width: z.number().default(84).describe("SVG width in px."),
+	height: z.number().default(20).describe("SVG height in px."),
+	color: z
+		.string()
+		.default("var(--chart-1)")
+		.describe("Any CSS color, typically a `--chart-1`..`--chart-6` token."),
+	fill: z.boolean().default(true).describe("Tinted area under the line."),
+});
+
+export type SparklineProps = z.infer<typeof sparklineProps>;
+
+export default function Sparkline({
+	values = [],
+	width = 84,
+	height = 20,
+	color = "var(--chart-1)",
+	fill = true,
+}: SparklineProps) {
+	const nums = values.map(Number).filter((value) => !Number.isNaN(value));
+	if (nums.length < 2) return null;
+
+	const min = Math.min(...nums);
+	const max = Math.max(...nums);
+	const span = max - min || 1;
+	const xAt = (index: number) => (index / (nums.length - 1)) * (width - 2) + 1;
+	const yAt = (value: number) => height - 2 - ((value - min) / span) * (height - 4);
+	const pathData = nums
+		.map(
+			(value, index) => (index ? "L" : "M") + xAt(index).toFixed(1) + " " + yAt(value).toFixed(1),
+		)
+		.join(" ");
+
+	return (
+		<svg
+			width={width}
+			height={height}
+			viewBox={`0 0 ${width} ${height}`}
+			className="not-prose inline-block align-middle"
+			role="img"
+		>
+			{fill ? (
+				<path
+					d={`${pathData} L${width - 1} ${height} L1 ${height} Z`}
+					fill={color}
+					opacity="0.13"
+				/>
+			) : null}
+			<path
+				d={pathData}
+				fill="none"
+				stroke={color}
+				strokeWidth="1.5"
+				strokeLinecap="round"
+				strokeLinejoin="round"
+			/>
+			<circle cx={xAt(nums.length - 1)} cy={yAt(nums[nums.length - 1])} r="2" fill={color} />
+		</svg>
+	);
+}

package/client/builtins/Tabs.tsx

@@ -0,0 +1,169 @@
+import {
+	Children,
+	isValidElement,
+	useId,
+	useRef,
+	useState,
+	type KeyboardEvent,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { motion } from "framer-motion";
+import { z } from "zod";
+import { TRANSITIONS } from "../motion";
+import { CrossFade } from "../CrossFade";
+
+export const tabProps = z.object({
+	label: z.string().describe("Tab label shown in the tab list."),
+	value: z
+		.string()
+		.optional()
+		.describe("Stable identifier for this tab; defaults to a slug of `label`."),
+	children: z.custom<ReactNode>().describe("Tab panel content; any MDX/Markdown content."),
+});
+
+export type TabProps = z.infer<typeof tabProps>;
+
+/**
+ * Renders nothing on its own — `Tabs` reads each `Tab` child's props to build
+ * the tab list and panels, matching on `props.label` rather than `type ===
+ * Tab` (component identity changes under Fast Refresh; see client/CodeBlock.tsx).
+ */
+export function Tab(_props: TabProps) {
+	return null;
+}
+
+export const tabsProps = z.object({
+	defaultValue: z
+		.string()
+		.optional()
+		.describe("Value of the tab selected initially; defaults to the first tab."),
+	children: z.custom<ReactNode>().describe("One or more `<Tab>` elements."),
+});
+
+export type TabsProps = z.infer<typeof tabsProps>;
+
+function slugify(label: string): string {
+	return label
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/(^-|-$)/g, "");
+}
+
+interface TabEntry {
+	value: string;
+	label: string;
+	content: ReactNode;
+}
+
+type TabLikeElement = ReactElement<{ label: string; value?: string; children?: ReactNode }>;
+
+/**
+ * Pull { label, value, children } out of each `Tab` child. Matches by
+ * `typeof props.label === "string"` rather than `child.type === Tab` — under
+ * Fast Refresh, component identity changes across re-executions, so a type
+ * check would silently stop matching (see the `Figure` lesson in CodeBlock.tsx).
+ */
+function collectTabs(children: ReactNode): TabEntry[] {
+	return Children.toArray(children)
+		.filter(
+			(child): child is TabLikeElement =>
+				isValidElement(child) && typeof (child.props as { label?: unknown }).label === "string",
+		)
+		.map((child) => {
+			const { label, value, children: content } = child.props;
+			return { label, value: value ?? slugify(label), content };
+		});
+}
+
+export default function Tabs({ defaultValue, children }: TabsProps) {
+	const tabs = collectTabs(children);
+	const [active, setActive] = useState<string | undefined>(defaultValue ?? tabs[0]?.value);
+	const scopeId = useId();
+	const listRef = useRef<HTMLDivElement>(null);
+
+	const activeIndex = Math.max(
+		0,
+		tabs.findIndex((tab) => tab.value === active),
+	);
+	const activeTab = tabs[activeIndex];
+
+	function focusTabAt(index: number) {
+		const buttons = listRef.current?.querySelectorAll<HTMLButtonElement>('[role="tab"]');
+		buttons?.[index]?.focus();
+	}
+
+	function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+		if (tabs.length === 0) return;
+		let nextIndex: number | null = null;
+		if (event.key === "ArrowRight") nextIndex = (activeIndex + 1) % tabs.length;
+		else if (event.key === "ArrowLeft") nextIndex = (activeIndex - 1 + tabs.length) % tabs.length;
+		else if (event.key === "Home") nextIndex = 0;
+		else if (event.key === "End") nextIndex = tabs.length - 1;
+
+		if (nextIndex !== null) {
+			event.preventDefault();
+			setActive(tabs[nextIndex].value);
+			focusTabAt(nextIndex);
+		}
+	}
+
+	if (!activeTab) return null;
+
+	return (
+		<div>
+			<div
+				ref={listRef}
+				role="tablist"
+				onKeyDown={handleKeyDown}
+				className="not-prose flex gap-1 border-b border-border-default"
+			>
+				{tabs.map((tab) => {
+					const isActive = tab.value === activeTab.value;
+					return (
+						<button
+							key={tab.value}
+							type="button"
+							role="tab"
+							id={`${scopeId}-tab-${tab.value}`}
+							aria-selected={isActive}
+							aria-controls={`${scopeId}-panel-${tab.value}`}
+							tabIndex={isActive ? 0 : -1}
+							onClick={() => setActive(tab.value)}
+							className={
+								"relative h-[34px] cursor-pointer px-3 font-sans font-medium leading-normal text-[length:var(--size-sm)] transition-colors " +
+								(isActive
+									? "font-semibold text-text-heading"
+									: "font-medium text-text-subtle hover:text-text-body")
+							}
+						>
+							{tab.label}
+							{isActive ? (
+								<motion.span
+									layoutId={`${scopeId}-tab-underline`}
+									transition={TRANSITIONS.snap}
+									className="absolute inset-x-0 -bottom-px h-0.5 rounded-full bg-teal-500"
+								/>
+							) : null}
+						</button>
+					);
+				})}
+			</div>
+			<CrossFade
+				active={activeTab.value}
+				panes={tabs.map((tab) => ({
+					key: tab.value,
+					node: (
+						<div className="pt-4 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">{tab.content}</div>
+					),
+					props: {
+						id: `${scopeId}-panel-${tab.value}`,
+						role: "tabpanel",
+						"aria-labelledby": `${scopeId}-tab-${tab.value}`,
+					},
+				}))}
+			/>
+		</div>
+	);
+}

package/client/builtins/Tooltip.tsx

@@ -0,0 +1,52 @@
+import { useRef, type ReactNode, type RefObject } from "react";
+import Tippy from "@tippyjs/react";
+import { z } from "zod";
+
+// tippy.js's base CSS is pulled in via client/app.css (`@import
+// "tippy.js/dist/tippy.css"`) instead of a side-effect import here: this
+// module is imported by scripts/build-registry.ts under plain Node (via
+// tsx) to read `tooltipProps`, and a top-level `import "*.css"` there would
+// crash with ERR_UNKNOWN_FILE_EXTENSION. Routing all CSS through app.css also
+// matches how the rest of the app's styling is centralized.
+
+export const tooltipProps = z.object({
+	content: z.string().describe("Tooltip text shown on hover/focus."),
+	placement: z
+		.enum(["top", "bottom", "left", "right"])
+		.default("top")
+		.describe("Preferred side of the target."),
+	delay: z.number().default(100).describe("Delay in milliseconds before the tooltip appears."),
+	children: z.custom<ReactNode>().describe("The element the tooltip is attached to."),
+});
+
+export type TooltipProps = z.infer<typeof tooltipProps>;
+
+export default function Tooltip({
+	content,
+	placement = "top",
+	delay = 100,
+	children,
+}: TooltipProps) {
+	// Attach via `reference` rather than wrapping a child element: @tippyjs/react
+	// clones its child and reads `element.ref`, which React 19 warns about.
+	const target = useRef<HTMLSpanElement>(null) as RefObject<HTMLSpanElement>;
+	return (
+		<>
+			<span
+				ref={target}
+				tabIndex={0}
+				className="cursor-help underline decoration-dotted decoration-text-subtle underline-offset-2"
+			>
+				{children}
+			</span>
+			<Tippy
+				reference={target}
+				content={content}
+				placement={placement}
+				delay={delay}
+				theme="mdxserve"
+				arrow
+			/>
+		</>
+	);
+}

package/client/builtins/chart-data.ts

@@ -0,0 +1,133 @@
+/**
+ * Pure maths for `Chart` (`Chart.tsx`): number coercion, "nice" axis maxima,
+ * tick placement, histogram binning, and the label-fitting used by the
+ * horizontal-bar category column. No React or DOM, so this runs in vitest's
+ * plain node environment the same way `mermaid-direction.ts` does.
+ */
+
+export interface HistogramBin {
+	/** `"<start>–<end>"`, formatted to the bin width's precision. */
+	label: string;
+	/** Count of values that fell in this bin. */
+	value: number;
+	start: number;
+	end: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value));
+}
+
+/** `Number(value)` when finite, else `0` — a single bad datum should drop a
+    bar or a point, never the whole series (a `NaN` in an SVG path breaks it). */
+export function toNumber(value: string | number | undefined): number {
+	const number = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(number) ? number : 0;
+}
+
+/** Rounds `value` up to a "nice" leading digit at its magnitude (94 → 100,
+    118 → 200). Non-finite or non-positive input becomes `1`. */
+export function niceMax(value: number): number {
+	if (!Number.isFinite(value) || value <= 0) return 1;
+	const magnitude = Math.pow(10, Math.floor(Math.log10(value)));
+	return Math.ceil(value / magnitude) * magnitude;
+}
+
+/** Unique ascending integer ticks from `0` to `max`, at most `desired`
+    of them. Rounding two fractions to the same integer (a small `max`)
+    collapses to one tick instead of a visible duplicate. */
+export function countTicks(max: number, desired = 5): number[] {
+	const safeMax = Number.isFinite(max) && max > 0 ? max : 1;
+	const steps = Math.max(1, desired - 1);
+	const ticks: number[] = [];
+	for (let index = 0; index <= steps; index++) {
+		const tick = Math.round((safeMax * index) / steps);
+		if (ticks.length === 0 || tick > ticks[ticks.length - 1]!) ticks.push(tick);
+	}
+	return ticks;
+}
+
+/** Sturges' rule (`ceil(log2 n + 1)`), clamped to `[1, 20]` — 5–8 bins for
+    the tens-of-values datasets a histogram here is meant for. */
+export function autoBinCount(count: number): number {
+	if (!Number.isFinite(count) || count <= 0) return 1;
+	return clamp(Math.ceil(Math.log2(count) + 1), 1, 20);
+}
+
+/** Decimal places implied by `step` — none once a bin spans 10 or more,
+    one below that, and enough to show a sub-unit step (`0.03` → 3) — so an
+    edge computed as `0.30000000000000004` prints `0.3`, and `22.333…` prints
+    `22.3` rather than six noise digits. */
+export function formatBinEdge(value: number, step: number): string {
+	const size = Number.isFinite(step) ? Math.abs(step) : 0;
+	let decimals = 0;
+	if (size > 0 && size < 10) {
+		decimals = size >= 1 ? 1 : Math.min(6, Math.ceil(-Math.log10(size)) + 1);
+	}
+	return String(Number(value.toFixed(decimals)));
+}
+
+/** Bins finite `values` into equal-width buckets (`bins`, else a Sturges
+    estimate, clamped to `[1, 50]`). Every value lands in exactly one
+    half-open bin except the last, which is closed at `max`. An empty input
+    yields `[]`; a zero-width range (every value equal) yields one bin
+    holding everything. */
+export function binValues(values: number[], bins?: number): HistogramBin[] {
+	const finite = values.filter((value) => Number.isFinite(value));
+	if (finite.length === 0) return [];
+	const min = Math.min(...finite);
+	const max = Math.max(...finite);
+	if (max === min) {
+		return [{ label: formatBinEdge(min, 1), value: finite.length, start: min, end: max }];
+	}
+	const count = clamp(bins ?? autoBinCount(finite.length), 1, 50);
+	const step = (max - min) / count;
+	const counts = new Array(count).fill(0) as number[];
+	for (const value of finite) {
+		const index = Math.min(count - 1, Math.floor(((value - min) / (max - min)) * count));
+		counts[index]++;
+	}
+	return counts.map((value, index) => {
+		const start = min + step * index;
+		const end = index === count - 1 ? max : min + step * (index + 1);
+		return {
+			label: `${formatBinEdge(start, step)}–${formatBinEdge(end, step)}`,
+			value,
+			start,
+			end,
+		};
+	});
+}
+
+/** A stride-thinned subset of `[0, edgeCount)`, always including the first
+    and last index, with at most `maxLabels` entries. */
+export function edgeTickIndices(edgeCount: number, maxLabels: number): number[] {
+	if (edgeCount <= 0) return [];
+	if (edgeCount === 1) return [0];
+	const cap = Math.max(2, maxLabels);
+	if (edgeCount <= cap) return Array.from({ length: edgeCount }, (_element, index) => index);
+	const stride = Math.ceil((edgeCount - 1) / (cap - 1));
+	const indices: number[] = [];
+	for (let index = 0; index < edgeCount; index += stride) indices.push(index);
+	if (indices[indices.length - 1] !== edgeCount - 1) indices.push(edgeCount - 1);
+	return indices;
+}
+
+/** Width in px for a category-label column: the longest label at roughly
+    0.58em per character, clamped to `[min, max]`. */
+export function labelColumnWidth(
+	labels: string[],
+	{ fontSize, min, max }: { fontSize: number; min: number; max: number },
+): number {
+	const longest = labels.reduce((widest, label) => Math.max(widest, label.length), 0);
+	return clamp(longest * 0.58 * fontSize + 8, min, max);
+}
+
+/** `label` unchanged if it fits in `maxWidth` at `fontSize`, else truncated
+    with a trailing `…`. */
+export function fitLabel(label: string, maxWidth: number, fontSize: number): string {
+	const charWidth = 0.58 * fontSize;
+	if (label.length * charWidth <= maxWidth) return label;
+	const maxChars = Math.max(1, Math.floor(maxWidth / charWidth) - 1);
+	return `${label.slice(0, maxChars)}…`;
+}