@karimsa/mdxserve 0.0.0-stage → 0.1.0

package/client/builtins/index.ts

@@ -0,0 +1,167 @@
+import type { ComponentType } from "react";
+import type { z } from "zod";
+import Callout, { calloutProps } from "./Callout";
+import Button, { buttonProps } from "./Button";
+import Tooltip, { tooltipProps } from "./Tooltip";
+import Tabs, { Tab, tabsProps, tabProps } from "./Tabs";
+import Badge, { badgeProps } from "./Badge";
+import Diff, { diffProps } from "./Diff";
+import Card, { CardGrid, cardProps, cardGridProps } from "./Card";
+import Kbd, { kbdProps } from "./Kbd";
+import FileTree, { fileTreeProps } from "./FileTree";
+import Chart, { chartProps } from "./Chart";
+import Sparkline, { sparklineProps } from "./Sparkline";
+import Dropdown, { Option, dropdownProps, optionProps } from "./Dropdown";
+import Screenshot, { screenshotProps } from "./Screenshot";
+
+export interface BuiltinDefinition {
+	name: string;
+	description: string;
+	whenToUse: string;
+	props: z.ZodObject<any>;
+	Component: ComponentType<any>;
+}
+
+export const builtins: BuiltinDefinition[] = [
+	{
+		name: "Callout",
+		description:
+			"A boxed aside with an icon, used to draw attention to a note or warning inline with the text.",
+		whenToUse:
+			'Use to highlight a tip, note, or warning that should stand out from surrounding prose. Prefer `tone="warn"` for caveats or risks, `tone="danger"` for breaking changes, `tone="tip"` or `tone="ok"` for positive asides, and the default `tone="note"` for general notes; add `title` when the callout needs a short heading. (`type` is a deprecated alias for `tone`.)',
+		props: calloutProps,
+		Component: Callout,
+	},
+	{
+		name: "Button",
+		description:
+			"A clickable button or link with primary/secondary/ghost/danger styles and a small tap animation.",
+		whenToUse:
+			'Use for a call to action inside MDX/JSX content — a link styled as a button (`href`) or an interactive action (`onClick`, JSX only). Prefer `variant="primary"` for the main action on a page, `secondary` or `ghost` for less prominent actions, and `danger` for destructive ones. `icon`/`iconRight` take a lucide icon name.',
+		props: buttonProps,
+		Component: Button,
+	},
+	{
+		name: "Tooltip",
+		description:
+			"Wraps inline content in a hover/focus tooltip (via tippy.js) that shows a short bit of text.",
+		whenToUse:
+			"Use to add a short explanation to a word, phrase, or another inline component (e.g. a `Badge`) without cluttering the surrounding prose. Keep `content` brief — it's not meant for long-form text.",
+		props: tooltipProps,
+		Component: Tooltip,
+	},
+	{
+		name: "Tabs",
+		description:
+			"A tabbed container that switches between panels of content, each declared with a `Tab` child.",
+		whenToUse:
+			"Use to present a few alternative or sequential views of content (e.g. per-language code samples, per-OS instructions) without showing them all at once. Each direct child should be a `Tab` with a `label`; the panel content cross-fades and the underline animates between tabs.",
+		props: tabsProps,
+		Component: Tabs,
+	},
+	{
+		name: "Tab",
+		description: "A single labeled panel within a `Tabs` container.",
+		whenToUse:
+			"Only as a direct child of `<Tabs>`. `label` is required; `value` defaults to a slug of `label`.",
+		props: tabProps,
+		Component: Tab,
+	},
+	{
+		name: "Badge",
+		description: "A small inline pill for a status, tag, or label, with tone/variant/dot options.",
+		whenToUse:
+			'Use inline with text (or inside a table cell) to call out a short status or category, e.g. a version, state, or tag. Prefer `variant="soft"` (the default) for most uses; `solid` for emphasis, `outline` for a quieter look; set `dot` for a status indicator. Tones: `neutral`, `teal`, `info`, `ok`, `warn`, `danger`, `note`. (`color` is a deprecated alias for `tone`.)',
+		props: badgeProps,
+		Component: Badge,
+	},
+	{
+		name: "Diff",
+		description:
+			"Renders the difference between two code snippets with GitHub-style unified or side-by-side views.",
+		whenToUse:
+			"Use for before/after API changes, config migrations, or 'change this to that' instructions. Prefer a plain fence when only showing the final code.",
+		props: diffProps,
+		Component: Diff,
+	},
+	{
+		name: "Card",
+		description:
+			"A bordered content card with an optional icon, title, description, and meta line.",
+		whenToUse:
+			"Use for a link or highlighted block that needs more visual weight than a plain link — a related page, an external resource, a next step. Set `href` (or `interactive`) to enable the hover lift and trailing arrow. Group several inside `CardGrid` for a responsive layout.",
+		props: cardProps,
+		Component: Card,
+	},
+	{
+		name: "CardGrid",
+		description: "A responsive 2- or 3-column grid for laying out `Card` elements.",
+		whenToUse:
+			'Wrap 2 or more `Card` elements to lay them out side by side; set `columns="3"` for a wider grid.',
+		props: cardGridProps,
+		Component: CardGrid,
+	},
+	{
+		name: "Kbd",
+		description: "A small styled key cap for keyboard shortcuts.",
+		whenToUse:
+			"Use inline for a literal keystroke, e.g. `<Kbd>⌘</Kbd><Kbd>K</Kbd>`. Not for regular inline code — use a backtick fence for that.",
+		props: kbdProps,
+		Component: Kbd,
+	},
+	{
+		name: "FileTree",
+		description: "A collapsible file/folder tree, for showing a project layout.",
+		whenToUse:
+			"Use to show the shape of a directory a reader needs to navigate, e.g. 'here's what the generated project looks like'. Pass `nodes` as a plain JSON array of `{ name, path?, children?, open? }`; set `activePath` to highlight one row.",
+		props: fileTreeProps,
+		Component: FileTree,
+	},
+	{
+		name: "Chart",
+		description:
+			"A bar, line, area or histogram chart rendered as inline SVG, framed like a code block.",
+		whenToUse:
+			'For bar, line and area: `data` is `[{ label, <series>: number }, ...]`; `series` lists which keys to plot (defaults to `["value"]`), for small, self-contained datasets (four series or fewer) that are clearer as a shape than a table. Set `orientation="horizontal"` on a bar chart when labels are long or there are more than ~6 categories. For a histogram, set `type="histogram"` and pass raw numbers as `values`; leave `data`/`series` off and optionally cap the bin count with `bins`. Prefer a table once there\'s more data than a chart can read at a glance.',
+		props: chartProps,
+		Component: Chart,
+	},
+	{
+		name: "Sparkline",
+		description: "A tiny inline trend line with no axes or labels.",
+		whenToUse:
+			"Use inline (e.g. in a sentence or table cell) to show the shape of a trend without a full chart — 'requests over the last hour ' next to a Sparkline. Needs at least two `values`.",
+		props: sparklineProps,
+		Component: Sparkline,
+	},
+	{
+		name: "Dropdown",
+		description:
+			"A menu-style picker: a button that opens a popover list of options — a plain form control, or a content switcher when given `Option` children.",
+		whenToUse:
+			"Pass `options` (strings or `{ value, label }`) for a form-style select, e.g. a settings picker. Pass `Option` children instead — each with a `label` and its own content — to switch between longer or more numerous panels of content; prefer `Tabs` when there are only 2-4 visible alternatives, and `Dropdown` once the list gets longer than fits comfortably as tabs.",
+		props: dropdownProps,
+		Component: Dropdown,
+	},
+	{
+		name: "Option",
+		description: "A single labeled option within a `Dropdown` content switcher.",
+		whenToUse:
+			"Only as a direct child of `<Dropdown>`. `label` is required; `value` defaults to a slug of `label`.",
+		props: optionProps,
+		Component: Option,
+	},
+	{
+		name: "Screenshot",
+		description:
+			"An image framed as a macOS window — traffic-light buttons, an optional title, a raised border — for app and UI screenshots.",
+		whenToUse:
+			"Use instead of a plain Markdown image when the picture is a screenshot of an app, web page, or terminal, so it reads as a window rather than a bare bitmap. `src` resolves like a Markdown image; add `title` for the window name and `caption` for a note below. The title bar's expand control opens the image full-screen with pan and zoom, so a dense screenshot can stay small inline. Keep plain `![alt](src)` for diagrams, logos, and photos.",
+		props: screenshotProps,
+		Component: Screenshot,
+	},
+];
+
+export const builtinComponents: Record<string, ComponentType<any>> = Object.fromEntries(
+	builtins.map((builtin) => [builtin.name, builtin.Component]),
+);

