@miragon/mcp-toolkit-ui 0.10.1

package/src/theme/create-theme.ts

@@ -0,0 +1,158 @@
+import type { CSSProperties } from "react"
+
+/**
+ * A curated, brand-relevant subset of the toolkit's CSS-variable theming
+ * surface (the full set lives in `packages/ui/src/globals.css`). These are the
+ * tokens a white-label client almost always wants to change — the brand colour
+ * pair, the surface/accent colours, the border/ring, and the shape/typography
+ * knobs — expressed in plain, design-system terms.
+ *
+ * Every field is **optional**: a theme overrides only the tokens it cares about
+ * and inherits the rest from the toolkit defaults (`:root` / `.dark`). Colour
+ * values are any valid CSS colour string (`oklch(...)`, `#rrggbb`, `hsl(...)`),
+ * `radius` is any CSS length (e.g. `"0.5rem"`), and the font fields are CSS
+ * `font-family` lists.
+ *
+ * Unlisted CSS variables (`--popover`, `--chart-*`, `--sidebar-*`, …) are
+ * intentionally out of scope here: they are part of the theming surface but not
+ * the brand essentials, so a client tunes them by hand in CSS when needed. See
+ * {@link TOKEN_TO_CSS_VAR} for the exact field → variable mapping.
+ */
+export interface ThemeTokens {
+  /** Brand colour. Maps to `--primary`. */
+  primary?: string
+  /** Text/icon colour on a `primary` surface. Maps to `--primary-foreground`. */
+  primaryForeground?: string
+  /** Accent colour for subtle highlights. Maps to `--accent`. */
+  accent?: string
+  /** Text colour on an `accent` surface. Maps to `--accent-foreground`. */
+  accentForeground?: string
+  /** App/page background. Maps to `--background`. */
+  background?: string
+  /** Default text colour. Maps to `--foreground`. */
+  foreground?: string
+  /** Card/panel surface. Maps to `--card`. */
+  card?: string
+  /** Text colour on a `card` surface. Maps to `--card-foreground`. */
+  cardForeground?: string
+  /** Border colour for dividers/outlines. Maps to `--border`. */
+  border?: string
+  /** Focus-ring colour. Maps to `--ring`. */
+  ring?: string
+  /** Base corner radius (a CSS length). Maps to `--radius`. */
+  radius?: string
+  /** Body font-family list. Maps to `--font-sans`. */
+  fontSans?: string
+  /** Heading font-family list. Maps to `--font-heading`. */
+  fontHeading?: string
+}
+
+/** The CSS custom-property name a {@link ThemeTokens} field resolves to. */
+type CssVarName = `--${string}`
+
+/**
+ * The single source of truth mapping each curated {@link ThemeTokens} field to
+ * its real CSS variable name from `globals.css`. `tokensToVars` walks this map,
+ * so adding a field here (and to {@link ThemeTokens}) is all that is needed to
+ * extend the public theming surface.
+ */
+export const TOKEN_TO_CSS_VAR = {
+  primary: "--primary",
+  primaryForeground: "--primary-foreground",
+  accent: "--accent",
+  accentForeground: "--accent-foreground",
+  background: "--background",
+  foreground: "--foreground",
+  card: "--card",
+  cardForeground: "--card-foreground",
+  border: "--border",
+  ring: "--ring",
+  radius: "--radius",
+  fontSans: "--font-sans",
+  fontHeading: "--font-heading",
+} as const satisfies Record<keyof ThemeTokens, CssVarName>
+
+/** A serializable map of CSS custom properties (`--primary` → value). */
+export type ThemeVars = Record<CssVarName, string>
+
+/**
+ * A resolved, serializable theme: the CSS variables to apply at light scope,
+ * the optional dark-mode overrides, and a small helper to turn the light vars
+ * into a React `style` object.
+ *
+ * The struct is plain data (no functions on the wire except {@link toStyle},
+ * which is derived from `vars`) so it can be passed to a server component,
+ * logged, or persisted and rehydrated.
+ */
+export interface ThemeDefinition {
+  /** CSS variables applied at the theme scope (overrides `:root`). */
+  vars: ThemeVars
+  /** Dark-mode CSS variables, applied under `.dark` at the theme scope. */
+  darkVars?: ThemeVars
+  /**
+   * The light {@link vars} as a React `style` object (CSS custom properties are
+   * valid `CSSProperties` keys). Handy for inlining onto a wrapper element
+   * without the {@link ThemeProvider}.
+   */
+  toStyle(): CSSProperties
+}
+
+/**
+ * Map a {@link ThemeTokens} object to its CSS variables. Empty/partial token
+ * objects yield only the variables that were set; fields not present in
+ * {@link TOKEN_TO_CSS_VAR} (e.g. an unknown key passed loosely) are ignored.
+ */
+export function tokensToVars(tokens: ThemeTokens): ThemeVars {
+  const vars: ThemeVars = {}
+  for (const [field, cssVar] of Object.entries(TOKEN_TO_CSS_VAR) as [
+    keyof ThemeTokens,
+    CssVarName,
+  ][]) {
+    const value = tokens[field]
+    if (typeof value === "string" && value.length > 0) {
+      vars[cssVar] = value
+    }
+  }
+  return vars
+}
+
+/** Options for {@link createTheme}. */
+export interface CreateThemeOptions {
+  /**
+   * Dark-mode token overrides. Applied on top of the toolkit's `.dark` defaults
+   * when the active mode is dark (see {@link ThemeProvider}). Provide only the
+   * tokens that differ from light — typically a darker `background`/`card` and a
+   * brighter `primary`.
+   */
+  dark?: ThemeTokens
+}
+
+/**
+ * Build a serializable {@link ThemeDefinition} from a curated set of brand
+ * {@link ThemeTokens}. This is the one switch a white-label client flips: pass
+ * your brand's primary colour, radius, and (optionally) dark overrides, and
+ * every toolkit primitive that reads the design tokens — `Card`, `Button`,
+ * `Badge`, `bg-card`, `text-primary`, `rounded-lg` — re-skins to match.
+ *
+ * Pure and side-effect-free: it only maps fields to CSS-variable names. Apply
+ * the result with {@link ThemeProvider} (recommended) or by spreading
+ * `theme.toStyle()` onto a wrapper element.
+ *
+ * @example
+ * const brand = createTheme(
+ *   { primary: "oklch(0.55 0.2 264)", radius: "0.5rem" },
+ *   { dark: { primary: "oklch(0.7 0.18 264)" } },
+ * )
+ * // <ThemeProvider theme={brand}>…</ThemeProvider>
+ */
+export function createTheme(tokens: ThemeTokens, opts?: CreateThemeOptions): ThemeDefinition {
+  const vars = tokensToVars(tokens)
+  const darkTokens = opts?.dark
+  const darkVars = darkTokens ? tokensToVars(darkTokens) : undefined
+
+  return {
+    vars,
+    ...(darkVars && Object.keys(darkVars).length > 0 ? { darkVars } : {}),
+    toStyle: () => vars,
+  }
+}

