@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/lib/toast-model.ts

@@ -4,12 +4,28 @@
  * FITNESS.md) and the component stays a thin view over them.
  */
 
+import { resolveTone } from "./tone-utils.js"
+
 /** Status tone of a toast — the four status roles (`--success` … `--info`). */
 export type ToastTone = "success" | "warning" | "danger" | "info"
 
+/**
+ * The toast tone of any tone name: the four status tones as is, a retired
+ * name through `resolveTone` (`error` → `danger`), and `neutral` or anything
+ * unknown as `info`. Keeps a toast whose tone arrives untyped (plain JS, wire
+ * data) on the screen instead of crashing the view on a missing icon.
+ */
+export function resolveToastTone(name: unknown): ToastTone {
+  const tone = resolveTone(name, "info")
+  return tone === "neutral" ? "info" : tone
+}
+
 /** What a caller passes to `useToast().show(...)`. */
 export interface ToastOptions {
-  /** Status tone; drives the edge, the icon and the default duration. Default `"info"`. */
+  /**
+   * Status tone; drives the edge, the icon and the default duration. Default
+   * `"info"`. An untyped retired name still resolves ({@link resolveToastTone}).
+   */
   tone?: ToastTone
   /** The message. Say what happened, in one short sentence ("Job retried."). */
   title: string
@@ -43,7 +59,7 @@ export function toastDuration(tone: ToastTone, explicit?: number): number {
 
 /** Normalise caller options into a list item. */
 export function createToast(id: number, options: ToastOptions): ToastItem {
-  const tone = options.tone ?? "info"
+  const tone = resolveToastTone(options.tone)
   return {
     id,
     tone,
@@ -61,3 +77,89 @@ export function toastReducer(state: readonly ToastItem[], action: ToastAction):
   const next = state.filter((t) => t.id !== action.id)
   return next.length === state.length ? (state as ToastItem[]) : next
 }
+
+/**
+ * The clock a {@link createToastTimer} runs on. The default reads the global
+ * timers at call time, so fake timers installed in a test take effect.
+ */
+export interface ToastClock {
+  now: () => number
+  setTimeout: (callback: () => void, ms: number) => unknown
+  clearTimeout: (handle: unknown) => void
+}
+
+const SYSTEM_CLOCK: ToastClock = {
+  now: () => Date.now(),
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+/** The countdown of one toast (see {@link createToastTimer}). */
+export interface ToastTimer {
+  /**
+   * Hold the toast for `reason` (`"pointer"`, `"focus"`): the countdown
+   * pauses and keeps the time that was left.
+   */
+  hold: (reason: string) => void
+  /** Release `reason`; once nothing holds the toast, it resumes with the time that was left. */
+  release: (reason: string) => void
+  /** The time left in ms — frozen while held. */
+  remaining: () => number
+  /** Stop for good (the toast left early or unmounted); `onExpire` never fires afterwards. */
+  cancel: () => void
+}
+
+/**
+ * A pausable countdown: starts at once, pauses while anything holds it
+ * (hover, keyboard focus — so a reader can finish), and on release RESUMES
+ * WITH THE REMAINING TIME instead of restarting the full duration. Fires
+ * `onExpire` once.
+ */
+export function createToastTimer(
+  duration: number,
+  onExpire: () => void,
+  clock: ToastClock = SYSTEM_CLOCK,
+): ToastTimer {
+  let left = Math.max(duration, 0)
+  let startedAt = 0
+  let handle: unknown
+  let running = false
+  let finished = false
+  const holds = new Set<string>()
+
+  const elapsed = () => (running ? clock.now() - startedAt : 0)
+  const start = () => {
+    if (finished || running || holds.size > 0) return
+    running = true
+    startedAt = clock.now()
+    handle = clock.setTimeout(() => {
+      running = false
+      finished = true
+      left = 0
+      onExpire()
+    }, left)
+  }
+  const pause = () => {
+    if (!running) return
+    left = Math.max(left - elapsed(), 0)
+    running = false
+    clock.clearTimeout(handle)
+  }
+
+  start()
+  return {
+    hold: (reason) => {
+      holds.add(reason)
+      pause()
+    },
+    release: (reason) => {
+      holds.delete(reason)
+      start()
+    },
+    remaining: () => Math.max(left - elapsed(), 0),
+    cancel: () => {
+      pause()
+      finished = true
+    },
+  }
+}

package/src/lib/tone-utils.test.ts

@@ -1,18 +1,29 @@
 import { describe, expect, it } from "vitest"
 import {
+  isToneVariant,
+  resolveTone,
+  TONE_ALIASES,
   TONE_BORDER,
   TONE_DOT,
   TONE_ICON,
+  TONE_INK,
   TONE_SOFT,
   TONE_TEXT,
+  TONE_TINT,
+  TONE_VARIANTS,
   type ToneVariant,
 } from "./tone-utils.js"
 
 const ALL_TONES: ToneVariant[] = ["neutral", "info", "success", "warning", "danger"]
 const STATUS_TONES = ["info", "success", "warning", "danger"] as const
-const ALL_MAPS = { TONE_SOFT, TONE_DOT, TONE_TEXT, TONE_BORDER, TONE_ICON }
+const ALL_MAPS = { TONE_SOFT, TONE_TINT, TONE_DOT, TONE_INK, TONE_BORDER, TONE_ICON }
 
 describe("tone-utils", () => {
+  it("has ONE vocabulary of five tones, in severity order", () => {
+    expect(TONE_VARIANTS).toEqual(["danger", "warning", "success", "info", "neutral"])
+    expect([...TONE_VARIANTS].sort()).toEqual([...ALL_TONES].sort())
+  })
+
   it("covers every ToneVariant in each map (no missing tones)", () => {
     for (const map of Object.values(ALL_MAPS)) {
       expect(Object.keys(map).sort()).toEqual([...ALL_TONES].sort())
@@ -30,39 +41,104 @@ describe("tone-utils", () => {
   it("routes each status tone to its three roles (colour, tint, ink)", () => {
     for (const tone of STATUS_TONES) {
       expect(TONE_SOFT[tone]).toBe(`bg-${tone}-soft text-foreground`)
-      expect(TONE_TEXT[tone]).toBe(`text-${tone}-ink`)
+      expect(TONE_TINT[tone]).toBe(`bg-${tone}-soft`)
+      expect(TONE_INK[tone]).toBe(`text-${tone}-ink`)
       expect(TONE_DOT[tone]).toBe(`bg-${tone}`)
       expect(TONE_BORDER[tone]).toBe(`border-${tone}`)
       expect(TONE_ICON[tone]).toBe(`text-${tone}`)
     }
   })
 
+  it("keeps TONE_TEXT as the deprecated name of the very same TONE_INK map", () => {
+    expect(TONE_TEXT).toBe(TONE_INK)
+  })
+
   it("never sets text in a raw status colour outside the icon map (CI §3.3)", () => {
     // Success and warning reach 1.67:1 / 1.83:1 on white; text takes the
     // tone's -ink role. TONE_ICON is the one deliberate exception (SVG
     // currentColor, always next to a readable label).
     const rawStatusText = /\btext-(success|warning|danger|info)(?![-\w])/
-    for (const [name, map] of Object.entries({ TONE_SOFT, TONE_DOT, TONE_TEXT, TONE_BORDER })) {
+    for (const [name, map] of Object.entries({
+      TONE_SOFT,
+      TONE_TINT,
+      TONE_DOT,
+      TONE_INK,
+      TONE_BORDER,
+    })) {
       for (const tone of ALL_TONES) {
         expect(map[tone], `${name}:${tone}`).not.toMatch(rawStatusText)
       }
     }
   })
 
-  it("puts the foreground on every status tint, never the ink or the status colour (CI §3.3)", () => {
+  it("puts the foreground on every tint, never the ink or the status colour (CI §3.3)", () => {
     // "-soft: Text darauf --cd-schwarz, Rand in der Statusfarbe" — the rim
-    // (TONE_BORDER) carries the tone, danger/info ink is for plain surfaces.
-    for (const tone of STATUS_TONES) {
-      expect(TONE_SOFT[tone]).not.toMatch(/\btext-(?:success|warning|danger|info)/)
-      expect(TONE_SOFT[tone]).toMatch(/\btext-foreground\b/)
+    // (TONE_BORDER) carries the tone; a neutral count on the muted tint is a
+    // figure and stays in the foreground too.
+    for (const tone of ALL_TONES) {
+      expect(TONE_SOFT[tone]).toBe(`${TONE_TINT[tone]} text-foreground`)
+      expect(TONE_TINT[tone]).not.toMatch(/\btext-/)
     }
   })
 
   it("routes the neutral tone to the muted ramp", () => {
-    expect(TONE_SOFT.neutral).toBe("bg-muted text-muted-foreground")
+    expect(TONE_SOFT.neutral).toBe("bg-muted text-foreground")
+    expect(TONE_TINT.neutral).toBe("bg-muted")
     expect(TONE_DOT.neutral).toBe("bg-muted-foreground")
-    expect(TONE_TEXT.neutral).toBe("text-foreground")
+    expect(TONE_INK.neutral).toBe("text-foreground")
     expect(TONE_BORDER.neutral).toBe("border-border")
     expect(TONE_ICON.neutral).toBe("text-muted-foreground")
   })
 })
+
+describe("the tone vocabulary: retired names map onto the five tones", () => {
+  it("pins every alias (one red, one amber: critical/error/destructive are danger)", () => {
+    expect(TONE_ALIASES).toEqual({
+      critical: "danger",
+      error: "danger",
+      destructive: "danger",
+      failure: "danger",
+      warn: "warning",
+      ok: "success",
+      positive: "success",
+      notice: "info",
+      default: "neutral",
+      muted: "neutral",
+      secondary: "neutral",
+    })
+    for (const tone of Object.values(TONE_ALIASES)) expect(isToneVariant(tone)).toBe(true)
+    for (const alias of Object.keys(TONE_ALIASES)) expect(isToneVariant(alias)).toBe(false)
+  })
+
+  it("keeps a tone as it is", () => {
+    for (const tone of ALL_TONES) expect(resolveTone(tone)).toBe(tone)
+  })
+
+  it("maps every alias onto its tone, ignoring case and padding", () => {
+    for (const [alias, tone] of Object.entries(TONE_ALIASES)) {
+      expect(resolveTone(alias), alias).toBe(tone)
+    }
+    expect(resolveTone("Critical")).toBe("danger")
+    expect(resolveTone("  WARN ")).toBe("warning")
+    expect(resolveTone(" Danger")).toBe("danger")
+  })
+
+  it("falls back to neutral (or the caller's fallback) for anything else", () => {
+    for (const unknown of ["", "   ", "purple", "constructor", "toString", "__proto__"]) {
+      expect(resolveTone(unknown), JSON.stringify(unknown)).toBe("neutral")
+    }
+    for (const notAString of [undefined, null, 3, true, {}, ["danger"]]) {
+      expect(resolveTone(notAString)).toBe("neutral")
+    }
+    expect(resolveTone("purple", "info")).toBe("info")
+    expect(resolveTone(undefined, "warning")).toBe("warning")
+    expect(resolveTone("critical", "info")).toBe("danger")
+  })
+
+  it("isToneVariant accepts exactly the five tones", () => {
+    for (const tone of ALL_TONES) expect(isToneVariant(tone)).toBe(true)
+    for (const other of ["Danger", "critical", "", undefined, null, 1, { tone: "info" }]) {
+      expect(isToneVariant(other)).toBe(false)
+    }
+  })
+})

package/src/lib/tone-utils.ts

@@ -1,6 +1,11 @@
 /**
  * Single source of truth for the semantic "tones" used across the tone-aware
- * components (`Pills`, `KpiGrid`, `WidgetHeader`, `Badge`, …).
+ * components (`Pills`, `StatusBadge`, `KpiGrid`, `Badge`, …).
+ *
+ * ONE vocabulary: `success | warning | danger | info | neutral`
+ * ({@link TONE_VARIANTS}). Retired or foreign names (`critical`, `error`,
+ * `destructive`, …) map onto it through {@link resolveTone}, so a tone that
+ * arrives as data (a server-built KPI cell) never renders without a colour.
  *
  * Every status tone has THREE roles (Miragon CI §3.3), each its own token in
  * `theme.css` with light and dark values:
@@ -8,14 +13,14 @@
  * | Role                         | Token           | Map            |
  * | ---------------------------- | --------------- | -------------- |
  * | fill, dot, border, icon      | `--<tone>`      | `TONE_DOT`, `TONE_BORDER`, `TONE_ICON` |
- * | tint (badge/banner surface)  | `--<tone>-soft` | `TONE_SOFT` (text on it: the foreground) |
- * | text on a plain surface      | `--<tone>-ink`  | `TONE_TEXT`    |
+ * | tint (badge/banner surface)  | `--<tone>-soft` | `TONE_SOFT`, `TONE_TINT` (text on it: the foreground) |
+ * | text on a plain surface      | `--<tone>-ink`  | `TONE_INK`     |
  *
  * Status is never text in its own colour: success and warning reach only
  * 1.67:1 / 1.83:1 on white, so their ink is the foreground and the tone shows
  * as a dot, icon or border NEXT to the text. On a tint the text is always the
  * foreground (CI §3.3: "-soft: Text darauf --cd-schwarz, Rand in der
- * Statusfarbe"), so pair `TONE_SOFT` with `TONE_BORDER`. `TONE_TEXT` is for
+ * Statusfarbe"), so pair `TONE_SOFT` with `TONE_BORDER`. `TONE_INK` is for
  * a tone's words on a plain surface (a field error); figures — counts, KPI
  * values, trends — never take it: they stay in the foreground next to a
  * `TONE_DOT`. In dark mode the colours are the `-hell` values and the tints
@@ -27,20 +32,90 @@
  */
 export type ToneVariant = "neutral" | "info" | "success" | "warning" | "danger"
 
+/** Every tone, in severity order (for loops, pickers and validation). */
+export const TONE_VARIANTS: readonly ToneVariant[] = [
+  "danger",
+  "warning",
+  "success",
+  "info",
+  "neutral",
+]
+
+/**
+ * Retired or foreign tone names and the tone each one means. One red and one
+ * amber (CI §3.3): `critical`, `error` and `destructive` are `danger`; there
+ * is no separate severity above it. The names on the left are deprecated:
+ * write the {@link ToneVariant} on the right. The map stays so data written
+ * against an older vocabulary (a widget-shell `critical`, a shadcn
+ * `destructive`) keeps its colour.
+ */
+export const TONE_ALIASES = {
+  critical: "danger",
+  error: "danger",
+  destructive: "danger",
+  failure: "danger",
+  warn: "warning",
+  ok: "success",
+  positive: "success",
+  notice: "info",
+  default: "neutral",
+  muted: "neutral",
+  secondary: "neutral",
+} as const satisfies Record<string, ToneVariant>
+
+/** A name {@link resolveTone} maps onto a tone (see {@link TONE_ALIASES}). */
+export type ToneAlias = keyof typeof TONE_ALIASES
+
+/**
+ * What a tone-aware component accepts: a {@link ToneVariant}, or a retired
+ * name that {@link resolveTone} maps onto one.
+ */
+export type ToneName = ToneVariant | ToneAlias
+
+const TONE_SET: ReadonlySet<string> = new Set(TONE_VARIANTS)
+
+/** Whether `value` is one of the five tones (a type guard for data from the wire). */
+export function isToneVariant(value: unknown): value is ToneVariant {
+  return typeof value === "string" && TONE_SET.has(value)
+}
+
+/**
+ * Map any tone name onto the vocabulary: a {@link ToneVariant} as is, a
+ * retired name ({@link TONE_ALIASES}, case-insensitive) onto its tone, and
+ * anything else — unknown, empty, not a string — onto `fallback` (default
+ * `"neutral"`, the tone without a state).
+ */
+export function resolveTone(name: unknown, fallback: ToneVariant = "neutral"): ToneVariant {
+  if (typeof name !== "string") return fallback
+  const key = name.trim().toLowerCase()
+  if (TONE_SET.has(key)) return key as ToneVariant
+  return Object.hasOwn(TONE_ALIASES, key) ? TONE_ALIASES[key as ToneAlias] : fallback
+}
+
 /**
  * Tinted surface + its text (the foreground: CI §3.3) — badges, pills,
  * banners. Pair it with {@link TONE_BORDER}: the rim carries the tone, and in
- * dark mode (no tints) it is all that does.
+ * dark mode (no tints) it is all that does. The neutral tint is the muted
+ * surface, its text the foreground too (a count on it is a figure).
  */
 export const TONE_SOFT: Record<ToneVariant, string> = {
-  neutral: "bg-muted text-muted-foreground",
+  neutral: "bg-muted text-foreground",
   info: "bg-info-soft text-foreground",
   success: "bg-success-soft text-foreground",
   warning: "bg-warning-soft text-foreground",
   danger: "bg-danger-soft text-foreground",
 }
 
-/** Solid dot colour — a status dot next to a label. */
+/** The tint alone, for a surface that sets its text itself (a soft KPI card). */
+export const TONE_TINT: Record<ToneVariant, string> = {
+  neutral: "bg-muted",
+  info: "bg-info-soft",
+  success: "bg-success-soft",
+  warning: "bg-warning-soft",
+  danger: "bg-danger-soft",
+}
+
+/** Solid dot colour — a status dot next to a label, a bar, a meter fill. */
 export const TONE_DOT: Record<ToneVariant, string> = {
   neutral: "bg-muted-foreground",
   info: "bg-info",
@@ -56,7 +131,7 @@ export const TONE_DOT: Record<ToneVariant, string> = {
  * {@link TONE_ICON} to show the tone. Never on a tint (use {@link TONE_SOFT})
  * and never for figures (they stay in the foreground next to a dot).
  */
-export const TONE_TEXT: Record<ToneVariant, string> = {
+export const TONE_INK: Record<ToneVariant, string> = {
   neutral: "text-foreground",
   info: "text-info-ink",
   success: "text-success-ink",
@@ -64,6 +139,12 @@ export const TONE_TEXT: Record<ToneVariant, string> = {
   danger: "text-danger-ink",
 }
 
+/**
+ * @deprecated Renamed to {@link TONE_INK} after the role it maps onto
+ * (`--<tone>-ink`); the same object, kept for existing imports.
+ */
+export const TONE_TEXT: Record<ToneVariant, string> = TONE_INK
+
 /** Border colour in the tone — the rim of a tinted badge, banner or toast. */
 export const TONE_BORDER: Record<ToneVariant, string> = {
   neutral: "border-border",