@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/render-cases.tsx

@@ -1,24 +1,31 @@
 import type { ReactElement } from "react"
+import { ExternalLink, Inbox } from "lucide-react"
 import {
   Button,
   CountPill,
   DrillButton,
+  EmptyState,
+  ErrorState,
   FilterBar,
   GridItem,
   GridLayout,
   GroupCard,
   KpiGrid,
+  KpiGridSkeleton,
   ListFooter,
   LivePill,
   LocaleProvider,
+  PagedListFooter,
   SectionHeading,
+  StatusBadge,
   ThemeProvider,
   themePresets,
+  ToastProvider,
   useLocale,
   WidgetHeader,
 } from "./index.js"
 import { createStandaloneHostBridge, HostBridgeProvider, useHostBridge } from "./app/host-bridge.js"
-import { HostModelContext } from "./app/adapt-data-widget.js"
+import { HostModelContext } from "./app/model-context.js"
 import { WidgetFixtureHost, type FixtureWidget } from "./app/widget-fixture.js"
 import { PRIMITIVE_RENDER_CASES, type RenderCase } from "./render-cases-primitives.js"
 
@@ -107,11 +114,17 @@ export const RENDER_CASES: RenderCase[] = [
             trendDirection: "up",
           },
           { label: "Done", value: 12, fraction: "/19", tone: "success" },
-          { label: "Total", value: 19, onClick: noop, ariaLabel: "Show all" },
+          { label: "Total", value: 19, onClick: noop, actionHint: "Shows all orders" },
         ]}
       />
     ),
   },
+  {
+    // A skeleton has no text; the marker is its busy state.
+    name: "KpiGridSkeleton",
+    marker: 'aria-busy="true"',
+    render: () => <KpiGridSkeleton cells={4} boxed />,
+  },
   {
     name: "LivePill",
     marker: "RC:LivePill",
@@ -122,6 +135,11 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "RC:CountPill",
     render: () => <CountPill tone="warning">RC:CountPill</CountPill>,
   },
