@designtools/docs 0.0.0-stage → 0.1.0

package/src/lib/pseudo.ts

@@ -0,0 +1,74 @@
+/**
+ * Pinned states. A pointer cannot be faked, so instead every `:hover`, `:focus`
+ * and `:active` rule on the page gets a twin that applies inside an element
+ * carrying `data-pseudo="hover"` (or `focus`, `active`; space-separated for more
+ * than one). The twin sits beside the original, in the same layer and media
+ * query, so it wins and loses exactly where the real state would. This is how
+ * Storybook's pseudo-states addon works, done in the browser with no build step.
+ */
+
+export type Pseudo = "hover" | "focus" | "active";
+
+const PATTERNS: [Pseudo, RegExp][] = [
+  ["hover", /:hover(?![-\w])/g],
+  ["focus", /:focus-visible(?![-\w])/g],
+  ["focus", /:focus(?![-\w])/g],
+  ["active", /:active(?![-\w])/g],
+];
+
+/** A state inside :not(), :has(), :is() or :where() changes what the selector means when removed, so those are left alone. */
+const NESTED = /:(?:not|has|is|where)\([^)]*:(?:hover|focus|active)/;
+
+const done = new WeakSet<CSSStyleSheet>();
+
+/** Adds the twins to every stylesheet not yet seen. Cheap to call again: it runs once per sheet, and again only for sheets added since. */
+export function installPseudoStates(): void {
+  for (const sheet of Array.from(document.styleSheets)) {
+    if (done.has(sheet)) continue;
+    try {
+      walk(sheet);
+      done.add(sheet);
+    } catch {
+      // a stylesheet from another origin cannot be read; its states stay unpinnable
+    }
+  }
+}
+
+type Parent = CSSStyleSheet | CSSGroupingRule | CSSStyleRule;
+
+function walk(parent: Parent): void {
+  const rules = parent.cssRules;
+  // backwards, so a twin inserted after its rule never shifts the rules still to visit
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i];
+    if (rule instanceof CSSStyleRule) {
+      const twin = twinOf(rule.selectorText);
+      if (twin) {
+        try {
+          parent.insertRule(`${twin} { ${rule.style.cssText} }`, i + 1);
+        } catch {
+          // a selector the browser will not take back (a vendor pseudo-element): skip it
+        }
+      }
+      if (rule.cssRules?.length) walk(rule);
+    } else if ("cssRules" in rule) {
+      walk(rule as CSSGroupingRule);
+    }
+  }
+}
+
+function twinOf(selector: string): string | null {
+  const out: string[] = [];
+  // split on commas that are not inside parentheses
+  for (const part of selector.split(/,(?![^(]*\))/)) {
+    if (NESTED.test(part)) continue;
+    for (const [state, pattern] of PATTERNS) {
+      pattern.lastIndex = 0;
+      if (!pattern.test(part)) continue;
+      const rest = part.replace(pattern, "").trim();
+      out.push(`:where([data-pseudo~="${state}"]) ${rest || "*"}`);
+      break;
+    }
+  }
+  return out.length ? out.join(", ") : null;
+}

package/src/lib/registry.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+/**
+ * Everything the docs render that lives in the project: each component, examples
+ * module, pattern module and brand asset, keyed the way the manifest names them.
+ * The project's generated registry (`designtools-docs map`) imports them and
+ * renders a `RegistryProvider` around the docs; a server page cannot hand a
+ * component to a client block, so this is how the blocks reach them.
+ */
+export interface Registry {
+  // biome-ignore lint/suspicious/noExplicitAny: components of every shape
+  components: Record<string, ComponentType<any>>;
+  examples: Record<string, Record<string, unknown>>;
+  patterns: Record<string, Record<string, unknown>>;
+  assets: Record<string, string | { src: string }>;
+}
+
+const EMPTY: Registry = { components: {}, examples: {}, patterns: {}, assets: {} };
+const RegistryContext = createContext<Registry>(EMPTY);
+
+export function RegistryProvider({ value, children }: { value: Registry; children: ReactNode }) {
+  return <RegistryContext.Provider value={value}>{children}</RegistryContext.Provider>;
+}
+
+export function useRegistry(): Registry {
+  return useContext(RegistryContext);
+}