package/src/theme/index.ts

@@ -0,0 +1,9 @@
+// White-label theming. Browser-safe (React + DOM only, no `mcp-use/react`), so
+// it is re-exported from the root barrel — a consumer can theme the toolkit's
+// primitives without pulling in the host runtime.
+export { createTheme, tokensToVars, TOKEN_TO_CSS_VAR } from "./create-theme.js"
+export type { ThemeTokens, ThemeDefinition, ThemeVars, CreateThemeOptions } from "./create-theme.js"
+export { ThemeProvider, useTheme } from "./theme-provider.js"
+export type { ThemeMode, ThemeContextValue, ThemeProviderProps } from "./theme-provider.js"
+export { themePresets } from "./presets.js"
+export type { ThemePresetId } from "./presets.js"

package/src/theme/presets.ts

@@ -0,0 +1,82 @@
+import { createTheme, type ThemeDefinition } from "./create-theme.js"
+
+/**
+ * Ready-made white-label themes — a demonstration of {@link createTheme} and a
+ * starting point a client can fork. Each preset sets a distinct brand `primary`,
+ * a matching `ring`/`accent`, and a `radius`, plus a `dark` override that
+ * brightens the brand colour for legibility on dark surfaces (mirroring how
+ * `globals.css` brightens tokens under `.dark`).
+ *
+ * Colours are authored in `oklch` to stay consistent with the toolkit's token
+ * palette in `globals.css`. Apply one with `<ThemeProvider theme={themePresets.violet}>`.
+ */
+export const themePresets = {
+  /**
+   * The toolkit's own brand: a confident indigo-blue with a slightly tighter
+   * radius. A sensible default when a client has no brand of their own yet.
+   */
+  miragon: createTheme(
+    {
+      primary: "oklch(0.52 0.21 264)",
+      primaryForeground: "oklch(0.985 0 0)",
+      accent: "oklch(0.95 0.03 264)",
+      accentForeground: "oklch(0.32 0.12 264)",
+      ring: "oklch(0.52 0.21 264)",
+      radius: "0.5rem",
+    },
+    {
+      dark: {
+        primary: "oklch(0.7 0.16 264)",
+        primaryForeground: "oklch(0.18 0.02 264)",
+        accent: "oklch(0.32 0.06 264)",
+        accentForeground: "oklch(0.97 0 0)",
+        ring: "oklch(0.7 0.16 264)",
+      },
+    },
+  ),
+
+  /** A vivid violet brand with rounder corners — playful, consumer-facing. */
+  violet: createTheme(
+    {
+      primary: "oklch(0.55 0.24 295)",
+      primaryForeground: "oklch(0.985 0 0)",
+      accent: "oklch(0.95 0.04 295)",
+      accentForeground: "oklch(0.34 0.14 295)",
+      ring: "oklch(0.55 0.24 295)",
+      radius: "0.875rem",
+    },
+    {
+      dark: {
+        primary: "oklch(0.72 0.18 295)",
+        primaryForeground: "oklch(0.18 0.03 295)",
+        accent: "oklch(0.33 0.08 295)",
+        accentForeground: "oklch(0.97 0 0)",
+        ring: "oklch(0.72 0.18 295)",
+      },
+    },
+  ),
+
+  /** A grounded emerald brand with a crisp, near-square radius — enterprise. */
+  emerald: createTheme(
+    {
+      primary: "oklch(0.58 0.15 162)",
+      primaryForeground: "oklch(0.985 0 0)",
+      accent: "oklch(0.95 0.04 162)",
+      accentForeground: "oklch(0.34 0.1 162)",
+      ring: "oklch(0.58 0.15 162)",
+      radius: "0.375rem",
+    },
+    {
+      dark: {
+        primary: "oklch(0.72 0.15 162)",
+        primaryForeground: "oklch(0.17 0.03 162)",
+        accent: "oklch(0.32 0.07 162)",
+        accentForeground: "oklch(0.97 0 0)",
+        ring: "oklch(0.72 0.15 162)",
+      },
+    },
+  ),
+} satisfies Record<string, ThemeDefinition>
+
+/** The id of a built-in preset in {@link themePresets}. */
+export type ThemePresetId = keyof typeof themePresets

