@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/providers/query-provider.tsx

@@ -1,5 +1,6 @@
-import { createContext, useContext, type ReactNode } from "react"
+import { createContext, useContext, useMemo, type ReactNode } from "react"
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { useHostBridgeOrNull } from "../app/host-bridge.js"
 
 // `object` (not `Record<string, unknown>`) because generated tool input
 // interfaces lack an implicit index signature and TS rejects the assignment
@@ -8,6 +9,9 @@ type CallToolFn = (name: string, args: object) => Promise<unknown>
 
 const CallToolContext = createContext<CallToolFn | undefined>(undefined)
 
+/** Whether the data hooks put the tool name into their cache keys (`toolQueryKey`). */
+const ToolNameInQueryKeyContext = createContext(false)
+
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
@@ -17,22 +21,79 @@ const queryClient = new QueryClient({
   },
 })
 
+/** The client of the nearest `AppQueryProvider`, which a nested one without `client` keeps. */
+const AppQueryClientContext = createContext<QueryClient>(queryClient)
+
+/**
+ * The query client and tool transport of the toolkit's data hooks.
+ *
+ * `callTool` is how `useToolQuery` & co. reach the server; without it they
+ * fall back to the nearest `HostBridgeProvider`'s bridge (toolkit#176 N25).
+ * `client` replaces the shared module-level client, e.g. one per mount;
+ * omitted, a nested provider keeps its parent's client (as `McpAppView`'s
+ * own provider does), and the outermost one shares the toolkit's client
+ * (`queryClient`). `toolNameInQueryKey` puts the tool name into the hooks'
+ * cache keys (`[...queryKey, toolName, args]`, see `toolQueryKey`), so two
+ * tools never share an entry; omitted, a nested provider keeps its parent's
+ * setting, and the outermost one uses the 2.x key `[...queryKey, args]`. The
+ * next major makes the tool name the default.
+ */
 export function AppQueryProvider({
   children,
   callTool,
+  client,
+  toolNameInQueryKey,
 }: {
   children: ReactNode
   callTool?: CallToolFn
+  client?: QueryClient
+  toolNameInQueryKey?: boolean
 }) {
+  const inheritedClient = useAppQueryClient()
+  const inherited = useContext(ToolNameInQueryKeyContext)
+  const effective = client ?? inheritedClient
   return (
-    <QueryClientProvider client={queryClient}>
-      <CallToolContext.Provider value={callTool}>{children}</CallToolContext.Provider>
-    </QueryClientProvider>
+    <AppQueryClientContext.Provider value={effective}>
+      <QueryClientProvider client={effective}>
+        <CallToolContext.Provider value={callTool}>
+          <ToolNameInQueryKeyContext.Provider value={toolNameInQueryKey ?? inherited}>
+            {children}
+          </ToolNameInQueryKeyContext.Provider>
+        </CallToolContext.Provider>
+      </QueryClientProvider>
+    </AppQueryClientContext.Provider>
   )
 }
 
+/**
+ * The client an `AppQueryProvider` without `client` uses at this point: the
+ * nearest `AppQueryProvider`'s, else the toolkit's shared `queryClient`. A
+ * plain TanStack `QueryClientProvider` does not count.
+ */
+export function useAppQueryClient(): QueryClient {
+  return useContext(AppQueryClientContext)
+}
+
+/**
+ * Whether the nearest `AppQueryProvider` puts the tool name into the data
+ * hooks' cache keys (`toolNameInQueryKey`); `false` outside one.
+ */
+export function useToolNameInQueryKey(): boolean {
+  return useContext(ToolNameInQueryKeyContext)
+}
+
+/**
+ * The tool transport of the data hooks: `AppQueryProvider`'s `callTool`,
+ * else the nearest `HostBridgeProvider`'s `callTool`, else `undefined`.
+ */
 export function useCallTool(): CallToolFn | undefined {
-  return useContext(CallToolContext)
+  const explicit = useContext(CallToolContext)
+  const bridge = useHostBridgeOrNull()
+  return useMemo<CallToolFn | undefined>(() => {
+    if (explicit) return explicit
+    if (!bridge) return undefined
+    return (name, args) => bridge.callTool(name, args as Record<string, unknown>)
+  }, [explicit, bridge])
 }
 
 export { queryClient }

package/src/render-cases-primitives.tsx