package/src/lib/search.ts

@@ -0,0 +1,99 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+
+import fuzzysort from "fuzzysort";
+import { groupFamilies, slugOf } from "./manifest";
+import type { ComponentsManifest, PatternEntry, RuleEntry, TermEntry } from "./manifest-types";
+
+export type SearchKind = "Component" | "Rule" | "Pattern" | "Page";
+
+export interface SearchItem {
+  kind: SearchKind;
+  label: string;
+  href: string;
+  /** The taxonomy's wrong forms for it: typing one finds it, and the result says so. */
+  wrong: string[];
+  /** Anything else it answers to quietly, such as a rule's id. */
+  also?: string[];
+  /** One short line under the label: a category, "part of Card", a rule's kind. */
+  detail?: string;
+}
+
+export interface SearchGroup {
+  kind: SearchKind;
+  /** `matched` is the wrong form a result was found by ("Dropdown" for Select). */
+  items: (SearchItem & { matched?: string })[];
+}
+
+const ORDER: SearchKind[] = ["Component", "Rule", "Pattern", "Page"];
+
+export function searchIndex({
+  manifest,
+  rules = [],
+  patterns = [],
+  terms = [],
+  pages = [],
+  basePath = "/design/system",
+}: {
+  manifest: ComponentsManifest;
+  rules?: RuleEntry[];
+  patterns?: PatternEntry[];
+  terms?: TermEntry[];
+  pages?: { label: string; href: string }[];
+  basePath?: string;
+}): SearchItem[] {
+  const wrong = new Map<string, string[]>();
+  for (const t of terms) if (t.wrong?.length) wrong.set(t.name.toLowerCase(), t.wrong);
+  const wrongOf = (name: string) => wrong.get(name.toLowerCase()) ?? [];
+
+  const items: SearchItem[] = [];
+  for (const { category, families } of groupFamilies(manifest)) {
+    for (const { head, parts } of families) {
+      items.push({ kind: "Component", label: head.name, href: `${basePath}/components/${slugOf(head)}`, wrong: wrongOf(head.name), detail: category });
+      for (const p of parts) {
+        items.push({ kind: "Component", label: p.name, href: `${basePath}/components/${slugOf(p)}`, wrong: wrongOf(p.name), detail: `part of ${head.name}` });
+      }
+    }
+  }
+  for (const r of rules) {
+    items.push({ kind: "Rule", label: r.title, href: `${basePath}/rules#${r.id}`, wrong: wrongOf(r.title), also: [r.id.replace(/-/g, " ")], detail: r.kind === "brand" ? "Brand rule" : "Interface rule" });
+  }
+  for (const p of patterns) items.push({ kind: "Pattern", label: p.name, href: `${basePath}/patterns/${p.id}`, wrong: wrongOf(p.name) });
+  for (const p of pages) items.push({ kind: "Page", label: p.label, href: p.href, wrong: [] });
+  return items;
+}
+
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export function search(items: SearchItem[], query: string, perGroup = 6): SearchGroup[] {
+  const q = query.trim();
+  if (!q) return [];
+  const results = fuzzysort.go(q, items, { keys: ["label", (item: SearchItem) => item.wrong.join(" / "), (item: SearchItem) => (item.also ?? []).join(" / ")], limit: 0, threshold: 0.3 });
+  const ranked = [...results].sort(
+    (a, b) => b.score - a.score || ORDER.indexOf(a.obj.kind) - ORDER.indexOf(b.obj.kind) || (a.obj.label < b.obj.label ? -1 : a.obj.label > b.obj.label ? 1 : 0),
+  );
+  return ORDER.map((kind) => ({
+    kind,
+    items: ranked
+      .filter((r) => r.obj.kind === kind)
+      .slice(0, perGroup)
+      .map((r) => {
+        const viaWrong = (r[1]?.score ?? 0) > Math.max(r[0]?.score ?? 0, r[2]?.score ?? 0);
+        // the wrong form that matched best, to say why a result is here ("Dropdown" for Select)
+        const alias = viaWrong
+          ? r.obj.wrong
+              .map((a) => ({ a, score: fuzzysort.single(q, a)?.score ?? 0 }))
+              .sort((x, y) => y.score - x.score)[0]?.a
+          : undefined;
+        return alias ? { ...r.obj, matched: alias } : r.obj;
+      }),
+  })).filter((g) => g.items.length > 0);
+}

