@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/lib/toast-model.test.ts

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+  createToast,
+  createToastTimer,
+  MAX_VISIBLE_TOASTS,
+  resolveToastTone,
+  TOAST_DURATION_MS,
+  TOAST_ERROR_DURATION_MS,
+  toastDuration,
+  toastReducer,
+  type ToastClock,
+  type ToastItem,
+  type ToastOptions,
+} from "./toast-model.js"
+
+const item = (id: number): ToastItem => createToast(id, { title: `t${id}` })
+
+describe("toastDuration (CI §8: about 2.8 s, errors about 5 s)", () => {
+  it("defaults to 2.8 s and gives errors 5 s", () => {
+    expect(TOAST_DURATION_MS).toBe(2800)
+    expect(TOAST_ERROR_DURATION_MS).toBe(5000)
+    expect(toastDuration("success")).toBe(2800)
+    expect(toastDuration("info")).toBe(2800)
+    expect(toastDuration("warning")).toBe(2800)
+    expect(toastDuration("danger")).toBe(5000)
+  })
+
+  it("honours an explicit positive duration and ignores an unusable one", () => {
+    expect(toastDuration("danger", 1200)).toBe(1200)
+    expect(toastDuration("info", 0)).toBe(2800)
+    expect(toastDuration("info", -5)).toBe(2800)
+    expect(toastDuration("danger", Number.NaN)).toBe(5000)
+    expect(toastDuration("danger", Number.POSITIVE_INFINITY)).toBe(5000)
+  })
+})
+
+describe("createToast", () => {
+  it("defaults to the info tone and drops an empty description", () => {
+    expect(createToast(1, { title: "Saved" })).toEqual({
+      id: 1,
+      tone: "info",
+      title: "Saved",
+      duration: 2800,
+    })
+    expect(createToast(2, { title: "x", description: "" })).not.toHaveProperty("description")
+  })
+
+  it("keeps tone, description and the tone's duration", () => {
+    expect(createToast(3, { tone: "danger", title: "Failed", description: "503" })).toEqual({
+      id: 3,
+      tone: "danger",
+      title: "Failed",
+      description: "503",
+      duration: 5000,
+    })
+  })
+
+  it("resolves an untyped retired tone instead of keeping a name no icon exists for", () => {
+    // Plain JS or wire data: `error` is `danger`, with the error toast's 5 s.
+    const fromWire = { tone: "error", title: "Failed" } as unknown as ToastOptions
+    expect(createToast(4, fromWire)).toMatchObject({ tone: "danger", duration: 5000 })
+    const unknown = { tone: "purple", title: "x" } as unknown as ToastOptions
+    expect(createToast(5, unknown).tone).toBe("info")
+  })
+})
+
+describe("resolveToastTone (fail-soft for an untyped tone)", () => {
+  it("keeps the four toast tones and maps a retired name through resolveTone", () => {
+    for (const tone of ["success", "warning", "danger", "info"] as const) {
+      expect(resolveToastTone(tone)).toBe(tone)
+    }
+    expect(resolveToastTone("critical")).toBe("danger")
+    expect(resolveToastTone("Warn")).toBe("warning")
+    expect(resolveToastTone("ok")).toBe("success")
+    expect(resolveToastTone("notice")).toBe("info")
+  })
+
+  it("shows neutral, unknown and missing tones as info (a toast has no neutral edge)", () => {
+    expect(resolveToastTone("neutral")).toBe("info")
+    expect(resolveToastTone("secondary")).toBe("info")
+    expect(resolveToastTone("purple")).toBe("info")
+    expect(resolveToastTone(undefined)).toBe("info")
+    expect(resolveToastTone(42)).toBe("info")
+  })
+})
+
+describe("toastReducer", () => {
+  it("appends and keeps at most the newest MAX_VISIBLE_TOASTS", () => {
+    expect(MAX_VISIBLE_TOASTS).toBe(3)
+    let state: ToastItem[] = []
+    for (let id = 1; id <= 4; id++) state = toastReducer(state, { type: "add", toast: item(id) })
+    expect(state.map((t) => t.id)).toEqual([2, 3, 4])
+  })
+
+  it("dismisses by id and keeps the list identity when nothing matches", () => {
+    const state = [item(1), item(2)]
+    expect(toastReducer(state, { type: "dismiss", id: 1 }).map((t) => t.id)).toEqual([2])
+    expect(toastReducer(state, { type: "dismiss", id: 9 })).toBe(state)
+  })
+})
+
+describe("createToastTimer (a held toast resumes its REMAINING time)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("expires once, after the full duration, when nothing holds it", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire)
+    expect(timer.remaining()).toBe(2800)
+    vi.advanceTimersByTime(2799)
+    expect(onExpire).not.toHaveBeenCalled()
+    expect(timer.remaining()).toBe(1)
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+    expect(timer.remaining()).toBe(0)
+    vi.advanceTimersByTime(10_000)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("pauses while held and resumes with the time that was left, not a fresh duration", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire)
+    vi.advanceTimersByTime(1000)
+    timer.hold("pointer")
+    expect(timer.remaining()).toBe(1800)
+    vi.advanceTimersByTime(60_000) // reading for a minute: nothing runs out
+    expect(onExpire).not.toHaveBeenCalled()
+    expect(timer.remaining()).toBe(1800)
+    timer.release("pointer")
+    vi.advanceTimersByTime(1799)
+    expect(onExpire).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("keeps counting down across several holds (each resume continues the rest)", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(5000, onExpire)
+    vi.advanceTimersByTime(2000)
+    timer.hold("pointer")
+    vi.advanceTimersByTime(500)
+    timer.release("pointer")
+    vi.advanceTimersByTime(2000)
+    timer.hold("focus")
+    expect(timer.remaining()).toBe(1000)
+    timer.release("focus")
+    vi.advanceTimersByTime(999)
+    expect(onExpire).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("stays held until EVERY reason is released (hover and keyboard focus overlap)", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(1000, onExpire)
+    timer.hold("pointer")
+    timer.hold("focus")
+    timer.hold("focus")
+    timer.release("pointer")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    timer.release("unknown")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    timer.release("focus")
+    vi.advanceTimersByTime(1000)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("never fires after cancel, released or not", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(1000, onExpire)
+    vi.advanceTimersByTime(400)
+    timer.cancel()
+    expect(timer.remaining()).toBe(600)
+    timer.release("pointer")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    const held = createToastTimer(1000, onExpire)
+    held.hold("focus")
+    held.cancel()
+    held.release("focus")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+  })
+
+  it("expires at once for a non-positive duration", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(-50, onExpire)
+    expect(timer.remaining()).toBe(0)
+    vi.advanceTimersByTime(0)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("runs on an injected clock and clears the handle it scheduled", () => {
+    let now = 100
+    const pending = new Map<number, () => void>()
+    let nextHandle = 0
+    const cleared: unknown[] = []
+    const scheduled: number[] = []
+    const clock: ToastClock = {
+      now: () => now,
+      setTimeout: (callback, ms) => {
+        nextHandle += 1
+        pending.set(nextHandle, callback)
+        scheduled.push(ms)
+        return nextHandle
+      },
+      clearTimeout: (handle) => {
+        cleared.push(handle)
+        pending.delete(handle as number)
+      },
+    }
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire, clock)
+    expect(scheduled).toEqual([2800])
+    now += 800
+    timer.hold("pointer")
+    expect(cleared).toEqual([1])
+    expect(pending.size).toBe(0)
+    now += 10_000
+    timer.release("pointer")
+    expect(scheduled).toEqual([2800, 2000])
+    now += 2000
+    pending.get(2)?.()
+    expect(onExpire).toHaveBeenCalledTimes(1)
+    expect(timer.remaining()).toBe(0)
+  })
+})

