@miragon/mcp-toolkit-ui 2.6.0 → 2.7.0

package/ui-catalog.json

@@ -46,9 +46,9 @@
       "props": [
         {
           "name": "variant",
-          "type": "\"default\" | \"secondary\" | \"destructive\" | \"outline\" | \"ghost\" | \"link\"",
+          "type": "\"default\" | \"secondary\" | \"destructive\" | \"success\" | \"warning\" | \"info\" | \"outline\" | \"ghost\" | \"link\"",
           "required": false,
-          "description": "Visual style. Default 'default'."
+          "description": "Visual style. Default 'default'. destructive/success/warning/info follow the tone model: tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER)."
         },
         {
           "name": "className",
@@ -411,7 +411,7 @@
           "description": "Group header shown above the strip when boxed: { label, badge? }."
         }
       ],
-      "whenToUse": "Show a row of headline metrics in a widget (replaces the old single-metric KPICard). Pre-format values for locale/currency. Set a cell tone for emphasis (e.g. 'danger') and onClick to make a metric a drill target."
+      "whenToUse": "Show a row of headline metrics in a widget (replaces the old single-metric KPICard). Pre-format values for locale/currency. A cell tone (e.g. 'danger') shows as a status dot next to its label — figures stay in the foreground colour; set onClick to make a metric a drill target."
     },
     {
       "name": "LivePill",
@@ -424,7 +424,7 @@
           "name": "tone",
           "type": "ToneVariant",
           "required": false,
-          "description": "Status tone driving the dot + tint ('neutral'|'info'|'success'|'warning'|'danger'). Default 'info'."
+          "description": "Status tone driving the dot, tint and border ('neutral'|'info'|'success'|'warning'|'danger'): tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER). Default 'info'."
         },
         {
           "name": "children",
@@ -446,7 +446,7 @@
           "name": "tone",
           "type": "ToneVariant",
           "required": false,
-          "description": "Status tone driving the tint. Default 'neutral'."
+          "description": "Status tone driving the tint and border: tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER); the number never takes a tone colour. Default 'neutral'."
         },
         {
           "name": "children",
@@ -680,10 +680,10 @@
           "name": "noun",
           "type": "string",
           "required": false,
-          "description": "Plural noun for the count, e.g. 'instances'. Default 'rows'."
+          "description": "Plural noun for the count, e.g. 'instances'. Default: the locale's word for rows."
         }
       ],
