@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/app/use-build-mode-focus.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, type RefObject } from "react"
+
+/** Where focus goes when build mode opens: the builder's title. */
+export const BUILDER_FOCUS_TARGET = '[data-slot="builder-title"]'
+/** Where focus goes when build mode closes (Apply or Discard): the edit button that opened it. */
+export const VIEW_FOCUS_TARGET = '[data-slot="view-edit"]'
+
+/**
+ * The selector focus moves to when build mode switches, or `null` when it
+ * did not switch (the first render included). Pure, so the hand-off is
+ * unit-testable without a DOM.
+ */
+export function buildModeFocusTarget(previous: boolean, current: boolean): string | null {
+  if (previous === current) return null
+  return current ? BUILDER_FOCUS_TARGET : VIEW_FOCUS_TARGET
+}
+
+/**
+ * Where focus goes when a `LayoutBuilder` mounts, by its reset `generation`:
+ * after a reset (Discard without `onExit`, > 0) the builder's title, because
+ * the Discard button that had the focus went with the old builder; on the
+ * first mount nowhere (McpAppView's build-mode switch handles that one).
+ */
+export function builderMountFocusTarget(generation: number): string | null {
+  return generation > 0 ? BUILDER_FOCUS_TARGET : null
+}
+
+/**
+ * Focuses the element `target` selects inside the returned ref's element once
+ * it mounts; `null` focuses nothing. `LayoutBuilder` passes
+ * {@link builderMountFocusTarget} of its reset generation.
+ */
+export function useFocusOnMount<T extends HTMLElement>(target: string | null): RefObject<T | null> {
+  const ref = useRef<T>(null)
+  useEffect(() => {
+    if (target) ref.current?.querySelector<HTMLElement>(target)?.focus()
+  }, [target])
+  return ref
+}
+
+/**
+ * Moves focus across the build-mode switch: the button that opened the
+ * builder disappears with the toolbar, so focus lands on the builder's title;
+ * Apply and Discard unmount the builder, so focus returns to the edit button.
+ * Focus that already sits outside the view (another frame, the host) stays
+ * where it is.
+ */
+export function useBuildModeFocus(
+  buildMode: boolean,
+  frameRef: RefObject<HTMLElement | null>,
+): void {
+  const previous = useRef(buildMode)
+  useEffect(() => {
+    const target = buildModeFocusTarget(previous.current, buildMode)
+    previous.current = buildMode
+    const frame = frameRef.current
+    if (!target || !frame) return
+    const active = frame.ownerDocument.activeElement
+    if (active && active !== frame.ownerDocument.body && !frame.contains(active)) return
+    frame.querySelector<HTMLElement>(target)?.focus()
+  }, [buildMode, frameRef])
+}

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

@@ -0,0 +1,89 @@
+import { useCallback, useState } from "react"
+import type { QueryClient } from "@tanstack/react-query"
+import { useDisplayMode } from "mcp-use/react"
+import { useToast } from "../components/Toast.js"
+import type { ViewMessages } from "../locale/toolkit-messages.js"
+import { fullscreenAvailable, isCompleteViewData, type ViewData } from "./mcp-app-view-chrome.js"
+import { decodeViewResult } from "./view-lifecycle.js"
+
+/**
+ * The toolbar actions of `McpAppView`: refresh and the fullscreen toggle.
+ * Their failures raise a toast in catalog words; the raw reason goes to the
+ * console, never to the user.
+ */
+
+/**
+ * Refresh via the refresh tool. A failure keeps the data and says so in a
+ * toast. A refresh that went through invalidates the queries of `client`,
+ * the one the view's widgets fetch through.
+ */
+export function useViewRefresh(options: {
+  viewData: ViewData | null
+  setViewData: (next: ViewData) => void
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+  refreshToolName: string
+  labels: Pick<ViewMessages, "refreshFailed" | "refreshFailedHint">
+  client: QueryClient
+}) {
+  const { viewData, setViewData, callTool, refreshToolName, labels, client } = options
+  const toast = useToast()
+  const [isRefreshing, setIsRefreshing] = useState(false)
+  const refreshView = useCallback(async () => {
+    if (!viewData?._refreshParams) return
+    setIsRefreshing(true)
+    let failure: unknown = null
+    try {
+      const result = await callTool(
+        refreshToolName,
+        viewData._refreshParams as unknown as Record<string, unknown>,
+      )
+      // One decoding convention with `useToolQuery` (structured-first), with a
+      // typed outcome: an unusable payload is a failure, never exception text.
+      const outcome = decodeViewResult(result, isCompleteViewData)
+      if (outcome.ok) setViewData(outcome.data)
+      else failure = outcome.reason ?? "the refresh tool returned no view"
+      // The call went through, so self-fetching widgets refresh as well;
+      // a tool error refreshes nothing.
+      if (outcome.ok || !outcome.isError) void client.invalidateQueries()
+    } catch (e) {
+      failure = e
+    } finally {
+      setIsRefreshing(false)
+    }
+    if (failure === null) return
+    console.warn("[mcp-toolkit] refresh failed:", failure)
+    toast.show({
+      tone: "danger",
+      title: labels.refreshFailed,
+      description: labels.refreshFailedHint,
+    })
+  }, [callTool, client, labels, refreshToolName, setViewData, toast, viewData])
+  return { isRefreshing, refreshView }
+}
+
+/** The fullscreen toggle, gated on the host's offer; a rejected request raises a toast. */
+export function useFullscreenToggle(
+  labels: Pick<ViewMessages, "fullscreenFailed" | "fullscreenFailedHint">,
+) {
+  const { displayMode, availableDisplayModes, requestDisplayMode } = useDisplayMode()
+  const toast = useToast()
+  const toggle = useCallback(async () => {
+    const mode = displayMode === "fullscreen" ? "inline" : "fullscreen"
+    try {
+      // Advisory since 2.x: `displayMode` updates when the host applies it.
+      await requestDisplayMode({ mode })
+    } catch (e) {
+      console.warn("[mcp-toolkit] display-mode request failed:", e)
+      toast.show({
+        tone: "danger",
+        title: labels.fullscreenFailed,
+        description: labels.fullscreenFailedHint,
+      })
+    }
+  }, [displayMode, labels, requestDisplayMode, toast])
+  return {
+    isFullscreen: displayMode === "fullscreen",
+    canFullscreen: fullscreenAvailable(displayMode, availableDisplayModes),
+    toggle,
+  }
+}

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

@@ -0,0 +1,122 @@
+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 recovery policy kept the view from re-running a stripped result's tool. */
+  recoveryBlocked?: boolean
+  /** The host reports the originating tool as writing (no retry after a block). */
+  toolWrites?: 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,
+    recoveryBlocked: options.recoveryBlocked,
+    toolWrites: options.toolWrites,
+    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 }
+}