@@ -226,7 +226,7 @@ export const PRIMITIVE_RENDER_CASES: RenderCase[] = [
     name: "Alert",
     marker: "RC:Alert",
     render: () => (
-      <Alert variant="destructive">
+      <Alert variant="danger">
         <AlertTitle>RC:Alert</AlertTitle>
         <AlertDescription>The engine rejected the job.</AlertDescription>
       </Alert>

package/src/render-cases.tsx

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react"
-import { Inbox } from "lucide-react"
+import { ExternalLink, Inbox } from "lucide-react"
 import {
   Button,
   CountPill,
@@ -11,10 +11,13 @@ import {
   GridLayout,
   GroupCard,
   KpiGrid,
+  KpiGridSkeleton,
   ListFooter,
   LivePill,
   LocaleProvider,
+  PagedListFooter,
   SectionHeading,
+  StatusBadge,
   ThemeProvider,
   themePresets,
   ToastProvider,
@@ -22,7 +25,7 @@ import {
   WidgetHeader,
 } from "./index.js"
 import { createStandaloneHostBridge, HostBridgeProvider, useHostBridge } from "./app/host-bridge.js"
-import { HostModelContext } from "./app/adapt-data-widget.js"
+import { HostModelContext } from "./app/model-context.js"
 import { WidgetFixtureHost, type FixtureWidget } from "./app/widget-fixture.js"
 import { PRIMITIVE_RENDER_CASES, type RenderCase } from "./render-cases-primitives.js"
 
@@ -111,11 +114,17 @@ export const RENDER_CASES: RenderCase[] = [
             trendDirection: "up",
           },
           { label: "Done", value: 12, fraction: "/19", tone: "success" },
-          { label: "Total", value: 19, onClick: noop, ariaLabel: "Show all" },
+          { label: "Total", value: 19, onClick: noop, actionHint: "Shows all orders" },
         ]}
       />
     ),
   },
+  {
+    // A skeleton has no text; the marker is its busy state.
+    name: "KpiGridSkeleton",
+    marker: 'aria-busy="true"',
+    render: () => <KpiGridSkeleton cells={4} boxed />,
+  },
   {
     name: "LivePill",
     marker: "RC:LivePill",
@@ -126,6 +135,11 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "RC:CountPill",
     render: () => <CountPill tone="warning">RC:CountPill</CountPill>,
   },
