@miragon/mcp-toolkit-ui 1.1.0 → 2.0.0

package/src/render-cases-primitives.tsx

@@ -0,0 +1,255 @@
+import type { ReactElement } from "react"
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  Badge,
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  Input,
+  ScrollArea,
+  ScrollBar,
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+  Separator,
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+  Skeleton,
+  Switch,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "./index.js"
+
+/**
+ * One SSR render case (see `render-cases.tsx`, which aggregates this module's
+ * primitive cases with the composed/host ones — split only to respect the
+ * 400-effective-line budget; the exported surface is `RENDER_CASES` there).
+ */
+export interface RenderCase {
+  /** Catalog entry name (`ui-catalog.json` → `components[].name`) this case covers. */
+  name: string
+  /** Distinctive text expected in the SSR markup, when the component can carry one. */
+  marker?: string
+  /** Renders the component with minimal realistic props. */
+  render: () => ReactElement
+}
+
+const noop = (): void => {}
+
+/** SSR render cases for the catalogued shadcn primitives (kind "primitive"). */
+export const PRIMITIVE_RENDER_CASES: RenderCase[] = [
+  {
+    name: "Card",
+    marker: "RC:Card",
+    render: () => (
+      <Card size="sm">
+        <CardHeader>
+          <CardTitle>RC:Card</CardTitle>
+          <CardDescription>Order summary</CardDescription>
+          <CardAction>
+            <Badge variant="outline">new</Badge>
+          </CardAction>
+        </CardHeader>
+        <CardContent>Three orders this week.</CardContent>
+        <CardFooter>Updated just now</CardFooter>
+      </Card>
+    ),
+  },
+  {
+    name: "Badge",
+    marker: "RC:Badge",
+    render: () => <Badge variant="secondary">RC:Badge</Badge>,
+  },
+  {
+    name: "Button",
+    marker: "RC:Button",
+    render: () => (
+      <Button variant="outline" size="sm" onClick={noop}>
+        RC:Button
+      </Button>
+    ),
+  },
+  {
+    // The marker lands in the placeholder/value attributes of the markup.
+    name: "Input",
+    marker: "RC:Input",
+    render: () => <Input type="text" placeholder="RC:Input" defaultValue="42" onChange={noop} />,
+  },
+  {
+    // SSR limitation: SelectContent renders through a Radix portal targeting
+    // document.body, which does not exist server-side — the portal yields
+    // nothing. The trigger + placeholder are the SSR surface; item/label
+    // rendering needs a browser host.
+    name: "Select",
+    marker: "RC:Select",
+    render: () => (
+      <Select onValueChange={noop}>
+        <SelectTrigger>
+          <SelectValue placeholder="RC:Select" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectGroup>
+            <SelectLabel>Period</SelectLabel>
+            <SelectItem value="7d">Last 7 days</SelectItem>
+            <SelectSeparator />
+            <SelectItem value="30d">Last 30 days</SelectItem>
+          </SelectGroup>
+        </SelectContent>
+      </Select>
+    ),
+  },
+  {
+    // The marker lands in the aria-label attribute of the markup.
+    name: "Switch",
+    marker: "RC:Switch",
+    render: () => <Switch defaultChecked aria-label="RC:Switch" onCheckedChange={noop} />,
+  },
+  {
+    name: "Table",
+    marker: "RC:Table",
+    render: () => (
+      <Table>
+        <TableCaption>RC:Table</TableCaption>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Order</TableHead>
+            <TableHead>Status</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableCell>o-1001</TableCell>
+            <TableCell>shipped</TableCell>
+          </TableRow>
+        </TableBody>
+        <TableFooter>
+          <TableRow>
+            <TableCell>1 order</TableCell>
+            <TableCell />
+          </TableRow>
+        </TableFooter>
+      </Table>
+    ),
+  },
+  {
+    name: "Tabs",
+    marker: "RC:Tabs",
+    render: () => (
+      <Tabs defaultValue="overview" onValueChange={noop}>
+        <TabsList>
+          <TabsTrigger value="overview">Overview</TabsTrigger>
+          <TabsTrigger value="detail">Detail</TabsTrigger>
+        </TabsList>
+        <TabsContent value="overview">RC:Tabs</TabsContent>
+        <TabsContent value="detail">Per-order detail</TabsContent>
+      </Tabs>
+    ),
+  },
+  {
+    // SSR limitation: DialogContent renders through a Radix portal targeting
+    // document.body, so the modal body cannot SSR even with `open` — the
+    // trigger is the SSR surface. Portal content needs a browser host.
+    name: "Dialog",
+    marker: "RC:Dialog",
+    render: () => (
+      <Dialog open onOpenChange={noop}>
+        <DialogTrigger>RC:Dialog</DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Archive order?</DialogTitle>
+            <DialogDescription>The order can be restored later.</DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <DialogClose>Cancel</DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    ),
+  },
+  {
+    // SSR limitation: same portal constraint as Dialog — SheetContent targets
+    // document.body; the trigger is the SSR surface.
+    name: "Sheet",
+    marker: "RC:Sheet",
+    render: () => (
+      <Sheet open onOpenChange={noop}>
+        <SheetTrigger>RC:Sheet</SheetTrigger>
+        <SheetContent side="right">
+          <SheetHeader>
+            <SheetTitle>Order o-1001</SheetTitle>
+            <SheetDescription>Edit without leaving the widget.</SheetDescription>
+          </SheetHeader>
+          <SheetFooter>
+            <SheetClose>Close</SheetClose>
+          </SheetFooter>
+        </SheetContent>
+      </Sheet>
+    ),
+  },
+  {
+    name: "Alert",
+    marker: "RC:Alert",
+    render: () => (
+      <Alert variant="destructive">
+        <AlertTitle>RC:Alert</AlertTitle>
+        <AlertDescription>The engine rejected the job.</AlertDescription>
+      </Alert>
+    ),
+  },
+  {
+    name: "ScrollArea",
+    marker: "RC:ScrollArea",
+    render: () => (
+      <ScrollArea className="h-24">
+        <div>RC:ScrollArea</div>
+        <ScrollBar orientation="vertical" />
+      </ScrollArea>
+    ),
+  },
+  {
+    // Pure placeholder box — no text content to mark.
+    name: "Skeleton",
+    render: () => <Skeleton className="h-6 w-32" />,
+  },
+  {
+    // Decorative divider — no text content to mark.
+    name: "Separator",
+    render: () => <Separator orientation="horizontal" />,
+  },
+]

