@miragon/mcp-toolkit-ui 2.6.0 → 2.7.0

package/src/app/widget-renderer.render.test.tsx

@@ -0,0 +1,131 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it, vi } from "vitest"
+import type { WidgetProps } from "@miragon/mcp-toolkit-core"
+import { LocaleProvider } from "../locale/locale-provider.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { decodeEntities } from "../render-scan.js"
+import {
+  buildPipelineContext,
+  RenderedWidget,
+  resetKeysChanged,
+  WidgetCrashFallback,
+  WidgetErrorBoundary,
+  WidgetRenderer,
+} from "./widget-renderer.js"
+
+const de = TOOLKIT_MESSAGES.de.renderer
+
+function Hello({ keys }: WidgetProps) {
+  return <p>hello {typeof keys.who === "string" ? keys.who : ""}</p>
+}
+
+describe("WidgetRenderer fallbacks (toolkit#176 N24, U19)", () => {
+  it("an unknown widget id renders a localized 'not available' note instead of vanishing", () => {
+    const html = renderToStaticMarkup(
+      <LocaleProvider locale="de">
+        <WidgetRenderer
+          layout={{ rows: [{ row: [{ widget: "demo:hello" }, { widget: "demo:gone" }] }] }}
+          keys={{ who: "ada" }}
+          errors={[]}
+          widgets={{ "demo:hello": Hello }}
+        />
+      </LocaleProvider>,
+    )
+    expect(html).toContain("hello ada")
+    expect(decodeEntities(html)).toContain(de.widgetUnavailable)
+    expect(html).toContain('data-widget-id="demo:gone"')
+  })
+
+  it("the crash fallback names what happened, keeps the raw error under Details, offers a retry", () => {
+    const html = decodeEntities(
+      renderToStaticMarkup(
+        <LocaleProvider locale="de">
+          <WidgetCrashFallback widgetId="demo:x" error={new Error("kaputt")} onRetry={() => {}} />
+        </LocaleProvider>,
+      ),
+    )
+    expect(html).toContain('role="alert"')
+    expect(html).toContain(de.widgetCrashed)
+    expect(html).toContain("demo:x: kaputt")
+    expect(html).toContain(`${TOOLKIT_MESSAGES.de.common.retry}</button>`)
+  })
+
+  it("the builder's empty-context hint is localized", () => {
+    const html = renderToStaticMarkup(
+      <LocaleProvider locale="de">
+        <RenderedWidget
+          widget={Hello}
+          widgetId="demo:hello"
+          props={{ keys: {}, context: { steps: {}, keys: {}, errors: [] } }}
+          showEmptyHint
+        />
+      </LocaleProvider>,
+    )
+    expect(html).toContain(TOOLKIT_MESSAGES.de.renderer.noDataYet)
+  })
+})
+
+describe("WidgetErrorBoundary reset", () => {
+  it("resets a latched crash when its reset keys change, not on an unrelated update", () => {
+    const keysA = [{ a: 1 }]
+    const boundary = new WidgetErrorBoundary({ widgetId: "w", children: null, resetKeys: keysA })
+    const setState = vi.fn()
+    boundary.setState = setState
+    boundary.state = { error: new Error("boom") }
+
+    // Same keys (identity) → stays failed.
+    boundary.componentDidUpdate({ resetKeys: keysA })
+    expect(setState).not.toHaveBeenCalled()
+
+    // New data → a fresh render.
+    boundary.componentDidUpdate({ resetKeys: [{ a: 1 }] })
+    expect(setState).toHaveBeenCalledWith({ error: null })
+  })
+
+  it("does nothing while healthy", () => {
+    const boundary = new WidgetErrorBoundary({ widgetId: "w", children: null, resetKeys: [1] })
+    const setState = vi.fn()
+    boundary.setState = setState
+    boundary.componentDidUpdate({ resetKeys: [2] })
+    expect(setState).not.toHaveBeenCalled()
+  })
+
+  it("its retry clears the error", () => {
+    const boundary = new WidgetErrorBoundary({ widgetId: "w", children: null })
+    const setState = vi.fn()
+    boundary.setState = setState
+    boundary.reset()
+    expect(setState).toHaveBeenCalledWith({ error: null })
+  })
+})
+
+describe("resetKeysChanged", () => {
+  it("compares by length and entry identity", () => {
+    const a = { x: 1 }
+    expect(resetKeysChanged([a], [a])).toBe(false)
+    expect(resetKeysChanged(undefined, undefined)).toBe(false)
+    const same = [a]
+    expect(resetKeysChanged(same, same)).toBe(false)
+    expect(resetKeysChanged([a], [{ x: 1 }])).toBe(true)
+    expect(resetKeysChanged([a], [a, a])).toBe(true)
+    expect(resetKeysChanged(undefined, [a])).toBe(true)
+    expect(resetKeysChanged([a], undefined)).toBe(true)
+    expect(resetKeysChanged([Number.NaN], [Number.NaN])).toBe(false)
+  })
+})
+
+describe("buildPipelineContext", () => {
+  it("tags each step with its id and passes keys and errors through", () => {
+    const keys = { k: 1 }
+    const errors = [{ stepId: "s2", reason: "x" }]
+    const ctx = buildPipelineContext(
+      keys,
+      { s1: { data: 1, keys: {}, _app: "a", _dataType: "a:t" } },
+      errors,
+    )
+    expect(ctx.steps.s1).toEqual({ data: 1, keys: {}, _app: "a", _dataType: "a:t", _step: "s1" })
+    expect(ctx.keys).toBe(keys)
+    expect(ctx.errors).toBe(errors)
+    expect(buildPipelineContext(keys, undefined, []).steps).toEqual({})
+  })
+})

