@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/app/widget-props-sheet.tsx

@@ -16,6 +16,10 @@ import {
   SheetTitle,
 } from "../primitives/sheet.js"
 import { Switch } from "../primitives/switch.js"
+import { useToolkitMessages } from "../locale/locale-provider.js"
+import type { PropsSheetMessages } from "../locale/toolkit-messages.js"
+import { propFieldText, type PropFieldText } from "./builder/builder-model.js"
+import { useDisplayResolver } from "./builder/use-display-resolver.js"
 
 /**
  * Tiny JSON-Schema-driven editor for a layout cell's `props`. The
@@ -29,6 +33,12 @@ import { Switch } from "../primitives/switch.js"
  *   - Nested objects/arrays/$ref/anyOf are not supported — the field
  *     shows an "edit JSON manually" hint so authors know to fall back.
  *
+ * Each field is labelled in user words: the property's `x-display` title
+ * (`PROPS_SCHEMA_DISPLAY_KEYWORD`, a key or per-locale text), else its JSON
+ * Schema `title`, else its name; the raw property name then follows as a
+ * quiet hint, and the help line is the `x-display` summary or the
+ * `description`.
+ *
  * The sheet writes a clean `Record<string, unknown>` (empty values
  * stripped) and reports `undefined` when the user clears every field, so
  * the cell's `props` field stays absent rather than `{}` — matches the
@@ -37,6 +47,7 @@ import { Switch } from "../primitives/switch.js"
 
 interface JsonSchemaProperty {
   type?: string
+  title?: string
   description?: string
   enum?: unknown[]
   default?: unknown
@@ -48,25 +59,8 @@ interface JsonSchemaObject {
   required?: string[]
 }
 
-export interface WidgetPropsSheetLabels {
-  title?: string
-  description?: string
-  apply?: string
-  cancel?: string
-  reset?: string
-  noProps?: string
-  unsetOption?: string
-}
-
-const DEFAULT_LABELS: Required<WidgetPropsSheetLabels> = {
-  title: "Configure widget",
-  description: "Set per-instance props for this widget.",
-  apply: "Apply",
-  cancel: "Cancel",
-  reset: "Reset",
-  noProps: "This widget takes no per-instance props.",
-  unsetOption: "(unset)",
-}
+/** Override strings of the sheet; each defaults to the locale's `propsSheet` catalog. */
+export type WidgetPropsSheetLabels = Partial<PropsSheetMessages>
 
 const UNSET_SENTINEL = "__unset__"
 