package/src/render-cases.tsx

@@ -0,0 +1,239 @@
+import type { ReactElement } from "react"
+import {
+  Button,
+  CountPill,
+  DrillButton,
+  FilterBar,
+  GridItem,
+  GridLayout,
+  GroupCard,
+  KpiGrid,
+  ListFooter,
+  LivePill,
+  LocaleProvider,
+  SectionHeading,
+  ThemeProvider,
+  themePresets,
+  useLocale,
+  WidgetHeader,
+} from "./index.js"
+import { createStandaloneHostBridge, HostBridgeProvider, useHostBridge } from "./app/host-bridge.js"
+import { HostModelContext } from "./app/adapt-data-widget.js"
+import { WidgetFixtureHost, type FixtureWidget } from "./app/widget-fixture.js"
+import { PRIMITIVE_RENDER_CASES, type RenderCase } from "./render-cases-primitives.js"
+
+export type { RenderCase } from "./render-cases-primitives.js"
+
+/**
+ * SSR render cases for every catalogued component/composite (FITNESS.md phase
+ * 5c). DATA module, not a test: `render-smoke.test.tsx` renders each case via
+ * `react-dom/server`'s `renderToStaticMarkup` (jsdom is deliberately renounced
+ * — SSR is the house render path) and enforces completeness against
+ * `ui-catalog.json` ∪ `ratchets/render-allowlist.json` (shrink-only).
+ *
+ * Each case mounts the component with minimal realistic props and, where the
+ * markup can carry one, a distinctive `marker` string the test asserts on.
+ * The primitive cases live in `render-cases-primitives.tsx` (file-length
+ * budget); this module aggregates them with the composed/host cases.
+ */
+
+const noop = (): void => {}
+
+/** Static bridge for the host-bridge cases — theme "dark" is the probed marker. */
+const probeBridge = createStandaloneHostBridge({
+  callTool: () => Promise.resolve({}),
+  theme: "dark",
+})
+
+/** Proves HostBridgeProvider actually provides: reads the bridge from context. */
+function BridgeThemeProbe(): ReactElement {
+  const bridge = useHostBridge()
+  return <span>RC:HostBridgeProvider {bridge.theme ?? "unset"}</span>
+}
+
+/** Proves LocaleProvider actually provides: reads the locale from context. */
+function LocaleProbe(): ReactElement {
+  const locale = useLocale()
+  return <span>RC:LocaleProvider {locale}</span>
+}
+
+/** Minimal raw `({ data })` widget for the WidgetFixtureHost case. */
+function FixtureProbeWidget({ data }: { data?: { label?: string } | null }): ReactElement {
+  return <div>RC:WidgetFixtureHost {data?.label ?? "no fixture"}</div>
+}
+
+export const RENDER_CASES: RenderCase[] = [
+  ...PRIMITIVE_RENDER_CASES,
+
+  // ── Composed components ──
+  {
+    name: "GridLayout",
+    marker: "RC:GridLayout",
+    render: () => (
+      <GridLayout>
+        <GridItem span={8}>
+          <div>RC:GridLayout</div>
+        </GridItem>
+        <GridItem span={4}>
+          <div>side tile</div>
+        </GridItem>
+      </GridLayout>
+    ),
+  },
+  {
+    name: "GridItem",
+    marker: "RC:GridItem",
+    render: () => (
+      <GridLayout>
+        <GridItem span={6}>
+          <div>RC:GridItem</div>
+        </GridItem>
+      </GridLayout>
+    ),
+  },
+  {
+    name: "KpiGrid",
+    marker: "RC:KpiGrid",
+    render: () => (
+      <KpiGrid
+        boxed
+        header={{ label: "RC:KpiGrid", badge: "live" }}
+        cells={[
+          {
+            label: "Open",
+            value: 7,
+            tone: "danger",
+            trend: "+2 vs yesterday",
+            trendDirection: "up",
+          },
+          { label: "Done", value: 12, fraction: "/19", tone: "success" },
+          { label: "Total", value: 19, onClick: noop, ariaLabel: "Show all" },
+        ]}
+      />
+    ),
+  },
+  {
+    name: "LivePill",
+    marker: "RC:LivePill",
+    render: () => <LivePill tone="success">RC:LivePill</LivePill>,
+  },
+  {
+    name: "CountPill",
+    marker: "RC:CountPill",
+    render: () => <CountPill tone="warning">RC:CountPill</CountPill>,
+  },
+  {
+    name: "SectionHeading",
+    marker: "RC:SectionHeading",
+    render: () => <SectionHeading title="RC:SectionHeading" hint="3 shown" />,
+  },
+  {
+    name: "WidgetHeader",
+    marker: "RC:WidgetHeader",
+    render: () => (
+      <WidgetHeader
+        icon="✓"
+        iconTone="info"
+        title="RC:WidgetHeader"
+        sub={<LivePill>Live</LivePill>}
+        actions={
+          <Button size="sm" variant="ghost" onClick={noop}>
+            Refresh
+          </Button>
+        }
+      />
+    ),
+  },
+  {
+    name: "GroupCard",
+    marker: "RC:GroupCard",
+    render: () => (
+      <GroupCard expanded onToggle={noop} summary={<div>RC:GroupCard</div>}>
+        <div>Expanded body row</div>
+      </GroupCard>
+    ),
+  },
+  {
+    // The search marker lands in the input's value attribute.
+    name: "FilterBar",
+    marker: "RC:FilterBar",
+    render: () => (
+      <FilterBar
+        search="RC:FilterBar"
+        searchPlaceholder="Filter tasks…"
+        onSearchChange={noop}
+        chips={[
+          { id: "high", label: "high", count: 2, active: true },
+          { id: "low", label: "low" },
+        ]}
+        onChipToggle={noop}
+      />
+    ),
+  },
+  {
+    name: "DrillButton",
+    marker: "RC:DrillButton",
+    render: () => (
+      <DrillButton onDrill={noop} icon="↗" size="sm" ariaLabel="Open order o-1001">
+        RC:DrillButton
+      </DrillButton>
+    ),
+  },
+  {
+    name: "ListFooter",
+    marker: "of 42 tasks",
+    render: () => <ListFooter shown={8} total={42} hasMore onLoadMore={noop} noun="tasks" />,
+  },
+
+  // ── Host seam / providers ──
+  {
+    name: "HostBridgeProvider",
+    marker: "RC:HostBridgeProvider dark",
+    render: () => (
+      <HostBridgeProvider bridge={probeBridge}>
+        <BridgeThemeProbe />
+      </HostBridgeProvider>
+    ),
+  },
+  {
+    // Outside an mcp-use view HostModelContext reports through the bridge in
+    // an effect (a no-op in SSR) and must still render its children.
+    name: "HostModelContext",
+    marker: "RC:HostModelContext",
+    render: () => (
+      <HostBridgeProvider bridge={probeBridge}>
+        <HostModelContext content="Viewing 3 open incidents">
+          <div>RC:HostModelContext</div>
+        </HostModelContext>
+      </HostBridgeProvider>
+    ),
+  },
+  {
+    name: "ThemeProvider",
+    marker: "RC:ThemeProvider",
+    render: () => (
+      <ThemeProvider theme={themePresets.miragon} mode="dark">
+        <div>RC:ThemeProvider</div>
+      </ThemeProvider>
+    ),
+  },
+  {
+    name: "LocaleProvider",
+    marker: "RC:LocaleProvider de",
+    render: () => (
+      <LocaleProvider locale="de">
+        <LocaleProbe />
+      </LocaleProvider>
+    ),
+  },
+  {
+    name: "WidgetFixtureHost",
+    marker: "RC:WidgetFixtureHost fixture-data",
+    render: () => (
+      <WidgetFixtureHost
+        widget={FixtureProbeWidget as FixtureWidget}
+        data={{ label: "fixture-data" }}
+      />
+    ),
+  },
+]