+  {
+    name: "StatusBadge",
+    marker: "RC:StatusBadge",
+    render: () => <StatusBadge tone="warning">RC:StatusBadge</StatusBadge>,
+  },
   {
     name: "SectionHeading",
     marker: "RC:SectionHeading",
@@ -136,9 +150,9 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "RC:WidgetHeader",
     render: () => (
       <WidgetHeader
-        icon="✓"
-        iconTone="info"
+        as="h2"
         title="RC:WidgetHeader"
+        badge={<StatusBadge tone="info">Running</StatusBadge>}
         sub={<LivePill>Live</LivePill>}
         actions={
           <Button size="sm" variant="ghost" onClick={noop}>
@@ -178,7 +192,7 @@ export const RENDER_CASES: RenderCase[] = [
     name: "DrillButton",
     marker: "RC:DrillButton",
     render: () => (
-      <DrillButton onDrill={noop} icon="↗" size="sm" ariaLabel="Open order o-1001">
+      <DrillButton onDrill={noop} icon={<ExternalLink />} size="sm" ariaLabel="Open order o-1001">
         RC:DrillButton
       </DrillButton>
     ),
@@ -188,6 +202,24 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "of 42 tasks",
     render: () => <ListFooter shown={8} total={42} hasMore onLoadMore={noop} noun="tasks" />,
   },
+  {
+    name: "PagedListFooter",
+    marker: "of 3 orders",
+    render: () => (
+      <PagedListFooter
+        paged={{
+          items: ["o-1", "o-2"],
+          total: 3,
+          hasMore: true,
+          loadMore: noop,
+          refreshing: true,
+          firstPage: {},
+          loadMoreError: new Error("HTTP 503"),
+        }}
+        noun="orders"
+      />
+    ),
+  },
 
   // ── Feedback and states ──
   {

package/src/render-effects.tsx

@@ -0,0 +1,96 @@
+/**
+ * Effect-running renders for the WIRING tests SSR cannot see: effects,
+ * subscriptions and timers of the view lifecycle and the data hooks
+ * (toolkit#176 review). `react-dom/client` + `act` in a test file that opts
+ * into a DOM with `// @vitest-environment happy-dom`. Not an interaction kit:
+ * the house render path stays SSR (`renderToStaticMarkup`), and these tests
+ * drive hooks through their inputs; a `click()` only where the wiring starts
+ * at a button.
+ */
+import { act, useEffect, type ReactNode } from "react"
+import { createRoot } from "react-dom/client"
+
+// React warns about updates outside act() unless the runtime says it is a test.
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+/**
+ * Run `work` in an ASYNC act scope: the promises it starts (a tool call that
+ * resolves, a state update after it) settle, and their renders commit,
+ * before the scope ends.
+ */
+export function inAct(work: () => unknown): Promise<void> {
+  return act(() => {
+    work()
+    return Promise.resolve()
+  })
+}
+
+export interface EffectRender {
+  container: HTMLElement
+  /** Render `node` into the same root (a new host state, new props). */
+  rerender: (node: ReactNode) => Promise<void>
+  /** Unmount and run the cleanups; a second call does nothing. */
+  unmount: () => Promise<void>
+}
+
+/** Mount `node` and run its effects. */
+export async function renderWithEffects(node: ReactNode): Promise<EffectRender> {
+  const container = document.createElement("div")
+  document.body.append(container)
+  const root = createRoot(container)
+  await inAct(() => root.render(node))
+  let mounted = true
+  return {
+    container,
+    rerender: (next) => inAct(() => root.render(next)),
+    unmount: async () => {
+      if (!mounted) return
+      mounted = false
+      await inAct(() => root.unmount())
+      container.remove()
+    },
+  }
+}
+
+/**
+ * Settle pending promises and the effects and renders they cause, with real
+ * timers: TanStack Query notifies its observers on a 0 ms timer, so each
+ * round lets one land (under fake timers use {@link advanceTimers}).
+ */
+export async function flushEffects(rounds = 3): Promise<void> {
+  for (let round = 0; round < rounds; round++) {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0))
+    })
+  }
+}
+
+/** Advance fake timers by `ms` inside act, so the renders they cause commit. */
+export function advanceTimers(advance: (ms: number) => unknown, ms: number): Promise<void> {
+  return inAct(() => advance(ms))
+}
+
+/**
+ * Renders `useValue` in a probe and keeps its latest committed value: read
+ * `current` after a render or flush.
+ */
+export function hookProbe<T>(useValue: () => T): {
+  Probe: () => null
+  current: () => T
+} {
+  const box: { value?: { current: T } } = {}
+  function Probe(): null {
+    const value = useValue()
+    useEffect(() => {
+      box.value = { current: value }
+    })
+    return null
+  }
+  return {
+    Probe,
+    current: () => {
+      if (!box.value) throw new Error("the probe has not committed yet")
+      return box.value.current
+    },
+  }
+}

package/src/theme/cd-tokens.test.ts

@@ -17,7 +17,9 @@ import { CD_TOKENS, CD_TOKENS_VERSION } from "./cd-tokens.js"
  * compared to it directly; everywhere else (CI) the pinned hash below holds it.
  *
  * To re-vendor: copy the new upstream file below the marker line, update the
- * version in the marker, CD_TOKENS_VERSION, UPSTREAM_SHA256 and CD_TOKENS.
+ * version in the marker, CD_TOKENS_VERSION, UPSTREAM_SHA256 and CD_TOKENS,
+ * then copy the result to docs/.vitepress/theme/ (the docs site vendors the
+ * same file; examples/test/docs-theme.test.ts holds the two byte-identical).
  */
 const UPSTREAM_SHA256 = "36d76f3a330a1250d332c6862be1dc4f7564d2461e7051d9a565ba723ef2c379"
 const UPSTREAM_REL = join("skills", "modeler-tool-design", "assets", "cd-tokens.generated.css")

package/src/theme/create-theme.test.ts

