{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "timer-tray",
  "title": "TimerTray",
  "description": "The timers that are running, paused or finished, in one strip, so a person who leaves a timer's screen can still see it count down, hear it at zero, and stop it.",
  "registryDependencies": [
    "@ouro/button",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages",
    "@ouro/lib-use-timer",
    "@ouro/timer"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/timer/timer-tray.tsx",
      "content": "\"use client\";\n\nimport { useEffect, type HTMLAttributes, type JSX, type MouseEvent, type Ref, type RefObject } from \"react\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useDevWarnings, type DevWarning } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { formatDuration, useTimer, type TimerDoneEvent } from \"@/registry/ouro/lib/ouro/use-timer\";\nimport { Button } from \"@/registry/ouro/components/ouro/button/button\";\nimport {\n  alertDone,\n  doneText,\n  registerView,\n  REPEAT_FOR,\n  repeatLength,\n  stopAlert,\n  timerAlerts,\n  wordsFor,\n  type TimerAlert,\n  type TimerLabels,\n} from \"@/registry/ouro/components/ouro/timer/timer-styles\";\n\n/** One timer a {@link TimerTray} watches. */\nexport interface TimerTrayItem {\n  /** The `timerId` the timer's `Timer` or `useTimer` has. */\n  timerId: string;\n  /** Not a key. A timer is named by `timerId`, as its `Timer` has it: `{ timerId: \"pasta\", label, duration }`. */\n  id?: { 'Use timerId: \"pasta\"': never };\n  /** What it is for, as its `Timer` says it: \"Pasta\". */\n  label: string;\n  /** Its length in seconds, as its `Timer` has it. */\n  duration: number;\n  /** Where the timer's own screen is, for a \"Go to\" link. */\n  href?: string | undefined;\n  /**\n   * Called once when this timer finishes. `event.first` says whether this view owns the alert;\n   * when a Timer shares it, that Timer owns it instead.\n   * @claim \"Called once when this timer finishes.\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > reports a timer's completion once with the same alert ownership as its Timer)\n   */\n  onDone?: ((event: TimerDoneEvent) => void) | undefined;\n}\n\n/** The props TimerTray adds to the `<section>` attributes it passes through. */\nexport interface TimerTrayOwnProps {\n  /** The timers to watch, by `timerId`. Only those that are running, paused or finished show. */\n  timers: readonly TimerTrayItem[];\n  /** Names the tray for screen readers, as a region. @default \"Timers\" */\n  label?: string | undefined;\n  /**\n   * No chime and no vibration when a timer reaches zero while only the tray shows it. A `Timer`\n   * on the page that shows the same timer alerts instead of the tray, by its own `silent`.\n   * @claim \"No chime and no vibration when\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > alerts on its own when the timer's screen is gone, unless silent)\n   */\n  silent?: boolean | undefined;\n  /**\n   * How it sounds when a timer reaches zero while only the tray shows it, as `Timer`'s\n   * `alert`: `once`, or `repeat`, again every 2.5 seconds until the timer is dismissed or\n   * `repeatFor` seconds pass. Dismiss or Cancel in the tray also stops a `Timer`'s repeating alert.\n   * @default \"once\"\n   * @claim \"Dismiss or Cancel in the tray\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > stops the Timer's repeating alert when the tray dismisses the timer)\n   * @claim \"`repeat`, again every 2.5 seconds until\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > repeats its own alert with alert=repeat until the timer is dismissed)\n   */\n  alert?: TimerAlert | (string & { 'Use \"once\" or \"repeat\"': never }) | undefined;\n  /**\n   * With `alert=\"repeat\"`, how long it keeps sounding, in seconds from when the time was up. A\n   * value that is not finite and above 0 is taken as 120, and development warns.\n   * @default 120\n   * @claim \"A value that is not finite\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:fileLine(registry/ouro/components/ouro/timer/timer-tray.test.tsx, /takes a repeatFor that is not finite and above 0 as two minutes/)\n   */\n  repeatFor?: number | undefined;\n  /** The words it shows and says, for apps in other languages. */\n  labels?: TimerLabels | undefined;\n  /**\n   * Where focus goes when Cancel or Dismiss stops the tray's last timer, such as the page\n   * heading (give it `tabIndex={-1}`): `finalFocus={headingRef}`. Stopping any other timer\n   * moves focus to the next timer's button, or the previous one's. Without it focus goes to\n   * the tray, which stays in view, empty, until focus leaves it.\n   */\n  finalFocus?: RefObject<HTMLElement | null> | undefined;\n  /** Layout only: margins, sticky placement (`sticky top-0`). Appearance classes warn in development. */\n  className?: string | undefined;\n  ref?: Ref<HTMLElement> | undefined;\n\n  /** Not a prop. The tray lists `timers`: `<TimerTray timers={[{ timerId, label, duration }]} />`. */\n  items?: { 'Use timers={[{ timerId, label, duration }]}': never };\n  /**\n   * Not a prop. The tray shows only timers that are running, paused or finished; pass them all.\n   *\n   * @claim \"The tray shows only timers that\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > is a region listing the running, paused and finished timers with their time, and hides idle ones)\n   * @claim \"The tray shows only timers that\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > hides itself while no timer is running)\n   */\n  hidden?: { 'The tray hides itself while no timer is running': never };\n}\n\n/** Props for {@link TimerTray}: its own props and the `<section>` attributes it passes through. */\nexport type TimerTrayProps = Omit<HTMLAttributes<HTMLElement>, keyof TimerTrayOwnProps> & TimerTrayOwnProps;\n\ninterface TrayRowProps {\n  item: TimerTrayItem;\n  words: ReturnType<typeof wordsFor>;\n  silent: boolean;\n  repeat: boolean;\n  repeatFor: number;\n  finalFocus: RefObject<HTMLElement | null> | undefined;\n}\n\nfunction TrayRow({ item, words, silent, repeat, repeatFor, finalFocus }: TrayRowProps): JSX.Element | null {\n  const timer = useTimer({\n    duration: item.duration,\n    timerId: item.timerId,\n    fallback: true,\n    onDone: (event) => {\n      alertDone(item.label, words.done, event, { silent, repeat, repeatFor, key: item.timerId });\n      item.onDone?.(event);\n    },\n  });\n  const done = timer.status === \"done\";\n  // Dismiss or Cancel, here or in the timer's own view, stops a repeating alert.\n  useEffect(() => {\n    if (!done) stopAlert(item.timerId);\n  }, [done, item.timerId]);\n  // The alert stops once no view of the timer is left: the row goes with the tray, or leaves timers.\n  // Stryker disable next-line ArrayDeclaration: rows are keyed by timerId, so a row's timerId never changes while it is mounted.\n  useEffect(() => registerView(item.timerId), [item.timerId]);\n  if (timer.status === \"idle\") return null;\n  // The row goes with the timer, so focus moves on first: to the next timer, the previous one, or out.\n  const stop = (event: MouseEvent<HTMLButtonElement>) => {\n    const row = event.currentTarget.closest(\"li\")!;\n    const focused = row.contains(document.activeElement);\n    const neighbour = row.nextElementSibling ?? row.previousElementSibling;\n    if (focused) {\n      if (neighbour) neighbour.querySelector<HTMLElement>('[data-ouro-control=\"timer-tray\"][data-ouro-part=\"stop\"]')!.focus();\n      else (finalFocus?.current ?? row.closest<HTMLElement>('[data-ouro=\"timer-tray\"]')!).focus();\n    }\n    timer.reset();\n  };\n  return (\n    <li data-status={timer.status} className=\"flex min-h-12 flex-wrap items-center gap-x-4 gap-y-2 py-2\">\n      <div className=\"min-w-40 flex-1\">\n        <p className=\"m-0 truncate text-sm leading-5 font-medium text-foreground\">{item.label}</p>\n        <p role=\"timer\" className={cn(\"m-0 text-lg leading-7 font-semibold tabular-nums\", done ? doneText : \"text-foreground\")}>\n          {done ? words.done : formatDuration(timer.remaining)}\n          {timer.status === \"paused\" ? <span className=\"ms-2 text-sm font-medium text-muted-foreground\">{words.paused}</span> : null}\n        </p>\n      </div>\n      <div className=\"flex gap-2\">\n        {item.href !== undefined ? (\n          <Button data-ouro-control=\"timer-tray\" data-ouro-part=\"go-to\" href={item.href} variant=\"plain\" tone=\"secondary\" size=\"sm\">\n            {words.goTo}\n            <span className=\"sr-only\"> {item.label}</span>\n          </Button>\n        ) : null}\n        <Button data-ouro-control=\"timer-tray\" data-ouro-part=\"stop\" onClick={stop} variant={done ? \"solid\" : \"outline\"} tone={done ? \"destructive\" : \"secondary\"} size=\"sm\">\n          {done ? words.dismiss : words.cancel}\n          <span className=\"sr-only\"> {item.label}</span>\n        </Button>\n      </div>\n    </li>\n  );\n}\n\n/**\n * The timers that are running, paused or finished, in one strip, so a person who leaves a\n * timer's screen can still see it count down, hear it at zero, and stop it. Pass every timer\n * the app has, by the `timerId` its `Timer` uses; the tray shows only those not idle, and hides\n * itself while none are. When a timer reaches zero while only the tray shows it, the tray\n * chimes and says so; when its `Timer` is on the page too, the `Timer` alerts instead (with its\n * own `silent`), whichever of the two mounted first.\n *\n * Put it where it stays in view, such as under the header (`className=\"sticky top-0\"`), and\n * leave out the timer on the screen in view.\n *\n * Use `Timer` instead for one timer with all its controls.\n *\n * @group Feedback\n * @see https://ui.ouroboros.bot/docs/timer-tray\n *\n * @example\n * <TimerTray timers={[{ timerId: \"pasta\", label: \"Pasta\", duration: 600, href: \"/steps/2\" }]} />\n * @claim \"The timers that are running, paused\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > is a region listing the running, paused and finished timers with their time, and hides idle ones)\n * @claim \"The timers that are running, paused\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > hides itself while no timer is running)\n * @claim \"When a timer reaches zero while\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > follows the Timer on the page, and alerts once at zero even when both show it)\n * @claim \"When a timer reaches zero while\" registry/ouro/components/ouro/timer/timer-tray.test.tsx verify:testExists(registry/ouro/components/ouro/timer/timer-tray.test.tsx::TimerTray > lets the Timer's silent decide the alert for a timer that ended just before a reload, with both mounted in one commit)\n */\nexport function TimerTray(props: TimerTrayProps): JSX.Element {\n  const {\n    timers,\n    label = \"Timers\",\n    silent,\n    alert: alertProp = \"once\",\n    repeatFor: repeatForProp = REPEAT_FOR,\n    labels,\n    finalFocus,\n    className,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    items,\n    hidden,\n    ...rest\n  } = props;\n  const words = wordsFor(labels);\n  const alert = timerAlerts.includes(alertProp as TimerAlert) ? (alertProp as TimerAlert) : \"once\";\n  const repeatFor = repeatLength(repeatForProp);\n  useAppearanceClassNameCheck(\n    \"TimerTray\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `remove \"${token}\"; TimerTray sets its own look from the theme`\n      : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"TimerTray\",\n    process.env.NODE_ENV !== \"production\"\n      ? (): DevWarning[] => [\n          items !== undefined && [\"items is not a prop\", \"<TimerTray timers={[{ timerId, label, duration }]} />\"],\n          ...timers.map((item): DevWarning => {\n            const { id } = item as { id?: unknown };\n            return id !== undefined && [\"id is not a key of a timer in timers\", `<TimerTray timers={[{ timerId: ${JSON.stringify(id)}, label, duration }]} />`];\n          }),\n          hidden !== undefined && [\"hidden is not a prop; the tray hides itself while no timer is running\", \"<TimerTray timers={timers} />\"],\n          alert !== alertProp && [`alert=\"${String(alertProp)}\" is not an alert; use \"once\" or \"repeat\"`, '<TimerTray alert=\"repeat\" timers={timers} />'],\n          repeatFor !== repeatForProp && [\n            `repeatFor={${String(repeatForProp)}} is not a length; it is in seconds and above 0`,\n            '<TimerTray alert=\"repeat\" repeatFor={120} timers={timers} />',\n          ],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  return (\n    <section\n      tabIndex={-1}\n      {...rest}\n      data-ouro=\"timer-tray\"\n      aria-label={label}\n      className={cn(\"min-w-0 border-0 border-b border-solid border-border bg-background px-4 outline-none not-has-[li]:not-focus:hidden\", className)}\n    >\n      <ul className=\"m-0 grid list-none divide-y divide-border p-0\">\n        {timers.map((item, index) => (\n          // A plain-JavaScript app may leave timerId out (development names the fix); the index keeps React's key.\n          <TrayRow\n            key={item.timerId ?? `index:${index}`}\n            item={item}\n            words={words}\n            silent={silent === true}\n            repeat={alert === \"repeat\"}\n            repeatFor={repeatFor}\n            finalFocus={finalFocus}\n          />\n        ))}\n      </ul>\n    </section>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/timer/timer-tray.tsx"
    }
  ],
  "docs": "The timers that are running, paused or finished, in one strip, so a person who leaves a timer's screen can still see it count down, hear it at zero, and stop it. Import: import { TimerTray } from \"@/components/ouro/timer/timer-tray\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: button, timer, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/timer-tray.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}