package/src/app/widget-renderer.tsx

@@ -1,46 +1,136 @@
-import { Component, type ComponentType, type ReactNode, type ErrorInfo } from "react"
+import {
+  Component,
+  createRef,
+  useMemo,
+  type ComponentType,
+  type ReactNode,
+  type ErrorInfo,
+} from "react"
 import type { LayoutConfig, PipelineContext, RowDef, WidgetProps } from "@miragon/mcp-toolkit-core"
 import { normalizeLayout } from "@miragon/mcp-toolkit-core"
+import { ErrorState } from "../components/ErrorState.js"
 import { GridLayout, GridItem } from "../components/GridLayout.js"
-import { Card, CardContent } from "../primitives/card.js"
+import { useToolkitMessages } from "../locale/locale-provider.js"
 import { Tabs, TabsList, TabsTrigger, TabsContent } from "../primitives/tabs.js"
 
 export type WidgetComponent = ComponentType<WidgetProps>
 
+/**
+ * True when two reset-key lists differ (length or any entry by identity).
+ * Exported for tests: it decides when a crashed widget gets a fresh render.
+ */
+export function resetKeysChanged(
+  prev: readonly unknown[] | undefined,
+  next: readonly unknown[] | undefined,
+): boolean {
+  if (prev === next) return false
+  if (!prev || !next || prev.length !== next.length) return true
+  return prev.some((value, idx) => !Object.is(value, next[idx]))
+}
+
 /**
  * Catches render-time crashes from a single widget so one broken widget
  * can't take down the entire iframe view (or the builder canvas/preview).
  *
+ * The fallback is localized, names what happened, keeps the raw error under
+ * "Details" and offers a retry. The boundary resets itself when its
+ * `resetKeys` change, so new data (a refresh, a new tool result, a builder
+ * edit) gets a fresh render instead of a latched failure (toolkit#176 N24).
+ * When a retry crashes again, keyboard focus moves to the new retry button
+ * instead of falling back to the document (the pressed one unmounted). After
+ * a retry that renders, the widget's own markup is unknown here, so focus
+ * returns to the document.
+ *
  * Exported so the visual builder's canvas + preview render sites reuse the
  * same isolation the rendered `WidgetRenderer` already had — every place a
  * widget component is rendered goes through {@link RenderedWidget}, which
  * wraps the component in this boundary.
  */
 export class WidgetErrorBoundary extends Component<