@@ -63,6 +63,11 @@ describe("tokensToVars (token → CSS-var mapping)", () => {
       fontSans: "Inter, sans-serif",
       fontMono: "JetBrains Mono, monospace",
       fontHeading: "Sora, sans-serif",
+      textTitle: "2rem",
+      textSection: "1.5rem",
+      textBody: "1.0625rem",
+      textDense: "0.9375rem",
+      textSmall: "0.875rem",
     }
     expect(tokensToVars(full)).toEqual({
       "--primary": "oklch(0.55 0.2 264)",
@@ -113,6 +118,11 @@ describe("tokensToVars (token → CSS-var mapping)", () => {
       "--font-sans": "Inter, sans-serif",
       "--font-mono": "JetBrains Mono, monospace",
       "--font-heading": "Sora, sans-serif",
+      "--text-title": "2rem",
+      "--text-section": "1.5rem",
+      "--text-body": "1.0625rem",
+      "--text-dense": "0.9375rem",
+      "--text-small": "0.875rem",
     })
   })
 

package/src/theme/create-theme.ts

@@ -134,6 +134,19 @@ export interface ThemeTokens {
   fontMono?: string
   /** Heading font-family list. Maps to `--font-heading`. */
   fontHeading?: string
+  /** Page title size (CI h2, 28 px). Maps to `--text-title` (`text-title`). */
+  textTitle?: string
+  /** Section title size (CI h3, 21 px). Maps to `--text-section` (`text-section`). */
+  textSection?: string
+  /** Running text size (16 px). Maps to `--text-body` (`text-body`). */
+  textBody?: string
+  /** Dense tables and controls (14 px), never running text. Maps to `--text-dense` (`text-dense`). */
+  textDense?: string
+  /**
+   * Captions, labels and hints: the smallest text the kit renders (13 px;
+   * keep it at 13 px or more). Maps to `--text-small` (`text-small`).
+   */
+  textSmall?: string
 }
 
 /** The CSS custom-property name a {@link ThemeTokens} field resolves to. */
@@ -194,6 +207,11 @@ export const TOKEN_TO_CSS_VAR = {
   fontSans: "--font-sans",
   fontMono: "--font-mono",
   fontHeading: "--font-heading",
+  textTitle: "--text-title",
+  textSection: "--text-section",
+  textBody: "--text-body",
+  textDense: "--text-dense",
+  textSmall: "--text-small",
 } as const satisfies Record<keyof ThemeTokens, CssVarName>
 
 /**
@@ -245,6 +263,11 @@ export const ROLE_TOKENS = [
   "--ease",
   "--font-sans",
   "--font-mono",
+  "--text-title",
+  "--text-section",
+  "--text-body",
+  "--text-dense",
+  "--text-small",
 ] as const satisfies readonly CssVarName[]
 
 /**
@@ -279,6 +302,11 @@ export const MODE_INVARIANT_VARS: ReadonlySet<CssVarName> = new Set<CssVarName>(
   "--font-sans",
   "--font-mono",
   "--font-heading",
+  "--text-title",
+  "--text-section",
+  "--text-body",
+  "--text-dense",
+  "--text-small",
 ])
 
 /** A serializable map of CSS custom properties (`--primary` → value). */

package/src/theme/theme-css.test.ts

@@ -8,6 +8,7 @@ import {
   resolveThemeVars,
   type ThemeVars,
 } from "./create-theme.js"
+import { TYPE_FLOOR_PX, TYPE_STEPS } from "../lib/typography.js"
 import { HOST_FONT_VARIABLES } from "./host-fonts.js"
 import { themePresets } from "./presets.js"
 
@@ -242,6 +243,56 @@ describe("theme.css — the role-token contract", () => {
     for (const value of Object.values(THEME_REFERENCE)) expect(value).not.toContain("calc(")
   })
 
+  it("defines the type scale per CI §4 (page title h2, section h3, body, dense, small) with a 13 px floor", () => {
+    const px = (rem: string | undefined) => Number(/^([\d.]+)rem$/.exec(rem ?? "")?.[1]) * 16
+    const scale = Object.fromEntries(
+      TYPE_STEPS.map((step) => [
+        step,
+        {
+          px: px(ROOT[`--text-${step}`]),
+          lineHeight: ROOT[`--text-${step}--line-height`],
+          weight: ROOT[`--text-${step}--font-weight`],
+        },
+      ]),
+    )
+    expect(scale).toEqual({
+      title: { px: 28, lineHeight: "1.2", weight: "700" },
+      section: { px: 21, lineHeight: "1.3", weight: "600" },
+      body: { px: 16, lineHeight: "1.6", weight: undefined },
+      dense: { px: 14, lineHeight: "1.5", weight: undefined },
+      small: { px: 13, lineHeight: "1.5", weight: undefined },
+    })
+    for (const { px: size } of Object.values(scale)) {
+      expect(size).toBeGreaterThanOrEqual(TYPE_FLOOR_PX)
+    }
+    // Mode-independent roles of the contract, themeable like the radii.
+    for (const step of TYPE_STEPS) {
+      expect(ROLE_TOKENS).toContain(`--text-${step}`)
+      expect(MODE_INVARIANT_VARS.has(`--text-${step}`)).toBe(true)
+      expect(LIGHT, step).not.toHaveProperty(`--text-${step}`)
+      expect(DARK, step).not.toHaveProperty(`--text-${step}`)
+    }
+  })
+
+  it("maps the type-scale utilities (text-title … text-small) onto the roles, size, leading and weight", () => {
+    for (const step of TYPE_STEPS) {
+      expect(THEME_REFERENCE[`--text-${step}`], step).toBe(`var(--text-${step})`)
+      expect(THEME_REFERENCE[`--text-${step}--line-height`], step).toBe(
+        `var(--text-${step}--line-height)`,
+      )
+    }
+    for (const step of ["title", "section"]) {
+      expect(THEME_REFERENCE[`--text-${step}--font-weight`], step).toBe(
+        `var(--text-${step}--font-weight)`,
+      )
+    }
+    // Tailwind's own steps stay untouched (text-xs is still 12 px): the floor
+    // is a gate on the kit's sources, not a redefinition of a consumer's scale.
+    for (const name of Object.keys({ ...THEME_INLINE, ...THEME_REFERENCE })) {
+      expect(name).not.toMatch(/^--text-(?:xs|sm|base|lg|\d?xl)\b/)
+    }
+  })
+
   it("exposes the new colour roles as utilities (bg-scrim, text-link, ring-focus, text-*-ink, …)", () => {
     for (const name of [
       "link",

package/src/theme.css

@@ -105,8 +105,22 @@
 /* Utilities whose role carries the utility's own name (`rounded-md` →
    `var(--radius-md)`, `shadow-2` → `var(--shadow-2)`, `font-mono` →
    `var(--font-mono)`). `reference` keeps Tailwind from emitting the
-   self-referencing theme variable; the roles below define the values. */
+   self-referencing theme variable; the roles below define the values.
+   The type scale works the same way: `text-small` sets the font size, line
+   height and weight of the `--text-small` role. */
 @theme inline reference {
+  --text-title: var(--text-title);
+  --text-title--line-height: var(--text-title--line-height);
+  --text-title--font-weight: var(--text-title--font-weight);
+  --text-section: var(--text-section);
+  --text-section--line-height: var(--text-section--line-height);
+  --text-section--font-weight: var(--text-section--font-weight);
+  --text-body: var(--text-body);
+  --text-body--line-height: var(--text-body--line-height);
+  --text-dense: var(--text-dense);
+  --text-dense--line-height: var(--text-dense--line-height);
+  --text-small: var(--text-small);
+  --text-small--line-height: var(--text-small--line-height);
   --radius-sm: var(--radius-sm);
   --radius-md: var(--radius-md);
   --radius-lg: var(--radius-lg);
@@ -132,6 +146,22 @@
   --motion-base: var(--cd-motion-base);
   --motion-slow: var(--cd-motion-slow);
   --ease: var(--cd-ease);
+  /* Type scale (modeler-tool-design §4, adapted for embedded widgets: the
+     page title is the CI h2, dense tables keep 14 px as the documented
+     product exception). 13 px is the floor: nothing renders smaller. In rem,
+     so a reader's font-size setting scales it. */
+  --text-title: 1.75rem; /* 28px */
+  --text-title--line-height: 1.2;
+  --text-title--font-weight: 700;
+  --text-section: 1.3125rem; /* 21px */
+  --text-section--line-height: 1.3;
+  --text-section--font-weight: 600;
+  --text-body: 1rem; /* 16px */
+  --text-body--line-height: 1.6;
+  --text-dense: 0.875rem; /* 14px */
+  --text-dense--line-height: 1.5;
+  --text-small: 0.8125rem; /* 13px */
+  --text-small--line-height: 1.5;
   /* Geist first, then the host's font, then the system stack. Loading Geist
      is opt-in (fonts.css or fontFaces()); where it is not loaded the next
      family renders. A SEP-1865 host sends its font as --font-sans and