@miragon/mcp-toolkit-ui 2.5.0 → 2.7.0

package/src/app/use-view-lifecycle.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useReducer, useRef, useState, type RefObject } from "react"
+import {
+  decodeViewResult,
+  errorMessage,
+  resolveViewLifecycle,
+  RETRY_IDLE,
+  retryFocusTarget,
+  retryReducer,
+  waitKey,
+  withSlowHint,
+  type RenderCallStatus,
+  type ViewLifecycle,
+} from "./view-lifecycle.js"
+
+export interface UseViewLifecycleOptions<T> {
+  hasViewData: boolean
+  callStatus: RenderCallStatus
+  cancelled: boolean
+  callError: unknown
+  recoveryFailed: boolean
+  /** The originating tool (`hostContext.toolInfo`); a retry needs it. */
+  toolName: string | undefined
+  toolInput: Record<string, unknown> | null | undefined
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+  isValid: (value: unknown) => value is T
+  /** Receives the payload of a successful retry. */
+  onResult: (data: T) => void
+  slowHintAfterMs: number
+}
+
+/**
+ * Drives the {@link resolveViewLifecycle} state machine: owns the retry and
+ * the slow-hint timer, and returns the current phase plus `retry()`.
+ */
+export function useViewLifecycle<T>(options: UseViewLifecycleOptions<T>): {
+  lifecycle: ViewLifecycle
+  retry: () => void
+} {
+  const { toolName, toolInput, callTool, isValid, onResult, slowHintAfterMs } = options
+  const [retryState, dispatch] = useReducer(retryReducer, RETRY_IDLE)
+  // The wait that went slow; a newer wait (another attempt) starts fresh.
+  const [slowWait, setSlowWait] = useState<string | null>(null)
+
+  const unslowed = resolveViewLifecycle({
+    hasViewData: options.hasViewData,
+    callStatus: options.callStatus,
+    cancelled: options.cancelled,
+    callErrorReason: errorMessage(options.callError),
+    recoveryFailed: options.recoveryFailed,
+    retryState,
+    slow: false,
+    canRetry: toolName !== undefined,
+  })
+  const currentWait = waitKey(unslowed, retryState)
+
+  useEffect(() => {
+    if (currentWait === null) return
+    const timer = setTimeout(() => setSlowWait(currentWait), slowHintAfterMs)
+    return () => clearTimeout(timer)
+  }, [currentWait, slowHintAfterMs])
+
+  const lifecycle = withSlowHint(unslowed, slowWait, currentWait)
+
+  const retry = useCallback(() => {
+    if (toolName === undefined) return
+    dispatch({ type: "start" })
+    void callTool(toolName, toolInput ?? {}).then(
+      (result) => {
+        const outcome = decodeViewResult(result, isValid)
+        if (outcome.ok) {
+          onResult(outcome.data)
+          dispatch({ type: "succeeded" })
+        } else {
+          dispatch({ type: "failed", reason: outcome.reason })
+        }
+      },
+      (err: unknown) => dispatch({ type: "failed", reason: errorMessage(err) }),
+    )
+  }, [callTool, isValid, onResult, toolInput, toolName])
+
+  return { lifecycle, retry }
+}
+
+/** The retry button of the view's error state (the focus target after a failed retry). */
+const RETRY_BUTTON = '[data-slot="error-state"] button'
+
+/**
+ * Keeps keyboard focus in the view across a user retry: the pressed button
+ * unmounts when the view starts waiting, so focus moves to the frame (a
+ * `tabIndex={-1}` container), then to the new retry button when the retry
+ * failed, or stays on the frame once the view rendered (see
+ * {@link retryFocusTarget}). Focus the user moved elsewhere meanwhile is left
+ * alone. Returns the frame ref and `retry` wrapped to start the hand-off.
+ */
+export function useRetryFocus(
+  phase: ViewLifecycle["phase"],
+  retry: () => void,
+): { frameRef: RefObject<HTMLDivElement | null>; retry: () => void } {
+  const frameRef = useRef<HTMLDivElement | null>(null)
+  const owed = useRef(false)
+  const retryWithFocus = useCallback(() => {
+    owed.current = true
+    retry()
+  }, [retry])
+  useEffect(() => {
+    const frame = frameRef.current
+    if (!owed.current || !frame) return
+    const { target, settled } = retryFocusTarget(phase)
+    if (settled) owed.current = false
+    const active = frame.ownerDocument.activeElement
+    if (active && active !== frame.ownerDocument.body && !frame.contains(active)) return
+    const button = target === "retry" ? frame.querySelector<HTMLElement>(RETRY_BUTTON) : null
+    ;(button ?? frame).focus()
+  }, [phase])
+  return { frameRef, retry: retryWithFocus }
+}