package/client/design/base/editor.css

@@ -0,0 +1,151 @@
+/* Base ProseMirror rules for the inline Tiptap editor (client/MdSectionEditor.tsx).
+   Hand-written rather than importing prosemirror-view's style/prosemirror.css
+   as a dependency — the file is tiny, and this keeps every value on an
+   mdxserve design token so dark mode is free. Selectors and defaults are
+   copied 1:1 from node_modules/prosemirror-view/style/prosemirror.css and
+   node_modules/prosemirror-gapcursor/style/gapcursor.css (read at
+   implementation time), with only the hardcoded colors swapped for tokens. */
+
+.ProseMirror {
+	position: relative;
+	white-space: pre-wrap;
+	white-space: break-spaces;
+	word-wrap: break-word;
+	font-variant-ligatures: none;
+	outline: none;
+}
+
+/* A selected node (an image, a table cell range) gets the accent ring the
+   rest of the design uses for interactive emphasis, instead of
+   prosemirror-view's hardcoded `#8cf`. */
+.ProseMirror-selectednode {
+	outline: 2px solid var(--border-accent);
+}
+
+/* The gap cursor (the blinking bar shown between block nodes that can't
+   otherwise take a text cursor, e.g. before/after a table). */
+.ProseMirror-gapcursor {
+	display: none;
+	pointer-events: none;
+	position: absolute;
+}
+
+.ProseMirror-gapcursor::after {
+	content: "";
+	display: block;
+	position: absolute;
+	top: -2px;
+	width: 20px;
+	border-top: 1px solid var(--text-body);
+	animation: ProseMirror-cursor-blink 1.1s steps(2, start) infinite;
+}
+
+@keyframes ProseMirror-cursor-blink {
+	to {
+		visibility: hidden;
+	}
+}
+
+.ProseMirror-focused .ProseMirror-gapcursor {
+	display: block;
+}
+
+/* The editing frame. Entering edit mode must not move a single glyph, so the
+   section keeps its read-mode box exactly and the glow is a positioned
+   pseudo-element that lays out nothing. Its edges are chosen so the frame
+   reads as *replacing* the section rules: the top edge sits where this
+   section's h2 rule was, the bottom edge where the next section's h2 rule
+   is (that rule is 3px wide and the ring covers it). Sections without an h2
+   on either side get half the prose gap instead. */
+.mdx-section[data-editing]::before {
+	content: "";
+	position: absolute;
+	pointer-events: none;
+	inset: calc(-1 * var(--prose-gap) / 2) calc(-1 * var(--space-4));
+	border-radius: var(--radius-md);
+	box-shadow: 0 0 0 3px var(--focus-ring);
+	/* The glow fades and grows in on entry; --dur-slow is 0ms under
+	   prefers-reduced-motion, so it simply appears there. */
+	animation: mdx-editor-glow-in var(--dur-slow) var(--ease-out);
+}
+
+/* This section opens with an h2: its rule is the frame's top edge. */
+.mdx-section[data-editing]:has(.ProseMirror > h2:first-child)::before {
+	top: 0;
+}
+
+/* The next section opens with an h2: its rule is the frame's bottom edge
+   (that h2 carries the heading gap as margin-top, so the rule sits exactly
+   one heading gap below this section's last line). */
+.mdx-section[data-editing]:has(+ .mdx-section > h2:first-child)::before {
+	bottom: calc(-1 * var(--prose-gap-heading));
+}
+
+@keyframes mdx-editor-glow-in {
+	from {
+		opacity: 0;
+		box-shadow: 0 0 0 0 var(--focus-ring);
+	}
+}
+
+/* The frame is the focus indicator; reset.css's global `:focus-visible` ring
+   would otherwise draw a second one hugging the contenteditable. */
+.mdx-section[data-editing] .ProseMirror:focus-visible {
+	box-shadow: none;
+}
+
+/* In read mode a top-level h2 draws the section divider (border-top +
+   padding-top, prose.css). Inside the frame the line collides with the glow,
+   but its box has to stay — dropping the padding would shift the heading up —
+   so only the colour goes. */
+.mdx-section[data-editing] .ProseMirror > h2,
+/* …and the next section's rule, which the frame's bottom edge stands in for
+   (it would otherwise show through under the rounded corners). */
+.mdx-section[data-editing] + .mdx-section > h2:first-child {
+	border-top-color: transparent;
+}
+
+/* app.css's `.mdx-prose pre { background: transparent }` assumes CodeFrame's
+   own card chrome (client/CodeBlock.tsx) draws the background/border — but a
+   code block typed straight into the editor has no CodeFrame around it, so
+   restore a plain, static version of that chrome here. */
+.mdx-prose .ProseMirror pre {
+	background: var(--code-bg);
+	border: 1px solid var(--code-border);
+	border-radius: var(--radius-md);
+	padding: var(--space-4);
+}
+
+/* GFM task items inside the editor: TaskList/TaskItem (@tiptap/extension-list)
+   render `<ul data-type="taskList"><li data-checked><label><input type="checkbox"></label><div>…</div></li></ul>`
+   (the `data-type="taskItem"` attribute exists only in TaskItem's *parse* rule,
+   not in its rendered markup), a different shape than the read-mode markup
+   styled in app.css's `.mdx-prose li:has(> input[type=checkbox])` rules — mirror
+   the same flex-row checkbox alignment so a task list doesn't visibly reflow
+   between read and edit mode. */
+.mdx-prose .ProseMirror ul[data-type="taskList"] {
+	list-style: none;
+	padding-left: 0;
+}
+
+.mdx-prose .ProseMirror ul[data-type="taskList"] > li {
+	display: flex;
+	align-items: baseline;
+}
+
+.mdx-prose .ProseMirror ul[data-type="taskList"] > li > label {
+	display: inline-flex;
+	align-items: center;
+	margin: 0 0.5em 0 0;
+	user-select: none;
+}
+
+.mdx-prose .ProseMirror ul[data-type="taskList"] > li > label input[type="checkbox"] {
+	accent-color: var(--teal-550);
+	vertical-align: -0.1em;
+}
+
+.mdx-prose .ProseMirror ul[data-type="taskList"] > li > div {
+	flex: 1 1 auto;
+	min-width: 0;
+}