@@ -74,6 +68,8 @@ export interface WidgetPropsSheetProps {
   open: boolean
   onOpenChange: (open: boolean) => void
   widgetId: string
+  /** The widget's human name (its title); the id then shows as a quiet hint under it. */
+  widgetTitle?: string
   schema: Record<string, unknown> | undefined
   value: Record<string, unknown> | undefined
   onApply: (next: Record<string, unknown> | undefined) => void
@@ -84,12 +80,15 @@ export function WidgetPropsSheet({
   open,
   onOpenChange,
   widgetId,
+  widgetTitle,
   schema,
   value,
   onApply,
   labels,
 }: WidgetPropsSheetProps) {
-  const L = { ...DEFAULT_LABELS, ...labels }
+  const messages = useToolkitMessages()
+  const { locale, resolveKey } = useDisplayResolver()
+  const L = { ...messages.propsSheet, ...labels }
   const obj = (schema ?? {}) as JsonSchemaObject
   const [draft, setDraft] = useState<Record<string, unknown>>(value ?? {})
 
@@ -121,9 +120,10 @@ export function WidgetPropsSheet({
       <SheetContent className="w-[400px] sm:max-w-md">
         <SheetHeader>
           <SheetTitle>{L.title}</SheetTitle>
-          <SheetDescription>
-            <span className="bg-muted rounded px-1 font-mono text-xs">{widgetId}</span> —{" "}
-            {L.description}
+          <SheetDescription className="flex flex-col items-start gap-1">
+            <span>{L.description}</span>
+            {widgetTitle && <span className="text-foreground font-medium">{widgetTitle}</span>}
+            <span className="bg-muted text-small rounded px-1 font-mono">{widgetId}</span>
           </SheetDescription>
         </SheetHeader>
         <div className="flex flex-col gap-4 px-4 py-4">
@@ -134,9 +134,11 @@ export function WidgetPropsSheet({
               <PropertyField
                 key={key}
                 name={key}
+                text={propFieldText(key, prop as Record<string, unknown>, locale, resolveKey)}
                 prop={prop}
                 value={draft[key]}
                 unsetLabel={L.unsetOption}
+                unsupportedLabel={L.unsupportedType}
                 onChange={(v) =>
                   setDraft((prev) => {
                     if (v === undefined) {
@@ -169,15 +171,19 @@ export function WidgetPropsSheet({
 
 function PropertyField({
   name,
+  text,
   prop,
   value,
   unsetLabel,
+  unsupportedLabel,
   onChange,
 }: {
   name: string
+  text: PropFieldText
   prop: JsonSchemaProperty
   value: unknown
   unsetLabel: string
+  unsupportedLabel: (type: string) => string
   onChange: (v: unknown) => void
 }) {
   const id = `prop-${name}`
@@ -186,12 +192,12 @@ function PropertyField({
     const options = prop.enum.filter((v): v is string => typeof v === "string")
     const current = typeof value === "string" && value !== "" ? value : UNSET_SENTINEL
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Select
           value={current}
           onValueChange={(v) => onChange(v === UNSET_SENTINEL ? undefined : v)}
         >
-          <SelectTrigger id={id}>
+          <SelectTrigger id={id} aria-describedby={helpId(id, text)}>
             <SelectValue placeholder={unsetLabel} />
           </SelectTrigger>
           <SelectContent>
@@ -210,9 +216,10 @@ function PropertyField({
   if (prop.type === "string") {
     const current = typeof value === "string" ? value : ""
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Input
           id={id}
+          aria-describedby={helpId(id, text)}
           value={current}
           onChange={(e) => onChange(e.target.value === "" ? undefined : e.target.value)}
         />
@@ -223,9 +230,10 @@ function PropertyField({
   if (prop.type === "number" || prop.type === "integer") {
     const current = typeof value === "number" ? String(value) : ""
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Input
           id={id}
+          aria-describedby={helpId(id, text)}
           type="number"
           value={current}
           onChange={(e) => {
@@ -243,9 +251,10 @@ function PropertyField({
   if (prop.type === "boolean") {
     const current = value === true
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Switch
           id={id}
+          aria-describedby={helpId(id, text)}
           checked={current}
           onCheckedChange={(checked) => onChange(checked || undefined)}
         />
@@ -254,32 +263,51 @@ function PropertyField({
   }
 
   return (
-    <FieldShell id={id} name={name} description={prop.description}>
-      <p className="text-muted-foreground text-xs italic">
-        Unsupported type "{prop.type ?? "(none)"}" — edit raw JSON to set this field.
+    <FieldShell id={id} text={text}>
+      <p className="text-muted-foreground text-small italic">
+        {unsupportedLabel(prop.type ?? "?")}
       </p>
     </FieldShell>
   )
 }
 
+/** The id of a field's help line, when it has one (its `aria-describedby`). */
+function helpId(id: string, text: PropFieldText): string | undefined {
+  return text.help ? `${id}-help` : undefined
+}
+
+/**
+ * Label (the human title), the raw property name as a quiet hint beside it
+ * (outside the label, so the accessible name stays the title), the control,
+ * and the help line it is described by.
+ */
 function FieldShell({
   id,
-  name,
-  description,
+  text,
   children,
 }: {
   id: string
-  name: string
-  description?: string
+  text: PropFieldText
   children: ReactNode
 }) {
   return (
     <div className="flex flex-col gap-1.5">
-      <label htmlFor={id} className="text-sm font-medium">
-        {name}
-      </label>
+      <div className="flex flex-wrap items-baseline gap-x-2">
+        <label htmlFor={id} className="text-sm font-medium">
+          {text.label}
+        </label>
+        {text.hint && (
+          <code data-slot="prop-name" className="text-muted-foreground text-small font-mono">
+            {text.hint}
+          </code>
+        )}
+      </div>
       {children}
-      {description ? <p className="text-muted-foreground text-xs">{description}</p> : null}
+      {text.help ? (
+        <p id={helpId(id, text)} className="text-muted-foreground text-small">
+          {text.help}
+        </p>
+      ) : null}
     </div>
   )
 }

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="text-small mt-1 font-mono 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) {