-      "whenToUse": "Footer for a paginated list: an honest 'Showing X of Y' total + an explicit 'Load more' (not infinite scroll)."
+      "whenToUse": "Footer for a paginated list: an honest 'Showing X of Y' total + an explicit 'Load more' (not infinite scroll). Text and number format follow the active locale."
     },
     {
       "name": "Tone tokens",
@@ -691,9 +691,156 @@
       "importPath": "@miragon/mcp-toolkit-ui",
       "kind": "object",
       "group": "composed",
-      "parts": ["TONE_SOFT", "TONE_DOT", "TONE_TEXT"],
+      "parts": ["TONE_SOFT", "TONE_DOT", "TONE_TEXT", "TONE_BORDER", "TONE_ICON"],
       "props": [],
-      "whenToUse": "Record<ToneVariant, string> maps from a status tone ('neutral'|'info'|'success'|'warning'|'danger') to Tailwind class strings (TONE_SOFT = soft tint, TONE_DOT = dot colour, TONE_TEXT = text colour), backed by the semantic status tokens in globals.css and re-skinned by the theme. Use to colour a custom element by status without a tone === 'x' ? ... ternary; the tone-aware components (KpiGrid, LivePill, CountPill, WidgetHeader) consume these internally."
+      "whenToUse": "Record<ToneVariant, string> maps from a status tone ('neutral'|'info'|'success'|'warning'|'danger') to Tailwind class strings, three roles per tone (Miragon CI): the colour for fills, dots, borders and icons (TONE_DOT, TONE_BORDER, TONE_ICON), the tint (TONE_SOFT = tint + foreground text, rim in the tone via TONE_BORDER; never put TONE_TEXT/-ink on a tint) and the TEXT colour for a tone's words on a plain surface (TONE_TEXT = the tone's -ink role). Status is never text in its own colour: success and warning ink is the foreground, so show the tone as a dot, icon or border next to the text; figures (counts, KPI values) stay in the foreground. TONE_ICON is for SVG icons only. Use to colour a custom element by status without a tone === 'x' ? ... ternary; the tone-aware components (KpiGrid, LivePill, CountPill, Badge, WidgetHeader) consume these internally."
+    },
+    {
+      "name": "ToastProvider",
+      "export": "ToastProvider",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "Subtree that raises toasts via useToast."
+        }
+      ],
+      "whenToUse": "Provide toasts to a subtree and render their stack: bottom centre, status colour as left edge + icon next to plain text, ONE persistent live region (role=status, aria-live=polite), auto-dismiss after 2.8 s (errors 5 s), held while hovered or focused. Idempotent when nested. McpAppView mounts one, so widgets inside a view only call useToast. Toast icons follow the LucideProvider around the outermost ToastProvider (stroke 2.5 inside McpAppView)."
+    },
+    {
+      "name": "useToast",
+      "export": "useToast",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "feedback",
+      "props": [],
+      "whenToUse": "Raise feedback after a user action instead of logging to the console: useToast().show({ tone: 'success' | 'warning' | 'danger' | 'info', title, description?, duration? }) returns an id; dismiss(id) removes it early. Name the object in the title ('Job retried.'); the description says what to do next. Both come from your catalog: never put a raw error (e.message) in a toast, log it or show it under an ErrorState's Details. Outside a ToastProvider it is a safe no-op."
+    },
+    {
+      "name": "EmptyState",
+      "export": "EmptyState",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "What is empty, in plain words."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "One help line: why it is empty or what to do next."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Decorative icon or brand mark (aria-hidden): a Lucide icon for the situation (24 px), or a logo; an SVG with its own size-* class keeps that size."
+        },
+        {
+          "name": "tone",
+          "type": "'neutral' | 'success'",
+          "required": false,
+          "description": "Icon colour; 'success' for an 'all done' state. Default 'neutral'."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The primary next step (a Button)."
+        },
+        {
+          "name": "secondaryAction",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second, quieter step (at most two actions)."
+        },
+        {
+          "name": "titleAs",
+          "type": "'h2' | 'h3' | 'h4' | 'p'",
+          "required": false,
+          "description": "Title element. Default 'h3'."
+        }
+      ],
+      "whenToUse": "The one empty-state pattern for a list, table or view with nothing to show: icon or mark, a 600-weight title, one help line, up to two actions. Static (no live region). Use instead of a grey one-liner; for 'all done' pass <CircleCheck /> with tone 'success'."
+    },
+    {
+      "name": "ErrorState",
+      "export": "ErrorState",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "What happened, in plain words."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "What you can do next (or the human reason)."
+        },
+        {
+          "name": "details",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The raw technical reason, shown collapsed under a 'Details' disclosure."
+        },
+        {
+          "name": "onRetry",
+          "type": "() => void",
+          "required": false,
+          "description": "Renders a retry button (label from the locale) when set."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Further actions after the retry button."
+        },
+        {
+          "name": "tone",
+          "type": "'danger' | 'warning' | 'info'",
+          "required": false,
+          "description": "Default 'danger'."
+        },
+        {
+          "name": "variant",
+          "type": "'block' | 'inline'",
+          "required": false,
+          "description": "'block' replaces a view or widget body; 'inline' is an alert above content that still renders. Default 'block'."
+        },
+        {
+          "name": "role",
+          "type": "'alert' | 'status' | 'none'",
+          "required": false,
+          "description": "Live-region role. Default 'alert'."
+        },
+        {
+          "name": "icon",
+          "type": "LucideIcon",
+          "required": false,
+          "description": "Replace the tone's default Lucide icon."
+        },
+        {
+          "name": "titleAs",
+          "type": "'h2' | 'h3' | 'h4' | 'p'",
+          "required": false,
+          "description": "Title element. Default 'h2' (block) / 'p' (inline)."
+        }
+      ],
+      "whenToUse": "The one error pattern: icon, a title that says what happened, a line that says what you can do, the raw error under 'Details', and a retry. Never print a raw exception as the only text, never leave a failed fetch on an endless skeleton."
     },
     {
       "name": "useDebouncedValue",
@@ -845,7 +992,7 @@
           "description": "Whether the required id/key is present; fetch is disabled until ready and only when no initialData."
         }
       ],