package/src/lib/toast-model.ts

@@ -0,0 +1,165 @@
+/**
+ * Pure model behind `ToastProvider` / `useToast`: the toast list as a reducer
+ * plus the timing rules, so both are testable without a DOM (the house path,
+ * 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"`. An untyped retired name still resolves ({@link resolveToastTone}).
+   */
+  tone?: ToastTone
+  /** The message. Say what happened, in one short sentence ("Job retried."). */
+  title: string
+  /** Optional second line (what you can do next, or the affected object). */
+  description?: string
+  /** Auto-dismiss after this many ms. Defaults per {@link toastDuration}. */
+  duration?: number
+}
+
+/** A toast as it sits in the list. */
+export interface ToastItem {
+  id: number
+  tone: ToastTone
+  title: string
+  description?: string
+  duration: number
+}
+
+/** Default lifetime of a toast (CI §8: about 2.8 s). */
+export const TOAST_DURATION_MS = 2800
+/** Lifetime of an error toast (CI §8: about 5 s) — long enough to read the reason. */
+export const TOAST_ERROR_DURATION_MS = 5000
+/** At most this many toasts stack; the oldest leaves first. */
+export const MAX_VISIBLE_TOASTS = 3
+
+/** The lifetime of a toast: an explicit positive duration, else the tone's default. */
+export function toastDuration(tone: ToastTone, explicit?: number): number {
+  if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) return explicit
+  return tone === "danger" ? TOAST_ERROR_DURATION_MS : TOAST_DURATION_MS
+}
+
+/** Normalise caller options into a list item. */
+export function createToast(id: number, options: ToastOptions): ToastItem {
+  const tone = resolveToastTone(options.tone)
+  return {
+    id,
+    tone,
+    title: options.title,
+    ...(options.description ? { description: options.description } : {}),
+    duration: toastDuration(tone, options.duration),
+  }
+}
+
+export type ToastAction = { type: "add"; toast: ToastItem } | { type: "dismiss"; id: number }
+
+/** Add appends (dropping the oldest beyond {@link MAX_VISIBLE_TOASTS}); dismiss removes by id. */
+export function toastReducer(state: readonly ToastItem[], action: ToastAction): ToastItem[] {
+  if (action.type === "add") return [...state, action.toast].slice(-MAX_VISIBLE_TOASTS)
+  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,35 +1,144 @@
 import { describe, expect, it } from "vitest"
-import { TONE_DOT, TONE_SOFT, TONE_TEXT, type ToneVariant } from "./tone-utils.js"
+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_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 [TONE_SOFT, TONE_DOT, TONE_TEXT]) {
+    for (const map of Object.values(ALL_MAPS)) {
       expect(Object.keys(map).sort()).toEqual([...ALL_TONES].sort())
     }
   })
 
   it("maps each tone to a non-empty class string in every map", () => {
-    for (const tone of ALL_TONES) {
-      expect(TONE_SOFT[tone], `soft:${tone}`).toBeTruthy()
-      expect(TONE_DOT[tone], `dot:${tone}`).toBeTruthy()
-      expect(TONE_TEXT[tone], `text:${tone}`).toBeTruthy()
+    for (const [name, map] of Object.entries(ALL_MAPS)) {
+      for (const tone of ALL_TONES) {
+        expect(map[tone], `${name}:${tone}`).toBeTruthy()
+      }
+    }
+  })
+
+  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_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_TINT,
+      TONE_DOT,
+      TONE_INK,
+      TONE_BORDER,
+    })) {
+      for (const tone of ALL_TONES) {
+        expect(map[tone], `${name}:${tone}`).not.toMatch(rawStatusText)
+      }
     }
   })
 
-  it("routes each status tone to its matching design token", () => {
-    expect(TONE_SOFT.danger).toBe("bg-danger-soft text-danger")
-    expect(TONE_SOFT.warning).toBe("bg-warning-soft text-warning")
-    expect(TONE_SOFT.success).toBe("bg-success-soft text-success")
-    expect(TONE_SOFT.info).toBe("bg-info-soft text-info")
-    expect(TONE_DOT.danger).toBe("bg-danger")
-    expect(TONE_TEXT.success).toBe("text-success")
+  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; 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 shadcn muted ramp", () => {
-    expect(TONE_SOFT.neutral).toBe("bg-muted text-muted-foreground")
+  it("routes the neutral tone to the muted ramp", () => {
+    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)
+    }
   })
 })