package/src/theme/theme-provider.tsx

@@ -0,0 +1,152 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react"
+import type { ThemeDefinition } from "./create-theme.js"
+
+/**
+ * How the `.dark` class is resolved on the theme scope:
+ * - `"light"` / `"dark"` — forced, ignores the OS preference.
+ * - `"system"` — follows `prefers-color-scheme` via `matchMedia`, updating live.
+ *
+ * A host that already knows the colour scheme (e.g. `HostBridge.theme`) can pass
+ * its value straight through as `mode` so the white-label theme tracks the host.
+ */
+export type ThemeMode = "light" | "dark" | "system"
+
+/** The value exposed by {@link useTheme}. */
+export interface ThemeContextValue {
+  /** The active theme definition, or `null` when only a mode is being managed. */
+  theme: ThemeDefinition | null
+  /** The mode as requested on the provider (may be `"system"`). */
+  mode: ThemeMode
+  /** The mode actually applied right now (`"system"` resolved to light/dark). */
+  resolvedMode: "light" | "dark"
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+/**
+ * Read the active theme/mode from the nearest {@link ThemeProvider}. Throws when
+ * called outside a provider so a missing wrapper fails loudly rather than
+ * silently rendering the default theme.
+ */
+export function useTheme(): ThemeContextValue {
+  const value = useContext(ThemeContext)
+  if (!value) {
+    throw new Error("useTheme() must be used within a <ThemeProvider>.")
+  }
+  return value
+}
+
+/**
+ * Resolve `"system"` to a concrete `"light"` | `"dark"` and keep it in sync with
+ * the OS preference. SSR-safe: returns `"light"` until mounted (no `window`),
+ * then subscribes to `matchMedia` on the client. Forced modes short-circuit the
+ * media query entirely.
+ */
+function useResolvedMode(mode: ThemeMode): "light" | "dark" {
+  const [systemMode, setSystemMode] = useState<"light" | "dark">("light")
+
+  useEffect(() => {
+    if (mode !== "system") return
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return
+
+    const query = window.matchMedia("(prefers-color-scheme: dark)")
+    const sync = () => {
+      setSystemMode(query.matches ? "dark" : "light")
+    }
+    sync()
+    query.addEventListener("change", sync)
+    return () => {
+      query.removeEventListener("change", sync)
+    }
+  }, [mode])
+
+  return mode === "system" ? systemMode : mode
+}
+
+/** Props for {@link ThemeProvider}. */
+export interface ThemeProviderProps {
+  /**
+   * The white-label theme to apply (from {@link createTheme} or `themePresets`).
+   * Omit to manage only the light/dark `mode` against the toolkit defaults.
+   */
+  theme?: ThemeDefinition
+  /**
+   * Colour-scheme mode. Defaults to `"light"`. Pass `HostBridge.theme` through
+   * here to follow the host, or `"system"` to track the OS preference.
+   */
+  mode?: ThemeMode
+  /**
+   * The HTML element to render as the scope wrapper. Defaults to `"div"`. Use
+   * `"span"` for inline contexts; any intrinsic element with a `style`/className
+   * works.
+   */
+  as?: "div" | "span" | "section" | "main"
+  /** Extra classes merged onto the scope wrapper. */
+  className?: string
+  children: ReactNode
+}
+
+/**
+ * Apply a white-label {@link ThemeDefinition} to a subtree. Renders a wrapper
+ * element carrying the theme's CSS variables as inline `style`, so they override
+ * the `:root` defaults for every descendant — `Card`, `Button`, `bg-card`,
+ * `text-primary`, and `rounded-lg` all re-skin without touching the widgets.
+ *
+ * Dark mode is handled at the scope: the `.dark` class is toggled on the wrapper
+ * (not `<html>`) per the resolved {@link ThemeMode}, and the theme's `darkVars`
+ * are layered on under it. This keeps theming local — two differently themed
+ * subtrees (e.g. a brand preview gallery) coexist on one page.
+ *
+ * Uses only React + the DOM (no `mcp-use/react`), so it ships from the root
+ * barrel and works in a host-free standalone app, a host, or SSR alike.
+ *
+ * @example
+ * <ThemeProvider theme={themePresets.violet} mode={host.theme ?? "system"}>
+ *   <YourWidget />
+ * </ThemeProvider>
+ */
+export function ThemeProvider({
+  theme,
+  mode = "light",
+  as: As = "div",
+  className,
+  children,
+}: ThemeProviderProps): ReactNode {
+  const resolvedMode = useResolvedMode(mode)
+  const isDark = resolvedMode === "dark"
+
+  // Merge the light vars with the dark overrides only when dark is active, so a
+  // dark scope gets the brand's dark palette on top of `.dark`'s defaults.
+  const style = useMemo<CSSProperties>(() => {
+    if (!theme) return {}
+    if (isDark && theme.darkVars) {
+      return { ...theme.vars, ...theme.darkVars }
+    }
+    return theme.vars
+  }, [theme, isDark])
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ theme: theme ?? null, mode, resolvedMode }),
+    [theme, mode, resolvedMode],
+  )
+
+  const classes = [isDark ? "dark" : undefined, "bg-background text-foreground", className]
+    .filter(Boolean)
+    .join(" ")
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <As className={classes} style={style} data-theme-mode={resolvedMode}>
+        {children}
+      </As>
+    </ThemeContext.Provider>
+  )
+}

