{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "celebrate",
  "title": "Celebrate",
  "description": "A small moment of celebration for something the person finished: confetti bursts from a badge with the message (\"List cleared\") and screen readers hear the message once.",
  "registryDependencies": [
    "@ouro/lib-announce",
    "@ouro/lib-celebration-cap",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages",
    "@ouro/lib-use-ouro"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/celebrate/celebrate.tsx",
      "content": "\"use client\";\n\nimport { useEffect, useRef, useState, type CSSProperties, type HTMLAttributes, type JSX, type Ref } from \"react\";\nimport { announce } from \"@/registry/ouro/lib/ouro/announce\";\nimport { canCelebrate, celebrationPeriods, recordCelebration, type CelebrationPeriod } from \"@/registry/ouro/lib/ouro/celebration-cap\";\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 { useOuro } from \"@/registry/ouro/lib/ouro/use-ouro\";\n\n/** The props Celebrate adds to the `<span>` attributes it passes through. */\nexport interface CelebrateOwnProps {\n  /**\n   * Whether the moment is happening. When it turns `true`, confetti bursts from the message and\n   * screen readers hear the message, once; set it back to `false` to clear it, and to `true`\n   * again for another burst.\n   */\n  show: boolean;\n  /**\n   * How often the confetti may burst: at most `times` times `per` day, week, 30-day month or\n   * ever, counted in `localStorage` under `capKey` (or the cap's own `key`). Pass several to\n   * hold to all of them, such as once per conversation and three times a day across the app:\n   * `` cap={[{ times: 1, per: \"ever\", key: `cleared:${id}` }, { times: 3, per: \"day\", key: \"celebrations\" }]} ``.\n   * Past a cap the message still shows and is heard, with no confetti. `Moment` counts under the\n   * same keys, so the two can share a cap.\n   * @claim \"Past a cap the message still\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate cap > bursts at most times per period under its key, then shows and speaks the message alone)\n   * @claim \"How often the confetti may burst:\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate cap > bursts at most times per period under its key, then shows and speaks the message alone)\n   * @claim \"Pass several to hold to all\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate cap > holds to every cap it is given, and counts a burst against each)\n   * @claim \"`Moment` counts under the same keys,\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate cap > shares a key with Moment's cap)\n   */\n  cap?: CelebrateCap | readonly CelebrateCap[] | undefined;\n  /** The key a cap without its own `key` counts under, such as \"list-cleared\". Falls back to `id`. */\n  capKey?: string | undefined;\n  /** What was achieved, in a few words: \"List cleared\", \"Steps done\". Shown in a badge and spoken. */\n  message: string;\n  /** Speaks the message without showing the badge, for a screen that already says it. The confetti still bursts. */\n  hideMessage?: boolean | undefined;\n  /** Layout only: placement (`mx-auto`, `mt-4`). Appearance classes warn in development. */\n  className?: string | undefined;\n  ref?: Ref<HTMLSpanElement> | undefined;\n\n  /** Not a prop. Ouro UI uses `show`: `<Celebrate show={done} message=\"…\" />`. */\n  open?: { 'Use show={done}': never };\n  /** Not a prop. Ouro UI uses `show`: `<Celebrate show={done} message=\"…\" />`. */\n  active?: { 'Use show={done}': never };\n  /** Not a prop. The text is `message`: `<Celebrate show={done} message=\"List cleared\" />`. */\n  children?: { 'Use message=\"List cleared\"': never };\n}\n\n/** One limit on how often {@link Celebrate} bursts: `times` per period, under `key` or the component's `capKey`. */\nexport interface CelebrateCap {\n  times: number;\n  per: CelebrationPeriod | (string & { 'Use \"day\", \"week\", \"month\" or \"ever\"': never });\n  key?: string | undefined;\n}\n\n/** Props for {@link Celebrate}: its own props and the `<span>` attributes it passes through. */\nexport type CelebrateProps = Omit<HTMLAttributes<HTMLSpanElement>, keyof CelebrateOwnProps> & CelebrateOwnProps;\n\n/** Leaves time for the triggering control's state announcement before the celebration message. This fixed delay cannot detect when a screen reader has finished speaking; the badge and confetti show immediately. */\nconst SPEAK_DELAY_MS = 1500;\n\n// Twelve pieces around the circle, at two distances, in the theme's tones. Each lands inside\n// Celebrate's own box, a share of its width and height out from the middle, so the burst never\n// flies over what is around it: its layer grows from nothing to full size, carrying the piece out.\nconst PIECES = 12;\nconst tones = [\"bg-primary\", \"bg-success\", \"bg-warning\", \"bg-destructive\"] as const;\nconst pieces = Array.from({ length: PIECES }, (_, index) => {\n  const angle = (index / PIECES) * Math.PI * 2 + (index % 2 ? 0.2 : 0);\n  const reach = index % 2 ? 30 : 44;\n  return {\n    tone: tones[index % tones.length]!,\n    style: {\n      insetInlineStart: `calc(50% + ${Math.round(Math.cos(angle) * reach)}% - 4px)`,\n      top: `calc(50% + ${Math.round(Math.sin(angle) * reach)}% - 4px)`,\n      \"--ouro-celebrate-turn\": `${(index % 3) * 120 + 90}deg`,\n    } as CSSProperties,\n  };\n});\n\n/**\n * A small moment of celebration for something the person finished: confetti bursts from a badge with the message (\"List cleared\") and screen readers hear the message once. The confetti stays inside Celebrate's own box and never flies over what is around it: give it room with layout classes (`h-24 w-full`) for a wider burst. The message waits about 1.5 s to leave time for the triggering control's announcement; this does not detect when a screen reader finishes speaking. With reduced motion nothing flies: the badge only fades in. Put it where the eye already is, such as at the end of the list that was just cleared.\n *\n * Under `OuroProvider`'s `quiet`, for people who want less, only the message shows and is\n * heard: no confetti.\n *\n * Use `toast()` instead to confirm an everyday action (saved, sent), and `Alert` for a\n * message that should stay.\n *\n * While the moment lasts, the root carries `data-celebrate`, so a checker or a test can find it.\n *\n * @claim \"While the moment lasts, the root\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate > carries data-celebrate while the moment lasts, and not before or after)\n * @claim \"The confetti stays inside Celebrate's own\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate > throws twelve pieces in every direction, at two distances, in the theme's tones, inside its own box and hidden from screen readers)\n * @claim \"Under `OuroProvider`'s `quiet`, for people\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate > shows and speaks only the message under OuroProvider's quiet, with no confetti)\n * @claim \"The message waits about 1.5 s\" registry/ouro/components/ouro/celebrate/celebrate.test.tsx verify:testExists(registry/ouro/components/ouro/celebrate/celebrate.test.tsx::Celebrate > says the message once after a delay when the moment starts, and again for the next one)\n * @group Feedback\n * @see https://ui.ouroboros.bot/docs/celebrate\n *\n * @example\n * <Celebrate show={items.every((item) => item.checked)} message=\"List cleared\" />\n */\nexport function Celebrate(props: CelebrateProps): JSX.Element {\n  const {\n    show,\n    message,\n    hideMessage,\n    cap,\n    capKey,\n    className,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    open,\n    active,\n    children,\n    ...rest\n  } = props;\n  const caps: readonly CelebrateCap[] = cap === undefined ? [] : Array.isArray(cap) ? cap : [cap as CelebrateCap];\n  useAppearanceClassNameCheck(\n    \"Celebrate\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `remove \"${token}\"; Celebrate takes its colors from the theme`\n      : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"Celebrate\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          open !== undefined && [\"open is not a prop\", \"<Celebrate show={done} />\"],\n          active !== undefined && [\"active is not a prop\", \"<Celebrate show={done} />\"],\n          children !== undefined && [\"Celebrate takes its text as message\", `<Celebrate message=\"${typeof children === \"string\" ? children : \"All done\"}\" />`],\n          ...caps.flatMap((limit): DevWarning[] => [\n            !Object.hasOwn(celebrationPeriods, limit.per) && [`cap per \"${String(limit.per)}\" is not a period; use \"day\", \"week\", \"month\", \"ever\"`, '<Celebrate cap={{ times: 3, per: \"day\" }} capKey=\"cleared\">'],\n            (limit.key ?? capKey ?? rest.id) === undefined && [\"a cap counts bursts under its key, capKey or id, and this one has none\", '<Celebrate cap={{ times: 3, per: \"day\" }} capKey=\"cleared\">'],\n          ]),\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  const quiet = useOuro().quiet === true;\n  // Spoken when the moment starts, not when a page renders with it already shown.\n  const shown = useRef(show);\n  useEffect(() => {\n    if (show && !shown.current) announce(message, { delayMs: SPEAK_DELAY_MS });\n    shown.current = show;\n  }, [show, message]);\n\n  // With a cap, whether this showing may burst is decided once, as it starts, and counted.\n  const [allowed, setAllowed] = useState(false);\n  const decided = useRef(false);\n  useEffect(() => {\n    if (!show) {\n      decided.current = false;\n      requestAnimationFrame(() => setAllowed(false));\n      return;\n    }\n    if (decided.current) return;\n    decided.current = true;\n    const now = Date.now();\n    const counted = caps.flatMap((limit) => {\n      const key = limit.key ?? capKey ?? rest.id;\n      return key === undefined ? [] : [{ key, limit: { times: limit.times, per: Object.hasOwn(celebrationPeriods, limit.per) ? (limit.per as CelebrationPeriod) : \"day\" } }];\n    });\n    const ok = counted.every(({ key, limit }) => canCelebrate(key, limit, now));\n    if (ok) for (const { key, limit } of counted) recordCelebration(key, limit, now);\n    requestAnimationFrame(() => setAllowed(ok));\n    // The decision reads the caps as the showing starts; later changes to them wait for the next one.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [show]);\n  const burst = show && (caps.length === 0 || allowed);\n\n  return (\n    <span\n      {...rest}\n      data-ouro=\"celebrate\"\n      data-open={show ? \"\" : undefined}\n      data-celebrate={show ? \"\" : undefined}\n      data-quiet={quiet ? \"\" : undefined}\n      className={cn(\"relative inline-flex min-h-7 items-center justify-center\", className)}\n    >\n      {show ? (\n        <>\n          {burst && !quiet && (\n            <span aria-hidden=\"true\" className=\"pointer-events-none absolute inset-0 overflow-clip motion-reduce:hidden\">\n              {pieces.map((piece, index) => (\n                <span\n                  key={index}\n                  data-ouro-part=\"piece\"\n                  className={cn(\n                    \"absolute inset-0 opacity-0\",\n                    \"[transition:transform_var(--ouro-duration-sheet)_var(--ouro-ease-out),opacity_var(--ouro-duration-slow)_ease_var(--ouro-duration-base)]\",\n                    \"starting:opacity-100 starting:[transform:scale(0)]\",\n                  )}\n                >\n                  <span style={piece.style} className={cn(\"absolute size-2 rounded-[2px] [transform:rotate(var(--ouro-celebrate-turn))]\", piece.tone)} />\n                </span>\n              ))}\n            </span>\n          )}\n          <span\n            data-ouro-part=\"message\"\n            className={\n              hideMessage\n                ? \"sr-only\"\n                : \"inline-flex min-h-7 items-center rounded-full bg-success/10 px-3 text-sm leading-5 font-medium text-[color-mix(in_oklab,var(--success)_80%,var(--foreground))] \" +\n                  \"transition-opacity duration-(--ouro-duration-base) ease-(--ouro-ease-out) starting:opacity-0\"\n            }\n          >\n            {message}\n          </span>\n        </>\n      ) : null}\n    </span>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/celebrate/celebrate.tsx"
    }
  ],
  "docs": "A small moment of celebration for something the person finished: confetti bursts from a badge with the message (\"List cleared\") and screen readers hear the message once. Import: import { Celebrate } from \"@/components/ouro/celebrate/celebrate\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: the helpers it imports 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/celebrate.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}