-  { widgetId: string; children: ReactNode },
+  { widgetId: string; children: ReactNode; resetKeys?: readonly unknown[] },
   { error: Error | null }
 > {
   override state: { error: Error | null } = { error: null }
+  /** Set by the user's retry; consumed by the next update. */
+  private retryFocusOwed = false
+  private readonly fallbackRef = createRef<HTMLDivElement>()
   static getDerivedStateFromError(error: Error) {
     return { error }
   }
   override componentDidCatch(error: Error, info: ErrorInfo) {
     console.error(`Widget ${this.props.widgetId} crashed:`, error, info)
   }
+  override componentDidUpdate(prevProps: { resetKeys?: readonly unknown[] }) {
+    if (this.retryFocusOwed) {
+      this.retryFocusOwed = false
+      if (this.state.error) this.fallbackRef.current?.querySelector<HTMLElement>("button")?.focus()
+    }
+    if (this.state.error && resetKeysChanged(prevProps.resetKeys, this.props.resetKeys)) {
+      this.reset()
+    }
+  }
+  reset = () => {
+    this.setState({ error: null })
+  }
+  /** The fallback's retry: a reset that keeps keyboard focus if the widget crashes again. */
+  retry = () => {
+    this.retryFocusOwed = true
+    this.reset()
+  }
   override render() {
     if (this.state.error) {
       return (
-        <Card>
-          <CardContent className="text-muted-foreground py-3 text-sm">
-            Widget "{this.props.widgetId}" failed to render.
-          </CardContent>
-        </Card>
+        <div ref={this.fallbackRef} data-slot="widget-crash">
+          <WidgetCrashFallback
+            widgetId={this.props.widgetId}
+            error={this.state.error}
+            onRetry={this.retry}
+          />
+        </div>
       )
     }
     return this.props.children
   }
 }
 
