@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/locale/messages-en.ts

@@ -12,6 +12,8 @@ export const en: ToolkitMessages = {
     details: "Details",
     dismiss: "Close notification",
     notifications: "Notifications",
+    loadFailed: "This content couldn't be loaded",
+    loadFailedHint: "Try again. If it fails again, ask in the chat.",
   },
   view: {
     loading: "Loading view…",
@@ -26,6 +28,11 @@ export const en: ToolkitMessages = {
     errorHint: "Try again. If it fails again, ask in the chat.",
     errorHintNoRetry: "Ask in the chat to open this view again.",
     retry: "Try again",
+    blockedTitle: "The chat didn't pass the result to this view",
+    blockedHint: "Load the view yourself, or ask in the chat for the current state.",
+    blockedHintNoRetry:
+      "The action already ran, so the view doesn't start it again. Ask in the chat for the current state.",
+    blockedRetry: "Load view",
     errorDetails: "Details",
     stepErrorsTitle: "Some data couldn't be loaded",
     stepErrorsHint: "Try again to load the missing data.",
@@ -33,14 +40,21 @@ export const en: ToolkitMessages = {
     refreshFailedHint: "You're seeing the last loaded data. Try again in a moment.",
     fullscreenFailed: "Couldn't switch the display mode.",
     fullscreenFailedHint: "The view stays as it is. Try again in a moment.",
+    dataAsOf: (time) => `Reloaded at ${time}`,
   },
   listFooter: {
     showing: ({ shown, total, noun }) => `Showing ${shown} of ${total} ${noun}`.trimEnd(),
     defaultNoun: "rows",
     loadMore: "Load more",
     loadingMore: "Loading…",
+    updating: "Updating…",
+    noResults: "No entries",
+    refreshFailed: "Couldn't update the list",
+    refreshFailedHint: "You're seeing the previous result. Try again in a moment.",
+    loadMoreFailed: "Couldn't load more entries",
+    loadMoreFailedHint: "The entries above are current. Try again in a moment.",
   },
-  filterBar: { searchPlaceholder: "Filter…" },
+  filterBar: { searchPlaceholder: "Filter…", searchLabel: "Filter", chipsLabel: "Filters" },
   pills: { live: "Live" },
   renderer: {
     widgetUnavailable: "This element isn't available in this version.",
@@ -52,13 +66,37 @@ export const en: ToolkitMessages = {
     builderBadge: "Editing",
     previewBadge: "Preview",
     catalogue: "Catalogue",
-    save: "Save",
+    save: "Save as dashboard",
     done: "Done",
+    apply: "Apply",
+    applyHint: "Shows your changes in this view and saves nothing.",
+    discard: "Discard",
+    discardHint: "Leaves the editor. The view stays as it was.",
+    discardHintStandalone: "Resets your changes.",
+    saveHint: "Saves the layout as a dashboard you can open again later.",
+    unsavedChanges: "Unsaved changes",
+    discardDialogTitle: "Discard your changes?",
+    discardDialogDescription:
+      "You lose your changes to this view. The view stays as it was before you edited it.",
+    discardDialogDescriptionSaved:
+      "The view goes back to how it was before you edited it. Your saved dashboard keeps your changes.",
+    keepEditing: "Keep editing",
+    discardConfirm: "Discard changes",
+    advanced: "Advanced",
+    advancedHint: "Shows the data sources, the catalogue and the technical IDs.",
+    renameTabNamed: (label) => `Rename tab “${label}”`,
+    removeTabNamed: (label) => `Remove tab “${label}”`,
+    rowTarget: "New elements go here",
+    stepProvides: "provides",
+    keyValueFor: (key) => (key ? `Value of ${key}` : "Value"),
     viewLayoutTab: "Layout",
     viewPipelineTab: "Data sources",
     viewPreviewTab: "Preview",
-    saveDialogTitle: "Save dashboard",
-    saveDialogDescription: "Saves the layout together with the data sources that fill it.",
+    saveDialogTitle: "Save as dashboard",
+    saveDialogDescription:
+      "Saves the layout and its data sources as a dashboard you can open again later. To change this view, use Apply.",
+    saveDialogDescriptionStandalone:
+      "Saves the layout and its data sources as a dashboard you can open again later.",
     saveNameLabel: "Name",
     saveDescriptionLabel: "Description",
     saveConfirm: "Save dashboard",
@@ -75,10 +113,11 @@ export const en: ToolkitMessages = {
     emptyKeys: "No keys yet.",
     emptySteps: "No steps yet.",
     statusUpToDate: "Up to date",
-    statusPending: "Applying soon…",
-    statusRefreshing: "Applying…",
+    statusPending: "Updating soon…",
+    statusRefreshing: "Updating…",
     paletteHeader: "Elements",
-    paletteEmpty: "No elements available yet. Add a key or a step.",
+    paletteLoading: "Loading elements…",
+    paletteEmpty: "No elements available yet. Elements appear as soon as their data is there.",
     canvasEmpty: "Drag an element here or click one in the list.",
     canvasDropHint: "Drop to add",
     addRow: "Add row",
@@ -117,9 +156,9 @@ export const en: ToolkitMessages = {
     saveNamePlaceholder: "Name of the dashboard",
     saveDescriptionPlaceholder: "Optional",
     saved: (name) => `Dashboard “${name}” saved.`,
-    renameHint: "Double-click a tab to rename it.",
-    renameTitle: "Double-click to rename",
-    autoApplies: "Changes apply right away",
+    renameHint: "Rename a tab with F2, a double-click or its pencil button.",
+    renameTitle: "F2 or double-click to rename",
+    autoApplies: "Changes show in the preview right away",
     noMoreKeys: "No more keys available.",
     parsedType: "Detected type",
     valueType: (code) =>

package/src/locale/toolkit-messages.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest"
 import {
+  formatClockTime,
   formatCount,
+  resolveFormatLocale,
   resolveToolkitLocale,
   resolveToolkitMessages,
   TOOLKIT_LOCALES,
@@ -24,6 +26,9 @@ const SAMPLES: Record<string, unknown[]> = {
   configureElementSet: [2],
   unsupportedType: ["array"],
   valueType: ["num"],
+  renameTabNamed: ["Übersicht"],
+  removeTabNamed: ["Übersicht"],
+  keyValueFor: ["demo:id"],
 }
 
 /** Every message of a catalog as `[path, rendered text]`. */
@@ -155,6 +160,40 @@ describe("toolkit catalogs", () => {
     expect(de.propsSheet.unsupportedType("array")).toBe(
       "Diesen Feldtyp (array) kannst du hier nicht bearbeiten.",
     )
+    expect(en.builder.renameTabNamed("Ops")).toBe("Rename tab “Ops”")
+    expect(de.builder.renameTabNamed("Ops")).toBe("Tab „Ops“ umbenennen")
+    expect(en.builder.removeTabNamed("Ops")).toBe("Remove tab “Ops”")
+    expect(de.builder.removeTabNamed("Ops")).toBe("Tab „Ops“ entfernen")
+    expect(en.builder.keyValueFor("demo:id")).toBe("Value of demo:id")
+    expect(de.builder.keyValueFor("demo:id")).toBe("Wert von demo:id")
+    // A key row without a name yet still has an accessible name.
+    expect(en.builder.keyValueFor("")).toBe("Value")
+    expect(de.builder.keyValueFor("")).toBe("Wert")
+  })
+
+  it("builder: names Apply, Discard and Save apart in user words (U18)", () => {
+    const { en, de } = TOOLKIT_MESSAGES
+    expect([en.builder.apply, en.builder.discard, en.builder.save]).toEqual([
+      "Apply",
+      "Discard",
+      "Save as dashboard",
+    ])
+    expect([de.builder.apply, de.builder.discard, de.builder.save]).toEqual([
+      "Übernehmen",
+      "Verwerfen",
+      "Als Dashboard speichern",
+    ])
+    expect(de.builder.advanced).toBe("Erweitert")
+    // The refresh state no longer reuses the Apply verb.
+    for (const m of [en.builder, de.builder]) {
+      expect(m.statusPending).not.toMatch(/apply|übernomm/i)
+      expect(m.statusRefreshing).not.toMatch(/apply|übernomm/i)
+    }
+    // Rename is announced with its keyboard path, not double-click alone.
+    expect(en.builder.renameHint).toContain("F2")
+    expect(de.builder.renameHint).toContain("F2")
+    expect(en.builder.renameTitle).toContain("F2")
+    expect(de.builder.renameTitle).toContain("F2")
   })
 })
 
@@ -203,6 +242,31 @@ describe("resolveToolkitMessages", () => {
   })
 })
 
+describe("resolveToolkitMessages: the deprecated builder `done`", () => {
+  it("labels Apply with an override of `done`", () => {
+    const merged = resolveToolkitMessages("de", { builder: { done: "Los" } })
+    expect(merged.builder.apply).toBe("Los")
+    expect(merged.builder.done).toBe("Los")
+  })
+
+  it("keeps an `apply` override over `done`", () => {
+    const merged = resolveToolkitMessages("en", { builder: { done: "Finish", apply: "Show" } })
+    expect(merged.builder.apply).toBe("Show")
+  })
+
+  it("leaves Apply alone without a `done` override", () => {
+    expect(resolveToolkitMessages("en", { builder: { save: "Keep" } }).builder.apply).toBe(
+      TOOLKIT_MESSAGES.en.builder.apply,
+    )
+    expect(resolveToolkitMessages("de", { builder: { apply: "Zeigen" } }).builder.apply).toBe(
+      "Zeigen",
+    )
+    expect(resolveToolkitMessages("de", { view: { refresh: "Neu" } }).builder).toEqual(
+      TOOLKIT_MESSAGES.de.builder,
+    )
+  })
+})
+
 describe("formatCount", () => {
   it("groups digits per locale", () => {
     expect(formatCount(1234567, "en")).toBe("1,234,567")
@@ -214,3 +278,72 @@ describe("formatCount", () => {
     expect(formatCount(1234, "not a locale!")).toBe("1,234")
   })
 })
+
+describe("formatClockTime (the view's data-as-of stamp)", () => {
+  const at = Date.UTC(2026, 9, 11, 14, 32)
+
+  it("formats hours and minutes per locale in the host's time zone", () => {
+    expect(formatClockTime(at, "de-DE", "UTC")).toBe("14:32")
+    expect(formatClockTime(at, "de-DE", "Europe/Berlin")).toBe("16:32")
+    expect(formatClockTime(at, "en-GB", "UTC")).toBe("14:32")
+  })
+
+  it("never pads the hour of a 12-hour clock: 2:32 PM, not 02:32 PM", () => {
+    expect(formatClockTime(at, "en-US", "UTC")).toBe("2:32 PM")
+    expect(formatClockTime(Date.UTC(2026, 9, 11, 9, 5), "en-US", "UTC")).toBe("9:05 AM")
+    // Minutes keep two digits.
+    expect(formatClockTime(Date.UTC(2026, 9, 11, 14, 5), "de-DE", "UTC")).toBe("14:05")
+  })
+
+  it("a zone the runtime rejects drops the zone, never the locale", () => {
+    // Windows ids reach a view from some hosts; German stays a 24-hour clock.
+    expect(formatClockTime(at, "de", "W. Europe Standard Time")).toMatch(/^\d{2}:\d{2}$/)
+    expect(formatClockTime(at, "de-DE", "Not/AZone")).toMatch(/^\d{2}:\d{2}$/)
+    expect(formatClockTime(at, "en-US", "Not/AZone")).toMatch(/^[1-9]\d?:\d\d [AP]M$/)
+  })
+
+  it("an invalid tag falls back to English, in the host's zone when it is valid", () => {
+    expect(() => formatClockTime(at, "not a locale!", "UTC")).not.toThrow()
+    expect(formatClockTime(at, "not a locale!", "UTC")).toBe("2:32 PM")
+    expect(formatClockTime(at, "not a locale!", "Not/AZone")).toMatch(/^[1-9]\d?:\d\d [AP]M$/)
+  })
+
+  it("the catalogs stamp it in words that carry its meaning", () => {
+    expect(TOOLKIT_MESSAGES.en.view.dataAsOf("2:32 PM")).toBe("Reloaded at 2:32 PM")
+    expect(TOOLKIT_MESSAGES.de.view.dataAsOf("14:32")).toBe("Neu geladen um 14:32 Uhr")
+  })
+})
+
+describe("resolveFormatLocale (a time in the language of its sentence)", () => {
+  it("formats in the language the words come from, never the host's other language", () => {
+    // A German profile on an en-US host: German words, a German clock.
+    expect(resolveFormatLocale("de", "en-US")).toBe("de")
+    expect(resolveFormatLocale("en", "de-DE")).toBe("en")
+    expect(
+      formatClockTime(Date.UTC(2026, 9, 11, 14, 32), resolveFormatLocale("de", "en-US"), "UTC"),
+    ).toBe("14:32")
+  })
+
+  it("keeps the regional tag of the same language: en-GB keeps its 24-hour clock", () => {
+    expect(resolveFormatLocale("en", "en-GB")).toBe("en-GB")
+    expect(resolveFormatLocale("en-GB", "en-GB")).toBe("en-GB")
+    expect(resolveFormatLocale("de", "DE_AT")).toBe("DE-AT")
+    expect(resolveFormatLocale("  de ", "de-CH ")).toBe("de-CH")
+  })
+
+  it("prefers the text locale's own region over the host's", () => {
+    expect(resolveFormatLocale("en-GB", "en-US")).toBe("en-GB")
+    expect(resolveFormatLocale("de-AT", "de-DE")).toBe("de-AT")
+  })
+
+  it("maps a language without a catalog onto the catalog's, like the words", () => {
+    // French words fall back to English, so does their clock.
+    expect(resolveFormatLocale("fr-FR", "fr-FR")).toBe("en")
+    expect(resolveFormatLocale(undefined, "de-DE")).toBe("en")
+    expect(resolveFormatLocale(undefined, "en-AU")).toBe("en-AU")
+    expect(resolveFormatLocale("de")).toBe("de")
+    // A bare tag or a lookalike prefix is no region of the language.
+    expect(resolveFormatLocale("en", "en")).toBe("en")
+    expect(resolveFormatLocale("de", "dex-DE")).toBe("de")
+  })
+})

package/src/locale/toolkit-messages.ts

@@ -8,13 +8,14 @@
  * Pure data + functions (no React, no `mcp-use/react`): browser-safe and
  * shared by the root barrel and the `./app` shell alike.
  */
-import type { ToolkitMessages } from "./message-types.js"
+import type { BuilderMessages, ToolkitMessages } from "./message-types.js"
 import { de } from "./messages-de.js"
 import { en } from "./messages-en.js"
 
 export type {
   BuilderMessages,
   CommonMessages,
+  FilterBarMessages,
   ListFooterMessages,
   PropsSheetMessages,
   RendererMessages,
@@ -63,11 +64,24 @@ export function resolveToolkitMessages(
     filterBar: { ...base.filterBar, ...override.filterBar },
     pills: { ...base.pills, ...override.pills },
     renderer: { ...base.renderer, ...override.renderer },
-    builder: { ...base.builder, ...override.builder },
+    builder: mergeBuilder(base.builder, override.builder),
     propsSheet: { ...base.propsSheet, ...override.propsSheet },
   }
 }
 
+/**
+ * The builder section with its override. An override of the deprecated
+ * `done` still labels the commit button, Apply, unless it sets `apply` too.
+ */
+function mergeBuilder(
+  base: BuilderMessages,
+  override: Partial<BuilderMessages> | undefined,
+): BuilderMessages {
+  const merged = { ...base, ...override }
+  if (override?.done !== undefined && override.apply === undefined) merged.apply = override.done
+  return merged
+}
+
 /**
  * Format a count for display in `locale` (grouping separators per locale:
  * `1,234` / `1.234`). An invalid tag falls back to English instead of
@@ -80,3 +94,50 @@ export function formatCount(value: number, locale: string | undefined): string {
     return new Intl.NumberFormat("en").format(value)
   }
 }
+
+/**
+ * The tag a toolkit sentence formats its numbers and times in: the language
+ * its words come from (`textLocale`, mapped onto a shipped catalog the way
+ * {@link resolveToolkitMessages} maps it), with the regional tag of that
+ * language from `textLocale` or else `hostLocale`, so `en-GB` keeps its
+ * 24-hour clock. A tag of another language never mixes in: German words
+ * never carry an English clock ("Neu geladen um 4:32 PM Uhr").
+ */
+export function resolveFormatLocale(textLocale: string | undefined, hostLocale?: string): string {
+  const language = resolveToolkitLocale(textLocale)
+  const regionOfLanguage = (tag: string | undefined): string | undefined => {
+    const normal = tag?.trim().replace(/_/g, "-")
+    if (!normal?.includes("-")) return undefined
+    return normal.toLowerCase().split("-")[0] === language ? normal : undefined
+  }
+  return regionOfLanguage(textLocale) ?? regionOfLanguage(hostLocale) ?? language
+}
+
+/**
+ * Format the clock time (hours and minutes) of `epochMs` in `locale`, in the
+ * host's `timeZone` when it reports one: `14:32` / `2:32 PM`. The hour is
+ * `numeric`, so each locale pads it its own way (a 12-hour clock never shows
+ * `02:32 PM`). A zone the runtime rejects (a Windows id, say) drops the zone,
+ * never the locale; an invalid tag falls back to English. It never throws
+ * inside a render.
+ */
+export function formatClockTime(
+  epochMs: number,
+  locale: string | undefined,
+  timeZone?: string,
+): string {
+  const clock: Intl.DateTimeFormatOptions = { hour: "numeric", minute: "2-digit" }
+  const attempts: readonly (readonly [string | undefined, string | undefined])[] = [
+    [locale, timeZone],
+    [locale, undefined],
+    ["en", timeZone],
+  ]
+  for (const [tag, zone] of attempts) {
+    try {
+      return new Intl.DateTimeFormat(tag, { ...clock, timeZone: zone }).format(epochMs)
+    } catch {
+      // The next attempt drops what the runtime rejected.
+    }
+  }
+  return new Intl.DateTimeFormat("en", clock).format(epochMs)
+}

package/src/primitives/alert.tsx

@@ -11,6 +11,9 @@ const alertVariants = cva(
         default: "bg-card text-card-foreground",
         // Tone model: tint, a border and icon in the danger colour; title and
         // description in the foreground (CI §3.3: text on a tint is black).
+        danger:
+          "border-danger bg-danger-soft text-foreground *:data-[slot=alert-title]:text-foreground *:data-[slot=alert-description]:text-foreground [&>svg]:text-danger",
+        /** @deprecated Use `danger`: one name per tone. */
         destructive:
           "border-danger bg-danger-soft text-foreground *:data-[slot=alert-title]:text-foreground *:data-[slot=alert-description]:text-foreground [&>svg]:text-danger",
       },

package/src/primitives/badge.tsx

@@ -6,16 +6,21 @@ import { FOCUS_RING } from "../lib/focus-ring.js"
 import { TONE_BORDER, TONE_SOFT } from "../lib/tone-utils.js"
 import { cn } from "../lib/utils.js"
 
-// Badges and chips take radius sm (CI §6). The status variants follow the tone
-// model: tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER;
-// CI §3.3 "-soft: Text darauf --cd-schwarz"). The ink is never text on a tint.
+// Badges and chips take radius sm (CI §6) and the 13 px floor of the type
+// scale (`text-small`; `leading-4` keeps the one line inside the 20 px badge).
+// The status variants follow the tone model and its ONE vocabulary: tint +
+// foreground text, rim in the tone (TONE_SOFT + TONE_BORDER; CI §3.3 "-soft:
+// Text darauf --cd-schwarz"). The ink is never text on a tint. `danger` is the
+// status red; `destructive` is its deprecated name, kept for existing calls.
 const badgeVariants = cva(
-  `group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-sm border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all ${FOCUS_RING} has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-danger [&>svg]:pointer-events-none [&>svg]:size-3!`,
+  `group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-sm border border-transparent px-2 py-0.5 text-small leading-4 font-medium whitespace-nowrap transition-all ${FOCUS_RING} has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-danger [&>svg]:pointer-events-none [&>svg]:size-3!`,
   {
     variants: {
       variant: {
         default: "bg-primary text-primary-foreground [a]:hover:bg-primary-hover",
         secondary: "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+        danger: `${TONE_SOFT.danger} ${TONE_BORDER.danger}`,
+        /** @deprecated Use `danger`: one name per tone. */
         destructive: `${TONE_SOFT.danger} ${TONE_BORDER.danger}`,
         success: `${TONE_SOFT.success} ${TONE_BORDER.success}`,
         warning: `${TONE_SOFT.warning} ${TONE_BORDER.warning}`,

package/src/primitives/button.tsx

@@ -25,7 +25,7 @@ const buttonVariants = cva(
       },
       size: {
         default: "h-9 px-4 py-2 has-[>svg]:px-3",
-        xs: "h-6 gap-1 rounded-sm px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
+        xs: "h-6 gap-1 rounded-sm px-2 text-small has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
         sm: "h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5",
         lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
         icon: "size-9",

package/src/primitives/dialog.tsx

@@ -5,6 +5,7 @@ import { XIcon } from "lucide-react"
 import { Dialog as DialogPrimitive } from "radix-ui"
 
 import { FOCUS_RING } from "../lib/focus-ring.js"
+import { useFocusReturn } from "../lib/focus-return.js"
 import { useToolkitMessages } from "../locale/locale-provider.js"
 import { cn } from "../lib/utils.js"
 import { usePortalContainer } from "../theme/portal-container.js"
@@ -58,6 +59,8 @@ function DialogContent({
   children,
   showCloseButton = true,
   closeLabel,
+  onOpenAutoFocus,
+  onCloseAutoFocus,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
   showCloseButton?: boolean
@@ -65,6 +68,9 @@ function DialogContent({
   closeLabel?: string
 }) {
   const messages = useToolkitMessages()
+  // Without a DialogTrigger, Radix returns the focus nowhere: hand it back to
+  // the element that opened it (lib/focus-return.ts).
+  const focusReturn = useFocusReturn({ onOpenAutoFocus, onCloseAutoFocus })
   return (
     <DialogPortal data-slot="dialog-portal">
       <DialogOverlay />
@@ -75,6 +81,7 @@ function DialogContent({
           className,
         )}
         {...props}
+        {...focusReturn}
       >
         {children}
         {showCloseButton && (
@@ -136,7 +143,9 @@ function DialogTitle({ className, ...props }: React.ComponentProps<typeof Dialog
   return (
     <DialogPrimitive.Title
       data-slot="dialog-title"
-      className={cn("text-lg leading-none font-semibold", className)}
+      // The dialog's heading row (CI §8: weight 600) on the type scale's
+      // section step (21 px / 600, the CI h3).
+      className={cn("text-section", className)}
       {...props}
     />
   )

package/src/primitives/select.tsx

@@ -86,7 +86,7 @@ function SelectLabel({ className, ...props }: React.ComponentProps<typeof Select
   return (
     <SelectPrimitive.Label
       data-slot="select-label"
-      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
+      className={cn("text-muted-foreground text-small px-2 py-1.5", className)}
       {...props}
     />
   )

package/src/primitives/sheet.tsx

@@ -5,6 +5,7 @@ import { XIcon } from "lucide-react"
 import { Dialog as SheetPrimitive } from "radix-ui"
 
 import { FOCUS_RING } from "../lib/focus-ring.js"
+import { useFocusReturn } from "../lib/focus-return.js"
 import { useToolkitMessages } from "../locale/locale-provider.js"
 import { cn } from "../lib/utils.js"
 import { usePortalContainer } from "../theme/portal-container.js"
@@ -55,6 +56,8 @@ function SheetContent({
   side = "right",
   showCloseButton = true,
   closeLabel,
+  onOpenAutoFocus,
+  onCloseAutoFocus,
   ...props
 }: React.ComponentProps<typeof SheetPrimitive.Content> & {
   side?: "top" | "right" | "bottom" | "left"
@@ -63,6 +66,9 @@ function SheetContent({
   closeLabel?: string
 }) {
   const messages = useToolkitMessages()
+  // Without a SheetTrigger, Radix returns the focus nowhere: hand it back to
+  // the element that opened it (lib/focus-return.ts).
+  const focusReturn = useFocusReturn({ onOpenAutoFocus, onCloseAutoFocus })
   return (
     <SheetPortal>
       <SheetOverlay />
@@ -81,6 +87,7 @@ function SheetContent({
           className,
         )}
         {...props}
+        {...focusReturn}
       >
         {children}
         {showCloseButton && (

package/src/providers/query-provider.test.tsx

@@ -0,0 +1,154 @@
+import { QueryClient, QueryClientProvider, useQueryClient } from "@tanstack/react-query"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it, vi } from "vitest"
+import { createStandaloneHostBridge, HostBridgeProvider } from "../app/host-bridge.js"
+import { useToolQueryKey } from "../hooks/use-tool-query.js"
+import {
+  AppQueryProvider,
+  queryClient,
+  useCallTool,
+  useToolNameInQueryKey,
+} from "./query-provider.js"
+
+/**
+ * The tool transport and client of the data hooks (toolkit#176 N25, K18):
+ * `AppQueryProvider`'s `callTool`, else the nearest HostBridge — so the
+ * documented HostBridgeProvider mount fetches instead of idling.
+ */
+
+type Caller = ReturnType<typeof useCallTool>
+
+function probe(tree: (node: React.ReactNode) => React.ReactNode): {
+  callTool: Caller
+  client: QueryClient
+} {
+  let callTool: Caller
+  let client: QueryClient | undefined
+  function Probe() {
+    callTool = useCallTool()
+    client = useQueryClient()
+    return null
+  }
+  renderToStaticMarkup(tree(<Probe />))
+  if (!client) throw new Error("probe did not render")
+  return { callTool, client }
+}
+
+describe("useCallTool", () => {
+  it("AppQueryProvider's callTool wins over a bridge", async () => {
+    const explicit = vi.fn(() => Promise.resolve("explicit"))
+    const bridgeCall = vi.fn(() => Promise.resolve("bridge"))
+    const bridge = createStandaloneHostBridge({ callTool: bridgeCall })
+    const { callTool } = probe((node) => (
+      <HostBridgeProvider bridge={bridge}>
+        <AppQueryProvider callTool={explicit}>{node}</AppQueryProvider>
+      </HostBridgeProvider>
+    ))
+    await expect(callTool?.("t", { a: 1 })).resolves.toBe("explicit")
+    expect(explicit).toHaveBeenCalledWith("t", { a: 1 })
+    expect(bridgeCall).not.toHaveBeenCalled()
+  })
+
+  it("falls back to the nearest HostBridgeProvider's callTool (N25)", async () => {
+    const bridgeCall = vi.fn(() => Promise.resolve("bridge"))
+    const bridge = createStandaloneHostBridge({ callTool: bridgeCall })
+    const { callTool } = probe((node) => (
+      <AppQueryProvider>
+        <HostBridgeProvider bridge={bridge}>{node}</HostBridgeProvider>
+      </AppQueryProvider>
+    ))
+    await expect(callTool?.("orders_get", { id: 7 })).resolves.toBe("bridge")
+    expect(bridgeCall).toHaveBeenCalledWith("orders_get", { id: 7 })
+  })
+
+  it("is undefined with neither (the query then fails with NoToolTransportError)", () => {
+    const { callTool } = probe((node) => <AppQueryProvider>{node}</AppQueryProvider>)
+    expect(callTool).toBeUndefined()
+  })
+})
+
+describe("AppQueryProvider", () => {
+  it("shares the toolkit's client by default", () => {
+    expect(probe((node) => <AppQueryProvider>{node}</AppQueryProvider>).client).toBe(queryClient)
+  })
+
+  it("takes a client of its own, e.g. one per mount", () => {
+    const own = new QueryClient()
+    expect(probe((node) => <AppQueryProvider client={own}>{node}</AppQueryProvider>).client).toBe(
+      own,
+    )
+  })
+
+  it("a nested provider without client keeps its parent's, like toolNameInQueryKey", () => {
+    const own = new QueryClient()
+    const other = new QueryClient()
+    const nested = probe((node) => (
+      <AppQueryProvider client={own}>
+        <AppQueryProvider callTool={vi.fn()}>{node}</AppQueryProvider>
+      </AppQueryProvider>
+    ))
+    expect(nested.client).toBe(own)
+    const replaced = probe((node) => (
+      <AppQueryProvider client={own}>
+        <AppQueryProvider client={other}>{node}</AppQueryProvider>
+      </AppQueryProvider>
+    ))
+    expect(replaced.client).toBe(other)
+  })
+
+  it("a plain TanStack QueryClientProvider is not inherited: the shared client stays", () => {
+    const foreign = new QueryClient()
+    const { client } = probe((node) => (
+      <QueryClientProvider client={foreign}>
+        <AppQueryProvider>{node}</AppQueryProvider>
+      </QueryClientProvider>
+    ))
+    expect(client).toBe(queryClient)
+  })
+})
+
+describe("AppQueryProvider toolNameInQueryKey (K18)", () => {
+  /** The setting and the key `useToolQueryKey` builds under `tree`. */
+  function keyUnder(tree: (node: React.ReactNode) => React.ReactNode) {
+    let setting: boolean | undefined
+    let key: unknown[] | undefined
+    function Probe() {
+      setting = useToolNameInQueryKey()
+      key = useToolQueryKey(["feed"], "feed_data", { id: 1 })
+      return null
+    }
+    renderToStaticMarkup(tree(<Probe />))
+    return { setting, key }
+  }
+
+  it("is off by default: the 2.x key, outside a provider too", () => {
+    expect(keyUnder((node) => node)).toEqual({ setting: false, key: ["feed", { id: 1 }] })
+    expect(keyUnder((node) => <AppQueryProvider>{node}</AppQueryProvider>)).toEqual({
+      setting: false,
+      key: ["feed", { id: 1 }],
+    })
+  })
+
+  it("on, the hooks' key carries the tool name", () => {
+    expect(
+      keyUnder((node) => <AppQueryProvider toolNameInQueryKey>{node}</AppQueryProvider>),
+    ).toEqual({ setting: true, key: ["feed", "feed_data", { id: 1 }] })
+  })
+
+  it("a nested provider keeps its parent's setting unless it sets its own", () => {
+    expect(
+      keyUnder((node) => (
+        <AppQueryProvider toolNameInQueryKey>
+          <AppQueryProvider callTool={vi.fn()}>{node}</AppQueryProvider>
+        </AppQueryProvider>
+      )).setting,
+    ).toBe(true)
+    expect(
+      keyUnder((node) => (
+        <AppQueryProvider toolNameInQueryKey>
+          <AppQueryProvider toolNameInQueryKey={false}>{node}</AppQueryProvider>
+        </AppQueryProvider>
+      )).setting,
+    ).toBe(false)
+  })
+})