@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/components/DrillButton.tsx

@@ -1,37 +1,51 @@
 import type { ReactNode } from "react"
+import { ArrowRight } from "lucide-react"
+import { FOCUS_RING } from "../lib/focus-ring.js"
+import { cn } from "../lib/utils.js"
 
 export interface DrillButtonProps {
   /** Button label. */
   children: ReactNode
   /** Drill/navigation handler — wire to in-widget navigation (e.g. `showWidget`). */
   onDrill: () => void
-  /** Optional leading glyph (e.g. a domain icon). The trailing → is always rendered. */
+  /**
+   * Optional leading icon — a Lucide icon of the domain, never a typed glyph.
+   * Decorative (`aria-hidden`). The trailing arrow is always rendered.
+   */
   icon?: ReactNode
   /** `sm` for table rows, `md` for surface headers. Default `"sm"`. */
   size?: "sm" | "md"
-  /** Accessible label when the visible text is terse. */
+  /** Accessible label when the visible text is terse; keep the visible text in it (WCAG 2.5.3). */
   ariaLabel?: string
 }
 
 /**
  * The single, deterministic in-widget navigation control: a neutral outline
- * button with a trailing → that drills into a detail/sub-view. Use it for
- * every in-app drill (row "Open", header nav) so they read identically and stay
- * visually quieter than primary/agentic actions. Decoupled from any host — pass
- * an `onDrill` callback (e.g. wrapping `useHostActions().showWidget`).
+ * button with a trailing Lucide arrow that drills into a detail/sub-view. Use
+ * it for every in-app drill (row "Open", header nav) so they read identically
+ * and stay visually quieter than primary/agentic actions. Decoupled from any
+ * host — pass an `onDrill` callback (e.g. wrapping `useHostActions().showWidget`).
  */
 export function DrillButton({ children, onDrill, icon, size = "sm", ariaLabel }: DrillButtonProps) {
-  const pad = size === "md" ? "px-3 py-1.5 text-sm" : "px-2.5 py-1 text-xs"
+  const pad = size === "md" ? "px-3 py-1.5 text-dense" : "px-2.5 py-1 text-small"
   return (
     <button
       type="button"
       onClick={onDrill}
       aria-label={ariaLabel}
-      className={`border-border text-foreground hover:bg-muted focus-visible:ring-ring inline-flex items-center gap-1 rounded-md border font-medium transition-colors outline-none focus-visible:ring-2 ${pad}`}
+      className={cn(
+        "border-border text-foreground hover:border-focus hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1 rounded-md border font-medium transition-colors [&_svg:not([class*='size-'])]:size-4",
+        FOCUS_RING,
+        pad,
+      )}
     >
-      {icon && <span aria-hidden="true">{icon}</span>}
+      {icon && (
+        <span aria-hidden="true" className="inline-flex">
+          {icon}
+        </span>
+      )}
       {children}
-      <span aria-hidden="true">→</span>
+      <ArrowRight aria-hidden="true" className="size-4 shrink-0" />
     </button>
   )
 }