package/src/ui-catalog.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest"
+import catalog from "../ui-catalog.json" with { type: "json" }
+import * as rootBarrel from "./index.js"
+import * as appBarrel from "./app/index.js"
+import * as hooksBarrel from "./hooks/index.js"
+
+/**
+ * Drift guard for `packages/ui/ui-catalog.json` — the machine-readable catalog
+ * the docs (`docs/reference/components.md`) and the `build-mcp-widget` skill
+ * point an on-top-prompting agent at. The catalog is hand-maintained (the
+ * curated `whenToUse`/prop descriptions are the LLM-facing value), so these
+ * tests pin it to the real package surface: every entry must name a symbol that
+ * is actually exported from the `importPath` it claims. A rename or moved export
+ * fails here instead of silently feeding an agent a dead import.
+ */
+
+interface CatalogProp {
+  name: string
+  type: string
+  required: boolean
+  description: string
+}
+
+interface CatalogEntry {
+  name: string
+  export: string
+  importPath: string
+  kind: string
+  group: string
+  parts?: string[]
+  props: CatalogProp[]
+  whenToUse: string
+}
+
+interface Catalog {
+  importPaths: Record<"root" | "app" | "hooks", string>
+  components: CatalogEntry[]
+}
+
+// Imported as a JSON module (not read via `node:fs`) so this browser-oriented
+// package keeps typechecking without `@types/node`. The `as unknown as Catalog`
+// cast pins the structural contract the assertions below rely on.
+const catalogData = catalog as unknown as Catalog
+
+/** Map each `importPath` to the live module namespace it must resolve through. */
+const BARRELS: Record<string, Record<string, unknown>> = {
+  [catalogData.importPaths.root]: rootBarrel,
+  [catalogData.importPaths.app]: appBarrel,
+  [catalogData.importPaths.hooks]: hooksBarrel,
+}
+
+describe("ui-catalog.json", () => {
+  it("declares the three real subpath imports", () => {
+    expect(catalogData.importPaths).toEqual({
+      root: "@miragon/mcp-toolkit-ui",
+      app: "@miragon/mcp-toolkit-ui/app",
+      hooks: "@miragon/mcp-toolkit-ui/hooks",
+    })
+  })
+
+  it("has unique entry names", () => {
+    const names = catalogData.components.map((c) => c.name)
+    expect(new Set(names).size).toBe(names.length)
+  })
+
+  it("references only the three known import paths", () => {
+    const known = new Set(Object.values(catalogData.importPaths))
+    for (const entry of catalogData.components) {
+      expect(known, `${entry.name} → ${entry.importPath}`).toContain(entry.importPath)
+    }
+  })
+
+  describe("every entry's `export` is reachable from its `importPath`", () => {
+    for (const entry of catalogData.components) {
+      it(`${entry.name} is exported from ${entry.importPath}`, () => {
+        const barrel = BARRELS[entry.importPath]
+        expect(barrel, `no barrel for ${entry.importPath}`).toBeDefined()
+        // Types (e.g. DescribeForModel) erase at runtime, so they can't be probed
+        // on the namespace object — assert only value exports here. Type exports
+        // are guarded by the package's own typecheck (the barrels re-export them).
+        if (entry.kind === "type") return
+        expect(
+          Object.prototype.hasOwnProperty.call(barrel, entry.export),
+          `${entry.export} missing from ${entry.importPath}`,
+        ).toBe(true)
+      })
+    }
+  })
+
+  it("keeps every multi-part component's parts exported from the same barrel", () => {
+    for (const entry of catalogData.components) {
+      if (!entry.parts) continue
+      const barrel = BARRELS[entry.importPath]
+      for (const part of entry.parts) {
+        expect(
+          Object.prototype.hasOwnProperty.call(barrel, part),
+          `${entry.name} part ${part} missing from ${entry.importPath}`,
+        ).toBe(true)
+      }
+    }
+  })
+
+  it("gives every entry at least a name, kind, group and whenToUse", () => {
+    for (const entry of catalogData.components) {
+      expect(entry.name, "name").toBeTruthy()
+      expect(entry.kind, `${entry.name} kind`).toBeTruthy()
+      expect(entry.group, `${entry.name} group`).toBeTruthy()
+      expect(entry.whenToUse, `${entry.name} whenToUse`).toBeTruthy()
+      expect(Array.isArray(entry.props), `${entry.name} props`).toBe(true)
+    }
+  })
+})