@miragon/mcp-toolkit-ui 2.5.0 → 2.7.0

package/src/app/builder/Toolbar.tsx

@@ -1,7 +1,9 @@
 import { memo } from "react"
-import { Check, Eye, Layers, Library, Save } from "lucide-react"
+import { Check, Eye, Layers, Library, LucideProvider, Save } from "lucide-react"
+import { DENSE_ICON_STROKE } from "../../lib/icon-stroke.js"
 import { Badge } from "../../primitives/badge.js"
 import { Button } from "../../primitives/button.js"
+import { TONE_DOT, TONE_SOFT } from "../../lib/tone-utils.js"
 import { cn } from "../../lib/utils.js"
 import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js"
 import { StatusChip } from "./status-chip.js"
@@ -41,7 +43,7 @@ function ToolbarImpl({
         <span
           className={cn(
             "inline-flex size-6 items-center justify-center rounded-md",
-            previewMode ? "bg-emerald-500/10 text-emerald-500" : "bg-primary/10 text-primary",
+            previewMode ? TONE_SOFT.success : TONE_SOFT.info,
           )}
           aria-hidden="true"
         >
@@ -55,20 +57,21 @@ function ToolbarImpl({
 
       <div className="text-muted-foreground hidden items-center gap-3 text-[11px] sm:flex">
         <span className="inline-flex items-center gap-1.5">
-          <span className="size-1.5 rounded-full bg-emerald-500" />
+          <span aria-hidden="true" className={`size-1.5 rounded-full ${TONE_DOT.success}`} />
           <span>
-            <span className="text-foreground font-medium">{liveKeys}</span> live
+            <span className="text-foreground font-medium">{liveKeys}</span> {L.statsLive}
           </span>
         </span>
         <span className="bg-border h-3 w-px" aria-hidden="true" />
         <span>
-          <span className="text-foreground font-medium">{reachableCount}</span> reachable
+          <span className="text-foreground font-medium">{reachableCount}</span> {L.statsReachable}
         </span>
         {unreachableCount > 0 && (
           <>
             <span className="bg-border h-3 w-px" aria-hidden="true" />
             <span>
-              <span className="text-foreground font-medium">{unreachableCount}</span> unreachable
+              <span className="text-foreground font-medium">{unreachableCount}</span>{" "}
+              {L.statsUnreachable}
             </span>
           </>
         )}
@@ -92,4 +95,13 @@ function ToolbarImpl({
   )
 }
 
-export const Toolbar = memo(ToolbarImpl)
+/** A dense chrome bar: its Lucide icons draw at stroke 2 (CI §11), not the view's 2.5. */
+function DenseToolbar(props: Parameters<typeof ToolbarImpl>[0]) {
+  return (
+    <LucideProvider strokeWidth={DENSE_ICON_STROKE}>
+      <ToolbarImpl {...props} />
+    </LucideProvider>
+  )
+}
+
+export const Toolbar = memo(DenseToolbar)

package/src/app/builder/Workspace.tsx

@@ -82,7 +82,7 @@ function WorkspaceImpl({
               <div className="flex flex-col gap-3 pr-1">
                 {paletteByApp.map(([app, ws]) => (
                   <div key={app} className="flex flex-col gap-1">
-                    <div className="text-muted-foreground/80 text-[10px] font-semibold tracking-wide uppercase">
+                    <div className="text-muted-foreground text-[10px] font-semibold tracking-wide uppercase">
                       {app}
                     </div>
                     {ws.map((w) => (
@@ -160,10 +160,12 @@ function PaletteItemImpl({ w, onClick }: { w: ReachableWidget; onClick: () => vo
     >
       <span className="flex w-full items-center justify-between gap-2">
         <span className="truncate font-mono">{w.id}</span>
-        <GripVertical className="text-muted-foreground/40 group-hover:text-muted-foreground size-3" />
+        <GripVertical className="text-muted-foreground group-hover:text-accent-foreground size-3" />
       </span>
       {w.requires.length > 0 && (
-        <span className="text-muted-foreground/80 truncate font-mono text-[10px]">
+        // On the hovered --accent surface quiet text takes the surface's
+        // foreground: --muted-foreground drops to 3.66:1 there in dark.
+        <span className="text-muted-foreground group-hover:text-accent-foreground truncate font-mono text-[10px]">
           ← {w.requires.join(", ")}
         </span>
       )}

package/src/app/builder/builder-feedback.test.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { LocaleProvider } from "../../locale/locale-provider.js"
+import { TOOLKIT_MESSAGES } from "../../locale/toolkit-messages.js"
+import { attribute, decodeEntities, openingTags } from "../../render-scan.js"
+import { BuilderBanners } from "./BuilderBanners.js"
+import { EmptyHint } from "./EmptyHint.js"
+
+/**
+ * The builder's feedback states on their SSR markup: a failure says what
+ * happened and what to do in catalog words, keeps the raw reason under
+ * "Details", and offers the next step; the empty state leads with the blue
+ * primary button (CI §9).
+ */
+
+const de = TOOLKIT_MESSAGES.de
+const inGerman = (node: ReactNode) =>
+  renderToStaticMarkup(<LocaleProvider locale="de-DE">{node}</LocaleProvider>)
+const noop = (): void => {}
+const RAW = "MCP error -32602: Tool get-builder-catalogue not found"
+
+describe("BuilderBanners: catalogue failure", () => {
+  const html = inGerman(
+    <BuilderBanners
+      L={de.builder}
+      catalogueToolName="get-builder-catalogue"
+      refreshError={RAW}
+      validationIssues={[]}
+      onRetry={noop}
+    />,
+  )
+
+  it("is the kit's inline error state, announced as an alert", () => {
+    const root = openingTags(html, "div").find((t) => /data-slot="error-state"/.test(t)) ?? ""
+    expect(attribute(root, "role")).toBe("alert")
+    expect(attribute(root, "data-variant")).toBe("inline")
+  })
+
+  it("says what happened and what to do in German, with a retry", () => {
+    const text = decodeEntities(html)
+    expect(text).toContain(de.builder.catalogueError)
+    expect(text).toContain(de.builder.catalogueErrorHint)
+    expect(text).toContain(`${de.common.retry}</button>`)
+  })
+
+  it("keeps the raw reason under Details only, never in a sentence the user reads", () => {
+    const details = /<details[^>]*>([\s\S]*?)<\/details>/.exec(html)?.[1] ?? ""
+    expect(decodeEntities(details)).toContain(`get-builder-catalogue: ${RAW}`)
+    const outside = decodeEntities(html.replace(/<details[\s\S]*?<\/details>/g, ""))
+    expect(outside).not.toContain(RAW)
+  })
+
+  it("has no retry without a handler", () => {
+    const bare = inGerman(
+      <BuilderBanners
+        L={de.builder}
+        catalogueToolName="get-builder-catalogue"
+        refreshError={RAW}
+        validationIssues={[]}
+      />,
+    )
+    expect(bare).not.toContain("<button")
+  })
+})
+
+describe("EmptyHint", () => {
+  it("offers its one next step as the primary (blue) button", () => {
+    const html = inGerman(<EmptyHint L={de.builder} onGotoPipeline={noop} />)
+    const buttons = openingTags(html, "button")
+    expect(buttons).toHaveLength(1)
+    expect(attribute(buttons[0] ?? "", "data-variant")).toBe("default")
+    expect(decodeEntities(html)).toContain(`${de.builder.openDataSources}</button>`)
+  })
+})

package/src/app/builder/builder-model.test.ts

@@ -260,6 +260,11 @@ describe("formatLiveKeyValue", () => {
     expect(formatLiveKeyValue("abc")).toBe("live: abc")
   })
 
+  it("takes the localized prefix", () => {
+    expect(formatLiveKeyValue("abc", "vorhanden")).toBe("vorhanden: abc")
+    expect(formatLiveKeyValue(42, "vorhanden")).toBe("vorhanden: 42")
+  })
+
   it("JSON-stringifies non-string values", () => {
     expect(formatLiveKeyValue(42)).toBe("live: 42")
     expect(formatLiveKeyValue({ a: 1 })).toBe('live: {"a":1}')

package/src/app/builder/builder-model.ts

@@ -136,14 +136,15 @@ export function entriesToKeys(entries: KeyEntry[]): Record<string, unknown> {
  * Compact preview of a value as it currently lives in the pipeline.
  * Used as the placeholder when the editor's `rawValue` is empty so the
  * user can see what the server is actually working with right now
- * without the editor overwriting their (empty) input.
+ * without the editor overwriting their (empty) input. `prefix` is the
+ * localized word for "live" (the builder passes its catalog's).
  */
-export function formatLiveKeyValue(value: unknown): string | undefined {
+export function formatLiveKeyValue(value: unknown, prefix = "live"): string | undefined {
   if (value === undefined) return undefined
   if (value === "") return undefined
-  if (typeof value === "string") return `live: ${value}`
+  if (typeof value === "string") return `${prefix}: ${value}`
   try {
-    return `live: ${JSON.stringify(value)}`
+    return `${prefix}: ${JSON.stringify(value)}`
   } catch {
     return undefined
   }

package/src/app/builder/labels.ts

@@ -4,130 +4,24 @@
  * Extracted from `layout-builder.tsx` so the presentational sub-components
  * (Toolbar, PipelineStrip, Workspace, CatalogueSheet, SaveDialog, PreviewPane)
  * can depend on the labels without importing the orchestrating container —
- * which would create an import cycle. React-free and `mcp-use`-free.
+ * which would create an import cycle. React-free and `mcp-use`-free. The
+ * strings themselves live in the toolkit catalog (`locale/messages-*.ts`).
  */
 
-export interface LayoutBuilderLabels {
-  title?: string
-  builderBadge?: string
-  previewBadge?: string
-  catalogue?: string
-  save?: string
-  done?: string
-  viewLayoutTab?: string
-  viewPipelineTab?: string
-  viewPreviewTab?: string
-  saveDialogTitle?: string
-  saveDialogDescription?: string
-  saveNameLabel?: string
-  saveDescriptionLabel?: string
-  saveConfirm?: string
-  cancel?: string
-  pipelineHeader?: string
-  keysHeader?: string
-  stepsHeader?: string
-  keyName?: string
-  keyValue?: string
-  stepContextId?: string
-  stepPickerLabel?: string
-  addKey?: string
-  addStep?: string
-  emptyKeys?: string
-  emptySteps?: string
-  statusUpToDate?: string
-  statusPending?: string
-  statusRefreshing?: string
-  paletteHeader?: string
-  paletteEmpty?: string
-  canvasEmpty?: string
-  canvasDropHint?: string
-  addRow?: string
-  addTab?: string
-  removeRow?: string
-  renameTab?: string
-  removeTab?: string
-  tabsLabel?: string
-  catalogueDescription?: string
-  catalogueKeys?: string
-  catalogueSteps?: string
-  catalogueUnreachable?: string
-  catalogueUnreachableEmpty?: string
-  catalogueProducedBy?: string
-  catalogueConsumedBy?: string
-  catalogueNeedsKeys?: string
-  cataloguePickKey?: string
-  catalogueAddProducingStep?: string
-  catalogueLive?: string
-  catalogueMissing?: string
-  /** Banner shown when the catalogue fetch fails (prefixes the reason). */
-  catalogueError?: string
-  /** Heading for the pipeline-validation warning banner. */
-  validationWarning?: string
-  /** Inline message when a save fails (prefixes the reason). */
-  saveError?: string
-  /** Inline message when a tab rename is rejected (duplicate label). */
-  renameDuplicate?: string
-}
+import { TOOLKIT_MESSAGES, type BuilderMessages } from "../../locale/toolkit-messages.js"
 
-export const DEFAULT_LABELS: Required<LayoutBuilderLabels> = {
-  title: "View Builder",
-  builderBadge: "Builder",
-  previewBadge: "Preview",
-  catalogue: "Catalogue",
-  save: "Save",
-  done: "Done",
-  viewLayoutTab: "Layout",
-  viewPipelineTab: "Pipeline",
-  viewPreviewTab: "Preview",
-  saveDialogTitle: "Save dashboard",
-  saveDialogDescription:
-    "Persists the current layout along with the keys and steps that populate it.",
-  saveNameLabel: "Name",
-  saveDescriptionLabel: "Description",
-  saveConfirm: "Save dashboard",
-  cancel: "Cancel",
-  pipelineHeader: "Pipeline",
-  keysHeader: "Keys",
-  stepsHeader: "Steps",
-  keyName: "key",
-  keyValue: 'value, "literal", true, {…}',
-  stepContextId: "ctx id",
-  stepPickerLabel: "pick a step",
-  addKey: "Add key",
-  addStep: "Add step",
-  emptyKeys: "No keys seeded.",
-  emptySteps: "No steps configured.",
-  statusUpToDate: "Up to date",
-  statusPending: "Applying soon…",
-  statusRefreshing: "Applying…",
-  paletteHeader: "Palette",
-  paletteEmpty: "No widgets reachable yet — seed a key or add a step.",
-  canvasEmpty: "Drag a widget here, or click one in the palette.",
-  canvasDropHint: "Drop to add",
-  addRow: "Add row",
-  addTab: "Add tab",
-  removeRow: "Remove row",
-  renameTab: "Rename tab",
-  removeTab: "Remove tab",
-  tabsLabel: "Tabs",
-  catalogueDescription:
-    "Every key and widget the framework knows about, whether or not it's reachable right now.",
-  catalogueKeys: "Keys",
-  catalogueSteps: "Steps",
-  catalogueUnreachable: "Unreachable widgets",
-  catalogueUnreachableEmpty: "Every registered widget is reachable.",
-  catalogueProducedBy: "produced by",
-  catalogueConsumedBy: "consumed by",
-  catalogueNeedsKeys: "needs",
-  cataloguePickKey: "Add as key",
-  catalogueAddProducingStep: "Add producing step",
-  catalogueLive: "live",
-  catalogueMissing: "missing",
-  catalogueError: "Couldn't refresh the builder catalogue",
-  validationWarning: "This pipeline won't render as configured",
-  saveError: "Couldn't save",
-  renameDuplicate: "A tab with that name already exists.",
-}
+/**
+ * Override strings for every user-facing caption in the builder. Each field
+ * defaults to the active locale's toolkit catalog (`useToolkitMessages().builder`).
+ */
+export type LayoutBuilderLabels = Partial<BuilderMessages>
+
+/**
+ * English builder strings.
+ * @deprecated Read the active locale's strings with `useToolkitMessages().builder`
+ * (or `TOOLKIT_MESSAGES.en.builder`); this alias stays for existing imports.
+ */
+export const DEFAULT_LABELS: Required<LayoutBuilderLabels> = TOOLKIT_MESSAGES.en.builder
 
 /**
  * MIME type used to carry a widget id across the palette → canvas drag.

package/src/app/builder/status-chip.tsx

@@ -1,4 +1,5 @@
 import { CircleDot, Loader2 } from "lucide-react"
+import { TONE_DOT, TONE_TEXT } from "../../lib/tone-utils.js"
 import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js"
 
 /**
@@ -22,15 +23,18 @@ export function StatusChip({
   }
   if (status === "pending") {
     return (
-      <span className="inline-flex items-center gap-1.5 text-amber-600 dark:text-amber-400">
-        <span className="size-1.5 animate-pulse rounded-full bg-amber-500" />
+      <span className={`inline-flex items-center gap-1.5 ${TONE_TEXT.warning}`}>
+        <span
+          aria-hidden="true"
+          className={`size-1.5 animate-pulse rounded-full ${TONE_DOT.warning}`}
+        />
         {L.statusPending}
       </span>
     )
   }
   return (
-    <span className="text-primary inline-flex items-center gap-1.5">
-      <Loader2 className="size-3 animate-spin" />
+    <span className={`inline-flex items-center gap-1.5 ${TONE_TEXT.info}`}>
+      <Loader2 aria-hidden="true" className="size-3 animate-spin" />
       {L.statusRefreshing}
     </span>
   )

package/src/app/builder/use-builder-catalogue.ts

@@ -111,6 +111,11 @@ export function useBuilderCatalogue({
   useEffect(() => {
     refreshRef.current = refreshBuilder
   }, [refreshBuilder])
+  // Retry of the catalogue error state: fetch again right away, with the
+  // current keys and steps.
+  const retryCatalogue = useCallback(() => {
+    void refreshRef.current()
+  }, [])
   const isFirstRun = useRef(true)
   useEffect(() => {
     if (isFirstRun.current) {
@@ -178,6 +183,7 @@ export function useBuilderCatalogue({
     validationIssues,
     status,
     refreshError,
+    retryCatalogue,
     widgetById,
     propsSchemaByWidgetId,
     paletteByApp,

package/src/app/builder/use-save-dashboard.ts

@@ -22,6 +22,7 @@ export function useSaveDashboard({
   stepEntries,
   draft,
   onSaved,
+  onSuccess,
 }: {
   callTool: (name: string, args: object) => Promise<unknown>
   saveToolName: string
@@ -31,6 +32,8 @@ export function useSaveDashboard({
   stepEntries: PipelineStepRef[]
   draft: DraftLayout
   onSaved?: (result: { id: string; name: string }) => void
+  /** Confirms every successful save (the builder raises a toast), with the saved name. */
+  onSuccess?: (name: string) => void
 }) {
   const [isBusy, setBusy] = useState(false)
   const [saveOpen, setSaveOpen] = useState(false)
@@ -56,6 +59,7 @@ export function useSaveDashboard({
       })
       const saved = parseToolResult<{ id?: string; name?: string } | null>(result)
       setSaveOpen(false)
+      onSuccess?.(saved?.name ?? saveName.trim())
       if (saved?.id && onSaved) {
         onSaved({
           id: saved.id,
@@ -75,6 +79,7 @@ export function useSaveDashboard({
     draft,
     keyEntries,
     onSaved,
+    onSuccess,
     saveDescription,
     saveName,
     saveToolName,

package/src/app/index.ts

@@ -1,5 +1,12 @@
 export { McpAppView } from "./mcp-app-view.js"
-export type { McpAppViewProps, McpAppViewLabels } from "./mcp-app-view.js"
+export type {
+  McpAppViewProps,
+  McpAppViewLabels,
+  DescribeStep,
+  DescribeViewError,
+  ViewTitleLevel,
+  ViewTitleMode,
+} from "./mcp-app-view.js"
 export { McpToolkitApp, mountMcpToolkitApp } from "./mcp-toolkit-app.js"
 export {
   WidgetRenderer,

package/src/app/layout-builder.tsx

@@ -7,7 +7,7 @@ import {
   initBuilderState,
   type BuilderDraftState,
 } from "./builder/builder-reducer.js"
-import { DEFAULT_LABELS, type LayoutBuilderLabels } from "./builder/labels.js"
+import type { LayoutBuilderLabels } from "./builder/labels.js"
 import { Toolbar } from "./builder/Toolbar.js"
 import { PipelineStrip } from "./builder/PipelineStrip.js"
 import { CatalogueSheet } from "./builder/CatalogueSheet.js"
@@ -21,6 +21,8 @@ import { useBuilderCatalogue } from "./builder/use-builder-catalogue.js"
 import { useKeyStepEntries } from "./builder/use-key-step-entries.js"
 import { useSaveDashboard } from "./builder/use-save-dashboard.js"
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "../primitives/tabs.js"
+import { ToastProvider, useToast } from "../components/Toast.js"
+import { useToolkitMessages } from "../locale/locale-provider.js"
 import { type WidgetComponent } from "./widget-renderer.js"
 
 // -------------------------------------------------------------------------- //
@@ -73,7 +75,20 @@ export interface LayoutBuilderProps {
 // Main component
 // -------------------------------------------------------------------------- //
 
-export function LayoutBuilder({
+/**
+ * The visual view builder. Confirms a successful save with a toast (it mounts
+ * a `ToastProvider` when none is above it — inside `McpAppView` it shares the
+ * view's). Every caption follows the active locale (`labels` overrides).
+ */
+export function LayoutBuilder(props: LayoutBuilderProps) {
+  return (
+    <ToastProvider>
+      <LayoutBuilderImpl {...props} />
+    </ToastProvider>
+  )
+}
+
+function LayoutBuilderImpl({
   initialLayout,
   title,
   initialKeys,
@@ -87,7 +102,9 @@ export function LayoutBuilder({
   onSaved,
   onExit,
 }: LayoutBuilderProps) {
-  const L = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels])
+  const messages = useToolkitMessages()
+  const L = useMemo(() => ({ ...messages.builder, ...labels }), [messages.builder, labels])
+  const toast = useToast()
 
   // ── Draft layout (pure reducer) ─────────────────────────────────────────
   // The draft plus the UI indices coupled to draft mutations
@@ -148,6 +165,7 @@ export function LayoutBuilder({
     validationIssues,
     status,
     refreshError,
+    retryCatalogue,
     widgetById,
     propsSchemaByWidgetId,
     paletteByApp,
@@ -176,6 +194,7 @@ export function LayoutBuilder({
     stepEntries,
     draft,
     onSaved,
+    onSuccess: (name) => toast.show({ tone: "success", title: L.saved(name) }),
   })
 
   // ── DnD ──────────────────────────────────────────────────────────────────
@@ -326,6 +345,7 @@ export function LayoutBuilder({
         catalogueToolName={catalogueToolName}
         refreshError={refreshError}
         validationIssues={validationIssues}
+        onRetry={retryCatalogue}
       />
 
       <Tabs value={view} onValueChange={(v) => setView(v as typeof view)}>