@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/components/Toast.tsx

@@ -0,0 +1,206 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  type FocusEvent,
+  type ReactNode,
+} from "react"
+import { CircleAlert, CircleCheck, Info, TriangleAlert, X, type LucideIcon } from "lucide-react"
+import { useToolkitMessages } from "../locale/locale-provider.js"
+import { FOCUS_RING } from "../lib/focus-ring.js"
+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"
+
+export type { ToastOptions, ToastTone } from "../lib/toast-model.js"
+
+/** What {@link useToast} returns. */
+export interface ToastApi {
+  /** Show a toast; returns its id (for an early {@link ToastApi.dismiss}). */
+  show: (options: ToastOptions) => number
+  /** Remove a toast before its timer runs out. */
+  dismiss: (id: number) => void
+}
+
+const ToastContext = createContext<ToastApi | null>(null)
+
+/** Outside a provider `useToast()` degrades to a no-op instead of throwing. */
+const NOOP_TOASTS: ToastApi = { show: () => -1, dismiss: () => {} }
+
+/**
+ * Raise toasts from anywhere below a {@link ToastProvider}: `show({ tone,
+ * title })` after a write succeeded or failed, never a silent `console` line.
+ * Outside a provider it returns a no-op API, so a widget rendered in a bare
+ * fixture never crashes on feedback.
+ */
+export function useToast(): ToastApi {
+  return useContext(ToastContext) ?? NOOP_TOASTS
+}
+
+/**
+ * Status edge per tone — the status colour as border, never as text. Repeated
+ * under `dark:` so the card's dark 3:1 rim (`dark:border-input`, a later rule)
+ * does not paint over it.
+ */
+const TONE_EDGE: Record<ToastTone, string> = {
+  success: "border-l-success dark:border-l-success",
+  warning: "border-l-warning dark:border-l-warning",
+  danger: "border-l-danger dark:border-l-danger",
+  info: "border-l-info dark:border-l-info",
+}
+
+/**
+ * Lucide icon per tone, drawn in the tone colour (`TONE_ICON`, CI §3.3: status
+ * as edge and icon). The title next to it carries the message, so success and
+ * warning stay CI-exempt from 3:1 on light like every other status icon.
+ */
+const TOAST_ICON: Record<ToastTone, LucideIcon> = {
+  success: CircleCheck,
+  warning: TriangleAlert,
+  danger: CircleAlert,
+  info: Info,
+}
+
+/**
+ * The stack of toasts — a presentational view over a list (the provider owns
+ * 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,
+  onDismiss,
+}: {
+  toasts: readonly ToastItem[]
+  onDismiss: (id: number) => void
+}) {
+  const messages = useToolkitMessages()
+  return (
+    <div
+      data-slot="toast-viewport"
+      aria-live="polite"
+      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) => (
+        <ToastCard
+          key={toast.id}
+          toast={toast}
+          dismissLabel={messages.common.dismiss}
+          onDismiss={onDismiss}
+        />
+      ))}
+    </div>
+  )
+}
+
+function ToastCard({
+  toast,
+  dismissLabel,
+  onDismiss,
+}: {
+  toast: ToastItem
+  dismissLabel: string
+  onDismiss: (id: number) => void
+}) {
+  // 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(() => {
+    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={() => 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). 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],
+      )}
+    >
+      {/* 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 && (
+          <p className="text-muted-foreground mt-0.5 break-words">{toast.description}</p>
+        )}
+      </div>
+      <button
+        type="button"
+        aria-label={dismissLabel}
+        onClick={() => onDismiss(toast.id)}
+        className={`text-muted-foreground hover:text-foreground -mr-1 inline-flex size-6 shrink-0 items-center justify-center rounded-sm ${FOCUS_RING}`}
+      >
+        <X aria-hidden="true" className="size-4" />
+      </button>
+    </div>
+  )
+}
+
+function ToastRoot({ children }: { children: ReactNode }) {
+  const [toasts, dispatch] = useReducer(toastReducer, [])
+  const nextId = useRef(0)
+  const dismiss = useCallback((id: number) => dispatch({ type: "dismiss", id }), [])
+  const show = useCallback((options: ToastOptions) => {
+    nextId.current += 1
+    const id = nextId.current
+    dispatch({ type: "add", toast: createToast(id, options) })
+    return id
+  }, [])
+  const api = useMemo<ToastApi>(() => ({ show, dismiss }), [show, dismiss])
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      <ToastViewport toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  )
+}
+
+/**
+ * Provide toasts to a subtree and render their stack. Idempotent: nested
+ * inside another `ToastProvider` it adds nothing, so the app shell and an
+ * embedded builder share one stack and one live region. `McpAppView` mounts
+ * one for you.
+ */
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const parent = useContext(ToastContext)
+  return parent ? children : <ToastRoot>{children}</ToastRoot>
+}

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-xl 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>
         )}