@miragon/mcp-toolkit-ui 0.10.1

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

@@ -0,0 +1,285 @@
+import { useState, type ReactNode } from "react"
+import { Button } from "../primitives/button.js"
+import { Input } from "../primitives/input.js"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../primitives/select.js"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "../primitives/sheet.js"
+import { Switch } from "../primitives/switch.js"
+
+/**
+ * Tiny JSON-Schema-driven editor for a layout cell's `props`. The
+ * LayoutBuilder opens this sheet when the user clicks "Configure" on a
+ * cell whose widget advertises a `propsSchema` in the framework manifest.
+ *
+ * Scope (v1):
+ *   - Object-root schemas only.
+ *   - Top-level properties: `string`, `number`, `integer`, `boolean`.
+ *   - String enums render as a Select.
+ *   - Nested objects/arrays/$ref/anyOf are not supported — the field
+ *     shows an "edit JSON manually" hint so authors know to fall back.
+ *
+ * The sheet writes a clean `Record<string, unknown>` (empty values
+ * stripped) and reports `undefined` when the user clears every field, so
+ * the cell's `props` field stays absent rather than `{}` — matches the
+ * "no props" wire format used elsewhere.
+ */
+
+interface JsonSchemaProperty {
+  type?: string
+  description?: string
+  enum?: unknown[]
+  default?: unknown
+}
+
+interface JsonSchemaObject {
+  type?: string
+  properties?: Record<string, JsonSchemaProperty>
+  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)",
+}
+
+const UNSET_SENTINEL = "__unset__"
+
+export interface WidgetPropsSheetProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  widgetId: string
+  schema: Record<string, unknown> | undefined
+  value: Record<string, unknown> | undefined
+  onApply: (next: Record<string, unknown> | undefined) => void
+  labels?: WidgetPropsSheetLabels
+}
+
+export function WidgetPropsSheet({
+  open,
+  onOpenChange,
+  widgetId,
+  schema,
+  value,
+  onApply,
+  labels,
+}: WidgetPropsSheetProps) {
+  const L = { ...DEFAULT_LABELS, ...labels }
+  const obj = (schema ?? {}) as JsonSchemaObject
+  const [draft, setDraft] = useState<Record<string, unknown>>(value ?? {})
+
+  // Reset the form to the saved value on the open→true transition so a
+  // user who closes the sheet without applying gets their unsaved edits
+  // discarded next time. Render-time state update with a "prev" tracker
+  // is the React-recommended alternative to a setState-in-effect.
+  const [prevOpen, setPrevOpen] = useState(open)
+  if (open !== prevOpen) {
+    setPrevOpen(open)
+    if (open) setDraft(value ?? {})
+  }
+
+  const properties = obj.properties ?? {}
+  const propEntries = Object.entries(properties)
+
+  const handleApply = () => {
+    const cleaned: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(draft)) {
+      if (v === "" || v === undefined || v === null) continue
+      cleaned[k] = v
+    }
+    onApply(Object.keys(cleaned).length > 0 ? cleaned : undefined)
+    onOpenChange(false)
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <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>
+        </SheetHeader>
+        <div className="flex flex-col gap-4 px-4 py-4">
+          {propEntries.length === 0 ? (
+            <p className="text-muted-foreground text-sm">{L.noProps}</p>
+          ) : (
+            propEntries.map(([key, prop]) => (
+              <PropertyField
+                key={key}
+                name={key}
+                prop={prop}
+                value={draft[key]}
+                unsetLabel={L.unsetOption}
+                onChange={(v) =>
+                  setDraft((prev) => {
+                    if (v === undefined) {
+                      const rest: Record<string, unknown> = {}
+                      for (const [k, val] of Object.entries(prev)) {
+                        if (k !== key) rest[k] = val
+                      }
+                      return rest
+                    }
+                    return { ...prev, [key]: v }
+                  })
+                }
+              />
+            ))
+          )}
+        </div>
+        <div className="flex items-center justify-end gap-2 border-t px-4 py-3">
+          <Button variant="ghost" onClick={() => setDraft({})}>
+            {L.reset}
+          </Button>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            {L.cancel}
+          </Button>
+          <Button onClick={handleApply}>{L.apply}</Button>
+        </div>
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+function PropertyField({
+  name,
+  prop,
+  value,
+  unsetLabel,
+  onChange,
+}: {
+  name: string
+  prop: JsonSchemaProperty
+  value: unknown
+  unsetLabel: string
+  onChange: (v: unknown) => void
+}) {
+  const id = `prop-${name}`
+
+  if (prop.type === "string" && Array.isArray(prop.enum)) {
+    const options = prop.enum.filter((v): v is string => typeof v === "string")
+    const current = typeof value === "string" && value !== "" ? value : UNSET_SENTINEL
+    return (
+      <FieldShell id={id} name={name} description={prop.description}>
+        <Select
+          value={current}
+          onValueChange={(v) => onChange(v === UNSET_SENTINEL ? undefined : v)}
+        >
+          <SelectTrigger id={id}>
+            <SelectValue placeholder={unsetLabel} />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value={UNSET_SENTINEL}>{unsetLabel}</SelectItem>
+            {options.map((opt) => (
+              <SelectItem key={opt} value={opt}>
+                {opt}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FieldShell>
+    )
+  }
+
+  if (prop.type === "string") {
+    const current = typeof value === "string" ? value : ""
+    return (
+      <FieldShell id={id} name={name} description={prop.description}>
+        <Input
+          id={id}
+          value={current}
+          onChange={(e) => onChange(e.target.value === "" ? undefined : e.target.value)}
+        />
+      </FieldShell>
+    )
+  }
+
+  if (prop.type === "number" || prop.type === "integer") {
+    const current = typeof value === "number" ? String(value) : ""
+    return (
+      <FieldShell id={id} name={name} description={prop.description}>
+        <Input
+          id={id}
+          type="number"
+          value={current}
+          onChange={(e) => {
+            const raw = e.target.value
+            if (raw === "") return onChange(undefined)
+            const parsed =
+              prop.type === "integer" ? Number.parseInt(raw, 10) : Number.parseFloat(raw)
+            if (Number.isFinite(parsed)) onChange(parsed)
+          }}
+        />
+      </FieldShell>
+    )
+  }
+
+  if (prop.type === "boolean") {
+    const current = value === true
+    return (
+      <FieldShell id={id} name={name} description={prop.description}>
+        <Switch
+          id={id}
+          checked={current}
+          onCheckedChange={(checked) => onChange(checked || undefined)}
+        />
+      </FieldShell>
+    )
+  }
+
+  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>
+    </FieldShell>
+  )
+}
+
+function FieldShell({
+  id,
+  name,
+  description,
+  children,
+}: {
+  id: string
+  name: string
+  description?: string
+  children: ReactNode
+}) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      <label htmlFor={id} className="text-sm font-medium">
+        {name}
+      </label>
+      {children}
+      {description ? <p className="text-muted-foreground text-xs">{description}</p> : null}
+    </div>
+  )
+}

package/src/app/widget-renderer.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import type { PipelineContext } from "@miragon/mcp-toolkit-core"
+import { contextHasNoData } from "./widget-renderer.js"
+
+const ctx = (over: Partial<PipelineContext> = {}): PipelineContext => ({
+  steps: {},
+  keys: {},
+  errors: [],
+  ...over,
+})
+
+describe("contextHasNoData", () => {
+  it("is true for an empty context (no steps, no keys)", () => {
+    expect(contextHasNoData(ctx())).toBe(true)
+  })
+
+  it("is true even when there are errors but no data", () => {
+    expect(contextHasNoData(ctx({ errors: [{ stepId: "x", reason: "boom" }] }))).toBe(true)
+  })
+
+  it("is false when keys are present", () => {
+    expect(contextHasNoData(ctx({ keys: { "demo:id": "INV-1" } }))).toBe(false)
+  })
+
+  it("is false when step data is present", () => {
+    expect(
+      contextHasNoData(
+        ctx({
+          steps: {
+            result: {
+              data: { total: 1 },
+              keys: {},
+              _app: "demo",
+              _step: "result",
+              _dataType: "demo:data",
+            },
+          },
+        }),
+      ),
+    ).toBe(false)
+  })
+})

package/src/app/widget-renderer.tsx

@@ -0,0 +1,200 @@
+import { Component, type ComponentType, type ReactNode, type ErrorInfo } from "react"
+import type { LayoutConfig, PipelineContext, RowDef, WidgetProps } from "@miragon/mcp-toolkit-core"
+import { normalizeLayout } from "@miragon/mcp-toolkit-core"
+import { GridLayout, GridItem } from "../components/GridLayout.js"
+import { Card, CardContent } from "../primitives/card.js"
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "../primitives/tabs.js"
+
+export type WidgetComponent = ComponentType<WidgetProps>
+
+/**
+ * Catches render-time crashes from a single widget so one broken widget
+ * can't take down the entire iframe view (or the builder canvas/preview).
+ *
+ * Exported so the visual builder's canvas + preview render sites reuse the
+ * same isolation the rendered `WidgetRenderer` already had — every place a
+ * widget component is rendered goes through {@link RenderedWidget}, which
+ * wraps the component in this boundary.
+ */
+export class WidgetErrorBoundary extends Component<
+  { widgetId: string; children: ReactNode },
+  { error: Error | null }
+> {
+  override state: { error: Error | null } = { error: null }
+  static getDerivedStateFromError(error: Error) {
+    return { error }
+  }
+  override componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error(`Widget ${this.props.widgetId} crashed:`, error, info)
+  }
+  override render() {
+    if (this.state.error) {
+      return (
+        <Card>
+          <CardContent className="text-muted-foreground py-3 text-sm">
+            Widget "{this.props.widgetId}" failed to render.
+          </CardContent>
+        </Card>
+      )
+    }
+    return this.props.children
+  }
+}
+
+/**
+ * True when the pipeline context carries no widget data at all — no step
+ * results and no keys. A widget rendered against an empty context typically
+ * paints an empty shell (Finding [4]); callers use this to swap in a
+ * "data appears after refresh" hint instead.
+ *
+ * Intentionally coarse (per-view, not per-widget): the toolkit can't know
+ * which slice each widget reads without running its adapter, so it only
+ * degrades when there is provably nothing for any widget to show.
+ */
+export function contextHasNoData(context: PipelineContext): boolean {
+  return Object.keys(context.steps).length === 0 && Object.keys(context.keys).length === 0
+}
+
+/**
+ * The single render site for a layout cell's widget, shared across the
+ * rendered view (`RowsRenderer`), the builder canvas, and the builder
+ * preview so all three isolate crashes identically:
+ *   - missing component → "not bundled" fallback,
+ *   - render crash → caught by {@link WidgetErrorBoundary} (Finding [1]),
+ *   - (builder only, opt-in) empty pipeline context → a dezent
+ *     "no data yet" hint (Finding [4]).
+ *
+ * The empty-state hint is gated behind `showEmptyHint` and defaults off so
+ * the shipped rendered view is unchanged: self-fetching control widgets
+ * there render correctly against an empty key-only context. The builder's
+ * canvas/preview opt in because their live context is empty until the first
+ * catalogue refresh resolves, and an empty widget shell reads as broken.
+ *
+ * `notBundledClassName` lets each surface match its own chrome (the builder
+ * uses denser padding/text than the rendered view).
+ */
+export function RenderedWidget({
+  widget: Widget,
+  widgetId,
+  props,
+  cellProps,
+  showEmptyHint = false,
+  notBundledClassName = "text-muted-foreground rounded border border-dashed p-4 text-center text-xs",
+}: {
+  widget: WidgetComponent | undefined
+  widgetId: string
+  props: WidgetProps
+  cellProps?: Record<string, unknown>
+  showEmptyHint?: boolean
+  notBundledClassName?: string
+}) {
+  if (!Widget) {
+    return <div className={notBundledClassName}>Widget "{widgetId}" not bundled.</div>
+  }
+  if (showEmptyHint && contextHasNoData(props.context)) {
+    return (
+      <div className={notBundledClassName}>
+        No data for this widget yet — it appears after a refresh.
+      </div>
+    )
+  }
+  return (
+    <WidgetErrorBoundary widgetId={widgetId}>
+      <Widget {...props} widgetProps={cellProps} />
+    </WidgetErrorBoundary>
+  )
+}
+
+export interface WidgetRendererProps {
+  layout: LayoutConfig
+  keys: Record<string, unknown>
+  stepData?: Record<
+    string,
+    { data: unknown; keys: Record<string, unknown>; _app: string; _dataType: string }
+  >
+  errors: { stepId: string; reason: string }[]
+  /**
+   * Map of widget ID to React component. Consumers provide this so that the
+   * renderer can dispatch layout entries like `{widget: "camunda7:incident-panel"}`
+   * to the concrete component. The map is usually aggregated from each module's
+   * widget exports at the consumer's `main.tsx` entry point.
+   */
+  widgets: Record<string, WidgetComponent>
+}
+
+function RowsRenderer({
+  rows,
+  props,
+  widgets,
+}: {
+  rows: RowDef[]
+  props: WidgetProps
+  widgets: Record<string, WidgetComponent>
+}) {
+  return (
+    <div className="flex flex-col gap-4">
+      {rows.map((row, rowIdx) => (
+        <GridLayout key={rowIdx}>
+          {row.row.map((cell, cellIdx) => {
+            const WidgetComponent = widgets[cell.widget]
+            // Keep the rendered view's original behaviour of skipping cells
+            // whose component isn't bundled (no placeholder in the shipped
+            // view), while still routing the resolvable ones through the
+            // shared `RenderedWidget` for error-boundary + empty-state.
+            if (!WidgetComponent) return null
+            // Use a composite key so the same widget can appear in multiple
+            // cells of one row (e.g. side-by-side scoped dashboards) without
+            // colliding on React's reconciliation key.
+            return (
+              <GridItem key={`${cell.widget}-${cellIdx}`} span={cell.span ?? 12}>
+                <RenderedWidget
+                  widget={WidgetComponent}
+                  widgetId={cell.widget}
+                  props={props}
+                  cellProps={cell.props}
+                />
+              </GridItem>
+            )
+          })}
+        </GridLayout>
+      ))}
+    </div>
+  )
+}
+
+export function WidgetRenderer({ layout, keys, stepData, errors, widgets }: WidgetRendererProps) {
+  const steps: Record<string, PipelineContext["steps"][string]> = {}
+  if (stepData) {
+    for (const [id, result] of Object.entries(stepData)) {
+      steps[id] = { ...result, _step: id }
+    }
+  }
+  const pipelineContext: PipelineContext = {
+    steps,
+    keys,
+    errors,
+  }
+  const widgetProps: WidgetProps = { keys, context: pipelineContext }
+  const normalized = normalizeLayout(layout)
+
+  if ("tabs" in normalized) {
+    return (
+      <Tabs defaultValue={normalized.tabs[0]?.label}>
+        <TabsList>
+          {normalized.tabs.map((tab) => (
+            <TabsTrigger key={tab.label} value={tab.label}>
+              {tab.label}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+        {normalized.tabs.map((tab) => (
+          <TabsContent key={tab.label} value={tab.label}>
+            <RowsRenderer rows={tab.rows} props={widgetProps} widgets={widgets} />
+          </TabsContent>
+        ))}
+      </Tabs>
+    )
+  }
+
+  return <RowsRenderer rows={normalized.rows} props={widgetProps} widgets={widgets} />
+}

package/src/components/DrillButton.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react"
+
+export interface DrillButtonProps {
+  /** Button label. */
+  children: ReactNode
+  /** Drill/navigation handler — wire to in-widget navigation (e.g. `showWidget`). */
+  onDrill: () => void
+  /** Optional leading glyph (e.g. a domain icon). The trailing → is always rendered. */
+  icon?: ReactNode
+  /** `sm` for table rows, `md` for surface headers. Default `"sm"`. */
+  size?: "sm" | "md"
+  /** Accessible label when the visible text is terse. */
+  ariaLabel?: string
+}
+
+/**
+ * The single, deterministic in-widget navigation control: a neutral outline
+ * button with a trailing → that drills into a detail/sub-view. Use it for
+ * every in-app drill (row "Open", header nav) so they read identically and stay
+ * visually quieter than primary/agentic actions. Decoupled from any host — pass
+ * an `onDrill` callback (e.g. wrapping `useHostActions().showWidget`).
+ */
+export function DrillButton({ children, onDrill, icon, size = "sm", ariaLabel }: DrillButtonProps) {
+  const pad = size === "md" ? "px-3 py-1.5 text-sm" : "px-2.5 py-1 text-xs"
+  return (
+    <button
+      type="button"
+      onClick={onDrill}
+      aria-label={ariaLabel}
+      className={`border-border text-foreground hover:bg-muted focus-visible:ring-ring inline-flex items-center gap-1 rounded-md border font-medium transition-colors outline-none focus-visible:ring-2 ${pad}`}
+    >
+      {icon && <span aria-hidden="true">{icon}</span>}
+      {children}
+      <span aria-hidden="true">→</span>
+    </button>
+  )
+}

package/src/components/FilterBar.tsx

@@ -0,0 +1,68 @@
+import { Input } from "../primitives/input.js"
+
+export interface FilterChip {
+  /** Stable id passed back to `onChipToggle`. */
+  id: string
+  /** Visible chip label. */
+  label: string
+  /** Optional count rendered after the label. */
+  count?: number | string
+  /** Whether the chip is currently active. */
+  active?: boolean
+}
+
+export interface FilterBarProps {
+  /** Current search text (controlled). */
+  search: string
+  /** Placeholder for the search input. Default `"Filter…"`. */
+  searchPlaceholder?: string
+  /** Called with the new search text on every keystroke. */
+  onSearchChange: (next: string) => void
+  /** Filter chips rendered to the right of the search input. */
+  chips: FilterChip[]
+  /** Called with a chip id when it is toggled. */
+  onChipToggle: (id: string) => void
+}
+
+/**
+ * Search input + toggleable chip row for filtering a list/table of widget
+ * items. Pair with `useDebouncedValue` to avoid re-querying on every keystroke.
+ */
+export function FilterBar({
+  search,
+  searchPlaceholder = "Filter…",
+  onSearchChange,
+  chips,
+  onChipToggle,
+}: FilterBarProps) {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Input
+        type="search"
+        value={search}
+        onChange={(e) => onSearchChange(e.target.value)}
+        placeholder={searchPlaceholder}
+        className="h-9 min-w-[220px] flex-1 text-sm"
+      />
+      <div className="flex flex-wrap gap-1.5">
+        {chips.map((chip) => (
+          <button
+            type="button"
+            key={chip.id}
+            onClick={() => onChipToggle(chip.id)}
+            className={`inline-flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs font-medium transition-colors ${
+              chip.active
+                ? "bg-accent border-border text-accent-foreground font-semibold"
+                : "border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground"
+            }`}
+          >
+            {chip.label}
+            {chip.count !== undefined && chip.count !== "" && (
+              <span className="tabular-nums opacity-60">{chip.count}</span>
+            )}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/components/GridLayout.tsx

@@ -0,0 +1,49 @@
+import * as React from "react"
+import { cn } from "../lib/utils.js"
+
+export interface GridLayoutProps {
+  /** `GridItem` children to lay out across the 12 columns. */
+  children: React.ReactNode
+  /** Extra classes merged onto the grid container (e.g. to change the gap). */
+  className?: string
+}
+
+/**
+ * 12-column responsive grid container. Wrap `GridItem`s in it to compose
+ * dashboard rows; this is the same grid `WidgetRenderer` uses internally.
+ */
+export function GridLayout({ children, className }: GridLayoutProps) {
+  return <div className={cn("grid grid-cols-12 gap-4", className)}>{children}</div>
+}
+
+export interface GridItemProps {
+  /** Column span from 1–12. Defaults to a full-width `12`. */
+  span?: number
+  /** Cell content. */
+  children: React.ReactNode
+  /** Extra classes merged onto the cell. */
+  className?: string
+}
+
+const spanClasses: Record<number, string> = {
+  1: "col-span-1",
+  2: "col-span-2",
+  3: "col-span-3",
+  4: "col-span-4",
+  5: "col-span-5",
+  6: "col-span-6",
+  7: "col-span-7",
+  8: "col-span-8",
+  9: "col-span-9",
+  10: "col-span-10",
+  11: "col-span-11",
+  12: "col-span-12",
+}
+
+/**
+ * A cell inside a `GridLayout`, spanning `span` of the 12 columns. Out-of-range
+ * spans fall back to full width.
+ */
+export function GridItem({ span = 12, children, className }: GridItemProps) {
+  return <div className={cn(spanClasses[span] ?? "col-span-12", className)}>{children}</div>
+}