package/src/app/view-lifecycle.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest"
+import {
+  decodeViewResult,
+  DEFAULT_SLOW_HINT_MS,
+  errorMessage,
+  resolveViewLifecycle,
+  RETRY_IDLE,
+  retryFocusTarget,
+  retryReducer,
+  waitKey,
+  withSlowHint,
+  type RetryState,
+  type ViewLifecycleInput,
+} from "./view-lifecycle.js"
+
+/** The baseline: a rendering call still open on a host that knows the tool. */
+const waiting: ViewLifecycleInput = {
+  hasViewData: false,
+  callStatus: "pending",
+  cancelled: false,
+  callErrorReason: undefined,
+  recoveryFailed: false,
+  retryState: RETRY_IDLE,
+  slow: false,
+  canRetry: true,
+}
+
+const at = (over: Partial<ViewLifecycleInput>) => resolveViewLifecycle({ ...waiting, ...over })
+
+describe("resolveViewLifecycle (toolkit#176 state machine)", () => {
+  it("waits while the rendering call is open, slow once the hint delay passed", () => {
+    expect(at({})).toEqual({ phase: "waiting", slow: false })
+    expect(at({ slow: true })).toEqual({ phase: "waiting", slow: true })
+    // A latched-ready call without a complete payload (recovery in flight) still waits.
+    expect(at({ callStatus: "ready" })).toEqual({ phase: "waiting", slow: false })
+  })
+
+  it("an isError result is an error with its reason — never an endless wait (K14)", () => {
+    expect(at({ callStatus: "error", callErrorReason: "[503] engine down" })).toEqual({
+      phase: "error",
+      reason: "[503] engine down",
+      canRetry: true,
+    })
+  })
+
+  it("a failed stripped-result recovery is an error too (N22: a terminal state)", () => {
+    expect(at({ recoveryFailed: true })).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: true,
+    })
+  })
+
+  it("offers a retry only when the originating tool is known", () => {
+    expect(at({ callStatus: "error", canRetry: false })).toMatchObject({
+      phase: "error",
+      canRetry: false,
+    })
+  })
+
+  it("a latched non-view result nothing can recover is an error, not an endless wait", () => {
+    // No toolInfo: the recovery cannot re-run the tool, so the wait would never end.
+    expect(at({ callStatus: "ready", canRetry: false })).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: false,
+    })
+    // Still pending on such a host: the result may yet arrive.
+    expect(at({ callStatus: "pending", canRetry: false })).toEqual({
+      phase: "waiting",
+      slow: false,
+    })
+    // A running retry or a payload in hand still win.
+    expect(
+      at({ callStatus: "ready", canRetry: false, retryState: { status: "running", attempt: 1 } }),
+    ).toEqual({ phase: "waiting", slow: false })
+    expect(at({ callStatus: "ready", canRetry: false, hasViewData: true })).toEqual({
+      phase: "result",
+    })
+  })
+
+  it("a host cancellation is terminal and wins over the error status it latches as", () => {
+    expect(at({ cancelled: true, callStatus: "error", callErrorReason: "cancelled" })).toEqual({
+      phase: "cancelled",
+    })
+  })
+
+  it("a running retry waits (with its own slow flag), a failed retry shows ITS reason", () => {
+    const running: RetryState = { status: "running", attempt: 1 }
+    expect(at({ callStatus: "error", retryState: running })).toEqual({
+      phase: "waiting",
+      slow: false,
+    })
+    expect(at({ callStatus: "error", retryState: running, slow: true })).toEqual({
+      phase: "waiting",
+      slow: true,
+    })
+    const failed: RetryState = { status: "failed", attempt: 1, reason: "still down" }
+    expect(at({ callStatus: "error", callErrorReason: "first", retryState: failed })).toEqual({
+      phase: "error",
+      reason: "still down",
+      canRetry: true,
+    })
+    expect(at({ cancelled: true, retryState: failed, canRetry: false })).toEqual({
+      phase: "error",
+      reason: "still down",
+      canRetry: false,
+    })
+  })
+
+  it("a payload in hand always wins — the view renders", () => {
+    expect(at({ hasViewData: true, callStatus: "error", recoveryFailed: true })).toEqual({
+      phase: "result",
+    })
+    expect(at({ hasViewData: true, retryState: { status: "running", attempt: 2 } })).toEqual({
+      phase: "result",
+    })
+    expect(at({ hasViewData: true, cancelled: true })).toEqual({ phase: "result" })
+  })
+})
+
+describe("retryReducer", () => {
+  it("counts attempts: start runs the next one, failure keeps the count and the reason", () => {
+    const first = retryReducer(RETRY_IDLE, { type: "start" })
+    expect(first).toEqual({ status: "running", attempt: 1 })
+    const failed = retryReducer(first, { type: "failed", reason: "503" })
+    expect(failed).toEqual({ status: "failed", attempt: 1, reason: "503" })
+    const second = retryReducer(failed, { type: "start" })
+    expect(second).toEqual({ status: "running", attempt: 2 })
+    expect(retryReducer(second, { type: "succeeded" })).toEqual({ status: "idle", attempt: 2 })
+    expect(retryReducer(second, { type: "failed", reason: undefined })).toEqual({
+      status: "failed",
+      attempt: 2,
+      reason: undefined,
+    })
+  })
+})
+
+describe("waitKey", () => {
+  it("names each wait so the slow hint restarts per attempt and stops when not waiting", () => {
+    expect(waitKey({ phase: "waiting", slow: false }, RETRY_IDLE)).toBe("idle:0")
+    expect(waitKey({ phase: "waiting", slow: false }, { status: "running", attempt: 2 })).toBe(
+      "running:2",
+    )
+    expect(waitKey({ phase: "error", reason: undefined, canRetry: true }, RETRY_IDLE)).toBeNull()
+    expect(waitKey({ phase: "result" }, RETRY_IDLE)).toBeNull()
+    expect(waitKey({ phase: "cancelled" }, RETRY_IDLE)).toBeNull()
+  })
+
+  it("waits 8 s before the slow hint by default", () => {
+    expect(DEFAULT_SLOW_HINT_MS).toBe(8000)
+  })
+})
+
+describe("withSlowHint", () => {
+  const waiting = { phase: "waiting", slow: false } as const
+
+  it("turns the current wait slow once ITS delay passed", () => {
+    expect(withSlowHint(waiting, "idle:0", "idle:0")).toEqual({ phase: "waiting", slow: true })
+  })
+
+  it("keeps a new attempt and an unslowed wait without the hint", () => {
+    expect(withSlowHint(waiting, "idle:0", "running:1")).toBe(waiting)
+    expect(withSlowHint(waiting, null, "idle:0")).toBe(waiting)
+    expect(withSlowHint(waiting, null, null)).toBe(waiting)
+  })
+
+  it("never touches a phase that is not waiting", () => {
+    const error = { phase: "error", reason: "x", canRetry: true } as const
+    expect(withSlowHint(error, "idle:0", "idle:0")).toBe(error)
+    expect(withSlowHint({ phase: "result" }, "idle:0", "idle:0")).toEqual({ phase: "result" })
+  })
+})
+
+describe("retryFocusTarget", () => {
+  it("holds focus on the frame while the retry runs, then hands it on and settles", () => {
+    expect(retryFocusTarget("waiting")).toEqual({ target: "frame", settled: false })
+    expect(retryFocusTarget("error")).toEqual({ target: "retry", settled: true })
+    expect(retryFocusTarget("result")).toEqual({ target: "frame", settled: true })
+    expect(retryFocusTarget("cancelled")).toEqual({ target: "frame", settled: true })
+  })
+})
+
+describe("decodeViewResult", () => {
+  const isView = (v: unknown): v is { layout: unknown } =>
+    typeof v === "object" && v !== null && "layout" in v
+
+  it("returns the payload of a complete view", () => {
+    expect(decodeViewResult({ structuredContent: { layout: { rows: [] } } }, isView)).toEqual({
+      ok: true,
+      data: { layout: { rows: [] } },
+    })
+  })
+
+  it("types a tool error as such, with the isError text as the raw reason", () => {
+    expect(decodeViewResult({ isError: true, content: [{ text: "[503] down" }] }, isView)).toEqual({
+      ok: false,
+      isError: true,
+      reason: "[503] down",
+    })
+    // An isError result without text is still a tool error.
+    expect(decodeViewResult({ isError: true, content: [{ text: "" }] }, isView)).toEqual({
+      ok: false,
+      isError: true,
+      reason: undefined,
+    })
+  })
+
+  it("types a payload the shell cannot render as no view, without a reason", () => {
+    expect(decodeViewResult({ structuredContent: { other: 1 } }, isView)).toEqual({
+      ok: false,
+      isError: false,
+      reason: undefined,
+    })
+  })
+})
+
+describe("errorMessage", () => {
+  it("reads Error messages and strings, nothing else", () => {
+    expect(errorMessage(new Error("boom"))).toBe("boom")
+    expect(errorMessage(new Error(""))).toBeUndefined()
+    expect(errorMessage("plain")).toBe("plain")
+    expect(errorMessage("")).toBeUndefined()
+    expect(errorMessage({ message: "not an error" })).toBeUndefined()
+    expect(errorMessage(undefined)).toBeUndefined()
+  })
+})