-      "whenToUse": "The dual-mode seam: write ONE widget that renders host-pushed data when handed it (standalone *_show_* widget) AND self-fetches when embedded in a cockpit. Returns { data, loading, error }."
+      "whenToUse": "The dual-mode seam: write ONE widget that renders host-pushed data when handed it (standalone *_show_* widget) AND self-fetches when embedded in a cockpit. Returns { data, loading, error, refetch }; pass refetch as the error state's retry (<ErrorState onRetry={refetch} />)."
     },
     {
       "name": "useIsMobile",
@@ -1097,16 +1244,16 @@
           "name": "tokens",
           "type": "ThemeTokens",
           "required": true,
-          "description": "Curated brand tokens (all optional): primary, primaryForeground, accent, accentForeground, background, foreground, card, cardForeground, border, ring, radius, fontSans, fontHeading. Colors are any CSS color string (oklch/hex/hsl)."
+          "description": "Brand tokens (all optional), one field per role of the role-token contract (ROLE_TOKENS): primary, primaryForeground, primaryHover, link, focus, ring, background, foreground, card, popover, muted, mutedForeground, secondary, accent, border, input, destructive, success/warning/danger/info with *Soft and *Ink, radiusSm/Md/Lg/Pill, shadow1-3, scrim, motionFast/Base/Slow, ease, fontSans, fontMono, plus the legacy accentForeground, cardForeground, radius, fontHeading. Colors are any CSS color string."
         },
         {
           "name": "opts",
           "type": "{ dark?: ThemeTokens }",
           "required": false,
-          "description": "Dark-mode token overrides, applied on top of the .dark defaults when the active mode is dark."
+          "description": "Dark-mode token overrides. In dark mode a theme scope gets the toolkit's dark defaults, the theme's mode-invariant light tokens (brand button colour, radii, fonts) and these — never the other light values."
         }
       ],
-      "whenToUse": "Define a white-label theme from a single set of brand tokens. Maps the curated fields onto the real CSS variables (--primary, --radius, ...) and returns a serializable ThemeDefinition { vars, darkVars?, toStyle() }. Apply it with ThemeProvider so every primitive re-skins to the client's brand."
+      "whenToUse": "Define a white-label theme for a customer brand. The toolkit's default IS the Miragon theme (no theme needed for it). Maps the fields onto the role CSS variables (--primary, --link, --focus, ...) and returns a serializable ThemeDefinition { vars, darkVars?, toStyle() }. Apply it with ThemeProvider so every primitive re-skins; override roles only, never --cd-* tokens or component classes."
     },
     {
       "name": "ThemeProvider",
@@ -1119,7 +1266,7 @@
           "name": "theme",
           "type": "ThemeDefinition",
           "required": false,
-          "description": "The theme from createTheme/themePresets to apply. Omit to manage only the light/dark mode against the toolkit defaults."
+          "description": "The theme from createTheme to apply. Omit to manage only the light/dark mode against the toolkit defaults (the Miragon theme)."
         },
         {
           "name": "mode",
@@ -1146,7 +1293,7 @@
           "description": "Subtree that inherits the theme's CSS variables and dark class."
         }
       ],
