@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/theme/host-fonts.test.ts

@@ -0,0 +1,135 @@
+/// <reference types="node" />
+import { readFileSync } from "node:fs"
+import { describe, expect, it } from "vitest"
+import {
+  adoptHostFontVariables,
+  HOST_FONT_VARIABLES,
+  type InlineStyleTarget,
+} from "./host-fonts.js"
+
+/** `element.style` as a map: the inline custom properties of one element. */
+function inlineStyle(initial: Record<string, string> = {}): InlineStyleTarget & {
+  props: Map<string, string>
+} {
+  const props = new Map(Object.entries(initial))
+  return {
+    props,
+    getPropertyValue: (name) => props.get(name) ?? "",
+    setProperty: (name, value) => void props.set(name, value),
+    removeProperty: (name) => {
+      const old = props.get(name) ?? ""
+      props.delete(name)
+      return old
+    },
+  }
+}
+
+/** What mcp-use's ThemeProvider does with the host's style variables (ext-apps applyHostStyleVariables). */
+function applyHostStyleVariables(
+  style: InlineStyleTarget,
+  variables: Record<string, string | undefined>,
+): void {
+  for (const [name, value] of Object.entries(variables)) {
+    if (value !== undefined) style.setProperty(name, value)
+  }
+}
+
+const rootRole = (name: string): string => {
+  const css = readFileSync(new URL("../theme.css", import.meta.url), "utf8").replace(
+    /\/\*[\s\S]*?\*\//g,
+    "",
+  )
+  const root = /(?:^|\})\s*:root\s*\{([^{}]*)\}/.exec(css)?.[1] ?? ""
+  const decl = new RegExp(`${name}:([^;]+);`).exec(root)?.[1]
+  if (!decl) throw new Error(`theme.css :root has no ${name}`)
+  return decl.replace(/\s+/g, " ").trim()
+}
+
+/**
+ * The font stack <html> renders with: an inline value of the role wins over
+ * theme.css; otherwise the `:root` stack with `var(--host-font-*, fallback)`
+ * resolved against the inline style.
+ */
+function renderedStack(style: InlineStyleTarget, role: "--font-sans" | "--font-mono"): string {
+  const inline = style.getPropertyValue(role)
+  if (inline) return inline
+  return rootRole(role).replace(
+    /var\((--host-font-[a-z]+), ([^)]+)\)/,
+    (_all, slot: string, fallback: string) => style.getPropertyValue(slot) || fallback,
+  )
+}
+
+describe("adoptHostFontVariables (host font → fallback slot)", () => {
+  const HOST = { "--font-sans": '"Anthropic Sans", system-ui', "--font-mono": '"Host Mono"' }
+
+  it("keeps Geist first when a SEP-1865 host sends --font-sans/--font-mono", () => {
+    const html = inlineStyle()
+    applyHostStyleVariables(html, HOST)
+    // Without the toolkit's step the host replaces the whole stack:
+    expect(renderedStack(html, "--font-sans")).toBe('"Anthropic Sans", system-ui')
+    adoptHostFontVariables(html, HOST)
+    expect(renderedStack(html, "--font-sans")).toBe(
+      '"Geist", "Geist Variable", "Anthropic Sans", system-ui, system-ui, sans-serif',
+    )
+    expect(renderedStack(html, "--font-mono")).toBe(
+      '"Geist Mono", "Geist Mono Variable", "Host Mono", SFMono-Regular, Menlo, Consolas, monospace',
+    )
+  })
+
+  it("moves the host's values into the --host-font-* slots and clears the roles", () => {
+    const html = inlineStyle()
+    applyHostStyleVariables(html, HOST)
+    adoptHostFontVariables(html, HOST)
+    expect(Object.fromEntries(html.props)).toEqual({
+      "--host-font-sans": '"Anthropic Sans", system-ui',
+      "--host-font-mono": '"Host Mono"',
+    })
+  })
+
+  it("leaves an app's own inline brand font on the role alone", () => {
+    const html = inlineStyle({ "--font-sans": "Inter, sans-serif" })
+    adoptHostFontVariables(html, { "--font-sans": "HostSans" })
+    expect(html.props.get("--font-sans")).toBe("Inter, sans-serif")
+    expect(html.props.get("--host-font-sans")).toBe("HostSans")
+  })
+
+  it("compares the host's value and the inline role without surrounding whitespace", () => {
+    const html = inlineStyle({ "--font-sans": " HostSans " })
+    adoptHostFontVariables(html, { "--font-sans": "HostSans\n" })
+    expect(Object.fromEntries(html.props)).toEqual({ "--host-font-sans": "HostSans" })
+  })
+
+  it("is a no-op without host variables or with empty font values", () => {
+    const html = inlineStyle({ "--font-sans": "X" })
+    adoptHostFontVariables(html, undefined)
+    adoptHostFontVariables(html, null)
+    adoptHostFontVariables(html, { "--font-sans": "  ", "--font-mono": undefined })
+    expect(Object.fromEntries(html.props)).toEqual({ "--font-sans": "X" })
+    expect(renderedStack(inlineStyle(), "--font-sans")).toBe(
+      '"Geist", "Geist Variable", ui-sans-serif, system-ui, sans-serif',
+    )
+  })
+
+  it("is idempotent (mcp-use re-applies on every host-context update)", () => {
+    const html = inlineStyle()
+    for (let i = 0; i < 2; i++) {
+      applyHostStyleVariables(html, HOST)
+      adoptHostFontVariables(html, HOST)
+    }
+    expect(html.props.has("--font-sans")).toBe(false)
+    expect(html.props.get("--host-font-sans")).toBe('"Anthropic Sans", system-ui')
+  })
+
+  it("names exactly the two SEP-1865 font variables", () => {
+    expect(HOST_FONT_VARIABLES).toEqual({
+      "--font-sans": "--host-font-sans",
+      "--font-mono": "--host-font-mono",
+    })
+  })
+
+  it("is wired ABOVE mcp-use's ThemeProvider in McpToolkitApp (its layout effect runs after)", () => {
+    const app = readFileSync(new URL("../app/mcp-toolkit-app.tsx", import.meta.url), "utf8")
+    expect(app).toMatch(/adoptHostFontVariables\(document\.documentElement\.style,/)
+    expect(app).toMatch(/<HostFontRoles>\s*<ThemeProvider>/)
+  })
+})

package/src/theme/host-fonts.ts

@@ -0,0 +1,52 @@
+/**
+ * The host's font, demoted to the fallback slot of the font roles.
+ *
+ * SEP-1865 hosts send their fonts as the style variables `--font-sans` and
+ * `--font-mono`, the same names as the toolkit's font roles. mcp-use writes
+ * them inline on `<html>`, where they beat the role stacks in `theme.css` and
+ * replace them whole, so Geist never renders even when it is loaded. The
+ * toolkit's rule is Geist first, the host's font next, the system stack last:
+ * {@link adoptHostFontVariables} moves the host's value to
+ * `--host-font-sans` / `--host-font-mono`, which the role stacks name right
+ * after Geist. `McpToolkitApp` runs it after every host-context update; an app
+ * with its own document layer calls it after it applied the host variables.
+ */
+
+/** Each host font variable (SEP-1865 name) → where the toolkit keeps it. */
+export const HOST_FONT_VARIABLES = {
+  "--font-sans": "--host-font-sans",
+  "--font-mono": "--host-font-mono",
+} as const
+
+/** The slice of `CSSStyleDeclaration` the helper touches (`element.style`). */
+export interface InlineStyleTarget {
+  getPropertyValue(property: string): string
+  setProperty(property: string, value: string): void
+  removeProperty(property: string): string
+}
+
+/**
+ * Move the host's font variables off the role names on `style` (normally
+ * `document.documentElement.style`, where the host variables were applied):
+ * each non-empty `--font-sans` / `--font-mono` in `hostVariables` is written
+ * to its {@link HOST_FONT_VARIABLES} slot, and the role is cleared when it
+ * still holds exactly the host's value — an app's own inline brand font
+ * stays. Idempotent; a no-op without host variables.
+ *
+ * @example
+ * applyHostStyleVariables(vars) // the host layer writes --font-sans on <html>
+ * adoptHostFontVariables(document.documentElement.style, vars)
+ * // --font-sans: "Geist", "Geist Variable", <host font>, system-ui, sans-serif
+ */
+export function adoptHostFontVariables(
+  style: InlineStyleTarget,
+  hostVariables: Readonly<Record<string, string | undefined>> | null | undefined,
+): void {
+  if (!hostVariables) return
+  for (const [role, slot] of Object.entries(HOST_FONT_VARIABLES)) {
+    const value = hostVariables[role]?.trim()
+    if (!value) continue
+    style.setProperty(slot, value)
+    if (style.getPropertyValue(role).trim() === value) style.removeProperty(role)
+  }
+}

package/src/theme/index.ts

@@ -1,9 +1,23 @@
 // 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 {
+  createTheme,
+  tokensToVars,
+  resolveThemeVars,
+  TOKEN_TO_CSS_VAR,
+  ROLE_TOKENS,
+  MODE_INVARIANT_VARS,
+} 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 { usePortalContainer } from "./portal-container.js"
 export { themePresets } from "./presets.js"
 export type { ThemePresetId } from "./presets.js"