+/** The localized crash fallback of {@link WidgetErrorBoundary}. */
+export function WidgetCrashFallback({
+  widgetId,
+  error,
+  onRetry,
+}: {
+  widgetId: string
+  error: Error
+  onRetry: () => void
+}) {
+  const messages = useToolkitMessages()
+  return (
+    <ErrorState
+      variant="inline"
+      title={messages.renderer.widgetCrashed}
+      details={`${widgetId}: ${error.message}`}
+      onRetry={onRetry}
+    />
+  )
+}
+
+/** A layout cell names a widget the bundle does not contain: say so, quietly. */
+export function UnavailableWidget({
+  widgetId,
+  className = "text-muted-foreground rounded-md border border-dashed p-4 text-sm",
+}: {
+  widgetId: string
+  className?: string
+}) {
+  const messages = useToolkitMessages()
+  return (
+    <div data-slot="widget-unavailable" data-widget-id={widgetId} className={className}>
+      <p>{messages.renderer.widgetUnavailable}</p>
+      <p className="mt-1 font-mono text-xs break-all">{widgetId}</p>
+    </div>
+  )
+}
+
 /**
  * True when the pipeline context carries no widget data at all — no step
  * results and no keys. A widget rendered against an empty context typically
@@ -59,7 +149,7 @@ export function contextHasNoData(context: PipelineContext): boolean {
  * The single render site for a layout cell's widget, shared across the
  * rendered view (`RowsRenderer`), the builder canvas, and the builder
  * preview so all three isolate crashes identically:
- *   - missing component → "not bundled" fallback,
+ *   - missing component → a localized "not available in this version" note,
  *   - render crash → caught by {@link WidgetErrorBoundary} (Finding [1]),
  *   - (builder only, opt-in) empty pipeline context → a dezent
  *     "no data yet" hint (Finding [4]).
@@ -79,7 +169,7 @@ export function RenderedWidget({
   props,
   cellProps,
   showEmptyHint = false,
-  notBundledClassName = "text-muted-foreground rounded border border-dashed p-4 text-center text-xs",
+  notBundledClassName,
 }: {
   widget: WidgetComponent | undefined
   widgetId: string
@@ -88,23 +178,26 @@ export function RenderedWidget({
   showEmptyHint?: boolean
   notBundledClassName?: string
 }) {
-  if (!Widget) {
-    return <div className={notBundledClassName}>Widget "{widgetId}" not bundled.</div>
-  }
+  if (!Widget) return <UnavailableWidget widgetId={widgetId} className={notBundledClassName} />
   if (showEmptyHint && contextHasNoData(props.context)) {
-    return (
-      <div className={notBundledClassName}>
-        No data for this widget yet — it appears after a refresh.
-      </div>
-    )
+    return <NoDataYet className={notBundledClassName} />
   }
   return (
-    <WidgetErrorBoundary widgetId={widgetId}>
+    <WidgetErrorBoundary widgetId={widgetId} resetKeys={[props.context, props.keys, cellProps]}>
       <Widget {...props} widgetProps={cellProps} />
     </WidgetErrorBoundary>
   )
 }
 
+function NoDataYet({
+  className = "text-muted-foreground rounded-md border border-dashed p-4 text-sm",
+}: {
+  className?: string
+}) {
+  const messages = useToolkitMessages()
+  return <div className={className}>{messages.renderer.noDataYet}</div>
+}
+
 export interface WidgetRendererProps {
   layout: LayoutConfig
   keys: Record<string, unknown>
@@ -137,14 +230,11 @@ function RowsRenderer({
         <GridLayout key={rowIdx}>
           {row.row.map((cell, cellIdx) => {
             const WidgetComponent = widgets[cell.widget]
-            // Keep the rendered view's original behaviour of skipping cells
-            // whose component isn't bundled (no placeholder in the shipped
-            // view), while still routing the resolvable ones through the
-            // shared `RenderedWidget` for error-boundary + empty-state.
-            if (!WidgetComponent) return null
-            // Use a composite key so the same widget can appear in multiple
-            // cells of one row (e.g. side-by-side scoped dashboards) without
-            // colliding on React's reconciliation key.
+            // An unknown widget id renders the localized "not available"
+            // note in its cell instead of vanishing (an empty page reads as
+            // broken). The composite key lets the same widget appear in
+            // several cells of one row (e.g. side-by-side scoped dashboards)
+            // without colliding on React's reconciliation key.
             return (
               <GridItem key={`${cell.widget}-${cellIdx}`} span={cell.span ?? 12}>
                 <RenderedWidget
@@ -162,19 +252,27 @@ function RowsRenderer({
   )
 }
 
-export function WidgetRenderer({ layout, keys, stepData, errors, widgets }: WidgetRendererProps) {
+/**
+ * The pipeline context widgets read. `WidgetRenderer` rebuilds it only when
+ * the view data changes — its identity is the error boundaries' reset key.
+ */
+export function buildPipelineContext(
+  keys: Record<string, unknown>,
+  stepData: WidgetRendererProps["stepData"],
+  errors: WidgetRendererProps["errors"],
+): PipelineContext {
   const steps: Record<string, PipelineContext["steps"][string]> = {}
-  if (stepData) {
-    for (const [id, result] of Object.entries(stepData)) {
-      steps[id] = { ...result, _step: id }
-    }
+  for (const [id, result] of Object.entries(stepData ?? {})) {
+    steps[id] = { ...result, _step: id }
   }
-  const pipelineContext: PipelineContext = {
-    steps,
-    keys,
-    errors,
-  }
-  const widgetProps: WidgetProps = { keys, context: pipelineContext }
+  return { steps, keys, errors }
+}
+
+export function WidgetRenderer({ layout, keys, stepData, errors, widgets }: WidgetRendererProps) {
+  const widgetProps = useMemo<WidgetProps>(
+    () => ({ keys, context: buildPipelineContext(keys, stepData, errors) }),
+    [keys, stepData, errors],
+  )
   const normalized = normalizeLayout(layout)
 
   if ("tabs" in normalized) {

package/src/components/DrillButton.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react"
+import { FOCUS_RING } from "../lib/focus-ring.js"
 
 export interface DrillButtonProps {
   /** Button label. */
@@ -27,7 +28,7 @@ export function DrillButton({ children, onDrill, icon, size = "sm", ariaLabel }:
       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={`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 ${FOCUS_RING} ${pad}`}
     >
       {icon && <span aria-hidden="true">{icon}</span>}
       {children}

package/src/components/EmptyState.tsx

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react"
+import { 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) {
+  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[tone],
+          )}
+        >
+          {icon}
+        </div>
+      )}
+      <Title className="text-foreground text-base font-semibold">{title}</Title>
+      {description && (
+        <p className="text-muted-foreground max-w-prose text-sm 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,182 @@
+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 { 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. */
+  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,
+}
+
+/** Per-variant geometry: `block` replaces a surface, `inline` sits above content. */
+const VARIANT = {
+  block: {
+    box: "gap-4 p-4",
+    icon: "size-5",
+    title: "text-base",
+    defaultTitleAs: "h2",
+    retry: "default",
+  },
+  inline: {
+    box: "gap-3 px-4 py-3 text-sm",
+    icon: "size-4",
+    title: "text-sm",
+    defaultTitleAs: "p",
+    retry: "outline",
+  },
+} as const satisfies Record<
+  NonNullable<ErrorStateProps["variant"]>,
+  {
+    box: string
+    icon: string
+    title: 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 = "danger",
+  icon,
+  variant = "block",
+  role = "alert",
+  titleAs,
+  className,
+}: ErrorStateProps) {
+  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="text-sm break-words">{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-xs">
+      <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>
+  )
+}