package/src/render-smoke.test.tsx

@@ -0,0 +1,100 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import catalog from "../ui-catalog.json" with { type: "json" }
+import allowlist from "../../../ratchets/render-allowlist.json" with { type: "json" }
+import { RENDER_CASES } from "./render-cases.js"
+
+/**
+ * Render-coverage ratchet (FITNESS.md phase 5c). jsdom is deliberately
+ * renounced in this repo — SSR via `react-dom/server`'s `renderToStaticMarkup`
+ * is the house render path, and mutation testing does NOT measure the JSX
+ * render surface, so this suite is the compensating control:
+ *
+ * 1. every case in `render-cases.tsx` must SSR without throwing, produce
+ *    non-empty markup, and contain its marker where one is set;
+ * 2. every component-like `ui-catalog.json` entry must have a render case OR
+ *    a justified entry in `ratchets/render-allowlist.json` (shrink-only).
+ */
+
+interface CatalogEntry {
+  name: string
+  kind: string
+}
+
+const catalogEntries = (catalog as unknown as { components: CatalogEntry[] }).components
+
+/** Kinds that render as React elements and therefore need an SSR case. */
+const COMPONENT_KINDS = new Set(["primitive", "component"])
+/** Kinds that are not renderable on their own (values, hooks, types). */
+const NON_RENDER_KINDS = new Set(["hook", "function", "object", "type"])
+
+const componentEntryNames = new Set(
+  catalogEntries.filter((entry) => COMPONENT_KINDS.has(entry.kind)).map((entry) => entry.name),
+)
+const caseNames = new Set(RENDER_CASES.map((renderCase) => renderCase.name))
+const allowlistedNames = new Set(allowlist.components.map((entry) => entry.name))
+
+const GATE_HINT =
+  "add a RENDER_CASES entry in packages/ui/src/render-cases.tsx (SSR, no jsdom) " +
+  "or justify it in ratchets/render-allowlist.json (shrink-only)"
+
+describe("RENDER_CASES (SSR render suite)", () => {
+  it("has one case per name — duplicates would mask a missing component", () => {
+    expect(caseNames.size).toBe(RENDER_CASES.length)
+  })
+
+  for (const renderCase of RENDER_CASES) {
+    it(`${renderCase.name} SSR-renders to non-empty markup`, () => {
+      const html = renderToStaticMarkup(renderCase.render())
+      expect(html.length, `${renderCase.name} rendered empty markup`).toBeGreaterThan(0)
+      if (renderCase.marker) {
+        expect(html, `${renderCase.name} markup lost its marker`).toContain(renderCase.marker)
+      }
+    })
+  }
+})
+
+describe("render coverage (catalog completeness gate)", () => {
+  it("classifies every catalog kind — a new kind must be triaged here, not skipped silently", () => {
+    for (const entry of catalogEntries) {
+      expect(
+        COMPONENT_KINDS.has(entry.kind) || NON_RENDER_KINDS.has(entry.kind),
+        `Unknown catalog kind "${entry.kind}" on "${entry.name}". Add it to COMPONENT_KINDS ` +
+          `(then ${GATE_HINT}) or to NON_RENDER_KINDS in render-smoke.test.tsx.`,
+      ).toBe(true)
+    }
+  })
+
+  it("covers every component-like catalog entry (RENDER_CASES ∪ render-allowlist)", () => {
+    const missing = [...componentEntryNames].filter(
+      (name) => !caseNames.has(name) && !allowlistedNames.has(name),
+    )
+    expect(
+      missing,
+      `Catalogued component(s) [${missing.join(", ")}] have no SSR render case — ${GATE_HINT}.`,
+    ).toEqual([])
+  })
+
+  it("every RENDER_CASES entry names a component-like catalog entry (no drift)", () => {
+    const unknown = RENDER_CASES.map((c) => c.name).filter((name) => !componentEntryNames.has(name))
+    expect(
+      unknown,
+      `RENDER_CASES entr${unknown.length === 1 ? "y" : "ies"} [${unknown.join(", ")}] match(es) no ` +
+        "component-like ui-catalog.json entry — rename the case to the catalog name or catalogue the component.",
+    ).toEqual([])
+  })
+
+  it("allowlist hygiene: reasons present, entries real, none double-listed", () => {
+    for (const entry of allowlist.components) {
+      expect(entry.reason, `${entry.name} needs a non-empty reason`).toBeTruthy()
+      expect(
+        componentEntryNames.has(entry.name),
+        `${entry.name} is allowlisted but is no component-like ui-catalog.json entry — remove the row (shrink-only)`,
+      ).toBe(true)
+      expect(
+        caseNames.has(entry.name),
+        `${entry.name} is BOTH rendered in RENDER_CASES and allowlisted — remove the stale allowlist row`,
+      ).toBe(false)
+    }
+  })
+})