+export { CD_TOKENS, CD_TOKENS_VERSION } from "./cd-tokens.js"
+export type { CdTokenName } from "./cd-tokens.js"
+export { fontFaces, GEIST_FONT_FILES } from "./fonts.js"
+export type { FontFacesOptions } from "./fonts.js"
+export { adoptHostFontVariables, HOST_FONT_VARIABLES } from "./host-fonts.js"
+export type { InlineStyleTarget } from "./host-fonts.js"

package/src/theme/portal-container.ts

@@ -0,0 +1,20 @@
+import { createContext, useContext } from "react"
+
+/**
+ * The element portaled overlays (Dialog, Sheet, Select) render into. A
+ * {@link ThemeProvider} provides a node INSIDE its scope, so overlays opened
+ * from a themed subtree keep the theme's variables and its light/dark mode
+ * instead of falling back to `document.body` and the `:root` defaults
+ * (mcp-toolkit#178 N36). `null` — no provider, or before it mounted — means
+ * the overlay library's default (`document.body`).
+ */
+export const PortalContainerContext = createContext<HTMLElement | null>(null)
+
+/**
+ * The portal container of the nearest {@link ThemeProvider}, or `null`. Pass it
+ * as `container` to a portal of your own so it stays inside the theme scope;
+ * the toolkit's Dialog, Sheet and Select already do.
+ */
+export function usePortalContainer(): HTMLElement | null {
+  return useContext(PortalContainerContext)
+}

