@designtools/docs 0.0.0-stage → 0.2.0

package/src/playground.tsx

@@ -0,0 +1,357 @@
+"use client";
+
+import { Select } from "@base-ui/react/select";
+import { Switch } from "@base-ui/react/switch";
+import { Toggle } from "@base-ui/react/toggle";
+import { ToggleGroup } from "@base-ui/react/toggle-group";
+import { Tooltip } from "@base-ui/react/tooltip";
+import { Check, ChevronDown, Info, Moon, RotateCcw, SlidersHorizontal, Sun } from "lucide-react";
+import type { ReactNode } from "react";
+import { useId, useState } from "react";
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { toJSX } from "./lib/jsx";
+import { coerce, Missing, useLookup } from "./lib/lookup";
+import type { ComponentEntry, VariantAxis } from "./lib/manifest-types";
+import { Frame, IconButton, Stage, Toolbar } from "./lib/ui";
+
+/**
+ * The component, live, with controls generated from its variants and its own
+ * boolean props, and the JSX for exactly what is showing. Pass `props` for what
+ * it needs to render at all; the controls change everything else.
+ */
+export function Playground({
+  entry,
+  props: base = {},
+  children: initialText = entry.name,
+}: {
+  entry: ComponentEntry;
+  props?: Record<string, unknown>;
+  /** Text content, editable in the playground. Pass "" for a component without children. */
+  children?: string;
+}) {
+  const lookup = useLookup();
+  const Component = lookup.componentFor(entry);
+  const axes = entry.variants?.axes ?? [];
+  const axisNames = new Set(axes.map((a) => a.name));
+  const flags = Object.entries(entry.props)
+    .filter(([name, p]) => !p.from && !axisNames.has(name) && p.type === "boolean" && p.deprecated === undefined)
+    .map(([name]) => name);
+
+  const [variants, setVariants] = useState<Record<string, string>>({});
+  const [on, setOn] = useState<Record<string, boolean>>({});
+  const [text, setText] = useState(initialText);
+  const [theme, setTheme] = useState<"light" | "dark" | undefined>();
+
+  if (!Component) return <Missing name={entry.name} />;
+
+  const chosen = { ...coerce(variants), ...Object.fromEntries(Object.entries(on).filter(([, v]) => v)) };
+  const code = toJSX(entry.export, { ...visible(base), ...chosen }, text || undefined);
+
+  const changed = Object.keys(variants).length > 0 || Object.values(on).some(Boolean) || text !== initialText;
+  const reset = () => {
+    setVariants({});
+    setOn({});
+    setText(initialText);
+  };
+
+  return (
+    <Frame data-slot="playground">
+      <div className="grid lg:grid-cols-[minmax(0,1fr)_20rem]">
+        <div className="flex min-w-0 flex-col">
+          <Toolbar>
+            <span className="flex items-center gap-2 pl-2 text-xs font-medium text-muted-foreground">
+              <SlidersHorizontal aria-hidden className="size-(--dt-size-xs)" />
+              Live
+            </span>
+            <span className="flex items-center gap-0.5">
+              <IconButton
+                icon={theme === "dark" ? Sun : Moon}
+                label={theme === "dark" ? "Show in light mode" : "Show in dark mode"}
+                pressed={theme !== undefined}
+                onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+              />
+              <IconButton icon={RotateCcw} label="Reset the controls" onClick={reset} disabled={!changed} className="disabled:pointer-events-none disabled:opacity-40" />
+            </span>
+          </Toolbar>
+          <Stage theme={theme} data-slot="playground-preview" className="min-h-72 flex-1">
+            <Boundary label={entry.name}>
+              <Component {...base} {...chosen}>
+                {text || undefined}
+              </Component>
+            </Boundary>
+          </Stage>
+        </div>
+        <div data-slot="playground-controls" className="flex flex-col gap-6 border-t border-border p-5 lg:border-t-0 lg:border-l">
+          {axes.map((axis) => (
+            <AxisControl
+              key={axis.name}
+              axis={axis}
+              value={variants[axis.name] ?? axis.default ?? ""}
+              onChange={(v) => setVariants((s) => ({ ...s, [axis.name]: v }))}
+            />
+          ))}
+          {flags.map((name) => (
+            <FlagControl key={name} name={name} checked={!!on[name]} onChange={(v) => setOn((s) => ({ ...s, [name]: v }))} />
+          ))}
+          {initialText !== "" && <TextControl value={text} onChange={setText} />}
+          {axes.length === 0 && flags.length === 0 && initialText === "" && <p className="text-sm text-muted-foreground">Nothing to change: it has no variants or flags.</p>}
+        </div>
+      </div>
+      <div className="border-t border-border">
+        <CodeView code={code} label="JSX" bare />
+      </div>
+    </Frame>
+  );
+}
+
+/** Props passed only so the component renders (handlers, data) are left out of the snippet unless they are short. */
+export function visible(props: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(props).filter(([, v]) => typeof v !== "function" && JSON.stringify(v ?? "").length <= 40));
+}
+
+/** `variant` → `Variant`, `aria-label` → `Aria label`: a control reads as a setting, not a prop name. */
+export function title(name: string): string {
+  const words = name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/** Options fit one segmented row when there are few and their names are short; otherwise a menu. */
+const fitsSegments = (axis: VariantAxis) => axis.options.length <= 4 && axis.options.reduce((n, o) => n + o.name.length, 0) <= 26;
+
+/** A control's label, with the prop it sets and what its options mean behind an info button. */
+export function Label({ id, name, info, htmlFor }: { id?: string; name: string; info?: ReactNode; htmlFor?: string }) {
+  const text = (
+    <span className="text-sm font-medium">
+      {title(name)}
+    </span>
+  );
+  return (
+    <div className="flex items-center justify-between gap-2">
+      {htmlFor ? (
+        <label id={id} htmlFor={htmlFor}>
+          {text}
+        </label>
+      ) : (
+        <span id={id}>{text}</span>
+      )}
+      <Tooltip.Root>
+        <Tooltip.Trigger
+          delay={0}
+          closeDelay={0}
+          aria-label={`About ${title(name)}`}
+          className="relative inline-flex size-6 cursor-pointer items-center justify-center rounded-full text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2.5 after:content-['']"
+        >
+          <Info aria-hidden className="size-4" />
+        </Tooltip.Trigger>
+        <Tooltip.Portal>
+          <Tooltip.Positioner data-designtools="" side="left" sideOffset={8} className="z-50">
+            <Tooltip.Popup
+              data-slot="docs-tooltip"
+              className="flex max-w-64 flex-col gap-1 rounded-md bg-canvas-foreground px-2.5 py-2 text-xs leading-snug text-canvas shadow-md transition-opacity duration-(--dt-duration-fast) data-ending-style:opacity-0 data-starting-style:opacity-0 [&_*]:text-canvas/80"
+            >
+              <code className="font-mono font-medium text-canvas!">{name}</code>
+              {info}
+            </Tooltip.Popup>
+          </Tooltip.Positioner>
+        </Tooltip.Portal>
+      </Tooltip.Root>
+    </div>
+  );
+}
+
+function AxisInfo({ axis }: { axis: VariantAxis }) {
+  const described = axis.options.filter((o) => o.description);
+  return (
+    <>
+      {axis.default && <span className="text-muted-foreground">Default: {axis.default}</span>}
+      {described.map((o) => (
+        <span key={o.name}>
+          <span className="font-medium">{o.name}</span>: <span className="text-muted-foreground">{o.description}</span>
+        </span>
+      ))}
+    </>
+  );
+}
+
+export function AxisControl({ axis, value, onChange }: { axis: VariantAxis; value: string; onChange: (v: string) => void }) {
+  const id = useId();
+  if (fitsSegments(axis)) {
+    return (
+      <div className="flex flex-col gap-2">
+        <Label id={id} name={axis.name} info={<AxisInfo axis={axis} />} />
+        {/* one row: a filled track, the chosen option raised out of it */}
+        <ToggleGroup
+          aria-labelledby={id}
+          value={value ? [value] : []}
+          onValueChange={(next) => next[0] && onChange(String(next[0]))}
+          className="grid grid-flow-col auto-cols-fr gap-0.5 rounded-lg bg-muted p-1"
+        >
+          {axis.options.map((o) => (
+            <Toggle
+              key={o.name}
+              value={o.name}
+              className="relative h-8 min-w-0 cursor-pointer truncate rounded-md px-2 text-sm text-muted-foreground transition-colors duration-(--dt-duration-fast) after:absolute after:inset-x-0 after:-inset-y-1.5 after:content-[''] hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[pressed]:bg-canvas data-[pressed]:font-medium data-[pressed]:text-canvas-foreground data-[pressed]:shadow-xs"
+            >
+              {title(o.name)}
+            </Toggle>
+          ))}
+        </ToggleGroup>
+      </div>
+    );
+  }
+  return (
+    <div className="flex flex-col gap-2">
+      <Label id={id} name={axis.name} info={<AxisInfo axis={axis} />} />
+      <Select.Root value={value} onValueChange={(v) => typeof v === "string" && onChange(v)}>
+        <Select.Trigger
+          aria-labelledby={id}
+          className="flex h-10 cursor-pointer items-center justify-between rounded-lg bg-muted px-3 text-sm font-medium hover:bg-muted/70 focus-visible:outline-2 focus-visible:outline-ring"
+        >
+          <Select.Value>{(v: string) => title(v)}</Select.Value>
+          <Select.Icon aria-hidden>
+            <ChevronDown className="size-4 text-muted-foreground" />
+          </Select.Icon>
+        </Select.Trigger>
+        <Select.Portal>
+          <Select.Positioner data-designtools="" sideOffset={4} alignItemWithTrigger={false} className="z-50">
+            <Select.Popup className="min-w-(--anchor-width) rounded-lg border border-border bg-overlay p-1 text-overlay-foreground shadow-md">
+              <Select.List>
+                {axis.options.map((o) => (
+                  <Select.Item
+                    key={o.name}
+                    value={o.name}
+                    className="grid min-h-(--docs-target,2.75rem) cursor-pointer grid-cols-[1fr_auto] items-center gap-3 rounded-md px-3 text-sm outline-none data-[highlighted]:bg-muted"
+                  >
+                    <Select.ItemText>{title(o.name)}</Select.ItemText>
+                    <Select.ItemIndicator>
+                      <Check aria-hidden className="size-4" />
+                    </Select.ItemIndicator>
+                  </Select.Item>
+                ))}
+              </Select.List>
+            </Select.Popup>
+          </Select.Positioner>
+        </Select.Portal>
+      </Select.Root>
+    </div>
+  );
+}
+
+export function FlagControl({ name, checked, onChange }: { name: string; checked: boolean; onChange: (v: boolean) => void }) {
+  const id = useId();
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <label htmlFor={id} className="text-sm font-medium">
+        {title(name)}
+      </label>
+      <Switch.Root
+        id={id}
+        checked={checked}
+        onCheckedChange={onChange}
+        // drawn small, pressed large: the hit area reaches the docs' target without the switch growing
+        className="relative h-6 w-10 shrink-0 cursor-pointer rounded-full bg-input p-0.5 transition-colors duration-(--dt-duration-fast) after:absolute after:-inset-2.5 after:content-[''] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:bg-primary"
+      >
+        <Switch.Thumb className="block size-5 rounded-full bg-primary-foreground shadow-xs transition-transform duration-(--dt-duration-fast) data-[checked]:translate-x-4" />
+      </Switch.Root>
+    </div>
+  );
+}
+
+export function TextControl({ value, onChange }: { value: string; onChange: (v: string) => void }) {
+  const id = useId();
+  return (
+    <div className="flex flex-col gap-2">
+      <Label name="children" htmlFor={id} info={<span className="text-muted-foreground">The text inside it.</span>} />
+      <input
+        id={id}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="h-10 rounded-lg bg-muted px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+      />
+    </div>
+  );
+}
+
+/** A number prop: a field with steppers. */
+export function NumberControl({ name, value, onChange, info }: { name: string; value: number | undefined; onChange: (v: number | undefined) => void; info?: ReactNode }) {
+  const id = useId();
+  const step = (d: number) => onChange((value ?? 0) + d);
+  const button =
+    "relative flex w-9 cursor-pointer items-center justify-center text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-y-1 after:inset-x-0 after:content-['']";
+  return (
+    <div className="flex flex-col gap-2">
+      <Label name={name} htmlFor={id} info={info} />
+      <div className="flex h-10 items-stretch overflow-hidden rounded-lg bg-muted">
+        <button type="button" aria-label={`Less ${title(name)}`} onClick={() => step(-1)} className={button}>
+          −
+        </button>
+        <input
+          id={id}
+          type="number"
+          inputMode="decimal"
+          value={value ?? ""}
+          onChange={(e) => onChange(e.target.value === "" ? undefined : Number(e.target.value))}
+          className="min-w-0 flex-1 bg-transparent text-center font-mono text-sm tabular-nums outline-none [appearance:textfield] focus-visible:outline-2 focus-visible:outline-ring [&::-webkit-inner-spin-button]:appearance-none"
+        />
+        <button type="button" aria-label={`More ${title(name)}`} onClick={() => step(1)} className={button}>
+          +
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/** A string prop: a text field. */
+export function StringControl({ name, value, onChange, info }: { name: string; value: string; onChange: (v: string) => void; info?: ReactNode }) {
+  const id = useId();
+  return (
+    <div className="flex flex-col gap-2">
+      <Label name={name} htmlFor={id} info={info} />
+      <input
+        id={id}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="h-10 rounded-lg bg-muted px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+      />
+    </div>
+  );
+}
+
+/**
+ * An array or object prop (a Select's options): JSON, applied while it parses,
+ * and said plainly when it does not, so a half-typed edit never breaks the preview.
+ */
+export function JsonControl({ name, value, onChange, info }: { name: string; value: unknown; onChange: (v: unknown) => void; info?: ReactNode }) {
+  const id = useId();
+  const [text, setText] = useState(() => JSON.stringify(value ?? null, null, 2));
+  const [error, setError] = useState<string | null>(null);
+  return (
+    <div className="flex flex-col gap-2">
+      <Label name={name} htmlFor={id} info={info} />
+      <textarea
+        id={id}
+        value={text}
+        rows={Math.min(10, text.split("\n").length)}
+        spellCheck={false}
+        aria-invalid={!!error}
+        aria-describedby={error ? `${id}-error` : undefined}
+        onChange={(e) => {
+          setText(e.target.value);
+          try {
+            onChange(JSON.parse(e.target.value));
+            setError(null);
+          } catch (err) {
+            setError(err instanceof Error ? err.message : "Not valid JSON");
+          }
+        }}
+        className="resize-y rounded-lg bg-muted px-3 py-2 font-mono text-xs leading-relaxed focus-visible:outline-2 focus-visible:outline-ring aria-invalid:outline-2 aria-invalid:outline-destructive"
+      />
+      {error && (
+        <p id={`${id}-error`} className="text-xs text-destructive-subdued-foreground">
+          Not applied: {error}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/preview-frame.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import { ExternalLink, Monitor, Moon, Smartphone, Sun, Tablet } from "lucide-react";
+import { useEffect, useState, type ReactNode } from "react";
+import { Boundary } from "./lib/boundary";
+import { cx } from "./lib/cx";
+import { Missing, renderExample, useLookup } from "./lib/lookup";
+import type { ComponentEntry, PatternEntry } from "./lib/manifest-types";
+import { Frame, IconButton, IconLink, Toolbar } from "./lib/ui";
+
+type Theme = "light" | "dark";
+
+/**
+ * A preview route in an iframe, at set widths and in either mode, so a
+ * component is seen at a phone's width and its media queries actually fire.
+ */
+export function PreviewFrame({
+  src,
+  title,
+  widths = [375, 768, 1280],
+  height = 360,
+}: {
+  /** The preview route, e.g. `/design/system/preview/badge/canonical`. */
+  src: string;
+  title: string;
+  widths?: number[];
+  height?: number;
+}) {
+  const [width, setWidth] = useState(widths[0]);
+  const [theme, setTheme] = useState<Theme>("light");
+  const url = `${src}${src.includes("?") ? "&" : "?"}theme=${theme}`;
+  const device = (w: number) => (w < 600 ? Smartphone : w < 1024 ? Tablet : Monitor);
+
+  return (
+    <Frame data-slot="preview-frame">
+      <Toolbar>
+        <div role="group" aria-label="Preview width" className="flex items-center gap-0.5 rounded-lg border border-border p-0.5">
+          {widths.map((w) => {
+            const Icon = device(w);
+            return (
+              <button
+                key={w}
+                type="button"
+                aria-pressed={width === w}
+                onClick={() => setWidth(w)}
+                className={cx(
+                  "relative inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-md px-2.5 font-mono text-xs text-muted-foreground transition-colors duration-(--dt-duration-fast) hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:bg-muted aria-pressed:text-canvas-foreground",
+                  "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-1.75rem)/2)] after:content-['']",
+                )}
+              >
+                <Icon aria-hidden className="size-(--dt-size-xs)" />
+                {w}
+              </button>
+            );
+          })}
+        </div>
+        <span className="flex items-center gap-0.5">
+          <IconButton
+            icon={theme === "dark" ? Sun : Moon}
+            label={theme === "dark" ? "Show in light mode" : "Show in dark mode"}
+            pressed={theme === "dark"}
+            onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+          />
+          <IconLink icon={ExternalLink} label="Open in a new tab" href={url} target="_blank" rel="noreferrer" />
+        </span>
+      </Toolbar>
+      <div
+        className="overflow-x-auto bg-muted/50 bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px] p-6"
+        tabIndex={0}
+        role="region"
+        aria-label="Preview"
+      >
+        <div className="mx-auto flex flex-col overflow-hidden rounded-lg border border-border bg-canvas shadow-md" style={{ width, maxWidth: "none" }}>
+          <div aria-hidden className="flex items-center gap-3 border-b border-border bg-surface px-3 py-2">
+            <span className="flex gap-1.5">
+              <span className="size-2.5 rounded-full bg-border" />
+              <span className="size-2.5 rounded-full bg-border" />
+              <span className="size-2.5 rounded-full bg-border" />
+            </span>
+            <span className="min-w-0 flex-1 truncate rounded-md bg-muted px-2 py-0.5 text-center font-mono text-xs text-muted-foreground">
+              {title} · {width}px
+            </span>
+          </div>
+          <iframe title={`${title}, ${width}px wide, ${theme} mode`} src={url} data-slot="preview-iframe" className="block w-full resize-y bg-canvas" style={{ height }} />
+        </div>
+      </div>
+    </Frame>
+  );
+}
+
+/**
+ * What the preview route renders around a state: the page's canvas in the
+ * requested mode, set on the document too, so popups in portals match.
+ */
+export function PreviewSurface({ theme, children }: { theme?: string; children: ReactNode }) {
+  const mode: Theme | undefined = theme === "dark" || theme === "light" ? theme : undefined;
+  useEffect(() => {
+    if (!mode) return;
+    const root = document.documentElement;
+    const previous = root.dataset.theme;
+    root.dataset.theme = mode;
+    return () => {
+      if (previous === undefined) delete root.dataset.theme;
+      else root.dataset.theme = previous;
+    };
+  }, [mode]);
+
+  return (
+    <div data-designtools="" data-docs-stage="" data-slot="preview-surface" data-theme={mode} className="min-h-dvh bg-canvas p-6 text-canvas-foreground">
+      {children}
+    </div>
+  );
+}
+
+/** One example on its own, for the preview route to render inside a PreviewSurface. */
+export function PreviewExample({ entry, example }: { entry: ComponentEntry; example: string }) {
+  const lookup = useLookup();
+  const module = lookup.examplesFor(entry);
+  if (!module) return <Missing name={entry.name} what="examples" />;
+  if (!(example in module)) return <p className="text-sm">{entry.name} has no example called {example}.</p>;
+  return <Boundary label={example}>{renderExample(module[example], example)}</Boundary>;
+}
+
+/** One pattern composition on its own. */
+export function PreviewComposition({ pattern, composition }: { pattern: PatternEntry; composition: string }) {
+  const lookup = useLookup();
+  const module = lookup.compositionsFor(pattern);
+  if (!module) return <Missing name={pattern.name} what="compositions" />;
+  if (!(composition in module)) return <p className="text-sm">{pattern.name} has no composition called {composition}.</p>;
+  return <Boundary label={composition}>{renderExample(module[composition], composition)}</Boundary>;
+}

package/src/props-table.tsx

@@ -0,0 +1,154 @@
+import { ChevronDown } from "lucide-react";
+import { cx } from "./lib/cx";
+import type { ComponentEntry, PropEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/**
+ * A component's props, as an API reference: name, type and default on one line,
+ * each row opening to its description. Its own props first, then those of the
+ * primitive it wraps, folded away. Deprecated props are struck through with the
+ * reason; what it inherits from an element or primitive is named underneath.
+ */
+export function PropsTable({ entry }: { entry: ComponentEntry }) {
+  const rows = Object.entries(entry.props);
+  const own = rows.filter(([, p]) => !p.from);
+  const byPackage = new Map<string, [string, PropEntry][]>();
+  for (const row of rows.filter(([, p]) => p.from)) {
+    byPackage.set(row[1].from!, [...(byPackage.get(row[1].from!) ?? []), row]);
+  }
+
+  return (
+    <div data-slot="props-table" className="flex flex-col gap-4">
+      {own.length > 0 ? <Table rows={own} /> : <p className="text-sm text-muted-foreground">No props of its own.</p>}
+      {[...byPackage.entries()].map(([pkg, inherited]) => (
+        <details key={pkg} data-slot="props-inherited" className="group/inherited overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground">
+          <summary className="flex min-h-(--docs-target,2.75rem) cursor-pointer list-none items-center justify-between gap-3 px-4 text-sm hover:bg-muted [&::-webkit-details-marker]:hidden">
+            <span>
+              {inherited.length} more from <code className="font-mono text-xs">{pkg}</code>
+            </span>
+            <ChevronDown aria-hidden className="size-(--dt-size-xs) text-muted-foreground transition-transform group-open/inherited:rotate-180" />
+          </summary>
+          <div className="border-t border-border">
+            <Table rows={inherited} bare />
+          </div>
+        </details>
+      ))}
+      {entry.inherits && entry.inherits.length > 0 && (
+        <p data-slot="props-inherits" className="text-sm text-muted-foreground">
+          Also accepts every prop of{" "}
+          {entry.inherits.map((x, i) => (
+            <span key={x}>
+              {i > 0 && ", "}
+              <code className="rounded-sm bg-muted px-1 py-0.5 font-mono text-xs text-canvas-foreground">{/^[a-z][\w-]*$/.test(x) ? `<${x}>` : x}</code>
+            </span>
+          ))}
+          .
+        </p>
+      )}
+    </div>
+  );
+}
+
+const COLS = "grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 md:grid-cols-[minmax(9rem,0.9fr)_minmax(0,1.6fr)_minmax(5rem,0.6fr)_1.25rem] md:items-center";
+
+function Table({ rows, bare }: { rows: [string, PropEntry][]; bare?: boolean }) {
+  return (
+    <div className={cx("min-w-0 text-sm", !bare && "overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground")}>
+      {/* a visual header: each row reads in full on its own, name, type and default */}
+      <div aria-hidden className={cx(COLS, "hidden border-b border-border bg-muted/50 px-4 py-2.5 text-xs font-medium text-muted-foreground md:grid")}>
+        <span>Prop</span>
+        <span>Type</span>
+        <span>Default</span>
+        <span />
+      </div>
+      <ul aria-label="Props" className="divide-y divide-border">
+        {rows.map(([name, prop]) => (
+          <li key={name}>
+            <Row name={name} prop={prop} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function Row({ name, prop }: { name: string; prop: PropEntry }) {
+  const deprecated = prop.deprecated !== undefined;
+  const line = (
+    <>
+      <span className="flex min-w-0 items-center gap-1">
+        <code className={cx("truncate font-mono text-xs font-medium text-primary-subdued-foreground", deprecated && "line-through opacity-70")}>{name}</code>
+        {prop.required && (
+          <span data-slot="props-required" className="font-mono text-xs text-destructive-subdued-foreground" title="Required">
+            *<span className="sr-only"> required</span>
+          </span>
+        )}
+      </span>
+      <span className="col-span-2 min-w-0 md:col-span-1">
+        <span className="sr-only">, type </span>
+        <Type prop={prop} />
+      </span>
+      <span className="hidden font-mono text-xs text-muted-foreground md:block">
+        {prop.default !== undefined ? (
+          <>
+            <span className="sr-only">, default </span>
+            {prop.default}
+          </>
+        ) : (
+          <span aria-hidden>—</span>
+        )}
+      </span>
+    </>
+  );
+  const described = deprecated || !!prop.description;
+  if (!described)
+    return (
+      <div data-slot="props-row" className={cx(COLS, "px-4 py-3")}>
+        {line}
+        <span />
+      </div>
+    );
+  return (
+    <details data-slot="props-row" className="group/row">
+      <summary className={cx(COLS, "min-h-(--docs-target,2.75rem) cursor-pointer list-none px-4 py-3 hover:bg-muted/60 [&::-webkit-details-marker]:hidden")}>
+        {line}
+        <ChevronDown aria-hidden className="col-start-2 row-start-1 size-(--dt-size-xs) justify-self-end text-muted-foreground transition-transform group-open/row:rotate-180 md:col-start-4" />
+      </summary>
+      <div className="flex flex-col gap-2 px-4 pb-4 text-sm text-muted-foreground">
+        {prop.default !== undefined && (
+          <p className="md:hidden">
+            Default <code className="font-mono text-xs text-canvas-foreground">{prop.default}</code>
+          </p>
+        )}
+        {deprecated && <p className="font-medium text-canvas-foreground">Deprecated{prop.deprecated ? <>: {inline(prop.deprecated)}</> : "."}</p>}
+        {prop.description?.split("\n\n").map((p) => (
+          <p key={p} className="max-w-prose whitespace-pre-line">
+            {inline(p)}
+          </p>
+        ))}
+      </div>
+    </details>
+  );
+}
+
+/** A type, coloured by kind: literals, primitives and functions read apart at a glance. */
+function Type({ prop }: { prop: PropEntry }) {
+  const parts = prop.values ?? prop.type.split(/\s*\|\s*/);
+  return (
+    <span className="flex flex-wrap items-center gap-x-1 gap-y-1 font-mono text-xs">
+      {parts.map((t, i) => (
+        <span key={`${t}-${i}`} className="inline-flex items-center gap-1">
+          {i > 0 && <span className="text-muted-foreground">|</span>}
+          <span className={cx("break-all", tone(t, !!prop.values))}>{prop.values ? `"${t}"` : t}</span>
+        </span>
+      ))}
+    </span>
+  );
+}
+
+function tone(t: string, literal: boolean): string {
+  if (literal || /^["'].*["']$/.test(t)) return "text-success-subdued-foreground";
+  if (/^(boolean|number|string|true|false|null|undefined)$/.test(t)) return "text-primary-subdued-foreground";
+  if (/=>|^\(|Function|Handler|EventHandler/.test(t)) return "text-destructive-subdued-foreground";
+  return "text-canvas-foreground";
+}