package/client/design/base/prose.css

@@ -0,0 +1,143 @@
+/* Element rules carry a `:not(.not-prose *)` guard (added at port time) so builtin
+   components, which set `not-prose` on their root, keep their own typography. */
+/* .mdx-prose — the rendered-markdown container. This is the product's core surface:
+   every vertical rhythm decision in mdxserve lives here. */
+.mdx-prose {
+	font: var(--type-prose);
+	color: var(--text-body);
+	/* No max-width here: the column width is owned by AppShell's wrapper
+	   (`max-w-prose` by default, or the user's dragged doc width), so the
+	   article must fill it or the resize handles would only move the frame. */
+	/* Long identifiers in headings/prose (`Foo.get_arrow_schema`) have no break
+	   opportunities; let them wrap instead of pushing past the column. */
+	overflow-wrap: break-word;
+}
+/* `<MdSection>` (client/MdSection.tsx) wraps every editable run of top-level
+   markdown nodes but must be visually transparent in read mode — no padding,
+   border or overflow, just `position: relative` for the hover pencil — so
+   its children's margins keep collapsing through it exactly as if `.mdx-prose`
+   were their direct parent. */
+.mdx-section {
+	position: relative;
+}
+/* The direct-child rhythm rules below therefore have to reach three levels:
+   `.mdx-prose` itself (docs with no sections, or content before the first
+   one), `.mdx-section` (the normal wrapped case), and `.mdx-prose .ProseMirror`
+   (a section's own edit-mode surface) — the last one is what makes editing
+   WYSIWYG, since without it a heading/list typed into the editor would use
+   ProseMirror's default spacing instead of mdxserve's. */
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror) > * + * {
+	margin-top: var(--prose-gap);
+}
+.mdx-prose h1:not(:where(.not-prose, .not-prose *)) {
+	font: var(--type-h1);
+	margin-top: 0;
+}
+.mdx-prose h2:not(:where(.not-prose, .not-prose *)) {
+	font: var(--type-h2);
+	letter-spacing: var(--tracking-tight);
+}
+.mdx-prose h3:not(:where(.not-prose, .not-prose *)) {
+	font: var(--type-h3);
+	letter-spacing: var(--tracking-snug);
+}
+.mdx-prose h4:not(:where(.not-prose, .not-prose *)) {
+	font: var(--type-h4);
+}
+.mdx-prose h2:not(:where(.not-prose, .not-prose *)),
+.mdx-prose h3:not(:where(.not-prose, .not-prose *)),
+.mdx-prose h4:not(:where(.not-prose, .not-prose *)) {
+	position: relative;
+}
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror) > h2 {
+	margin-top: var(--prose-gap-heading);
+	padding-top: var(--space-6);
+	border-top: 1px solid var(--border-subtle);
+}
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror) > h3,
+:is(.mdx-prose, .mdx-section, .mdx-prose .ProseMirror) > h4 {
+	margin-top: var(--prose-gap-block);
+}
+.mdx-prose strong:not(:where(.not-prose, .not-prose *)) {
+	font-weight: var(--weight-bold);
+	color: var(--text-heading);
+}
+.mdx-prose em:not(:where(.not-prose, .not-prose *)) {
+	font-style: italic;
+}
+.mdx-prose code:not(:where(.not-prose, .not-prose *)) {
+	font: var(--type-code-inline);
+	background: var(--code-bg-inline);
+	color: var(--text-accent);
+	padding: 0.12em 0.34em;
+	border-radius: var(--radius-xs);
+}
+.mdx-prose a code:not(:where(.not-prose, .not-prose *)) {
+	color: inherit;
+}
+.mdx-prose ul:not(:where(.not-prose, .not-prose *)),
+.mdx-prose ol:not(:where(.not-prose, .not-prose *)) {
+	margin-bottom: 0;
+	padding-left: 1.35em;
+}
+.mdx-prose li + li:not(:where(.not-prose, .not-prose *)) {
+	margin-top: var(--space-2);
+}
+.mdx-prose li::marker:not(:where(.not-prose, .not-prose *)) {
+	color: var(--text-subtle);
+}
+.mdx-prose blockquote:not(:where(.not-prose, .not-prose *)) {
+	margin-bottom: 0;
+	padding: var(--space-1) 0 var(--space-1) var(--space-5);
+	border-left: 2px solid var(--border-accent);
+	color: var(--text-muted);
+	font-style: normal;
+}
+.mdx-prose table:not(:where(.not-prose, .not-prose *)) {
+	border-collapse: collapse;
+	width: 100%;
+	font-size: var(--size-md);
+}
+.mdx-prose th:not(:where(.not-prose, .not-prose *)) {
+	text-align: left;
+	font-weight: var(--weight-semibold);
+	color: var(--text-heading);
+	border-bottom: 1px solid var(--border-strong);
+	padding: var(--space-2-5) var(--space-3);
+}
+.mdx-prose td:not(:where(.not-prose, .not-prose *)) {
+	border-bottom: 1px solid var(--border-subtle);
+	padding: var(--space-2-5) var(--space-3);
+	vertical-align: top;
+}
+.mdx-prose img:not(:where(.not-prose, .not-prose *)) {
+	max-width: 100%;
+	border-radius: var(--radius-md);
+	border: 1px solid var(--border-default);
+}
+.mdx-prose hr:not(:where(.not-prose, .not-prose *)) {
+	margin: var(--space-10) 0;
+}
+/* anchor affordance: the ¶-style link appears on heading hover, never in print */
+.mdx-anchor {
+	position: absolute;
+	left: -1.1em;
+	/* Above DocView's ResizeHandle (z-10, absolute inset-y-0 on the same
+	   container): the glyph hangs in the left gutter where the handle lives,
+	   and without this the handle takes the hover and the click. */
+	z-index: 20;
+	/* `top: 0` would sit in an h2's padding-top (the rule above it); anchor
+	   to the bottom of the box so the glyph shares the heading's last line. */
+	bottom: 0;
+	opacity: 0;
+	color: var(--text-subtle);
+	text-decoration: none;
+	font-weight: var(--weight-regular);
+	transition: opacity var(--dur-fast) var(--ease-standard);
+}
+.mdx-prose h2:hover .mdx-anchor,
+.mdx-prose h3:hover .mdx-anchor,
+.mdx-prose h4:hover .mdx-anchor,
+.mdx-anchor:focus-visible {
+	opacity: 1;
+}