package/src/theme/presets.ts

@@ -2,23 +2,35 @@ 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`).
+ * starting point a client can fork. Each preset sets its whole interactive
+ * family from one brand hue, in light AND dark: `primary` with its
+ * `primaryForeground` and `primaryHover`, `link`, `focus` (plus the legacy
+ * `ring`), a matching `accent`, and a `radius`. The dark side brightens the
+ * brand colour for legibility on dark surfaces. Every preset meets the same
+ * contrast bar as the default theme in both modes (`theme-css.test.ts`).
  *
- * Colours are authored in `oklch` to stay consistent with the toolkit's token
- * palette in `globals.css`. Apply one with `<ThemeProvider theme={themePresets.violet}>`.
+ * The toolkit's DEFAULT is the Miragon theme (theme.css, built on the vendored
+ * corporate-design tokens); it needs no preset. A full customer brand may set
+ * more roles than these presets do (the status `*Ink` colours); see
+ * docs/guides/white-labeling.md. Apply one with
+ * `<ThemeProvider theme={themePresets.emerald}>`.
  */
 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.
+   * An approximation of the Miragon blue from before the toolkit shipped the
+   * Miragon corporate design.
+   *
+   * @deprecated The Miragon theme is now the toolkit's default: render without
+   * a theme (or `<ThemeProvider>` without `theme`) to get the exact CI values.
+   * This preset is off-palette and will be removed in the next major.
    */
   miragon: createTheme(
     {
       primary: "oklch(0.52 0.21 264)",
       primaryForeground: "oklch(0.985 0 0)",
+      primaryHover: "oklch(0.46 0.2 264)",
+      link: "oklch(0.52 0.21 264)",
+      focus: "oklch(0.52 0.21 264)",
       accent: "oklch(0.95 0.03 264)",
       accentForeground: "oklch(0.32 0.12 264)",
       ring: "oklch(0.52 0.21 264)",
@@ -28,6 +40,9 @@ export const themePresets = {
       dark: {
         primary: "oklch(0.7 0.16 264)",
         primaryForeground: "oklch(0.18 0.02 264)",
+        primaryHover: "oklch(0.76 0.13 264)",
+        link: "oklch(0.7 0.16 264)",
+        focus: "oklch(0.7 0.16 264)",
         accent: "oklch(0.32 0.06 264)",
         accentForeground: "oklch(0.97 0 0)",
         ring: "oklch(0.7 0.16 264)",
@@ -35,11 +50,20 @@ export const themePresets = {
     },
   ),
 
-  /** A vivid violet brand with rounder corners — playful, consumer-facing. */
+  /**
+   * A vivid violet brand with rounder corners — playful, consumer-facing.
+   *
+   * @deprecated The violet tech default is the look the Miragon design system
+   * rules out (anti-slop U9). Fork {@link createTheme} with your own brand
+   * values instead. Will be removed in the next major.
+   */
   violet: createTheme(
     {
       primary: "oklch(0.55 0.24 295)",
       primaryForeground: "oklch(0.985 0 0)",
+      primaryHover: "oklch(0.49 0.23 295)",
+      link: "oklch(0.55 0.24 295)",
+      focus: "oklch(0.55 0.24 295)",
       accent: "oklch(0.95 0.04 295)",
       accentForeground: "oklch(0.34 0.14 295)",
       ring: "oklch(0.55 0.24 295)",
@@ -49,6 +73,9 @@ export const themePresets = {
       dark: {
         primary: "oklch(0.72 0.18 295)",
         primaryForeground: "oklch(0.18 0.03 295)",
+        primaryHover: "oklch(0.78 0.15 295)",
+        link: "oklch(0.72 0.18 295)",
+        focus: "oklch(0.72 0.18 295)",
         accent: "oklch(0.33 0.08 295)",
         accentForeground: "oklch(0.97 0 0)",
         ring: "oklch(0.72 0.18 295)",
@@ -59,17 +86,23 @@ export const themePresets = {
   /** A grounded emerald brand with a crisp, near-square radius — enterprise. */
   emerald: createTheme(
     {
-      primary: "oklch(0.58 0.15 162)",
+      primary: "oklch(0.5 0.12 162)",
       primaryForeground: "oklch(0.985 0 0)",
+      primaryHover: "oklch(0.44 0.11 162)",
+      link: "oklch(0.5 0.12 162)",
+      focus: "oklch(0.5 0.12 162)",
       accent: "oklch(0.95 0.04 162)",
       accentForeground: "oklch(0.34 0.1 162)",
-      ring: "oklch(0.58 0.15 162)",
+      ring: "oklch(0.5 0.12 162)",
       radius: "0.375rem",
     },
     {
       dark: {
         primary: "oklch(0.72 0.15 162)",
         primaryForeground: "oklch(0.17 0.03 162)",
+        primaryHover: "oklch(0.78 0.14 162)",
+        link: "oklch(0.72 0.15 162)",
+        focus: "oklch(0.72 0.15 162)",
         accent: "oklch(0.32 0.07 162)",
         accentForeground: "oklch(0.97 0 0)",
         ring: "oklch(0.72 0.15 162)",