-      "whenToUse": "Wrap a widget (or a whole app) to apply a ThemeDefinition. Renders a wrapper carrying the theme's CSS variables inline (overriding :root) and toggles the .dark class on the scope per mode. React + DOM only — no host required."
+      "whenToUse": "Wrap a widget (or a whole app) to apply a ThemeDefinition and/or a light/dark mode to a scope. Light mode applies the theme's vars, dark mode the toolkit's dark roles plus the theme's dark and mode-invariant tokens (resolveThemeVars). A light scope stays light inside a dark document. Dialogs, Sheets and Select menus opened inside portal into the scope, so they keep its theme and mode. React + DOM only — no host required."
     },
     {
       "name": "useTheme",
@@ -1164,7 +1311,119 @@
       "kind": "object",
       "group": "theming",
       "props": [],
-      "whenToUse": "Ready-made white-label themes (themePresets.miragon, .violet, .emerald) — a demonstration of createTheme and a fork-able starting point. Pass one to ThemeProvider's theme prop."
+      "whenToUse": "Ready-made white-label themes — a demonstration of createTheme and a fork-able starting point (themePresets.emerald). themePresets.miragon and .violet are deprecated: the Miragon theme is the toolkit's default, use no theme for it. Pass a preset to ThemeProvider's theme prop."
+    },
+    {
+      "name": "resolveThemeVars",
+      "export": "resolveThemeVars",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "props": [
+        {
+          "name": "theme",
+          "type": "ThemeDefinition | null | undefined",
+          "required": true,
+          "description": "The theme; null/undefined yields {}."
+        },
+        {
+          "name": "mode",
+          "type": "\"light\" | \"dark\"",
+          "required": true,
+          "description": "The resolved mode of the scope."
+        }
+      ],
+      "whenToUse": "The CSS variables a ThemeDefinition applies at its scope in a mode — what ThemeProvider puts on its wrapper. Use it to theme an element without ThemeProvider (spread it into style), e.g. resolveThemeVars(theme, host.theme ?? 'light'). A legacy base radius also derives the sm/md/lg steps."
+    },
+    {
+      "name": "ROLE_TOKENS",
+      "export": "ROLE_TOKENS",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "theming",
+      "props": [],
+      "whenToUse": "The role-token contract as a readonly list of CSS variable names (--background … --font-mono). Components style through these roles only; a brand overrides only these. Use it to check a brand stylesheet or a host token map covers / stays within the contract."
+    },
+    {
+      "name": "usePortalContainer",
+      "export": "usePortalContainer",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "theming",
+      "props": [],
+      "whenToUse": "The portal node of the nearest ThemeProvider (or null). Pass it as `container` to a portal of your own so overlays keep the scope's theme and light/dark mode; the toolkit's Dialog, Sheet and Select already do."
+    },
+    {
+      "name": "CD_TOKENS",
+      "export": "CD_TOKENS",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "theming",
+      "parts": ["CD_TOKENS", "CD_TOKENS_VERSION"],
+      "props": [],
+      "whenToUse": "The Miragon corporate-design tokens (--cd-*) as plain TypeScript, keys without the prefix (CD_TOKENS.blau, CD_TOKENS['danger-soft']). For code that cannot read CSS variables — SVG/canvas renderers, chart marks, server-side images. Drift-tested against the vendored CSS. UI components style through the role tokens, never through these constants."
+    },
+    {
+      "name": "fontFaces",
+      "export": "fontFaces",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "parts": ["fontFaces", "GEIST_FONT_FILES"],
+      "props": [
+        {
+          "name": "baseUrl",
+          "type": "string",
+          "required": true,
+          "description": "Where the woff2 files (GEIST_FONT_FILES) are served from."
+        },
+        {
+          "name": "files",
+          "type": "{ sans?: string; mono?: string }",
+          "required": false,
+          "description": "File-name overrides."
+        },
+        {
+          "name": "display",
+          "type": "\"auto\" | \"block\" | \"swap\" | \"fallback\" | \"optional\"",
+          "required": false,
+          "description": "Default 'swap'."
+        }
+      ],
+      "whenToUse": "Opt-in Geist delivery by URL: returns the @font-face rules for Geist and Geist Mono (latin, variable weight) served from baseUrl. Inject into the view document, e.g. <style>{fontFaces({ baseUrl })}</style>, and allow that origin in the view CSP. Alternative: import @miragon/mcp-toolkit-ui/fonts.css (bundled). The font tokens name Geist first, so either path works; without either the host's font (see adoptHostFontVariables) or the system stack renders."
+    },
+    {
+      "name": "adoptHostFontVariables",
+      "export": "adoptHostFontVariables",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "parts": ["adoptHostFontVariables", "HOST_FONT_VARIABLES"],
+      "props": [
+        {
+          "name": "style",
+          "type": "InlineStyleTarget",
+          "required": true,
+          "description": "The inline style the host variables were applied to, normally document.documentElement.style."
+        },
+        {
+          "name": "hostVariables",
+          "type": "Record<string, string | undefined> | null | undefined",
+          "required": true,
+          "description": "The host's SEP-1865 style variables (hostContext.styles.variables)."
+        }
+      ],
+      "whenToUse": "Keeps Geist first when a host sends its font. SEP-1865 hosts send --font-sans/--font-mono, the same names as the toolkit's font roles, and would replace the Geist-first stacks whole; this moves them to --host-font-sans/--host-font-mono, the fallback slot right after Geist. McpToolkitApp already calls it; call it yourself only in an app with its own host-document layer, right after applying the host's style variables."
+    },
+    {
+      "name": "FOCUS_RING",
+      "export": "FOCUS_RING",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "widget-authoring",
+      "parts": ["FOCUS_RING", "FOCUS_RING_INSET"],
+      "props": [],
+      "whenToUse": "The kit's opaque focus ring as a class string (2px ring in --focus with an offset; FOCUS_RING_INSET draws it inside, for cells flush with a container edge). Spread it into a custom control's className so keyboard focus reads the same everywhere (3:1 or more in both modes)."
     },
     {
       "name": "LocaleProvider",
@@ -1185,6 +1444,12 @@
           "required": false,
           "description": "A translator from createTranslator(catalogs) (@miragon/mcp-toolkit-core). Omit to provide the locale only (useTranslate echoes keys)."
         },