package/src/lib/standards.ts

@@ -0,0 +1,82 @@
+/**
+ * The baselines a project records (`.mxa/stack.json` `baselines`), as a person
+ * reads them: titled sections, labelled rows, notes as sentences, and nothing
+ * shown for a value nobody has set. One shape, so the page and its markdown agree.
+ */
+
+export interface StandardsSection {
+  key: string;
+  title: string;
+  rows: { label: string; value: string }[];
+  notes: string[];
+}
+
+const TITLES: Record<string, string> = {
+  a11y: "Accessibility",
+  performance: "Performance budgets",
+  support: "Support",
+  seo: "Search and discovery",
+  licences: "Licences allowed",
+  textSize: "Text size",
+  touchTargets: "Touch targets",
+};
+
+const LABELS: Record<string, string> = {
+  browsers: "Browsers",
+  devices: "Devices",
+  viewports: "Viewports",
+  LCP: "Largest contentful paint",
+  CLS: "Cumulative layout shift",
+  TBT: "Total blocking time",
+  INP: "Interaction to next paint",
+  lighthouse: "Lighthouse score",
+  aiCrawlable: "Readable by AI crawlers",
+};
+
+const UNITS: Record<string, string> = { viewports: "px" };
+
+/** `textSize` to "Text size", `aiCrawlable` to "Ai crawlable": a fallback, never as good as a title. */
+export function humanise(key: string): string {
+  const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function shown(key: string, value: unknown): string | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (Array.isArray(value)) return value.length ? value.join(", ") + (UNITS[key] ? ` ${UNITS[key]}` : "") : "not agreed yet";
+  if (typeof value === "object") return undefined;
+  return String(value);
+}
+
+export function standardsSections(baselines: Record<string, unknown>): StandardsSection[] {
+  const keys = Object.keys(baselines).filter((k) => !k.startsWith("$"));
+  // `a11yNotes` is the note on `a11y`, not a section of its own
+  const noteOf = (k: string) => (/Notes?$/.test(k) && keys.includes(k.replace(/Notes?$/, "")) ? k.replace(/Notes?$/, "") : undefined);
+  const out: StandardsSection[] = [];
+  for (const key of keys) {
+    if (noteOf(key)) continue;
+    const value = baselines[key];
+    const section: StandardsSection = { key, title: TITLES[key] ?? humanise(key), rows: [], notes: [] };
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        if (k.startsWith("$")) continue;
+        if (/^notes?$/i.test(k)) {
+          if (typeof v === "string" && v) section.notes.push(v);
+          continue;
+        }
+        const text = shown(k, v);
+        if (text !== undefined) section.rows.push({ label: LABELS[k] ?? humanise(k), value: text });
+      }
+    } else {
+      const text = shown(key, value);
+      if (text !== undefined) section.rows.push({ label: "", value: text });
+    }
+    for (const k of keys) {
+      const v = baselines[k];
+      if (noteOf(k) === key && typeof v === "string" && v) section.notes.push(v);
+    }
+    if (section.rows.length || section.notes.length) out.push(section);
+  }
+  return out;
+}

package/src/lib/status.tsx

