Badge Unread Tarnish

1"use client";
2 
3import { useEffect, useId, useRef, useState } from "react";
4 
5// ---------------------------------------------------------------------------
6// PatinaPip — an unread badge that ages like brass instead of just counting.
7// Its data-stage is derived from the newest item's timestamp, not the count:
8// fresh (< 1 day) is a solid --foreground fill with background-token digits,
9// waning (< 1 week) thins to a transparent fill with a 1.5px --foreground
10// ring, dormant (>= 1 week) settles into a 1px --muted ring with --muted
11// digits — fill, outline weight and text tone all move together so the three
12// stages read apart under monochrome viewing, never by hue alone. Ordinary
13// aging (the interval tick, or a prop simply reflecting more elapsed time)
14// crossfades those properties over 400ms via a plain CSS transition; new
15// activity is different in kind, not degree, so it's fast-pathed around that
16// transition (a one-frame transitionDuration:0 clamp) straight to "fresh"
17// and topped with a 200ms spring-eased scale(1 → 1.12 → 1) flare via the Web
18// Animations API, so re-polish always reads as instantaneous, not eased.
19// The pip itself is decorative (role="img", not a control) — the accessible
20// name lives on it as an aria-label ("3 unread, newest 2 days ago") for a
21// focusable nav item to pull in via aria-describedby, and a visually-hidden
22// aria-live region separately announces new arrivals as they happen. Pure
23// DOM + CSS, zero dependencies, no canvas.
24// ---------------------------------------------------------------------------
25 
26export type PatinaPipStage = "fresh" | "waning" | "dormant";
27 
28export interface PatinaPipProps {
29  /** unread item count. Incidental to the component's point — see newestTimestamp. */
30  count: number;
31  /** timestamp of the newest unread item; the sole driver of the tarnish stage. */
32  newestTimestamp: number | Date;
33  /** id placed on the pip itself, e.g. so a nav item can aria-describedby it. Defaults to an internal useId. */
34  id?: string;
35  className?: string;
36}
37 
38const MINUTE_MS = 60_000;
39const HOUR_MS = 60 * MINUTE_MS;
40const DAY_MS = 24 * HOUR_MS;
41const WEEK_MS = 7 * DAY_MS;
42 
43// how often the pip re-checks its own age while mounted, so a badge left
44// open on screen tarnishes on its own without any new prop ever arriving.
45const TICK_MS = MINUTE_MS;
46 
47const FLARE_KEYFRAMES: Keyframe[] = [
48  { transform: "scale(1)" },
49  { transform: "scale(1.12)", offset: 0.5 },
50  { transform: "scale(1)" },
51];
52// … truncated