+        {
+          "name": "toolkitMessages",
+          "type": "ToolkitMessagesOverride",
+          "required": false,
+          "description": "Override individual toolkit strings per catalog section (e.g. { listFooter: { loadMore: 'Show more' } }). Omitted entries keep the shipped en/de catalog of locale."
+        },
         {
           "name": "children",
           "type": "ReactNode",
@@ -1192,7 +1457,7 @@
           "description": "Subtree whose widgets read the locale via useLocale/useTranslate."
         }
       ],
-      "whenToUse": "Wrap a widget (or a whole app) to provide the active locale + an optional translator. Widgets read it with useLocale/useTranslate. Pure React (no host required), mirroring ThemeProvider — pairs with createTranslator from @miragon/mcp-toolkit-core."
+      "whenToUse": "Wrap a widget (or a whole app) to provide the active locale + an optional translator. Widgets read it with useLocale/useTranslate. Pure React (no host required), mirroring ThemeProvider — pairs with createTranslator from @miragon/mcp-toolkit-core. The toolkit's own components read their strings from it too (en/de, English otherwise), so passing the locale localizes the whole toolkit chrome."
     },
     {
       "name": "useLocale",
@@ -1212,6 +1477,68 @@
       "props": [],
       "whenToUse": "Get a locale-bound translate (key, params?) => string from the nearest LocaleProvider. Outside a provider it echoes the key, so a missing wrapper degrades gracefully instead of crashing."
     },
+    {
+      "name": "useToolkitMessages",
+      "export": "useToolkitMessages",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "i18n",
+      "props": [],
+      "whenToUse": "Read the toolkit's own UI strings (common, view, listFooter, filterBar, pills, renderer, builder, propsSheet) for the nearest LocaleProvider's locale: the shipped en/de catalog, English for any other locale, with the provider's toolkitMessages override applied. Reuse them in a widget for consistent chrome copy (e.g. common.retry)."
+    },
+    {
+      "name": "TOOLKIT_MESSAGES",
+      "export": "TOOLKIT_MESSAGES",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "i18n",
+      "props": [],
+      "whenToUse": "The shipped toolkit catalogs keyed by locale ({ en, de }), typed as ToolkitMessages. Use it to build a LocaleProvider toolkitMessages override or to assert in a consumer test that no toolkit default leaks into a localized bundle."
+    },
+    {
+      "name": "resolveToolkitMessages",
+      "export": "resolveToolkitMessages",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "i18n",
+      "props": [
+        {
+          "name": "locale",
+          "type": "string | undefined",
+          "required": true,
+          "description": "Any BCP 47 tag; its primary language picks the catalog (en fallback)."
+        },
+        {
+          "name": "override",
+          "type": "ToolkitMessagesOverride",
+          "required": false,
+          "description": "Per-section partial override merged over the catalog."
+        }
+      ],
+      "whenToUse": "Resolve the toolkit catalog outside React (the pure function behind LocaleProvider/useToolkitMessages)."
+    },
+    {
+      "name": "formatCount",
+      "export": "formatCount",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "i18n",
+      "props": [
+        {
+          "name": "value",
+          "type": "number",
+          "required": true,
+          "description": "The count."
+        },
+        {
+          "name": "locale",
+          "type": "string | undefined",
+          "required": true,
+          "description": "The app locale (from useLocale), not the browser's."
+        }
+      ],
+      "whenToUse": "Format a count with the app locale's grouping (1,234 / 1.234); an invalid tag falls back to English instead of throwing in render."
+    },
     {
       "name": "McpToolkitApp",
       "export": "McpToolkitApp",