@@ -0,0 +1,32 @@
+import { cx } from "./cx";
+
+type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+
+const LOOK: Record<Any, string> = {
+  stable: "bg-success-subdued text-success-subdued-foreground",
+  confirmed: "bg-success-subdued text-success-subdued-foreground",
+  published: "bg-success-subdued text-success-subdued-foreground",
+  emerging: "bg-warning-subdued text-warning-subdued-foreground",
+  assumption: "bg-warning-subdued text-warning-subdued-foreground",
+  // generated from the tokens: a fact, not a decision, so neither settled nor pending
+  measured: "bg-muted text-muted-foreground",
+  draft: "bg-warning-subdued text-warning-subdued-foreground",
+  deprecated: "bg-destructive-subdued text-destructive-subdued-foreground",
+};
+
+/** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
+export function StatusBadge({ status, className }: { status?: Any; className?: string }) {
+  return (
+    <span
+      data-slot="status-badge"
+      data-status={status ?? "unset"}
+      className={cx(
+        "inline-flex h-6 items-center rounded-full px-2.5 text-xs font-medium",
+        status ? LOOK[status] : "border border-dashed border-border text-muted-foreground",
+        className,
+      )}
+    >
+      {status ?? "status not set"}
+    </span>
+  );
+}

package/src/lib/text.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+
+/** JSDoc prose: paragraphs split on blank lines, `code` spans set as code. Nothing else is interpreted. */
+export function Prose({ text, className }: { text: string; className?: string }) {
+  return (
+    <>
+      {text.split(/\n{2,}/).map((p, i) => (
+        <p key={i} className={className}>
+          {inline(p)}
+        </p>
+      ))}
+    </>
+  );
+}
+
+/** One line of prose with its `code` spans. */
+export function inline(text: string): ReactNode[] {
+  return text.split(/(`[^`]+`)/).map((part, i) =>
+    /^`[^`]+`$/.test(part) ? (
+      <code key={i} className="rounded-sm bg-muted px-1 font-mono text-[0.9em]">
+        {part.slice(1, -1)}
+      </code>
+    ) : (
+      part
+    ),
+  );
+}

package/src/lib/ui.tsx

@@ -0,0 +1,291 @@
+"use client";
+
+import { Menu } from "@base-ui/react/menu";
+import { Tabs } from "@base-ui/react/tabs";
+import { Check, ChevronDown, Copy, type LucideIcon } from "lucide-react";
+import { type ComponentProps, type ReactNode, useState } from "react";
+import { cx } from "./cx";
+
+/**
+ * The pieces every block is built from, so the docs read as one thing: the stage a
+ * component is shown on, the frame around a stage, small icon buttons, a segmented
+ * control and a copy button. All drawn from the semantic tokens.
+ */
+
+/**
+ * Where a component is shown: the page's canvas with a faint dot grid, so the
+ * component reads as an object on a surface rather than more page. `theme` renders
+ * it in one mode whatever the page is in; `width` narrows it to a phone.
+ */
+export function Stage({
+  theme,
+  width,
+  className,
+  children,
+  ...props
+}: { theme?: "light" | "dark"; width?: number; className?: string; children: ReactNode } & Omit<ComponentProps<"div">, "className">) {
+  return (
+    <div
+      data-slot="stage"
+      data-docs-stage=""
+      data-theme={theme}
+      className={cx(
+        "relative flex min-w-0 items-center justify-center overflow-auto bg-canvas p-8 text-canvas-foreground sm:p-10",
+        "bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px]",
+        className,
+      )}
+      {...props}
+    >
+      {width ? (
+        <div className="w-full rounded-lg border border-dashed border-border p-4" style={{ maxWidth: width }}>
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  );
+}
+
+/** A rounded card that frames a stage and its toolbar: every example, playground and preview sits in one. */
+export function Frame({ className, children, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="frame"
+      className={cx("flex min-w-0 flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** The bar along the top of a frame. */
+export function Toolbar({ className, children }: { className?: string; children: ReactNode }) {
+  return (
+    <div data-slot="frame-toolbar" className={cx("flex min-h-12 flex-wrap items-center justify-between gap-2 border-b border-border px-2 py-1.5", className)}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * A small icon button: drawn at 32px, pressed at the docs' target size (44px by
+ * default) through a transparent ring, so a toolbar stays tight and every button
+ * is still easy to hit.
+ */
+export function IconButton({
+  icon: Icon,
+  label,
+  pressed,
+  className,
+  ...props
+}: { icon: LucideIcon; label: string; pressed?: boolean } & Omit<ComponentProps<"button">, "children">) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      aria-pressed={pressed}
+      className={cx(
+        "relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+        "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+        "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:bg-muted aria-pressed:text-canvas-foreground",
+        className,
+      )}
+      {...props}
+    >
+      <Icon aria-hidden className="size-(--dt-size-xs)" />
+    </button>
+  );
+}
+
+/** An `IconButton` that goes somewhere: opening an example on its own, a source file. */
+export function IconLink({ icon: Icon, label, className, ...props }: { icon: LucideIcon; label: string } & Omit<ComponentProps<"a">, "children">) {
+  return (
+    <a
+      aria-label={label}
+      title={label}
+      className={cx(
+        "relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+        "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+        "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring",
+        className,
+      )}
+      {...props}
+    >
+      <Icon aria-hidden className="size-(--dt-size-xs)" />
+    </a>
+  );
+}
+
+/** Copies text, and says so: an icon button, or a labelled one with `withLabel`. */
+export function CopyButton({ text, label = "Copy", withLabel, className }: { text: string; label?: string; withLabel?: boolean; className?: string }) {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // clipboard refused (an insecure origin, a denied permission): nothing changes
+    }
+  };
+  return (
+    <>
+      {withLabel ? (
+        <button
+          type="button"
+          onClick={copy}
+          className={cx(
+            "inline-flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-2 rounded-md border border-border bg-surface px-3 text-sm font-medium text-surface-foreground shadow-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+            className,
+          )}
+        >
+          {copied ? <Check aria-hidden className="size-(--dt-size-xs)" /> : <Copy aria-hidden className="size-(--dt-size-xs) text-muted-foreground" />}
+          {copied ? "Copied" : label}
+        </button>
+      ) : (
+        <IconButton icon={copied ? Check : Copy} label={copied ? "Copied" : label} onClick={copy} className={className} />
+      )}
+      <span className="sr-only" aria-live="polite">
+        {copied ? "Copied" : ""}
+      </span>
+    </>
+  );
+}
+
+/**
+ * Two to four views of one thing, as a pill track with the chosen one raised.
+ * Tabs underneath, so arrow keys move between them and each panel is labelled by
+ * its tab. Put a `SegmentedList` where the switch belongs and a `SegmentedPanel`
+ * for each view.
+ */
+export function Segmented({ defaultValue, className, children }: { defaultValue: string; className?: string; children: ReactNode }) {
+  return (
+    <Tabs.Root data-slot="segmented" defaultValue={defaultValue} className={cx("flex min-w-0 flex-col", className)}>
+      {children}
+    </Tabs.Root>
+  );
+}
+
+/** The track of a `Segmented`: put it where the switch belongs, usually a toolbar. */
+export function SegmentedList({ items, label }: { items: { value: string; label: string; icon?: LucideIcon }[]; label: string }) {
+  return (
+    <Tabs.List aria-label={label} data-slot="segmented-list" className="relative flex items-center gap-0.5 rounded-lg border border-border p-0.5">
+      {items.map(({ value, label: text, icon: Icon }) => (
+        <Tabs.Tab
+          key={value}
+          value={value}
+          className={cx(
+            "relative inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+            "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-1.75rem)/2)] after:content-['']",
+            "hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-active:bg-muted data-active:text-canvas-foreground",
+          )}
+        >
+          {Icon && <Icon aria-hidden className="size-(--dt-size-xs)" />}
+          {text}
+        </Tabs.Tab>
+      ))}
+    </Tabs.List>
+  );
+}
+
+export function SegmentedPanel({ value, className, children }: { value: string; className?: string; children: ReactNode }) {
+  return (
+    <Tabs.Panel value={value} className={cx("min-w-0 outline-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring", className)}>
+      {children}
+    </Tabs.Panel>
+  );
+}
+
+/** A small label above a group of controls or a column. */
+export function Eyebrow({ className, children }: { className?: string; children: ReactNode }) {
+  return <p className={cx("text-xs font-medium tracking-wide text-muted-foreground uppercase", className)}>{children}</p>;
+}
+
+/**
+ * A toolbar menu for one setting: the trigger shows an icon and, when the setting
+ * is not at its default, its current value; the menu lists every option with the
+ * chosen one checked. For viewport, background, colour vision and the like.
+ */
+export function ToolbarMenu<T extends string>({
+  icon: Icon,
+  label,
+  value,
+  fallback,
+  options,
+  onChange,
+  swatch,
+}: {
+  icon: LucideIcon;
+  /** What the setting is, for the trigger's name and the menu's heading. */
+  label: string;
+  value: T;
+  /** The default: while chosen, the trigger shows only its icon. */
+  fallback: T;
+  options: { value: T; label: string; note?: string }[];
+  onChange: (value: T) => void;
+  /** A colour to paint beside each option: for backgrounds. */
+  swatch?: (value: T) => string | undefined;
+}) {
+  const current = options.find((o) => o.value === value);
+  const changed = value !== fallback;
+  return (
+    <Menu.Root>
+      <Menu.Trigger
+        aria-label={`${label}: ${current?.label ?? value}`}
+        title={label}
+        className={cx(
+          "relative inline-flex h-8 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+          "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+          "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted data-popup-open:text-canvas-foreground",
+          changed && "bg-muted text-canvas-foreground",
+        )}
+      >
+        {swatch && swatch(value) ? (
+          <span aria-hidden className="size-3.5 rounded-full ring-1 ring-border" style={{ background: swatch(value) }} />
+        ) : (
+          <Icon aria-hidden className="size-(--dt-size-xs)" />
+        )}
+        {changed && <span className="max-w-28 truncate">{current?.label ?? value}</span>}
+        <ChevronDown aria-hidden className="size-3 opacity-60" />
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Positioner data-designtools="" sideOffset={6} align="start" className="z-50">
+          <Menu.Popup className="min-w-56 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0">
+            <Menu.Group>
+              <Menu.GroupLabel className="px-3 pt-1.5 pb-1 text-xs text-muted-foreground">{label}</Menu.GroupLabel>
+              <Menu.RadioGroup value={value} onValueChange={(v) => onChange(v as T)}>
+                {options.map((o) => (
+                  <Menu.RadioItem
+                    key={o.value}
+                    value={o.value}
+                    closeOnClick
+                    className="grid min-h-(--docs-target,2.75rem) cursor-pointer grid-cols-[1rem_1fr] items-center gap-3 rounded-md px-3 text-sm outline-none select-none data-highlighted:bg-muted"
+                  >
+                    <Menu.RadioItemIndicator keepMounted className="flex items-center justify-center data-unchecked:invisible">
+                      <Check aria-hidden className="size-4" />
+                    </Menu.RadioItemIndicator>
+                    <span className="flex items-center gap-2.5">
+                      {swatch?.(o.value) && <span aria-hidden className="size-4 shrink-0 rounded-full ring-1 ring-border" style={{ background: swatch(o.value) }} />}
+                      <span className="flex flex-col">
+                        {o.label}
+                        {o.note && <span className="text-xs text-muted-foreground">{o.note}</span>}
+                      </span>
+                    </span>
+                  </Menu.RadioItem>
+                ))}
+              </Menu.RadioGroup>
+            </Menu.Group>
+          </Menu.Popup>
+        </Menu.Positioner>
+      </Menu.Portal>
+    </Menu.Root>
+  );
+}
+
+/** A thin upright rule between groups of toolbar controls. */
+export function ToolbarDivider() {
+  return <span aria-hidden className="mx-1 h-5 w-px shrink-0 bg-border" />;
+}