package/client/design/base/reset.css

@@ -0,0 +1,79 @@
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+}
+html {
+	-webkit-text-size-adjust: 100%;
+}
+body {
+	margin: 0;
+	background: var(--surface-page);
+	color: var(--text-body);
+	font: var(--type-ui);
+	-webkit-font-smoothing: antialiased;
+	text-rendering: optimizeLegibility;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+	margin: 0;
+	color: var(--text-heading);
+	letter-spacing: var(--tracking-tight);
+	text-wrap: balance;
+}
+p {
+	margin: 0;
+	text-wrap: pretty;
+}
+/* Link colour is scoped to prose (port-time change): the design applied it to every <a>,
+   but this sheet is unlayered, so that rule beat Tailwind utilities on anchors that are
+   buttons, cards and nav rows. UI anchors style themselves. */
+.mdx-prose a:not(:where(.not-prose, .not-prose *)) {
+	color: var(--text-link);
+	text-decoration: underline;
+	text-decoration-color: color-mix(in oklab, var(--text-link) 35%, transparent);
+	text-underline-offset: 0.18em;
+	transition: var(--transition-color);
+}
+.mdx-prose a:not(:where(.not-prose, .not-prose *)):hover {
+	color: var(--text-link-hover);
+	text-decoration-color: currentColor;
+}
+code,
+pre,
+kbd,
+samp {
+	font-family: var(--font-mono);
+}
+/* (button/input font+color inherit removed at port time — Tailwind preflight already does it,
+   and an unlayered copy here would beat utility classes on buttons.) */
+:focus-visible {
+	outline: none;
+	box-shadow: var(--shadow-focus);
+	border-radius: var(--radius-sm);
+}
+::selection {
+	background: color-mix(in oklab, var(--teal-400) 28%, transparent);
+}
+hr {
+	border: 0;
+	border-top: 1px solid var(--border-default);
+}
+::-webkit-scrollbar {
+	width: 10px;
+	height: 10px;
+}
+::-webkit-scrollbar-thumb {
+	background: var(--border-strong);
+	border-radius: var(--radius-pill);
+	border: 3px solid transparent;
+	background-clip: content-box;
+}
+::-webkit-scrollbar-thumb:hover {
+	background: var(--n-400);
+	background-clip: content-box;
+}