package/src/components/EmptyState.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react"
+import { resolveTone, TONE_ICON } from "../lib/tone-utils.js"
+import { cn } from "../lib/utils.js"
+
+/** Heading element for an empty/error state title (the surface decides the outline level). */
+export type StateHeadingLevel = "h2" | "h3" | "h4" | "p"
+
+export interface EmptyStateProps {
+  /**
+   * Icon or mark above the title, rendered decoratively (`aria-hidden`): a
+   * Lucide icon for the concrete situation (e.g. `<CircleCheck />` for "all
+   * done"), or a brand mark (an app passes its logo; a customer brand passes
+   * its own or nothing). An SVG renders at 24 px unless it carries its own
+   * `size-*` class, so a mark can be larger (`<Komet className="size-12" />`).
+   */
+  icon?: ReactNode
+  /** Colour of the icon slot: `"neutral"` (muted, default) or `"success"` ("all done"). */
+  tone?: "neutral" | "success"
+  /** What is empty, in plain words ("No open incidents"). */
+  title: ReactNode
+  /** One help line: why it is empty or what to do next. */
+  description?: ReactNode
+  /** The primary next step (a `Button`). */
+  action?: ReactNode
+  /** An optional second, quieter step. Empty states carry at most two actions. */
+  secondaryAction?: ReactNode
+  /** Element of the title. Default `"h3"` (inside a widget below its own heading). */
+  titleAs?: StateHeadingLevel
+  className?: string
+}
+
+/** The icon slot in the tone's icon colour (`TONE_ICON`): quiet, or the success tone. */
+const ICON_TONE: Record<NonNullable<EmptyStateProps["tone"]>, string> = {
+  neutral: TONE_ICON.neutral,
+  success: TONE_ICON.success,
+}
+
+/**
+ * The one empty-state pattern: icon or mark, a title (600), one help line and
+ * up to two actions, centred in the space the content would take. Static (no
+ * live region): it replaces content, it does not announce a change.
+ */
+export function EmptyState({
+  icon,
+  tone = "neutral",
+  title,
+  description,
+  action,
+  secondaryAction,
+  titleAs: Title = "h3",
+  className,
+}: EmptyStateProps) {
+  // An untyped tone resolves (`ok` → success); anything else stays quiet.
+  const iconTone = resolveTone(tone) === "success" ? "success" : "neutral"
+  return (
+    <div
+      data-slot="empty-state"
+      className={cn("flex flex-col items-center gap-2 px-4 py-8 text-center", className)}
+    >
+      {icon && (
+        <div
+          aria-hidden="true"
+          className={cn(
+            "mb-1 flex items-center justify-center [&_svg:not([class*='size-'])]:size-6",
+            ICON_TONE[iconTone],
+          )}
+        >
+          {icon}
+        </div>
+      )}
+      <Title className="text-foreground text-body font-semibold">{title}</Title>
+      {description && (
+        <p className="text-muted-foreground text-body max-w-prose text-balance">{description}</p>
+      )}
+      {(action || secondaryAction) && (
+        <div className="mt-2 flex flex-wrap items-center justify-center gap-2">
+          {action}
+          {secondaryAction}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ErrorState.tsx

@@ -0,0 +1,204 @@
+import type { ReactNode } from "react"
+import { CircleAlert, Info, RefreshCw, TriangleAlert, type LucideIcon } from "lucide-react"
+import { useToolkitMessages } from "../locale/locale-provider.js"
+import { Button } from "../primitives/button.js"
+import { FOCUS_RING } from "../lib/focus-ring.js"
+import { resolveTone, TONE_BORDER, TONE_ICON, TONE_SOFT } from "../lib/tone-utils.js"
+import { cn } from "../lib/utils.js"
+import type { StateHeadingLevel } from "./EmptyState.js"
+
+/** Status tone of an {@link ErrorState}. */
+export type ErrorStateTone = "danger" | "warning" | "info"
+
+export interface ErrorStateProps {
+  /** What happened, in plain words ("This view couldn't be loaded"). */
+  title: ReactNode
+  /** What you can do next — or the human reason, when you can map the raw one. */
+  description?: ReactNode
+  /**
+   * The raw technical reason (engine exception, HTTP status), shown collapsed
+   * under a "Details" disclosure so it informs without leading.
+   */
+  details?: ReactNode
+  /** Summary text of the details disclosure. Default: the locale's "Details". */
+  detailsLabel?: string
+  /** Renders a retry button when set. */
+  onRetry?: () => void
+  /** Retry button label. Default: the locale's "Try again". */
+  retryLabel?: string
+  /** Further actions after the retry button (e.g. a link to another view). */
+  actions?: ReactNode
+  /**
+   * Default `"danger"`. `"warning"` for partial failures, `"info"` for
+   * notices. An untyped retired name still resolves (`error` → `danger`).
+   */
+  tone?: ErrorStateTone
+  /** Replace the tone's default Lucide icon. */
+  icon?: LucideIcon
+  /**
+   * `"block"` (default): the state that replaces a whole view or widget body.
+   * `"inline"`: a compact alert above content that still renders.
+   */
+  variant?: "block" | "inline"
+  /**
+   * Live-region role. Default `"alert"` — an error that appears after the
+   * fact is announced. Use `"status"` for a quieter notice, or `"none"` when
+   * the state is part of the first paint.
+   */
+  role?: "alert" | "status" | "none"
+  /** Element of the title. Default `"h2"` for `block`, `"p"` for `inline`. */
+  titleAs?: StateHeadingLevel
+  className?: string
+}
+
+const STATE_ICON: Record<ErrorStateTone, LucideIcon> = {
+  danger: CircleAlert,
+  warning: TriangleAlert,
+  info: Info,
+}
+
+/**
+ * The state's tone from whatever arrives: its three tones as is, a retired
+ * name through `resolveTone` (`error` → `danger`, `notice` → `info`), any
+ * other tone or unknown name as the default `danger`. A tone from untyped
+ * data (plain JS, the wire) never crashes the view on a missing icon.
+ */
+function stateTone(name: unknown): ErrorStateTone {
+  const tone = resolveTone(name, "danger")
+  return tone === "warning" || tone === "info" ? tone : "danger"
+}
+
+/**
+ * Per-variant geometry: `block` replaces a surface and reads as running text
+ * (16 px), `inline` is the compact alert box above content that still renders
+ * (14 px, the dense-controls exception of the type scale).
+ */
+const VARIANT = {
+  block: {
+    box: "gap-4 p-4",
+    icon: "size-5",
+    title: "text-body",
+    description: "text-body",
+    defaultTitleAs: "h2",
+    retry: "default",
+  },
+  inline: {
+    box: "gap-3 px-4 py-3 text-dense",
+    icon: "size-4",
+    title: "text-dense",
+    description: "text-dense",
+    defaultTitleAs: "p",
+    retry: "outline",
+  },
+} as const satisfies Record<
+  NonNullable<ErrorStateProps["variant"]>,
+  {
+    box: string
+    icon: string
+    title: string
+    description: string
+    defaultTitleAs: StateHeadingLevel
+    retry: "default" | "outline"
+  }
+>
+
+/**
+ * The one error pattern: a Lucide icon, a title that says what happened, a
+ * line that says what you can do, the raw reason collapsed under "Details",
+ * and a retry. `inline` is the alert form above content that still renders
+ * (failed data steps); `block` replaces a whole view or widget body.
+ */
+export function ErrorState({
+  title,
+  description,
+  details,
+  detailsLabel,
+  onRetry,
+  retryLabel,
+  actions,
+  tone: toneProp,
+  icon,
+  variant = "block",
+  role = "alert",
+  titleAs,
+  className,
+}: ErrorStateProps) {
+  const tone = stateTone(toneProp)
+  const style = VARIANT[variant]
+  const Icon = icon ?? STATE_ICON[tone]
+  const Title = titleAs ?? style.defaultTitleAs
+  // The status colour as rim, tint and icon; every word on the tint is the
+  // foreground (TONE_SOFT, CI §3.3). On dark the tint is transparent and the
+  // rim carries the tone.
+  return (
+    <div
+      data-slot="error-state"
+      data-variant={variant}
+      data-tone={tone}
+      role={role === "none" ? undefined : role}
+      className={cn(
+        "flex items-start rounded-md border",
+        style.box,
+        TONE_SOFT[tone],
+        TONE_BORDER[tone],
+        className,
+      )}
+    >
+      <Icon aria-hidden="true" className={cn("mt-0.5 shrink-0", style.icon, TONE_ICON[tone])} />
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <Title className={cn("font-semibold", style.title)}>{title}</Title>
+        {description && <div className={cn("break-words", style.description)}>{description}</div>}
+        {details && <ErrorDetails label={detailsLabel}>{details}</ErrorDetails>}
+        <ErrorActions
+          onRetry={onRetry}
+          retryLabel={retryLabel}
+          retryVariant={style.retry}
+          actions={actions}
+        />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The raw reason, collapsed: a native disclosure (keyboard + screen-reader
+ * ready). It sits on the tint, so its text stays the foreground; the collapse
+ * and the small mono type keep it quieter than the title.
+ */
+function ErrorDetails({ label, children }: { label: string | undefined; children: ReactNode }) {
+  const messages = useToolkitMessages()
+  return (
+    <details className="text-small">
+      <summary className={`w-fit cursor-pointer rounded-sm py-0.5 select-none ${FOCUS_RING}`}>
+        {label ?? messages.common.details}
+      </summary>
+      <pre className="mt-1 font-mono break-words whitespace-pre-wrap">{children}</pre>
+    </details>
+  )
+}
+
+function ErrorActions({
+  onRetry,
+  retryLabel,
+  retryVariant,
+  actions,
+}: {
+  onRetry: (() => void) | undefined
+  retryLabel: string | undefined
+  retryVariant: "default" | "outline"
+  actions: ReactNode
+}) {
+  const messages = useToolkitMessages()
+  if (!onRetry && !actions) return null
+  return (
+    <div className="mt-2 flex flex-wrap items-center gap-2">
+      {onRetry && (
+        <Button type="button" size="sm" variant={retryVariant} onClick={onRetry}>
+          <RefreshCw aria-hidden="true" />
+          {retryLabel ?? messages.common.retry}
+        </Button>
+      )}
+      {actions}
+    </div>
+  )
+}

package/src/components/FilterBar.test.tsx

@@ -0,0 +1,82 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { LocaleProvider } from "../locale/locale-provider.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { attribute, openingTags } from "../render-scan.js"
+import { FOCUS_RING } from "../lib/focus-ring.js"
+import { TONE_BORDER, TONE_SOFT } from "../lib/tone-utils.js"
+import { FilterBar } from "./FilterBar.js"
+
+const noop = (): void => {}
+const classOf = (tag: string | undefined) => attribute(tag ?? "", "class") ?? ""
+
+function render(props: Partial<Parameters<typeof FilterBar>[0]> = {}, locale = "en") {
+  return renderToStaticMarkup(
+    <LocaleProvider locale={locale}>
+      <FilterBar
+        search=""
+        onSearchChange={noop}
+        chips={[
+          { id: "open", label: "Open", count: 3, active: true },
+          { id: "done", label: "Done" },
+        ]}
+        onChipToggle={noop}
+        {...props}
+      />
+    </LocaleProvider>,
+  )
+}
+
+describe("FilterBar: a labelled search and toggle chips", () => {
+  it("labels the search input in the locale (a placeholder is no label)", () => {
+    const [input] = openingTags(render(), "input")
+    expect(attribute(input ?? "", "type")).toBe("search")
+    expect(attribute(input ?? "", "aria-label")).toBe(TOOLKIT_MESSAGES.en.filterBar.searchLabel)
+    expect(attribute(input ?? "", "placeholder")).toBe("Filter…")
+    const [german] = openingTags(render({}, "de-DE"), "input")
+    expect(attribute(german ?? "", "aria-label")).toBe("Filtern")
+    expect(attribute(german ?? "", "placeholder")).toBe("Filtern…")
+  })
+
+  it("takes the caller's search label and placeholder", () => {
+    const [input] = openingTags(
+      render({ searchAriaLabel: "Filter tasks", searchPlaceholder: "Filter tasks…" }),
+      "input",
+    )
+    expect(attribute(input ?? "", "aria-label")).toBe("Filter tasks")
+    expect(attribute(input ?? "", "placeholder")).toBe("Filter tasks…")
+  })
+
+  it("groups the chips under a name and marks each one's state with aria-pressed", () => {
+    const html = render()
+    const group = openingTags(html, "div").find((t) => attribute(t, "role") === "group")
+    expect(attribute(group ?? "", "aria-label")).toBe("Filters")
+    expect(
+      attribute(openingTags(render({ chipsAriaLabel: "Priority" }), "div")[1] ?? "", "aria-label"),
+    ).toBe("Priority")
+    const [open, done] = openingTags(html, "button")
+    expect(attribute(open ?? "", "aria-pressed")).toBe("true")
+    expect(attribute(done ?? "", "aria-pressed")).toBe("false")
+    for (const chip of [open, done]) {
+      expect(attribute(chip ?? "", "type")).toBe("button")
+      expect(classOf(chip)).toContain(FOCUS_RING)
+      expect(classOf(chip)).toContain("text-small")
+    }
+  })
+
+  it("shows the active chip as a selection: info tint and edge around foreground text", () => {
+    const [open, done] = openingTags(render(), "button")
+    expect(classOf(open)).toContain(TONE_SOFT.info)
+    expect(classOf(open)).toContain(TONE_BORDER.info)
+    expect(classOf(open)).not.toMatch(/text-info|text-accent-foreground/)
+    expect(classOf(done)).toContain("text-muted-foreground")
+    expect(classOf(done)).not.toContain("bg-info-soft")
+  })
+
+  it("renders no empty group without chips and merges a className", () => {
+    const html = render({ chips: [], className: "mb-4" })
+    expect(html).not.toContain('role="group"')
+    expect(classOf(openingTags(html, "div")[0])).toContain("mb-4")
+    expect(html).not.toMatch(/text-xs|text-\[\d+px\]/)
+  })
+})

package/src/components/FilterBar.tsx

@@ -1,68 +1,97 @@
+import { FOCUS_RING } from "../lib/focus-ring.js"
+import { TONE_BORDER, TONE_SOFT } from "../lib/tone-utils.js"
+import { cn } from "../lib/utils.js"
+import { useToolkitMessages } from "../locale/locale-provider.js"
 import { Input } from "../primitives/input.js"
 
 export interface FilterChip {
   /** Stable id passed back to `onChipToggle`. */
   id: string
-  /** Visible chip label. */
+  /** Visible chip label (its accessible name, with the count). */
   label: string
   /** Optional count rendered after the label. */
   count?: number | string
-  /** Whether the chip is currently active. */
+  /** Whether the chip is currently active (`aria-pressed`). */
   active?: boolean
 }
 
 export interface FilterBarProps {
   /** Current search text (controlled). */
   search: string
-  /** Placeholder for the search input. Default `"Filter…"`. */
+  /** Placeholder for the search input. Default: the locale's "Filter…". */
   searchPlaceholder?: string
+  /**
+   * Accessible name of the search input. Default: the locale's "Filter" — a
+   * placeholder is no label (it disappears while you type).
+   */
+  searchAriaLabel?: string
   /** Called with the new search text on every keystroke. */
   onSearchChange: (next: string) => void
   /** Filter chips rendered to the right of the search input. */
   chips: FilterChip[]
   /** Called with a chip id when it is toggled. */
   onChipToggle: (id: string) => void
+  /** Names the chip row (`role="group"`). Default: the locale's "Filters". */
+  chipsAriaLabel?: string
+  className?: string
 }
 
 /**
  * Search input + toggleable chip row for filtering a list/table of widget
- * items. Pair with `useDebouncedValue` to avoid re-querying on every keystroke.
+ * items. The input is labelled; every chip is a toggle button whose state is
+ * `aria-pressed`. An active chip is a selection in the CI pattern: the info
+ * tint and edge around foreground text. Pair with `useDebouncedValue` to
+ * avoid re-querying on every keystroke.
  */
 export function FilterBar({
   search,
-  searchPlaceholder = "Filter…",
+  searchPlaceholder,
+  searchAriaLabel,
   onSearchChange,
   chips,
   onChipToggle,
+  chipsAriaLabel,
+  className,
 }: FilterBarProps) {
+  const { filterBar } = useToolkitMessages()
   return (
-    <div className="flex flex-wrap items-center gap-2">
+    <div data-slot="filter-bar" className={cn("flex flex-wrap items-center gap-2", className)}>
       <Input
         type="search"
         value={search}
         onChange={(e) => onSearchChange(e.target.value)}
-        placeholder={searchPlaceholder}
-        className="h-9 min-w-[220px] flex-1 text-sm"
+        placeholder={searchPlaceholder ?? filterBar.searchPlaceholder}
+        aria-label={searchAriaLabel ?? filterBar.searchLabel}
+        className="text-dense md:text-dense h-9 min-w-[220px] flex-1"
       />
-      <div className="flex flex-wrap gap-1.5">
-        {chips.map((chip) => (
-          <button
-            type="button"
-            key={chip.id}
-            onClick={() => onChipToggle(chip.id)}
-            className={`inline-flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs font-medium transition-colors ${
-              chip.active
-                ? "bg-accent border-border text-accent-foreground font-semibold"
-                : "border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground"
-            }`}
-          >
-            {chip.label}
-            {chip.count !== undefined && chip.count !== "" && (
-              <span className="tabular-nums opacity-60">{chip.count}</span>
-            )}
-          </button>
-        ))}
-      </div>
+      {chips.length > 0 && (
+        <div
+          role="group"
+          aria-label={chipsAriaLabel ?? filterBar.chipsLabel}
+          className="flex flex-wrap gap-1.5"
+        >
+          {chips.map((chip) => (
+            <button
+              type="button"
+              key={chip.id}
+              onClick={() => onChipToggle(chip.id)}
+              aria-pressed={Boolean(chip.active)}
+              className={cn(
+                "text-small inline-flex items-center gap-1.5 rounded-sm border px-2.5 py-1 font-medium transition-colors",
+                FOCUS_RING,
+                chip.active
+                  ? cn(TONE_SOFT.info, TONE_BORDER.info, "font-semibold")
+                  : "border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground",
+              )}
+            >
+              {chip.label}
+              {chip.count !== undefined && chip.count !== "" && (
+                <span className="font-normal tabular-nums">{chip.count}</span>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
     </div>
   )
 }

package/src/components/GroupCard.tsx

@@ -1,4 +1,5 @@
 import type { KeyboardEvent, MouseEvent, ReactNode } from "react"
+import { FOCUS_RING_INSET } from "../lib/focus-ring.js"
 
 export interface GroupCardProps {
   /** Whether the body is expanded. */
@@ -33,14 +34,14 @@ export function GroupCard({ expanded, onToggle, summary, children }: GroupCardPr
   }
 
   return (
-    <div className="border-border mb-2 overflow-hidden rounded-lg border">
+    <div className="border-border mb-2 overflow-hidden rounded-md border">
       <div
         role="button"
         tabIndex={0}
         aria-expanded={expanded}
         onClick={handleClick}
         onKeyDown={handleKeyDown}
-        className={`bg-card hover:bg-muted focus-visible:ring-ring/50 cursor-pointer transition-colors focus:outline-none focus-visible:ring-2 ${
+        className={`bg-card hover:bg-muted cursor-pointer transition-colors ${FOCUS_RING_INSET} ${
           expanded ? "border-border border-b" : ""
         }`}
       >