+  {
+    name: "StatusBadge",
+    marker: "RC:StatusBadge",
+    render: () => <StatusBadge tone="warning">RC:StatusBadge</StatusBadge>,
+  },
   {
     name: "SectionHeading",
     marker: "RC:SectionHeading",
@@ -132,9 +150,9 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "RC:WidgetHeader",
     render: () => (
       <WidgetHeader
-        icon="✓"
-        iconTone="info"
+        as="h2"
         title="RC:WidgetHeader"
+        badge={<StatusBadge tone="info">Running</StatusBadge>}
         sub={<LivePill>Live</LivePill>}
         actions={
           <Button size="sm" variant="ghost" onClick={noop}>
@@ -174,7 +192,7 @@ export const RENDER_CASES: RenderCase[] = [
     name: "DrillButton",
     marker: "RC:DrillButton",
     render: () => (
-      <DrillButton onDrill={noop} icon="↗" size="sm" ariaLabel="Open order o-1001">
+      <DrillButton onDrill={noop} icon={<ExternalLink />} size="sm" ariaLabel="Open order o-1001">
         RC:DrillButton
       </DrillButton>
     ),
@@ -184,6 +202,64 @@ export const RENDER_CASES: RenderCase[] = [
     marker: "of 42 tasks",
     render: () => <ListFooter shown={8} total={42} hasMore onLoadMore={noop} noun="tasks" />,
   },
+  {
+    name: "PagedListFooter",
+    marker: "of 3 orders",
+    render: () => (
+      <PagedListFooter
+        paged={{
+          items: ["o-1", "o-2"],
+          total: 3,
+          hasMore: true,
+          loadMore: noop,
+          refreshing: true,
+          firstPage: {},
+          loadMoreError: new Error("HTTP 503"),
+        }}
+        noun="orders"
+      />
+    ),
+  },
+
+  // ── Feedback and states ──
+  {
+    // The provider renders its children plus the (empty) live region.
+    name: "ToastProvider",
+    marker: "RC:ToastProvider",
+    render: () => (
+      <ToastProvider>
+        <div>RC:ToastProvider</div>
+      </ToastProvider>
+    ),
+  },
+  {
+    name: "EmptyState",
+    marker: "RC:EmptyState",
+    render: () => (
+      <EmptyState
+        icon={<Inbox />}
+        title="RC:EmptyState"
+        description="No orders in this period."
+        action={
+          <Button size="sm" onClick={noop}>
+            New order
+          </Button>
+        }
+      />
+    ),
+  },
+  {
+    name: "ErrorState",
+    marker: "RC:ErrorState",
+    render: () => (
+      <ErrorState
+        title="RC:ErrorState"
+        description="Check the connection and try again."
+        details="HTTP 503 Service Unavailable"
+        onRetry={noop}
+      />
+    ),
+  },
 
   // ── Host seam / providers ──
   {
@@ -212,7 +288,7 @@ export const RENDER_CASES: RenderCase[] = [
     name: "ThemeProvider",
     marker: "RC:ThemeProvider",
     render: () => (
-      <ThemeProvider theme={themePresets.miragon} mode="dark">
+      <ThemeProvider theme={themePresets.emerald} mode="dark">
         <div>RC:ThemeProvider</div>
       </ThemeProvider>
     ),

package/src/render-effects.tsx

@@ -0,0 +1,96 @@
+/**
+ * Effect-running renders for the WIRING tests SSR cannot see: effects,
+ * subscriptions and timers of the view lifecycle and the data hooks
+ * (toolkit#176 review). `react-dom/client` + `act` in a test file that opts
+ * into a DOM with `// @vitest-environment happy-dom`. Not an interaction kit:
+ * the house render path stays SSR (`renderToStaticMarkup`), and these tests
+ * drive hooks through their inputs; a `click()` only where the wiring starts
+ * at a button.
+ */
+import { act, useEffect, type ReactNode } from "react"
+import { createRoot } from "react-dom/client"
+
+// React warns about updates outside act() unless the runtime says it is a test.
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+/**
+ * Run `work` in an ASYNC act scope: the promises it starts (a tool call that
+ * resolves, a state update after it) settle, and their renders commit,
+ * before the scope ends.
+ */
+export function inAct(work: () => unknown): Promise<void> {
+  return act(() => {
+    work()
+    return Promise.resolve()
+  })
+}
+
+export interface EffectRender {
+  container: HTMLElement
+  /** Render `node` into the same root (a new host state, new props). */
+  rerender: (node: ReactNode) => Promise<void>
+  /** Unmount and run the cleanups; a second call does nothing. */
+  unmount: () => Promise<void>
+}
+
+/** Mount `node` and run its effects. */
+export async function renderWithEffects(node: ReactNode): Promise<EffectRender> {
+  const container = document.createElement("div")
+  document.body.append(container)
+  const root = createRoot(container)
+  await inAct(() => root.render(node))
+  let mounted = true
+  return {
+    container,
+    rerender: (next) => inAct(() => root.render(next)),
+    unmount: async () => {
+      if (!mounted) return
+      mounted = false
+      await inAct(() => root.unmount())
+      container.remove()
+    },
+  }
+}
+
+/**
+ * Settle pending promises and the effects and renders they cause, with real
+ * timers: TanStack Query notifies its observers on a 0 ms timer, so each
+ * round lets one land (under fake timers use {@link advanceTimers}).
+ */
+export async function flushEffects(rounds = 3): Promise<void> {
+  for (let round = 0; round < rounds; round++) {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0))
+    })
+  }
+}
+
+/** Advance fake timers by `ms` inside act, so the renders they cause commit. */
+export function advanceTimers(advance: (ms: number) => unknown, ms: number): Promise<void> {
+  return inAct(() => advance(ms))
+}
+
+/**
+ * Renders `useValue` in a probe and keeps its latest committed value: read
+ * `current` after a render or flush.
+ */
+export function hookProbe<T>(useValue: () => T): {
+  Probe: () => null
+  current: () => T
+} {
+  const box: { value?: { current: T } } = {}
+  function Probe(): null {
+    const value = useValue()
+    useEffect(() => {
+      box.value = { current: value }
+    })
+    return null
+  }
+  return {
+    Probe,
+    current: () => {
+      if (!box.value) throw new Error("the probe has not committed yet")
+      return box.value.current
+    },
+  }
+}

package/src/render-scan.ts

@@ -0,0 +1,75 @@
+/**
+ * Read SSR markup (`renderToStaticMarkup`) the way a user — sighted or with a
+ * screen reader — meets it: its text nodes plus the attributes that carry
+ * text (accessible names, tooltips, placeholders). DATA/TEST support module
+ * like `render-cases.tsx`: the a11y and i18n render suites scan through it,
+ * so it stays pure and dependency-free. React's SSR output is well-formed
+ * (attributes always double-quoted), which is what keeps these regexes honest.
+ */
+
+/** Attributes whose value a user reads or hears. */
+export const TEXT_ATTRIBUTES = [
+  "aria-label",
+  "aria-description",
+  "aria-roledescription",
+  "aria-valuetext",
+  "title",
+  "placeholder",
+  "alt",
+] as const
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+}
+
+/** Decode the HTML entities React's SSR emits (named, decimal and hex). */
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, ref: string) => {
+    if (ref.startsWith("#x") || ref.startsWith("#X")) {
+      return String.fromCodePoint(Number.parseInt(ref.slice(2), 16))
+    }
+    if (ref.startsWith("#")) return String.fromCodePoint(Number.parseInt(ref.slice(1), 10))
+    return NAMED_ENTITIES[ref.toLowerCase()] ?? whole
+  })
+}
+
+/** One piece of user-facing text in the markup. */
+export interface MarkupText {
+  /** `"text"` for a text node, else the attribute name. */
+  source: string
+  value: string
+}
+
+/** Every non-blank text node and text-bearing attribute value, decoded. */
+export function userFacingTexts(html: string): MarkupText[] {
+  const out: MarkupText[] = []
+  const withoutRawText = html.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, "")
+  for (const chunk of withoutRawText.split(/<[^>]*>/)) {
+    const value = decodeEntities(chunk).trim()
+    if (value) out.push({ source: "text", value })
+  }
+  for (const tag of withoutRawText.match(/<[a-z][^>]*>/gi) ?? []) {
+    for (const name of TEXT_ATTRIBUTES) {
+      const value = attribute(tag, name)
+      if (value?.trim()) out.push({ source: name, value: value.trim() })
+    }
+  }
+  return out
+}
+
+/** The opening tags of every element named `tag` (e.g. `"button"`). */
+export function openingTags(html: string, tag: string): string[] {
+  return html.match(new RegExp(`<${tag}(?=[\\s>/])[^>]*>`, "gi")) ?? []
+}
+
+/** The decoded value of `name` on one opening tag, `undefined` when absent. */
+export function attribute(openingTag: string, name: string): string | undefined {
+  const escaped = name.replace(/[-]/g, "\\-")
+  const match = new RegExp(`\\s${escaped}="([^"]*)"`, "i").exec(openingTag)
+  return match ? decodeEntities(match[1] ?? "") : undefined
+}