package/src/ui-catalog.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest"
 import catalog from "../ui-catalog.json" with { type: "json" }
+import allowlist from "../ui-catalog.allowlist.json" with { type: "json" }
 import * as rootBarrel from "./index.js"
 import * as appBarrel from "./app/index.js"
 import * as hooksBarrel from "./hooks/index.js"
@@ -109,4 +110,55 @@ describe("ui-catalog.json", () => {
       expect(Array.isArray(entry.props), `${entry.name} props`).toBe(true)
     }
   })
+
+  // ── Reverse direction (FITNESS.md, phase 5a) ──
+  // The catalog ships in the tarball and is LLM-consumer surface: a NEW
+  // export that reaches a barrel without a catalog entry (or a justified
+  // allowlist row) is invisible to every prompting agent — and previously
+  // fell through this guard, which only checked catalog → barrel.
+
+  /** Every value export a catalog entry or its parts account for. */
+  function cataloguedExports(): Set<string> {
+    const names = new Set<string>()
+    for (const entry of catalogData.components) {
+      names.add(entry.export)
+      for (const part of entry.parts ?? []) names.add(part)
+    }
+    return names
+  }
+
+  /** Exported for the difference logic to stay testable (see fitness gates). */
+  function uncataloguedExports(barrel: Record<string, unknown>): string[] {
+    const catalogued = cataloguedExports()
+    const allowed = new Set(allowlist.allow.map((a) => a.export))
+    return Object.keys(barrel)
+      .filter((name) => !catalogued.has(name) && !allowed.has(name))
+      .sort()
+  }
+
+  it("no uncatalogued export escapes the barrels (catalog ∪ allowlist)", () => {
+    for (const [importPath, barrel] of Object.entries(BARRELS)) {
+      const escaped = uncataloguedExports(barrel)
+      expect(
+        escaped,
+        `New export(s) [${escaped.join(", ")}] from ${importPath} are neither in ui-catalog.json nor in ui-catalog.allowlist.json. Catalogue them (name/export/importPath/kind/group/props/whenToUse — the catalog ships to LLM consumers) or add a justified allowlist row. The allowlist is shrink-only.`,
+      ).toEqual([])
+    }
+  })
+
+  it("allowlist hygiene: entries carry reasons and still exist in a barrel", () => {
+    const allExports = new Set(Object.values(BARRELS).flatMap((b) => Object.keys(b)))
+    const catalogued = cataloguedExports()
+    for (const row of allowlist.allow) {
+      expect(row.reason, `${row.export} needs a reason`).toBeTruthy()
+      expect(
+        allExports.has(row.export),
+        `${row.export} is allowlisted but no barrel exports it — remove the row (shrink-only)`,
+      ).toBe(true)
+      expect(
+        catalogued.has(row.export),
+        `${row.export} is BOTH catalogued and allowlisted — remove the stale allowlist row`,
+      ).toBe(false)
+    }
+  })
 })