@miragon/mcp-toolkit-ui 2.7.0 → 2.8.1

package/src/app/builder/Toolbar.tsx

@@ -1,17 +1,95 @@
 import { memo } from "react"
-import { Check, Eye, Layers, Library, LucideProvider, Save } from "lucide-react"
+import { Check, Library, LucideProvider, Save, Undo2, Wrench } from "lucide-react"
 import { DENSE_ICON_STROKE } from "../../lib/icon-stroke.js"
+import { FOCUS_RING } from "../../lib/focus-ring.js"
 import { Badge } from "../../primitives/badge.js"
 import { Button } from "../../primitives/button.js"
-import { TONE_DOT, TONE_SOFT } from "../../lib/tone-utils.js"
+import { TONE_DOT } from "../../lib/tone-utils.js"
 import { cn } from "../../lib/utils.js"
 import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js"
 import { StatusChip } from "./status-chip.js"
 
 // -------------------------------------------------------------------------- //
-// Toolbar — sticky top, dense status row + actions
+// Toolbar — sticky top: title + unsaved marker, then the actions
 // -------------------------------------------------------------------------- //
 
+export interface ToolbarProps {
+  L: Required<LayoutBuilderLabels>
+  previewMode: boolean
+  isBusy: boolean
+  status: RefreshStatus
+  liveKeys: number
+  reachableCount: number
+  unreachableCount: number
+  /** Advanced mode: shows the stats and the catalogue (the data sources tab lives below). */
+  advanced: boolean
+  onToggleAdvanced: () => void
+  /** The draft has changes that would be lost (the marker next to the title). */
+  unsaved: boolean
+  onOpenCatalogue: () => void
+  onOpenSave: () => void
+  /** Leaves the builder without the edits (or, without `onApply`, resets the draft in place). */
+  onDiscard: () => void
+  /** Shows the draft in the view and leaves the builder; absent when there is no view to apply to. */
+  onApply?: () => void
+  hasAnyCell: boolean
+}
+
+/** The live-context stats and the refresh state: data-source vocabulary, so advanced mode only. */
+function Stats({
+  L,
+  status,
+  liveKeys,
+  reachableCount,
+  unreachableCount,
+}: Pick<ToolbarProps, "L" | "status" | "liveKeys" | "reachableCount" | "unreachableCount">) {
+  return (
+    <div className="text-muted-foreground text-small hidden items-center gap-3 sm:flex">
+      <span className="inline-flex items-center gap-1.5">
+        <span aria-hidden="true" className={`size-1.5 rounded-full ${TONE_DOT.success}`} />
+        <span>
+          <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> {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>{" "}
+            {L.statsUnreachable}
+          </span>
+        </>
+      )}
+      <StatusChip status={status} L={L} />
+    </div>
+  )
+}
+
+/**
+ * The unsaved marker. The live region is always mounted (only its content
+ * changes), so a screen reader hears the marker appear and go.
+ */
+function UnsavedMarker({ L, unsaved }: { L: Required<LayoutBuilderLabels>; unsaved: boolean }) {
+  return (
+    <span
+      role="status"
+      data-slot="builder-unsaved"
+      className="text-muted-foreground text-small inline-flex items-center gap-1.5"
+    >
+      {unsaved && (
+        <>
+          <span aria-hidden="true" className={`size-2 rounded-full ${TONE_DOT.warning}`} />
+          {L.unsavedChanges}
+        </>
+      )}
+    </span>
+  )
+}
+
 function ToolbarImpl({
   L,
   previewMode,
@@ -20,74 +98,81 @@ function ToolbarImpl({
   liveKeys,
   reachableCount,
   unreachableCount,
+  advanced,
+  onToggleAdvanced,
+  unsaved,
   onOpenCatalogue,
   onOpenSave,
-  onDone,
+  onDiscard,
+  onApply,
   hasAnyCell,
-}: {
-  L: Required<LayoutBuilderLabels>
-  previewMode: boolean
-  isBusy: boolean
-  status: RefreshStatus
-  liveKeys: number
-  reachableCount: number
-  unreachableCount: number
-  onOpenCatalogue: () => void
-  onOpenSave: () => void
-  onDone?: () => void
-  hasAnyCell: boolean
-}) {
+}: ToolbarProps) {
   return (
-    <header className="bg-background/80 sticky top-0 z-10 -mx-1 flex flex-wrap items-center gap-3 border-b px-1 py-2 backdrop-blur">
-      <div className="flex items-center gap-2">
-        <span
-          className={cn(
-            "inline-flex size-6 items-center justify-center rounded-md",
-            previewMode ? TONE_SOFT.success : TONE_SOFT.info,
-          )}
-          aria-hidden="true"
+    <header className="bg-background/80 sticky top-0 z-10 -mx-1 flex flex-wrap items-center gap-x-3 gap-y-2 border-b px-1 py-2 backdrop-blur">
+      <div className="flex min-w-0 flex-wrap items-center gap-2">
+        {/* No tinted icon tile before the title: a mode is no status, and the
+            badge next to the title already names it (anti-slop U2, CI §3.3).
+            The focus target when build mode opens (McpAppView moves focus here). */}
+        <h2
+          data-slot="builder-title"
+          tabIndex={-1}
+          className={cn("rounded-sm text-sm font-semibold tracking-tight", FOCUS_RING)}
         >
-          {previewMode ? <Eye className="size-3.5" /> : <Layers className="size-3.5" />}
-        </span>
-        <h2 className="text-sm font-semibold tracking-tight">{L.title}</h2>
+          {L.title}
+        </h2>
         <Badge variant={previewMode ? "outline" : "secondary"} className="font-normal">
           {previewMode ? L.previewBadge : L.builderBadge}
         </Badge>
+        <UnsavedMarker L={L} unsaved={unsaved} />
       </div>
 
-      <div className="text-muted-foreground hidden items-center gap-3 text-[11px] sm:flex">
-        <span className="inline-flex items-center gap-1.5">
-          <span aria-hidden="true" className={`size-1.5 rounded-full ${TONE_DOT.success}`} />
-          <span>
-            <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> {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>{" "}
-              {L.statsUnreachable}
-            </span>
-          </>
-        )}
-        <StatusChip status={status} L={L} />
-      </div>
+      {advanced && (
+        <Stats
+          L={L}
+          status={status}
+          liveKeys={liveKeys}
+          reachableCount={reachableCount}
+          unreachableCount={unreachableCount}
+        />
+      )}
 
-      <div className="ml-auto flex items-center gap-1">
-        <Button variant="ghost" size="sm" onClick={onOpenCatalogue}>
-          <Library /> {L.catalogue}
+      <div className="ml-auto flex flex-wrap items-center gap-1">
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-pressed={advanced}
+          title={L.advancedHint}
+          onClick={onToggleAdvanced}
+          className="aria-pressed:bg-accent aria-pressed:text-accent-foreground"
+        >
+          <Wrench aria-hidden="true" /> {L.advanced}
+        </Button>
+        {advanced && (
+          <Button variant="ghost" size="sm" onClick={onOpenCatalogue}>
+            <Library aria-hidden="true" /> {L.catalogue}
+          </Button>
+        )}
+        <Button
+          variant="outline"
+          size="sm"
+          title={L.saveHint}
+          onClick={onOpenSave}
+          disabled={isBusy || !hasAnyCell}
+        >
+          <Save aria-hidden="true" /> {L.save}
         </Button>
-        <Button size="sm" onClick={onOpenSave} disabled={isBusy || !hasAnyCell}>
-          <Save /> {L.save}
+        <Button
+          variant="ghost"
+          size="sm"
+          // Without Apply there is no view to leave to: Discard resets in place.
+          title={onApply ? L.discardHint : L.discardHintStandalone}
+          onClick={onDiscard}
+        >
+          <Undo2 aria-hidden="true" /> {L.discard}
         </Button>
-        {onDone && (
-          <Button variant="outline" size="sm" onClick={onDone}>
-            <Check /> {L.done}
+        {onApply && (
+          <Button size="sm" title={L.applyHint} onClick={onApply}>
+            <Check aria-hidden="true" /> {L.apply}
           </Button>
         )}
       </div>
@@ -96,7 +181,7 @@ function 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]) {
+function DenseToolbar(props: ToolbarProps) {
   return (
     <LucideProvider strokeWidth={DENSE_ICON_STROKE}>
       <ToolbarImpl {...props} />

package/src/app/builder/Workspace.tsx

@@ -1,13 +1,17 @@
-import { memo } from "react"
-import { GripVertical, Plus } from "lucide-react"
-import type { ReachableWidget, RowDef, WidgetProps } from "@miragon/mcp-toolkit-core"
+import { memo, useId } from "react"
+import { GripVertical, Plus, SlidersHorizontal } from "lucide-react"
+import type { DisplayText, ReachableWidget, RowDef, WidgetProps } from "@miragon/mcp-toolkit-core"
+import { FOCUS_RING } from "../../lib/focus-ring.js"
+import { cn } from "../../lib/utils.js"
 import { Badge } from "../../primitives/badge.js"
 import { Button } from "../../primitives/button.js"
-import { ScrollArea } from "../../primitives/scroll-area.js"
+import { Skeleton } from "../../primitives/skeleton.js"
 import type { WidgetComponent } from "../widget-renderer.js"
+import { displayLabel } from "./builder-model.js"
 import type { LayoutBuilderLabels } from "./labels.js"
 import { WIDGET_DRAG_MIME } from "./labels.js"
 import { CanvasRow } from "./CanvasRow.js"
+import { useDisplayResolver } from "./use-display-resolver.js"
 
 // -------------------------------------------------------------------------- //
 // Workspace — palette + canvas (palette sticky on lg+)
@@ -21,7 +25,13 @@ import { CanvasRow } from "./CanvasRow.js"
 export interface WorkspaceProps {
   L: Required<LayoutBuilderLabels>
   paletteByApp: [string, ReachableWidget[]][]
+  /** Each app's title (or its key) by app name: the palette's group headings. */
+  appDisplayByName: Map<string, DisplayText>
   paletteCount: number
+  /** The first catalogue answer is still on its way: the palette shows a loading state. */
+  paletteLoading: boolean
+  /** The empty palette's next step: show the data sources (it turns on advanced mode). */
+  onOpenDataSources: () => void
   activeRows: RowDef[]
   focusedRowIndex: number
   setFocusedRowIndex: (idx: number) => void
@@ -35,16 +45,23 @@ export interface WorkspaceProps {
   onAddWidget: (widgetId: string, targetRowIdx?: number) => void
   onConfigureCell: (rowIdx: number, cellIdx: number) => void
   propsSchemaByWidgetId: Map<string, Record<string, unknown>>
+  /** Title, summary (or their keys) per widget id: the canvas cells' names. */
+  displayByWidgetId: Map<string, DisplayText>
+  /** Advanced mode adds the technical lines (a widget's required keys, cell ids). */
+  advanced: boolean
   widgets: Record<string, WidgetComponent>
   widgetProps: WidgetProps
-  showAddTabButton?: boolean
+  /** Offered next to "Add row" while the draft has no tabs yet. */
   onAddTab?: () => void
 }
 
 function WorkspaceImpl({
   L,
   paletteByApp,
+  appDisplayByName,
   paletteCount,
+  paletteLoading,
+  onOpenDataSources,
   activeRows,
   focusedRowIndex,
   setFocusedRowIndex,
@@ -58,53 +75,24 @@ function WorkspaceImpl({
   onAddWidget,
   onConfigureCell,
   propsSchemaByWidgetId,
+  displayByWidgetId,
+  advanced,
   widgets,
   widgetProps,
-  showAddTabButton,
   onAddTab,
 }: WorkspaceProps) {
   return (
     <div className="grid grid-cols-12 gap-4">
-      <aside className="col-span-12 lg:col-span-3 xl:col-span-2">
-        <div className="lg:sticky lg:top-16">
-          <div className="text-muted-foreground mb-2 flex items-center gap-2 text-[10px] font-semibold tracking-[0.12em] uppercase">
-            {L.paletteHeader}
-            <Badge variant="outline" className="px-1.5 text-[10px]">
-              {paletteCount}
-            </Badge>
-          </div>
-          {paletteCount === 0 ? (
-            <div className="text-muted-foreground rounded-md border border-dashed p-3 text-xs">
-              {L.paletteEmpty}
-            </div>
-          ) : (
-            <ScrollArea className="lg:max-h-[70vh]">
-              <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 text-[10px] font-semibold tracking-wide uppercase">
-                      {app}
-                    </div>
-                    {ws.map((w) => (
-                      <PaletteItem key={w.id} w={w} onClick={() => onAddWidget(w.id)} />
-                    ))}
-                  </div>
-                ))}
-              </div>
-            </ScrollArea>
-          )}
-          {showAddTabButton && onAddTab && (
-            <Button
-              variant="ghost"
-              size="xs"
-              onClick={onAddTab}
-              className="text-muted-foreground hover:text-foreground mt-3"
-            >
-              <Plus /> {L.addTab}
-            </Button>
-          )}
-        </div>
-      </aside>
+      <Palette
+        L={L}
+        paletteByApp={paletteByApp}
+        appDisplayByName={appDisplayByName}
+        paletteCount={paletteCount}
+        loading={paletteLoading}
+        advanced={advanced}
+        onAddWidget={onAddWidget}
+        onOpenDataSources={onOpenDataSources}
+      />
 
       <section className="col-span-12 lg:col-span-9 xl:col-span-10">
         <div className="flex flex-col gap-3">
@@ -127,13 +115,22 @@ function WorkspaceImpl({
               onAddWidget={onAddWidget}
               onConfigureCell={onConfigureCell}
               propsSchemaByWidgetId={propsSchemaByWidgetId}
+              displayByWidgetId={displayByWidgetId}
+              advanced={advanced}
               widgets={widgets}
               widgetProps={widgetProps}
             />
           ))}
-          <Button variant="outline" size="sm" onClick={onAddRow} className="self-start text-xs">
-            <Plus /> {L.addRow}
-          </Button>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button variant="outline" size="sm" onClick={onAddRow}>
+              <Plus aria-hidden="true" /> {L.addRow}
+            </Button>
+            {onAddTab && (
+              <Button variant="ghost" size="sm" onClick={onAddTab}>
+                <Plus aria-hidden="true" /> {L.addTab}
+              </Button>
+            )}
+          </div>
         </div>
       </section>
     </div>
@@ -142,31 +139,202 @@ function WorkspaceImpl({
 
 export const Workspace = memo(WorkspaceImpl)
 
+// -------------------------------------------------------------------------- //
+// Palette — the elements to add, grouped by app (sticky on lg+)
+// -------------------------------------------------------------------------- //
+
+function Palette({
+  L,
+  paletteByApp,
+  appDisplayByName,
+  paletteCount,
+  loading,
+  advanced,
+  onAddWidget,
+  onOpenDataSources,
+}: Pick<WorkspaceProps, "L" | "paletteByApp" | "appDisplayByName" | "paletteCount" | "advanced"> & {
+  loading: boolean
+  onAddWidget: (widgetId: string) => void
+  onOpenDataSources: () => void
+}) {
+  const headingId = useId()
+  return (
+    <aside aria-labelledby={headingId} className="col-span-12 lg:col-span-3 xl:col-span-2">
+      <div className="lg:sticky lg:top-16">
+        <h3
+          id={headingId}
+          className="text-muted-foreground text-small mb-2 flex items-center gap-2 font-semibold"
+        >
+          {L.paletteHeader}
+          {/* No count while loading: "0" would say there are none. */}
+          {!loading && (
+            <Badge variant="outline" className="px-1.5">
+              {paletteCount}
+            </Badge>
+          )}
+        </h3>
+        {loading ? (
+          <PaletteLoading L={L} />
+        ) : paletteCount === 0 ? (
+          <PaletteEmpty L={L} onOpenDataSources={onOpenDataSources} />
+        ) : (
+          // A native scroll box: its height is its own, so nothing after the
+          // palette can be painted over by the list (the old ScrollArea let
+          // the list overflow its max height).
+          <div className="flex flex-col gap-3 lg:max-h-[70vh] lg:overflow-y-auto lg:pr-1">
+            {paletteByApp.map(([app, ws]) => (
+              <div key={app} className="flex flex-col gap-1">
+                <PaletteGroupHeading
+                  app={app}
+                  display={appDisplayByName.get(app)}
+                  advanced={advanced}
+                />
+                <ul className="flex flex-col gap-1">
+                  {ws.map((w) => (
+                    <li key={w.id}>
+                      <PaletteItem
+                        L={L}
+                        w={w}
+                        advanced={advanced}
+                        onClick={() => onAddWidget(w.id)}
+                      />
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </aside>
+  )
+}
+
+/** The palette while the first catalogue answer is on its way (CI §9: a skeleton, not "none"). */
+function PaletteLoading({ L }: { L: Required<LayoutBuilderLabels> }) {
+  return (
+    <div data-slot="builder-palette-loading" className="flex flex-col gap-1">
+      <Skeleton aria-hidden="true" className="h-9 w-full" />
+      <Skeleton aria-hidden="true" className="h-9 w-full" />
+      <Skeleton aria-hidden="true" className="h-9 w-3/4" />
+      <p role="status" className="text-muted-foreground text-small mt-1">
+        {L.paletteLoading}
+      </p>
+    </div>
+  )
+}
+
+/**
+ * The palette without any element. It speaks no data-source words (they sit
+ * behind Advanced); its one next step opens the data sources, also when the
+ * layout already has cells and the builder's empty state is not shown.
+ * Exported for its tests only.
+ */
+export function PaletteEmpty({
+  L,
+  onOpenDataSources,
+}: {
+  L: Required<LayoutBuilderLabels>
+  onOpenDataSources: () => void
+}) {
+  return (
+    <div
+      data-slot="builder-palette-empty"
+      className="text-muted-foreground text-small flex flex-col items-start gap-2 rounded-md border border-dashed p-3"
+    >
+      <p>{L.paletteEmpty}</p>
+      <Button size="sm" variant="outline" onClick={onOpenDataSources}>
+        <SlidersHorizontal aria-hidden="true" /> {L.openDataSources}
+      </Button>
+    </div>
+  )
+}
+
+// -------------------------------------------------------------------------- //
+// Palette group heading
+// -------------------------------------------------------------------------- //
+
+/**
+ * The heading of one app's group in the palette: the app's title. Without a
+ * title the app's name is a technical namespace, so it heads the group only in
+ * advanced mode; there it also follows a title as a quiet mono hint.
+ */
+function PaletteGroupHeading({
+  app,
+  display,
+  advanced,
+}: {
+  app: string
+  display: DisplayText | undefined
+  advanced: boolean
+}) {
+  const { locale, resolveKey } = useDisplayResolver()
+  const { label, hint } = displayLabel(display ?? {}, app, locale, resolveKey)
+  if (hint === undefined && !advanced) return null
+  return (
+    <div
+      data-slot="builder-palette-group"
+      className="text-muted-foreground text-small font-semibold"
+    >
+      {label}
+      {advanced && hint && <span className="ml-1.5 font-mono font-normal">{hint}</span>}
+    </div>
+  )
+}
+
 // -------------------------------------------------------------------------- //
 // Palette item
 // -------------------------------------------------------------------------- //
 
-function PaletteItemImpl({ w, onClick }: { w: ReachableWidget; onClick: () => void }) {
+/**
+ * One widget in the palette: its title and one-line summary, the widget id as
+ * a quiet mono line (only next to a real title), and in advanced mode the keys
+ * it needs. A click (or Enter) adds it to the target row; dragging drops it
+ * on any row.
+ */
+function PaletteItemImpl({
+  L,
+  w,
+  advanced,
+  onClick,
+}: {
+  L: Required<LayoutBuilderLabels>
+  w: ReachableWidget
+  advanced: boolean
+  onClick: () => void
+}) {
+  const { locale, resolveKey } = useDisplayResolver()
+  const { label, hint, summary } = displayLabel(w, w.id, locale, resolveKey)
+  // On the hovered --accent surface quiet text takes the surface's
+  // foreground: --muted-foreground drops to 3.66:1 there in dark.
+  const quiet = "text-muted-foreground group-hover:text-accent-foreground block w-full truncate"
   return (
     <button
       type="button"
       draggable
+      data-slot="builder-palette-item"
       onDragStart={(e) => {
         e.dataTransfer.setData(WIDGET_DRAG_MIME, w.id)
         e.dataTransfer.effectAllowed = "copy"
       }}
       onClick={onClick}
-      className="hover:bg-accent hover:text-accent-foreground group bg-background/50 flex cursor-grab flex-col items-start gap-0.5 rounded-md border px-2 py-1.5 text-left text-xs transition-colors active:cursor-grabbing"
+      className={cn(
+        "hover:bg-accent hover:text-accent-foreground group bg-background flex w-full cursor-grab flex-col items-start gap-0.5 rounded-md border px-2 py-1.5 text-left transition-colors active:cursor-grabbing",
+        FOCUS_RING,
+      )}
     >
       <span className="flex w-full items-center justify-between gap-2">
-        <span className="truncate font-mono">{w.id}</span>
-        <GripVertical className="text-muted-foreground group-hover:text-accent-foreground size-3" />
+        <span className="truncate text-sm font-medium">{label}</span>
+        <GripVertical
+          aria-hidden="true"
+          className="text-muted-foreground group-hover:text-accent-foreground size-3.5 shrink-0"
+        />
       </span>
-      {w.requires.length > 0 && (
-        // 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(", ")}
+      {summary && <span className={cn(quiet, "text-small")}>{summary}</span>}
+      {hint && <span className={cn(quiet, "text-small font-mono")}>{hint}</span>}
+      {advanced && w.requires.length > 0 && (
+        <span className={cn(quiet, "text-small")}>
+          {L.catalogueNeedsKeys} <span className="font-mono">{w.requires.join(", ")}</span>
         </span>
       )}
     </button>