{
  "schemaVersion": 1,
  "target": "react",
  "name": "banner",
  "version": "0.1.0",
  "category": "feedback",
  "title": "Banner",
  "description": "A dismissible announcement bar for the top of a page or a section, in info, success, warning and critical tones, with an optional action, countdown or date and a remembered dismissal.",
  "tags": [
    "banner",
    "announcement",
    "alert",
    "notice",
    "countdown",
    "dismissible"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [],
  "docsPath": "/components/banner",
  "props": [
    {
      "name": "variant",
      "type": "\"info\" | \"success\" | \"warning\" | \"critical\"",
      "default": "\"info\"",
      "description": "Tone and glyph."
    },
    {
      "name": "title / children",
      "type": "ReactNode",
      "description": "The lead in medium weight, then the message."
    },
    {
      "name": "action",
      "type": "{ label, href?, onClick? }",
      "description": "A link (with href) or button at the end of the bar."
    },
    {
      "name": "countdownTo",
      "type": "Date | string | number",
      "description": "Counts down to this moment, such as \"Starts in 2d 4h\". Seconds show in the last hour."
    },
    {
      "name": "countdownLabel",
      "type": "string",
      "default": "\"Starts in\"",
      "description": "Words before the countdown."
    },
    {
      "name": "onCountdownEnd",
      "type": "() => void",
      "description": "Called once when the countdown reaches zero."
    },
    {
      "name": "date / dateFormat / locale",
      "type": "Date | string | number / Intl.DateTimeFormatOptions / string",
      "description": "A fixed moment to show instead of a countdown."
    },
    {
      "name": "dismissible",
      "type": "boolean",
      "default": "true",
      "description": "Shows the close button."
    },
    {
      "name": "storageKey",
      "type": "string",
      "description": "Remembers the dismissal in local storage under this key. Storage errors are ignored."
    },
    {
      "name": "onDismiss",
      "type": "() => void",
      "description": "Called when the banner is dismissed."
    },
    {
      "name": "layout",
      "type": "\"page\" | \"inline\"",
      "default": "\"page\"",
      "description": "A full-width bar with a bottom hairline, or a rounded box for a section."
    },
    {
      "name": "appear",
      "type": "boolean",
      "default": "true",
      "description": "Opens with the entrance. Off (and without storageKey), it renders open at once."
    }
  ],
  "accessibility": [
    "The banner is a region named by its tone (Information, Success, Warning, Critical), and the message starts with that word for screen readers, so tone does not rely on color.",
    "The close button is labeled \"Dismiss\". When it had focus, focus moves to the next focusable element after the banner instead of falling to the page.",
    "While collapsed (before opening and while closing) the banner is inert, so its link and button cannot take focus.",
    "The countdown is a time element with a machine-readable dateTime; it is not a live region, so it never interrupts.",
    "With reduced motion the banner opens and closes without the height, fade, blur or glyph transitions."
  ],
  "states": [
    "info",
    "success",
    "warning",
    "critical",
    "countdown",
    "dismissed"
  ],
  "files": [
    {
      "path": "ui/banner.tsx",
      "content": "\"use client\";\n\nimport { useEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nexport type BannerVariant = \"info\" | \"success\" | \"warning\" | \"critical\";\n\nconst variants: Record<BannerVariant, { name: string; glyph: string; surface: string }> = {\n  info: { name: \"Information\", glyph: \"text-sky-600 dark:text-sky-400\", surface: \"border-sky-500/35 bg-sky-500/[0.08]\" },\n  success: { name: \"Success\", glyph: \"text-emerald-600 dark:text-emerald-400\", surface: \"border-emerald-500/30 bg-emerald-500/[0.08]\" },\n  warning: { name: \"Warning\", glyph: \"text-amber-600 dark:text-amber-400\", surface: \"border-amber-500/35 bg-amber-500/[0.08]\" },\n  critical: { name: \"Critical\", glyph: \"text-red-600 dark:text-red-400\", surface: \"border-red-500/35 bg-red-500/[0.08]\" },\n};\n\nexport interface BannerAction {\n  label: ReactNode;\n  /** Renders a link. Leave it out and pass `onClick` for a button. */\n  href?: string;\n  onClick?: () => void;\n}\n\nexport interface BannerProps extends Omit<ComponentProps<\"section\">, \"title\"> {\n  /** Tone and glyph. Defaults to `info`. */\n  variant?: BannerVariant;\n  /** The lead, in medium weight. */\n  title?: ReactNode;\n  /** The message after the title. */\n  children?: ReactNode;\n  /** A link or button at the end of the bar, such as \"Read the notes\". */\n  action?: BannerAction;\n  /** Counts down to this moment (\"Starts in 2d 4h\"); shows \"Now\" once it passes. */\n  countdownTo?: Date | string | number;\n  /** Words before the countdown. Defaults to \"Starts in\". */\n  countdownLabel?: string;\n  /** Called once when the countdown reaches zero. */\n  onCountdownEnd?: () => void;\n  /** A fixed moment to show instead of a countdown, formatted with `dateFormat`. */\n  date?: Date | string | number;\n  dateFormat?: Intl.DateTimeFormatOptions;\n  locale?: string;\n  /** Shows the close button. Defaults to true. */\n  dismissible?: boolean;\n  /** Remembers the dismissal under this key in local storage, so the banner stays closed on later visits. */\n  storageKey?: string;\n  /** Called when the person dismisses the banner. */\n  onDismiss?: () => void;\n  /** `page` is a full-width bar for the top of a page; `inline` is a rounded box for a section. */\n  layout?: \"page\" | \"inline\";\n  /** Opens with the entrance (height grows, content settles in). Off, it renders open at once. */\n  appear?: boolean;\n}\n\ntype Phase = \"pending\" | \"open\" | \"closing\" | \"closed\";\n\nconst focusable = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])';\n\nfunction readDismissed(key: string) {\n  try {\n    return window.localStorage.getItem(key) != null;\n  } catch {\n    return false;\n  }\n}\n\nfunction writeDismissed(key: string) {\n  try {\n    window.localStorage.setItem(key, new Date().toISOString());\n  } catch {\n    // Storage can be full or blocked (private mode, sandboxed frames); the dismissal still holds for this view.\n  }\n}\n\n/**\n * A dismissible announcement bar for the top of a page or a section, in four tones, with an\n * optional action, countdown or date. It opens by growing to its height while the content settles\n * in, and closes by fading the content and collapsing the height, so the page below rises instead\n * of jumping. With `storageKey` a dismissal is remembered.\n */\nexport function Banner({\n  variant = \"info\",\n  title,\n  children,\n  action,\n  countdownTo,\n  countdownLabel = \"Starts in\",\n  onCountdownEnd,\n  date,\n  dateFormat,\n  locale,\n  dismissible = true,\n  storageKey,\n  onDismiss,\n  layout = \"page\",\n  appear = true,\n  className,\n  ...props\n}: BannerProps) {\n  const tone = variants[variant];\n  // A remembered dismissal can only be read in the browser, so a banner with a storage key (or an\n  // entrance) renders collapsed first and opens after mount; nothing flashes and then disappears.\n  const [phase, setPhase] = useState<Phase>(appear || storageKey ? \"pending\" : \"open\");\n  const [mounted, setMounted] = useState(false);\n  const root = useRef<HTMLDivElement>(null);\n\n  useEffect(() => {\n    setMounted(true);\n    if (storageKey && readDismissed(storageKey)) {\n      setPhase(\"closed\");\n      return;\n    }\n    // Two frames so the collapsed state is painted before the transition starts.\n    let second = 0;\n    const first = requestAnimationFrame(() => {\n      second = requestAnimationFrame(() => setPhase((p) => (p === \"pending\" ? \"open\" : p)));\n    });\n    return () => {\n      cancelAnimationFrame(first);\n      cancelAnimationFrame(second);\n    };\n  }, [storageKey]);\n\n  function dismiss() {\n    if (storageKey) writeDismissed(storageKey);\n    // Focus would fall to the page when the bar closes, so hand it to whatever comes next.\n    const here = root.current;\n    if (here?.contains(document.activeElement)) {\n      const next = Array.from(document.querySelectorAll<HTMLElement>(focusable)).find(\n        (el) => !here.contains(el) && here.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING && el.offsetParent !== null,\n      );\n      next?.focus({ preventScroll: true });\n    }\n    // Reduced motion has no transition to wait for, so the banner goes at once.\n    setPhase(window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches ? \"closed\" : \"closing\");\n    onDismiss?.();\n  }\n\n  if (phase === \"closed\") return null;\n  const open = phase === \"open\";\n\n  return (\n    <div\n      ref={root}\n      data-state={phase}\n      inert={!open || undefined}\n      onTransitionEnd={(event) => {\n        if (phase === \"closing\" && event.target === event.currentTarget && event.propertyName === \"grid-template-rows\") setPhase(\"closed\");\n      }}\n      className={cx(\n        \"grid motion-reduce:transition-none\",\n        open\n          ? \"grid-rows-[1fr] transition-[grid-template-rows] duration-300 ease-[cubic-bezier(0.23,1,0.32,1)]\"\n          : \"grid-rows-[0fr] transition-[grid-template-rows] duration-200 ease-[cubic-bezier(0.23,1,0.32,1)]\",\n      )}\n    >\n      <div className=\"min-h-0 overflow-hidden\">\n        <section\n          aria-label={tone.name}\n          className={cx(\n            \"border text-sm text-zinc-950 dark:text-white\",\n            tone.surface,\n            layout === \"page\" ? \"border-x-0 border-t-0\" : \"rounded-xl\",\n            className,\n          )}\n          {...props}\n        >\n          <div\n            className={cx(\n              \"flex items-start gap-3\",\n              layout === \"page\" ? \"mx-auto max-w-6xl py-2.5 pr-2.5 pl-4 sm:pl-6\" : \"py-2.5 pr-2.5 pl-4\",\n              \"motion-reduce:transition-none\",\n              open\n                ? \"translate-y-0 opacity-100 blur-none transition-[opacity,translate,filter] delay-75 duration-300 ease-[cubic-bezier(0.23,1,0.32,1)]\"\n                : \"-translate-y-1.5 opacity-0 blur-[2px] transition-[opacity,translate,filter] duration-150 ease-out\",\n            )}\n          >\n            <BannerGlyph\n              variant={variant}\n              className={cx(\n                \"mt-0.5 size-4 shrink-0 motion-reduce:transition-none\",\n                tone.glyph,\n                open ? \"scale-100 transition-[scale] delay-150 duration-200 ease-[cubic-bezier(0.23,1,0.32,1)]\" : \"scale-90\",\n              )}\n            />\n            <div className=\"flex min-w-0 flex-1 flex-wrap items-center gap-x-4 gap-y-1\">\n              <p className=\"min-w-[min(100%,16rem)] flex-1 leading-5\">\n                <span className=\"sr-only\">{tone.name}: </span>\n                {title != null ? <span className=\"font-medium\">{title}</span> : null}\n                {title != null && children != null ? \" \" : null}\n                {children != null ? <span className=\"text-zinc-700 dark:text-zinc-300\">{children}</span> : null}\n              </p>\n              {countdownTo != null || date != null || action ? (\n                <div className=\"flex min-h-5 flex-wrap items-center gap-x-4 gap-y-1\">\n                  {countdownTo != null ? (\n                    <Countdown to={countdownTo} label={countdownLabel} onEnd={onCountdownEnd} mounted={mounted} />\n                  ) : date != null ? (\n                    <FormattedDate value={date} format={dateFormat} locale={locale} mounted={mounted} />\n                  ) : null}\n                  {action ? <BannerActionLink action={action} /> : null}\n                </div>\n              ) : null}\n            </div>\n            {dismissible ? (\n              <button\n                type=\"button\"\n                onClick={dismiss}\n                aria-label=\"Dismiss\"\n                className={cx(\n                  \"-my-1 inline-flex size-7 shrink-0 items-center justify-center rounded-md text-zinc-500\",\n                  \"transition-[background-color,color,scale] duration-150 ease-out motion-safe:active:scale-[0.97] motion-reduce:transition-none\",\n                  \"hover:bg-zinc-950/[0.06] hover:text-zinc-950 dark:text-zinc-400 dark:hover:bg-white/[0.08] dark:hover:text-white\",\n                  \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-0 focus-visible:outline-sky-500\",\n                )}\n              >\n                <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" className=\"size-4\">\n                  <path d=\"m4.5 4.5 7 7m0-7-7 7\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n                </svg>\n              </button>\n            ) : null}\n          </div>\n        </section>\n      </div>\n    </div>\n  );\n}\n\nfunction BannerActionLink({ action }: { action: BannerAction }) {\n  const className = cx(\n    \"group/action inline-flex items-center gap-1 rounded-sm font-medium whitespace-nowrap text-zinc-950 dark:text-white\",\n    \"underline decoration-zinc-950/25 underline-offset-4 transition-[text-decoration-color] duration-150 ease-out hover:decoration-current motion-reduce:transition-none\",\n    \"dark:decoration-white/30\",\n    \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n  );\n  const content = (\n    <>\n      {action.label}\n      <svg\n        aria-hidden=\"true\"\n        viewBox=\"0 0 16 16\"\n        className=\"size-3.5 transition-transform duration-150 ease-out group-hover/action:translate-x-0.5 motion-reduce:transition-none\"\n      >\n        <path d=\"M3.5 8h9m-3.5-3.5L12.5 8 9 11.5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n      </svg>\n    </>\n  );\n  return action.href ? (\n    <a href={action.href} onClick={action.onClick} className={className}>\n      {content}\n    </a>\n  ) : (\n    <button type=\"button\" onClick={action.onClick} className={cx(className, \"cursor-pointer\")}>\n      {content}\n    </button>\n  );\n}\n\nfunction toDate(value: Date | string | number) {\n  return value instanceof Date ? value : new Date(value);\n}\n\nfunction Countdown({ to, label, onEnd, mounted }: { to: Date | string | number; label: string; onEnd?: () => void; mounted: boolean }) {\n  const target = toDate(to).getTime();\n  const [now, setNow] = useState<number | null>(null);\n  const ended = useRef(false);\n  const endRef = useRef(onEnd);\n  endRef.current = onEnd;\n\n  useEffect(() => {\n    if (!mounted) return;\n    let timer: ReturnType<typeof setTimeout>;\n    const tick = () => {\n      const t = Date.now();\n      setNow(t);\n      const left = target - t;\n      if (left <= 0) {\n        if (!ended.current) {\n          ended.current = true;\n          endRef.current?.();\n        }\n        return;\n      }\n      // Seconds only matter in the last hour; before that the minute is enough.\n      const step = left < 3_600_000 ? 1000 - (t % 1000) : 60_000 - (t % 60_000);\n      timer = setTimeout(tick, step + 5);\n    };\n    tick();\n    return () => clearTimeout(timer);\n  }, [target, mounted]);\n\n  const iso = Number.isFinite(target) ? new Date(target).toISOString() : undefined;\n  const text = now == null ? \"\" : formatLeft(target - now);\n  return (\n    // Written after mount: a target computed from the clock differs between server and browser.\n    <time dateTime={mounted ? iso : undefined} className=\"min-w-[9ch] font-mono text-xs whitespace-nowrap text-zinc-600 tabular-nums dark:text-zinc-400\">\n      {now == null ? \" \" : target - now <= 0 ? \"Now\" : `${label} ${text}`}\n    </time>\n  );\n}\n\nfunction formatLeft(ms: number) {\n  const total = Math.max(0, Math.floor(ms / 1000));\n  const d = Math.floor(total / 86_400);\n  const h = Math.floor((total % 86_400) / 3600);\n  const m = Math.floor((total % 3600) / 60);\n  const s = total % 60;\n  const pad = (n: number) => String(n).padStart(2, \"0\");\n  if (d > 0) return `${d}d ${h}h`;\n  if (h > 0) return `${h}h ${pad(m)}m`;\n  return `${m}m ${pad(s)}s`;\n}\n\nfunction FormattedDate({\n  value,\n  format,\n  locale,\n  mounted,\n}: {\n  value: Date | string | number;\n  format?: Intl.DateTimeFormatOptions;\n  locale?: string;\n  mounted: boolean;\n}) {\n  const date = toDate(value);\n  // Time zones differ between server and browser, so the text is written after mount.\n  const text = useMemo(\n    () =>\n      mounted && !Number.isNaN(date.getTime())\n        ? new Intl.DateTimeFormat(locale, format ?? { month: \"short\", day: \"numeric\", hour: \"numeric\", minute: \"2-digit\", timeZoneName: \"short\" }).format(date)\n        : \" \",\n    [mounted, date.getTime(), locale, format], // eslint-disable-line react-hooks/exhaustive-deps\n  );\n  return (\n    <time dateTime={Number.isNaN(date.getTime()) ? undefined : date.toISOString()} className=\"font-mono text-xs whitespace-nowrap text-zinc-600 tabular-nums dark:text-zinc-400\">\n      {text}\n    </time>\n  );\n}\n\nfunction BannerGlyph({ variant, className }: { variant: BannerVariant; className?: string }) {\n  const stroke = { fill: \"none\", stroke: \"currentColor\", strokeWidth: 1.5, strokeLinecap: \"round\", strokeLinejoin: \"round\" } as const;\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" className={className}>\n      {variant === \"info\" ? (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"6.25\" {...stroke} />\n          <path d=\"M8 7.25V11\" {...stroke} />\n          <circle cx=\"8\" cy=\"5\" r=\"0.85\" fill=\"currentColor\" />\n        </>\n      ) : variant === \"success\" ? (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"6.25\" {...stroke} />\n          <path d=\"m5.5 8.25 1.75 1.75 3.25-3.75\" {...stroke} />\n        </>\n      ) : variant === \"warning\" ? (\n        <>\n          <path d=\"M7.13 2.5a1 1 0 0 1 1.74 0l5.25 9.5a1 1 0 0 1-.87 1.5H2.75a1 1 0 0 1-.87-1.5Z\" {...stroke} />\n          <path d=\"M8 6.25V9\" {...stroke} />\n          <circle cx=\"8\" cy=\"11.1\" r=\"0.85\" fill=\"currentColor\" />\n        </>\n      ) : (\n        <>\n          <path d=\"M5.4 1.75h5.2l3.65 3.65v5.2l-3.65 3.65H5.4L1.75 10.6V5.4Z\" {...stroke} />\n          <path d=\"M8 4.75v3.75\" {...stroke} />\n          <circle cx=\"8\" cy=\"10.9\" r=\"0.85\" fill=\"currentColor\" />\n        </>\n      )}\n    </svg>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { Banner } from \"@/components/shaken/ui/banner\";\n\nexport default function BannerExample() {\n  return (\n    <div className=\"grid w-full max-w-2xl gap-3\">\n      <Banner\n        layout=\"inline\"\n        variant=\"info\"\n        title=\"Scheduled maintenance.\"\n        countdownTo=\"2026-11-22T02:00:00Z\"\n        action={{ label: \"View status\", href: \"#status\" }}\n        storageKey=\"maintenance-2026-11-22\"\n      >\n        Agent runs pause on Sunday from 02:00 to 02:20 UTC.\n      </Banner>\n    </div>\n  );\n}\n"
  }
}