package/src/theme/cd-tokens.generated.css

@@ -0,0 +1,48 @@
+/* Aus Miragon/corporate-identity übernommen (miragon-brand 1.8.0, modeler-tool-design/assets/cd-tokens.generated.css). Nicht ändern, zum Aktualisieren neu aus der Skill kopieren. */
+/* AUTOMATISCH GENERIERT aus brand/tokens.json. Nicht von Hand ändern, sondern die Quelle bearbeiten und `npm run tokens:build` laufen lassen. */
+:root {
+  --cd-blau: #335DE5;
+  --cd-gruen: #00E676;
+  --cd-grau: #F9F7F7;
+  --cd-schwarz: #1D1D1D;
+  --cd-weiss: #FFFFFF;
+  --cd-blau-link: #2B50D4;
+  --cd-blau-hell: #6B8AFF;
+  --cd-success: #00E676;
+  --cd-success-soft: #DAFBEB;
+  --cd-success-hell: #00E676;
+  --cd-warning: #FFB000;
+  --cd-warning-soft: #FFF1D2;
+  --cd-warning-hell: #FFB000;
+  --cd-danger: #CD1839;
+  --cd-danger-soft: #FBEEF0;
+  --cd-danger-hell: #FB6D73;
+  --cd-info: #335DE5;
+  --cd-info-soft: #EEF1FD;
+  --cd-info-hell: #6B8AFF;
+  --cd-linie: #E6E2E2;
+  --cd-kontur: #8F8A8A;
+  --cd-text-leise: #6B6666;
+  --cd-gradient-brand: linear-gradient(120deg, #335DE5 30%, #00E676);
+  --cd-gradient-format: linear-gradient(135deg, #335DE5 0%, #00E676 140%);
+  --cd-space-1: 4px;
+  --cd-space-2: 8px;
+  --cd-space-3: 16px;
+  --cd-space-4: 24px;
+  --cd-space-5: 32px;
+  --cd-space-6: 48px;
+  --cd-space-7: 64px;
+  --cd-space-8: 96px;
+  --cd-radius-sm: 6px;
+  --cd-radius-md: 12px;
+  --cd-radius-lg: 16px;
+  --cd-radius-pill: 999px;
+  --cd-shadow-1: 0 1px 2px rgba(29, 29, 29, 0.06), 0 1px 3px rgba(29, 29, 29, 0.10);
+  --cd-shadow-2: 0 4px 12px rgba(29, 29, 29, 0.10);
+  --cd-shadow-3: 0 12px 32px rgba(29, 29, 29, 0.16);
+  --cd-motion-fast: 150ms;
+  --cd-motion-base: 250ms;
+  --cd-motion-slow: 400ms;
+  --cd-ease: cubic-bezier(0.4, 0, 0.2, 1);
+  --cd-ease-out: cubic-bezier(0, 0, 0.2, 1);
+}

package/src/theme/cd-tokens.test.ts

@@ -0,0 +1,109 @@
+/// <reference types="node" />
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { CD_TOKENS, CD_TOKENS_VERSION } from "./cd-tokens.js"
+
+/**
+ * Drift guard for the vendored Miragon corporate-design tokens
+ * (modeler-tool-design §13): the copy must stay the skill's file, unchanged.
+ *
+ * `cd-tokens.generated.css` = ONE marker line + the upstream file byte for
+ * byte. Upstream is miragon-brand's `modeler-tool-design/assets/
+ * cd-tokens.generated.css`. When a checkout of the plugin is reachable
+ * (`MIRAGON_CD_TOKENS` or a Claude plugin cache under $HOME), the copy is
+ * compared to it directly; everywhere else (CI) the pinned hash below holds it.
+ *
+ * To re-vendor: copy the new upstream file below the marker line, update the
+ * version in the marker, CD_TOKENS_VERSION, UPSTREAM_SHA256 and CD_TOKENS,
+ * then copy the result to docs/.vitepress/theme/ (the docs site vendors the
+ * same file; examples/test/docs-theme.test.ts holds the two byte-identical).
+ */
+const UPSTREAM_SHA256 = "36d76f3a330a1250d332c6862be1dc4f7564d2461e7051d9a565ba723ef2c379"
+const UPSTREAM_REL = join("skills", "modeler-tool-design", "assets", "cd-tokens.generated.css")
+const MARKER =
+  `/* Aus Miragon/corporate-identity übernommen (miragon-brand ${CD_TOKENS_VERSION}, ` +
+  "modeler-tool-design/assets/cd-tokens.generated.css). Nicht ändern, zum Aktualisieren neu aus der Skill kopieren. */\n"
+
+const vendored = readFileSync(new URL("./cd-tokens.generated.css", import.meta.url), "utf8")
+const upstreamPart = vendored.slice(MARKER.length)
+
+/** A reachable upstream copy of this version, or null (CI). */
+function findUpstream(): string | null {
+  const explicit = process.env.MIRAGON_CD_TOKENS
+  if (explicit) return existsSync(explicit) ? explicit : null
+  const home = homedir()
+  let entries: string[]
+  try {
+    entries = readdirSync(home).filter((name) => name.startsWith(".claude"))
+  } catch {
+    return null
+  }
+  for (const dir of entries) {
+    const candidate = join(
+      home,
+      dir,
+      "plugins",
+      "cache",
+      "miragon-agent-skills",
+      "miragon-brand",
+      CD_TOKENS_VERSION,
+      UPSTREAM_REL,
+    )
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/** `--cd-name: value;` declarations of the vendored `:root`. */
+function cssTokens(css: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const match of css.matchAll(/--cd-([a-z0-9-]+):\s*([^;]+);/g)) {
+    out[match[1] as string] = (match[2] as string).trim()
+  }
+  return out
+}
+
+describe("cd-tokens.generated.css (vendored, never edited)", () => {
+  it("starts with the generated-file marker naming the brand version", () => {
+    expect(vendored.startsWith(MARKER)).toBe(true)
+  })
+
+  it("is the upstream file byte for byte below the marker (pinned hash)", () => {
+    const hash = createHash("sha256").update(upstreamPart, "utf8").digest("hex")
+    expect(hash, "re-vendor from the skill instead of editing the copy").toBe(UPSTREAM_SHA256)
+  })
+
+  it("is byte-identical to the skill's file when a plugin checkout is reachable", () => {
+    const upstream = findUpstream()
+    // Off-machine (CI) the pinned hash above is the guard; say so loudly.
+    if (!upstream) {
+      console.warn(
+        `cd-tokens drift: no miragon-brand ${CD_TOKENS_VERSION} checkout found — relying on the pinned hash`,
+      )
+      return
+    }
+    expect(upstreamPart).toBe(readFileSync(upstream, "utf8"))
+  })
+})
+
+describe("CD_TOKENS (the TS mirror of :root)", () => {
+  const css = cssTokens(upstreamPart)
+
+  it("mirrors every --cd-* token value exactly", () => {
+    for (const [name, value] of Object.entries(css)) {
+      expect(CD_TOKENS[name as keyof typeof CD_TOKENS], `--cd-${name}`).toBe(value)
+    }
+  })
+
+  it("declares no token the CSS does not", () => {
+    expect(Object.keys(CD_TOKENS).sort()).toEqual(Object.keys(css).sort())
+  })
+
+  it("parses a non-trivial token set (the parser itself is alive)", () => {
+    expect(Object.keys(css).length).toBeGreaterThanOrEqual(40)
+    expect(css.blau).toBe("#335DE5")
+  })
+})

package/src/theme/cd-tokens.ts

@@ -0,0 +1,67 @@
+/**
+ * The Miragon corporate-design tokens (`--cd-*`) as plain TypeScript, for code
+ * that cannot read CSS variables — an SVG or canvas renderer (BPMN overlays,
+ * chart marks), a server-side image, a test. Keys are the CSS names without the
+ * `--cd-` prefix.
+ *
+ * The source of truth is the vendored `cd-tokens.generated.css` next to this
+ * file (miragon-brand 1.8.0, copied unchanged from Miragon/corporate-identity).
+ * This module mirrors it value for value; `cd-tokens.test.ts` fails on any
+ * drift (modeler-tool-design §13). Never edit a value here without re-vendoring
+ * the CSS first.
+ *
+ * UI code styles through the role tokens (`bg-primary`, `text-link`,
+ * `border-danger`, …), never through these constants.
+ */
+export const CD_TOKENS = {
+  blau: "#335DE5",
+  gruen: "#00E676",
+  grau: "#F9F7F7",
+  schwarz: "#1D1D1D",
+  weiss: "#FFFFFF",
+  "blau-link": "#2B50D4",
+  "blau-hell": "#6B8AFF",
+  success: "#00E676",
+  "success-soft": "#DAFBEB",
+  "success-hell": "#00E676",
+  warning: "#FFB000",
+  "warning-soft": "#FFF1D2",
+  "warning-hell": "#FFB000",
+  danger: "#CD1839",
+  "danger-soft": "#FBEEF0",
+  "danger-hell": "#FB6D73",
+  info: "#335DE5",
+  "info-soft": "#EEF1FD",
+  "info-hell": "#6B8AFF",
+  linie: "#E6E2E2",
+  kontur: "#8F8A8A",
+  "text-leise": "#6B6666",
+  "gradient-brand": "linear-gradient(120deg, #335DE5 30%, #00E676)",
+  "gradient-format": "linear-gradient(135deg, #335DE5 0%, #00E676 140%)",
+  "space-1": "4px",
+  "space-2": "8px",
+  "space-3": "16px",
+  "space-4": "24px",
+  "space-5": "32px",
+  "space-6": "48px",
+  "space-7": "64px",
+  "space-8": "96px",
+  "radius-sm": "6px",
+  "radius-md": "12px",
+  "radius-lg": "16px",
+  "radius-pill": "999px",
+  "shadow-1": "0 1px 2px rgba(29, 29, 29, 0.06), 0 1px 3px rgba(29, 29, 29, 0.10)",
+  "shadow-2": "0 4px 12px rgba(29, 29, 29, 0.10)",
+  "shadow-3": "0 12px 32px rgba(29, 29, 29, 0.16)",
+  "motion-fast": "150ms",
+  "motion-base": "250ms",
+  "motion-slow": "400ms",
+  ease: "cubic-bezier(0.4, 0, 0.2, 1)",
+  "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+} as const
+
+/** A key of {@link CD_TOKENS} — the `--cd-*` name without its prefix. */
+export type CdTokenName = keyof typeof CD_TOKENS
+
+/** The miragon-brand release the vendored tokens come from. */
+export const CD_TOKENS_VERSION = "1.8.0"