package/src/app/view-lifecycle.ts

@@ -0,0 +1,174 @@
+/**
+ * The `McpAppView` lifecycle as an explicit state machine (toolkit#176).
+ *
+ * Before the view payload exists the shell is in exactly one phase:
+ *
+ *   waiting ──result──▶ result
+ *      │  ╲
+ *      │   ╲──tool error / failed recovery / unrecoverable result──▶ error ──retry──▶ waiting
+ *      │
+ *      └──host cancelled──▶ cancelled (terminal: the user stopped it)
+ *
+ * `waiting` carries a `slow` flag once loading outlasts the slow-hint delay.
+ * An `isError` result (or a failed call) is an `error`, never an endless
+ * skeleton, and a retry re-runs the originating tool once on the user's click.
+ * A latched result that is no view on a host that names no originating tool
+ * is an `error` too: nothing could recover it, so waiting would never end.
+ * Pure functions only: the hook in `use-view-lifecycle.ts` feeds them.
+ */
+import { parseToolResult } from "../lib/parse-tool-result.js"
+
+/** `useToolContext().status` of the rendering call. */
+export type RenderCallStatus = "pending" | "ready" | "error"
+
+/** The user-triggered retry of the rendering call. */
+export type RetryState =
+  | { status: "idle"; attempt: number }
+  | { status: "running"; attempt: number }
+  | { status: "failed"; attempt: number; reason: string | undefined }
+
+export const RETRY_IDLE: RetryState = { status: "idle", attempt: 0 }
+
+export type RetryAction =
+  { type: "start" } | { type: "failed"; reason: string | undefined } | { type: "succeeded" }
+
+/** start → running (next attempt); failed → failed with reason; succeeded → idle. */
+export function retryReducer(state: RetryState, action: RetryAction): RetryState {
+  switch (action.type) {
+    case "start":
+      return { status: "running", attempt: state.attempt + 1 }
+    case "failed":
+      return { status: "failed", attempt: state.attempt, reason: action.reason }
+    case "succeeded":
+      return { status: "idle", attempt: state.attempt }
+  }
+}
+
+export interface ViewLifecycleInput {
+  /** A renderable payload is in hand (host-delivered, recovered or retried). */
+  hasViewData: boolean
+  /** Status of the original rendering call. */
+  callStatus: RenderCallStatus
+  /** The host cancelled the original rendering call. */
+  cancelled: boolean
+  /** Message of the original call's error, when it failed. */
+  callErrorReason: string | undefined
+  /** The automatic stripped-result recovery ran and failed. */
+  recoveryFailed: boolean
+  /** The user-triggered retry. */
+  retryState: RetryState
+  /** Loading has outlasted the slow-hint delay. */
+  slow: boolean
+  /** The originating tool is known, so a retry can re-run it. */
+  canRetry: boolean
+}
+
+export type ViewLifecycle =
+  | { phase: "result" }
+  | { phase: "waiting"; slow: boolean }
+  | { phase: "cancelled" }
+  | { phase: "error"; reason: string | undefined; canRetry: boolean }
+
+/**
+ * Resolve the single phase the view is in. Precedence: a payload always wins;
+ * a running retry is waiting; a failed retry is an error with ITS reason; a
+ * cancellation is terminal; a failed call, a failed recovery or a latched
+ * non-view result nothing can recover is an error; everything else is still
+ * waiting.
+ */
+export function resolveViewLifecycle(input: ViewLifecycleInput): ViewLifecycle {
+  if (input.hasViewData) return { phase: "result" }
+  const { retryState } = input
+  if (retryState.status === "running") return { phase: "waiting", slow: input.slow }
+  if (retryState.status === "failed") {
+    return { phase: "error", reason: retryState.reason, canRetry: input.canRetry }
+  }
+  if (input.cancelled) return { phase: "cancelled" }
+  if (input.callStatus === "error") {
+    return { phase: "error", reason: input.callErrorReason, canRetry: input.canRetry }
+  }
+  if (input.recoveryFailed) return { phase: "error", reason: undefined, canRetry: input.canRetry }
+  // A latched result without a renderable view: the recovery re-runs the
+  // originating tool, so it can only help when the host names that tool.
+  if (input.callStatus === "ready" && !input.canRetry) {
+    return { phase: "error", reason: undefined, canRetry: false }
+  }
+  return { phase: "waiting", slow: input.slow }
+}
+
+/**
+ * The phase with its slow flag: a wait turns slow only while the wait that
+ * outlasted the delay (`slowWait`, a {@link waitKey}) is still the current one,
+ * so a new attempt starts without the hint.
+ */
+export function withSlowHint(
+  lifecycle: ViewLifecycle,
+  slowWait: string | null,
+  currentWait: string | null,
+): ViewLifecycle {
+  return lifecycle.phase === "waiting" && slowWait !== null && slowWait === currentWait
+    ? { phase: "waiting", slow: true }
+    : lifecycle
+}
+
+/**
+ * Where keyboard focus goes after the user pressed retry (the button unmounts
+ * as the view starts waiting): the view frame while waiting, the new retry
+ * button when the retry failed, the frame again once the view or a
+ * cancellation replaced the state. `settled` ends the hand-off.
+ */
+export function retryFocusTarget(phase: ViewLifecycle["phase"]): {
+  target: "frame" | "retry"
+  settled: boolean
+} {
+  if (phase === "waiting") return { target: "frame", settled: false }
+  if (phase === "error") return { target: "retry", settled: true }
+  return { target: "frame", settled: true }
+}
+
+/**
+ * Identity of the current wait, so the slow-hint timer restarts for every new
+ * wait (the first load, then each retry attempt) and never for a finished one.
+ * `null` when the view is not waiting.
+ */
+export function waitKey(lifecycle: ViewLifecycle, retryState: RetryState): string | null {
+  return lifecycle.phase === "waiting" ? `${retryState.status}:${retryState.attempt}` : null
+}
+
+/** Default delay before the waiting placeholder adds its slow hint. */
+export const DEFAULT_SLOW_HINT_MS = 8000
+
+/**
+ * A decoded view call (a retry or a refresh), typed so a failure never turns
+ * into UI text: `isError` tells a tool error (with its raw `reason`, for the
+ * Details disclosure or the console) from a payload that is no view.
+ */
+export type ViewResultOutcome<T> =
+  { ok: true; data: T } | { ok: false; isError: boolean; reason: string | undefined }
+
+/**
+ * Decode a view call's result: the payload when it is a complete view,
+ * otherwise a failure — a tool error with its `isError` text, or a payload
+ * the shell cannot render (no reason).
+ */
+export function decodeViewResult<T>(
+  result: unknown,
+  isValid: (value: unknown) => value is T,
+): ViewResultOutcome<T> {
+  let decoded: unknown
+  try {
+    decoded = parseToolResult<unknown>(result)
+  } catch (err) {
+    return { ok: false, isError: true, reason: errorMessage(err) }
+  }
+  return isValid(decoded)
+    ? { ok: true, data: decoded }
+    : { ok: false, isError: false, reason: undefined }
+}
+
+/** A displayable message for anything thrown. */
+export function errorMessage(err: unknown): string | undefined {
+  if (err instanceof Error) return err.message || undefined
+  if (typeof err === "string") return err || undefined
+  return undefined
+}

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

