@miragon/mcp-toolkit-ui 2.7.0 → 2.8.1

package/src/components/Toast.tsx

@@ -6,7 +6,7 @@ import {
   useMemo,
   useReducer,
   useRef,
-  useState,
+  type FocusEvent,
   type ReactNode,
 } from "react"
 import { CircleAlert, CircleCheck, Info, TriangleAlert, X, type LucideIcon } from "lucide-react"
@@ -16,9 +16,11 @@ import { TONE_ICON } from "../lib/tone-utils.js"
 import { cn } from "../lib/utils.js"
 import {
   createToast,
+  createToastTimer,
   toastReducer,
   type ToastItem,
   type ToastOptions,
+  type ToastTimer,
   type ToastTone,
 } from "../lib/toast-model.js"
 
@@ -73,9 +75,15 @@ const TOAST_ICON: Record<ToastTone, LucideIcon> = {
 
 /**
  * The stack of toasts — a presentational view over a list (the provider owns
- * the state). The container is ONE persistent live region (`role="status"`,
- * `aria-live="polite"`), so a newly added toast is announced without stealing
- * focus. Bottom centre, above dialogs (z 60), per CI §5/§8.
+ * the state). The container is ONE persistent live region
+ * (`aria-live="polite"`, mounted before the first toast so that toast is
+ * announced, each new toast on its own: `aria-atomic="false"`), without
+ * stealing focus. Its attributes never change: a role or name that switched
+ * on with the first toast would make the browser rebuild the region in the
+ * same commit that inserts the toast, and a region created with its content
+ * already in it is not announced. So it carries no role (a generic element
+ * takes no name either): an idle stack is no second "status" next to a view's
+ * own loading status. Bottom centre, above dialogs (z 60), per CI §5/§8.
  */
 export function ToastViewport({
   toasts,
@@ -88,9 +96,8 @@ export function ToastViewport({
   return (
     <div
       data-slot="toast-viewport"
-      role="status"
       aria-live="polite"
-      aria-label={messages.common.notifications}
+      aria-atomic="false"
       className="pointer-events-none fixed inset-x-0 bottom-4 z-60 flex flex-col items-center gap-2 px-4"
     >
       {toasts.map((toast) => (
@@ -114,31 +121,42 @@ function ToastCard({
   dismissLabel: string
   onDismiss: (id: number) => void
 }) {
-  // Hover or keyboard focus holds the toast: the timer restarts on leave.
-  const [held, setHeld] = useState(false)
+  // Hover or keyboard focus holds the toast; on leave it resumes with the
+  // time that was LEFT (createToastTimer), never a fresh full duration.
+  const timer = useRef<ToastTimer | null>(null)
   useEffect(() => {
-    if (held) return
-    const timer = setTimeout(() => onDismiss(toast.id), toast.duration)
-    return () => clearTimeout(timer)
-  }, [held, onDismiss, toast.id, toast.duration])
+    const countdown = createToastTimer(toast.duration, () => onDismiss(toast.id))
+    timer.current = countdown
+    return () => {
+      countdown.cancel()
+      timer.current = null
+    }
+  }, [onDismiss, toast.id, toast.duration])
+  const releaseFocus = (event: FocusEvent<HTMLDivElement>) => {
+    // Focus moving inside the toast (card → close button) keeps the hold.
+    if (!event.currentTarget.contains(event.relatedTarget)) {
+      timer.current?.release("focus")
+    }
+  }
   const Icon = TOAST_ICON[toast.tone]
   return (
     <div
       data-slot="toast"
       data-tone={toast.tone}
-      onMouseEnter={() => setHeld(true)}
-      onMouseLeave={() => setHeld(false)}
-      onFocus={() => setHeld(true)}
-      onBlur={() => setHeld(false)}
+      onMouseEnter={() => timer.current?.hold("pointer")}
+      onMouseLeave={() => timer.current?.release("pointer")}
+      onFocus={() => timer.current?.hold("focus")}
+      onBlur={releaseFocus}
       className={cn(
         // An overlay like Dialog/Sheet: shadow-2 on light, the 3:1 input rim on
-        // dark (shadows vanish on the ground).
-        "bg-popover text-popover-foreground dark:border-input shadow-2 pointer-events-auto flex w-full max-w-sm items-start gap-3 rounded-md border border-l-4 px-4 py-3 text-sm",
+        // dark (shadows vanish on the ground). Its words are running text (16 px).
+        "bg-popover text-popover-foreground dark:border-input shadow-2 text-body pointer-events-auto flex w-full max-w-sm items-start gap-3 rounded-md border border-l-4 px-4 py-3",
         "motion-safe:animate-in motion-safe:fade-in-0 motion-safe:slide-in-from-bottom-2 motion-safe:duration-(--motion-base) motion-safe:ease-(--ease)",
         TONE_EDGE[toast.tone],
       )}
     >
-      <Icon aria-hidden="true" className={cn("mt-0.5 size-4 shrink-0", TONE_ICON[toast.tone])} />
+      {/* mt-1 centres the 16 px icon on the first 16/1.6 line. */}
+      <Icon aria-hidden="true" className={cn("mt-1 size-4 shrink-0", TONE_ICON[toast.tone])} />
       <div className="min-w-0 flex-1">
         <p className="font-medium break-words">{toast.title}</p>
         {toast.description && (

package/src/components/WidgetHeader.test.tsx

@@ -0,0 +1,78 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { MICRO_LABEL } from "../lib/typography.js"
+import { attribute, openingTags } from "../render-scan.js"
+import { StatusBadge } from "./Pills.js"
+import { SectionHeading } from "./SectionHeading.js"
+import { WidgetHeader, type WidgetHeadingLevel } from "./WidgetHeader.js"
+
+const classOf = (tag: string | undefined) => attribute(tag ?? "", "class") ?? ""
+
+describe("WidgetHeader: one title at the level of its surface", () => {
+  it("is an h1 at the page-title size by default", () => {
+    const html = renderToStaticMarkup(<WidgetHeader title="Incidents" />)
+    expect(html).toMatch(/<h1 class="[^"]*text-title[^"]*">Incidents<\/h1>/)
+    expect(html).not.toMatch(/text-3xl|text-xs/)
+  })
+
+  it.each(["h2", "h3", "h4", "h5", "h6"] satisfies WidgetHeadingLevel[])(
+    "takes the heading level %s from `as`, keeping the size",
+    (level) => {
+      const html = renderToStaticMarkup(<WidgetHeader as={level} title="Incidents" />)
+      expect(html).toMatch(
+        new RegExp(`<${level} class="[^"]*text-title[^"]*">Incidents</${level}>`),
+      )
+      expect(html).not.toContain("<h1")
+    },
+  )
+
+  it("renders the compact detail size at the section step", () => {
+    const html = renderToStaticMarkup(<WidgetHeader as="h2" size="detail" title="Instance" />)
+    expect(classOf(openingTags(html, "h2")[0])).toContain("text-section")
+    expect(classOf(openingTags(html, "h2")[0])).not.toContain("text-title")
+  })
+
+  it("puts a state badge above the title and a suffix inside the heading", () => {
+    const html = renderToStaticMarkup(
+      <WidgetHeader
+        title="Invoice"
+        titleSuffix={<span>v3</span>}
+        badge={<StatusBadge tone="warning">Suspended</StatusBadge>}
+        sub="Updated 14:32"
+        actions={<button type="button">Refresh</button>}
+      />,
+    )
+    expect(html.indexOf("Suspended")).toBeLessThan(html.indexOf("<h1"))
+    expect(html).toMatch(/<h1[^>]*>Invoice<span>v3<\/span><\/h1>/)
+    expect(html).toContain("Updated 14:32")
+    expect(html).toContain("Refresh</button>")
+    expect(html).not.toContain("size-11")
+    // The meta row is a caption at the 13 px step, not running text in the
+    // dense-table size.
+    const meta = openingTags(html, "div").find((t) => /flex-wrap items-center gap-2/.test(t))
+    expect(classOf(meta)).toMatch(/(^| )text-small( |$)/)
+    expect(html).not.toMatch(/\btext-dense\b/)
+  })
+
+  it("still renders the deprecated icon tile, hidden from assistive tech", () => {
+    const html = renderToStaticMarkup(<WidgetHeader icon={<svg />} iconTone="info" title="Tasks" />)
+    const tile = openingTags(html, "div").find((t) => /size-11/.test(t))
+    expect(attribute(tile ?? "", "aria-hidden")).toBe("true")
+    expect(classOf(tile)).toContain("bg-info-soft")
+  })
+
+  it("merges a className onto the header", () => {
+    const html = renderToStaticMarkup(<WidgetHeader title="x" className="mb-6" />)
+    expect(classOf(openingTags(html, "header")[0])).toContain("mb-6")
+  })
+})
+
+describe("SectionHeading: a block label inside a widget body", () => {
+  it("is a 13 px caption (MICRO_LABEL), never in the dense-table size", () => {
+    const html = renderToStaticMarkup(<SectionHeading title="Recent" hint="3 new" />)
+    const row = classOf(openingTags(html, "div")[0])
+    expect(row).toContain(MICRO_LABEL)
+    expect(row).toContain("text-muted-foreground")
+    expect(html).not.toMatch(/\btext-dense\b/)
+  })
+})

package/src/components/WidgetHeader.tsx

@@ -1,46 +1,93 @@
 import type { ReactNode } from "react"
-import { TONE_SOFT, type ToneVariant } from "../lib/tone-utils.js"
+import { resolveTone, TONE_SOFT, type ToneName } from "../lib/tone-utils.js"
+import { cn } from "../lib/utils.js"
+
+/** Heading element of a {@link WidgetHeader} title. */
+export type WidgetHeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
 
 export interface WidgetHeaderProps {
-  /** Optional icon/glyph rendered in a tinted tile above the title. */
-  icon?: ReactNode
-  /** Tone for the icon tile. Default `"neutral"`. */
-  iconTone?: ToneVariant
   /** The widget title. */
   title: ReactNode
-  /** Subtitle/meta row under the title (e.g. a live pill + counts). */
+  /**
+   * Heading element of the title. Default `"h1"`: the widget is the page.
+   * Pick the level that keeps ONE outline per view — below a toolbar title
+   * (`McpAppView` `titleMode="show"`, an h2 by default) use `"h3"`, inside a
+   * composed view under its own heading one level below it. The size follows
+   * `size`, not the level.
+   */
+  as?: WidgetHeadingLevel
+  /**
+   * `"default"`: the page title (28 px / 700, the CI h2 style). `"detail"`:
+   * the compact detail-page title (21 px / 600, the CI h3 style).
+   */
+  size?: "default" | "detail"
+  /** Inline after the title inside the heading (e.g. a version chip). */
+  titleSuffix?: ReactNode
+  /** Above the title — a `StatusBadge` that says the state in words. */
+  badge?: ReactNode
+  /** Subtitle/meta row under the title (e.g. a live pill + counts), a 13 px caption row. */
   sub?: ReactNode
   /** Right-aligned actions slot (buttons, drill controls). */
   actions?: ReactNode
+  /**
+   * @deprecated A glyph in a tinted tile above every title is the icon-tile
+   * pattern the CI rules out (anti-slop U2). Say a state in words with a
+   * `StatusBadge` in {@link WidgetHeaderProps.badge}. Still rendered when set.
+   */
+  icon?: ReactNode
+  /** @deprecated Tone of the deprecated {@link WidgetHeaderProps.icon} tile. */
+  iconTone?: ToneName
+  className?: string
+}
+
+const TITLE_SIZE: Record<NonNullable<WidgetHeaderProps["size"]>, string> = {
+  default: "text-title",
+  detail: "text-section",
 }
 
 /**
- * Page-level header for the top of a dashboard widget: an optional tinted icon
- * tile, a large title, a subtitle/meta row, and a right-aligned actions slot.
- * Use once per widget surface to anchor it.
+ * Page-level header at the top of a widget: an optional state badge, the
+ * title (heading level per `as`, size per `size`), a subtitle/meta row and a
+ * right-aligned actions slot. Use once per widget surface to anchor it.
  */
 export function WidgetHeader({
-  icon,
-  iconTone = "neutral",
   title,
+  as: Heading = "h1",
+  size = "default",
+  titleSuffix,
+  badge,
   sub,
   actions,
+  icon,
+  iconTone = "neutral",
+  className,
 }: WidgetHeaderProps) {
   return (
-    <header className="flex flex-wrap items-start justify-between gap-4">
+    <header
+      data-slot="widget-header"
+      className={cn("flex flex-wrap items-start justify-between gap-4", className)}
+    >
       <div className="min-w-0">
         {icon && (
           <div
-            className={`mb-3.5 grid size-11 place-items-center rounded-md text-xl ${TONE_SOFT[iconTone]}`}
+            aria-hidden="true"
+            className={cn(
+              "text-section mb-3.5 grid size-11 place-items-center rounded-md",
+              TONE_SOFT[resolveTone(iconTone)],
+            )}
           >
             {icon}
           </div>
         )}
-        <h1 className="text-foreground mb-1.5 text-3xl leading-tight font-bold tracking-tight">
+        {badge && <div className="mb-3">{badge}</div>}
+        <Heading
+          className={cn("text-foreground mb-1.5 tracking-tight break-words", TITLE_SIZE[size])}
+        >
           {title}
-        </h1>
+          {titleSuffix}
+        </Heading>
         {sub && (
-          <div className="text-muted-foreground flex flex-wrap items-center gap-2 text-sm">
+          <div className="text-muted-foreground text-small flex flex-wrap items-center gap-2">
             {sub}
           </div>
         )}

package/src/components/feedback-states.test.tsx

@@ -8,8 +8,8 @@ import { FOCUS_RING } from "../lib/focus-ring.js"
 import { createToast } from "../lib/toast-model.js"
 import { TONE_BORDER, TONE_ICON, TONE_SOFT } from "../lib/tone-utils.js"
 import { attribute, openingTags } from "../render-scan.js"
-import { EmptyState } from "./EmptyState.js"
-import { ErrorState } from "./ErrorState.js"
+import { EmptyState, type EmptyStateProps } from "./EmptyState.js"
+import { ErrorState, type ErrorStateTone } from "./ErrorState.js"
 import { ToastProvider, ToastViewport, useToast, type ToastApi } from "./Toast.js"
 
 /**
@@ -38,16 +38,41 @@ describe("Toast", () => {
     createToast(2, { tone: "danger", title: "Retry failed.", description: "Engine down (503)" }),
   ]
 
-  it("renders ONE persistent live region: role=status, aria-live=polite, a localized name", () => {
+  /** The stack's region, found by its slot (it has no role to query by). */
+  const regionOf = (html: string) =>
+    openingTags(html, "div").find((t) => attribute(t, "data-slot") === "toast-viewport") ?? ""
+
+  it("renders ONE persistent live region: aria-live=polite, each toast on its own", () => {
     const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
-    const [region, ...others] = openingTags(html, "div").filter((t) => /role="status"/.test(t))
+    const [region, ...others] = openingTags(html, "div").filter((t) => /aria-live=/.test(t))
     expect(others).toHaveLength(0)
+    expect(attribute(region ?? "", "data-slot")).toBe("toast-viewport")
     expect(attribute(region ?? "", "aria-live")).toBe("polite")
-    expect(attribute(region ?? "", "aria-label")).toBe(de.common.notifications)
-    // An empty stack keeps the region mounted, so the first toast is announced.
-    const empty = inGerman(<ToastViewport toasts={[]} onDismiss={noop} />)
-    expect(empty).toContain('role="status"')
-    expect(empty).toContain('aria-live="polite"')
+    // Each new toast is announced on its own, not the whole stack again.
+    expect(attribute(region ?? "", "aria-atomic")).toBe("false")
+    expect(html).not.toContain('role="status"')
+  })
+
+  it("keeps the region's attributes fixed from idle to the first toast", () => {
+    // An empty stack keeps the live region, so the first toast is announced.
+    // A role or name that switched on with that toast would make the browser
+    // rebuild the region in the same commit, with the toast already inside:
+    // not announced. So idle and busy carry exactly the same attributes…
+    const idle = regionOf(inGerman(<ToastViewport toasts={[]} onDismiss={noop} />))
+    const busy = regionOf(inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />))
+    expect(idle).not.toBe("")
+    expect(busy).toBe(idle)
+    // …and no role or name at all: an idle stack is no second "status" beside
+    // a view's own loading status (a generic element takes no aria-label).
+    expect(attribute(idle, "role")).toBeUndefined()
+    expect(attribute(idle, "aria-label")).toBeUndefined()
+    const loading = inGerman(
+      <ToastProvider>
+        <p role="status">Ansicht wird geladen…</p>
+      </ToastProvider>,
+    )
+    expect(loading.match(/role="status"/g)).toHaveLength(1)
+    expect(loading.match(/aria-live="polite"/g)).toHaveLength(1)
   })
 
   it("shows the status as edge + icon next to plain text, never as coloured text", () => {
@@ -69,6 +94,14 @@ describe("Toast", () => {
     expect(html).toContain("Engine down (503)")
   })
 
+  it("sets its words as running text (16 px), not in the dense-table size", () => {
+    const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
+    for (const card of openingTags(html, "div").filter((t) => /data-slot="toast"/.test(t))) {
+      expect(attribute(card, "class")).toMatch(/(^| )text-body( |$)/)
+      expect(attribute(card, "class")).not.toMatch(/\btext-dense\b/)
+    }
+  })
+
   it("gives every toast a native close button named in the locale, and steals no focus", () => {
     const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
     const buttons = openingTags(html, "button")
@@ -150,6 +183,29 @@ describe("EmptyState", () => {
     expect(openingTags(html, "button")).toHaveLength(2)
     expect(renderToStaticMarkup(<EmptyState title="Bare" />)).not.toContain("<button")
   })
+
+  it("sets its help line as running text (16 px), not in the dense-table size", () => {
+    const html = renderToStaticMarkup(<EmptyState title="Nothing" description="Add one." />)
+    const line = openingTags(html, "p").find((t) => /max-w-prose/.test(t)) ?? ""
+    expect(attribute(line, "class")).toMatch(/(^| )text-body( |$)/)
+    expect(html).not.toMatch(/\btext-dense\b/)
+  })
+
+  it("resolves an untyped tone: a retired success name colours the icon, anything else stays quiet", () => {
+    const iconClass = (tone: string) => {
+      const html = renderToStaticMarkup(
+        <EmptyState
+          icon={<CircleCheck />}
+          tone={tone as unknown as EmptyStateProps["tone"]}
+          title="x"
+        />,
+      )
+      return openingTags(html, "div").find((t) => /aria-hidden="true"/.test(t)) ?? ""
+    }
+    expect(iconClass("ok")).toContain(TONE_ICON.success)
+    expect(iconClass("danger")).toContain(TONE_ICON.neutral)
+    expect(iconClass("purple")).toContain(TONE_ICON.neutral)
+  })
 })
 
 describe("ErrorState", () => {
@@ -222,4 +278,37 @@ describe("ErrorState", () => {
     expect(html).toContain("Reload</button>")
     expect(html).toContain('<a href="#help">Help</a>')
   })
+
+  it("sets the block's description as running text (16 px); the inline alert box stays dense", () => {
+    const descriptionClass = (html: string) =>
+      /<div class="([^"]*)">what to do<\/div>/.exec(html)?.[1] ?? ""
+    const block = renderToStaticMarkup(<ErrorState title="x" description="what to do" />)
+    expect(descriptionClass(block)).toMatch(/(^| )text-body( |$)/)
+    const inline = renderToStaticMarkup(
+      <ErrorState variant="inline" title="x" description="what to do" />,
+    )
+    expect(descriptionClass(inline)).toMatch(/(^| )text-dense( |$)/)
+  })
+
+  it.each([
+    ["error", "danger"],
+    ["critical", "danger"],
+    ["warn", "warning"],
+    ["notice", "info"],
+    ["success", "danger"],
+    ["purple", "danger"],
+  ])(
+    "resolves an untyped tone %j to its %s state instead of crashing on a missing icon",
+    (name, tone) => {
+      const html = renderToStaticMarkup(
+        <ErrorState title="x" tone={name as unknown as ErrorStateTone} />,
+      )
+      const root = openingTags(html, "div")[0] ?? ""
+      expect(attribute(root, "data-tone")).toBe(tone)
+      expect(attribute(root, "class")).toContain(TONE_BORDER[tone as ErrorStateTone])
+      expect(attribute(openingTags(html, "svg")[0] ?? "", "class")).toContain(
+        TONE_ICON[tone as ErrorStateTone],
+      )
+    },
+  )
 })

package/src/components/tone-figures.test.tsx

@@ -28,13 +28,17 @@ describe("figures never take a tone colour", () => {
         ]}
       />,
     )
-    expect(html).not.toMatch(TONE_AS_TEXT)
-    // The tone is still there — as a dot.
+    // Icons draw in the tone (SVG currentColor, TONE_ICON); no WORD or digit does.
+    const words = html.replace(/<svg[\s\S]*?<\/svg>/g, "")
+    expect(words).not.toMatch(TONE_AS_TEXT)
+    // The tone is still there — as a dot next to a label, an icon next to a trend.
     expect(html).toMatch(/bg-danger\b/)
     expect(html).toMatch(/bg-success\b/)
+    expect(html).toMatch(/<svg[^>]*class="lucide lucide-trending-up[^"]*text-danger"/)
+    expect(html).toMatch(/<svg[^>]*class="lucide lucide-trending-down[^"]*text-success"/)
     // A toned trend reads in the foreground, an untoned one stays quiet.
-    expect(html).toMatch(/text-foreground[^"]*"><span aria-hidden="true"[^>]*bg-danger/)
-    expect(html).toMatch(/text-muted-foreground">±0/)
+    expect(html).toMatch(/<span class="text-foreground">\+12% vs last week<\/span>/)
+    expect(html).toMatch(/<span class="text-muted-foreground">±0<\/span>/)
   })
 
   it.each(TONES)(

package/src/hooks/index.ts

@@ -1,17 +1,20 @@
 export { useIsMobile } from "./use-mobile.js"
 export { useDebouncedValue } from "./use-debounced-value.js"
-export { useToolQuery, useToolMutation } from "./use-tool-query.js"
-export type { UseToolQueryOptions } from "./use-tool-query.js"
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./use-tool-query.js"
+export type { UseToolQueryOptions, UseToolMutationOptions } from "./use-tool-query.js"
 export { useViewToolQuery } from "./use-view-tool-query.js"
 export type { UseViewToolQueryOptions } from "./use-view-tool-query.js"
 export { useViewData } from "./use-view-data.js"
-export type { ViewDataResult } from "./use-view-data.js"
+export type { ViewDataResult, UseViewDataOptions, ViewDataMode } from "./use-view-data.js"
 export {
   useToolResultRecovery,
   resolveRecoveryToolName,
   decodeRecoveredResult,
 } from "./use-tool-result-recovery.js"
 export type {
+  RecoveryBlockReason,
+  RecoveryPolicy,
   ToolResultRecoveryOptions,
   ToolResultRecoveryState,
+  ToolSafety,
 } from "./use-tool-result-recovery.js"