@@ -16,6 +16,8 @@ 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"
 
 /**
  * Tiny JSON-Schema-driven editor for a layout cell's `props`. The
@@ -48,25 +50,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__"
 
@@ -89,7 +74,8 @@ export function WidgetPropsSheet({
   onApply,
   labels,
 }: WidgetPropsSheetProps) {
-  const L = { ...DEFAULT_LABELS, ...labels }
+  const messages = useToolkitMessages()
+  const L = { ...messages.propsSheet, ...labels }
   const obj = (schema ?? {}) as JsonSchemaObject
   const [draft, setDraft] = useState<Record<string, unknown>>(value ?? {})
 
@@ -121,9 +107,9 @@ 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>
+            <span className="bg-muted rounded px-1 font-mono text-xs">{widgetId}</span>
           </SheetDescription>
         </SheetHeader>
         <div className="flex flex-col gap-4 px-4 py-4">
@@ -137,6 +123,7 @@ export function WidgetPropsSheet({
                 prop={prop}
                 value={draft[key]}
                 unsetLabel={L.unsetOption}
+                unsupportedLabel={L.unsupportedType}
                 onChange={(v) =>
                   setDraft((prev) => {
                     if (v === undefined) {
@@ -172,12 +159,14 @@ function PropertyField({
   prop,
   value,
   unsetLabel,
+  unsupportedLabel,
   onChange,
 }: {
   name: string
   prop: JsonSchemaProperty
   value: unknown
   unsetLabel: string
+  unsupportedLabel: (type: string) => string
   onChange: (v: unknown) => void
 }) {
   const id = `prop-${name}`
@@ -255,9 +244,7 @@ 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.
-      </p>
+      <p className="text-muted-foreground text-xs italic">{unsupportedLabel(prop.type ?? "?")}</p>
     </FieldShell>
   )
 }