Resource Usage

npx shadcn@latest add https://ui.zyeon.ai/r/resource-usage.json

Build a React + TypeScript + Tailwind "ResourceUsage" panel with zod and
lucide-react.

Contract
- A zod schema (`resourceUsageItemSchema` in a sibling contract file) is the
  single source of truth for one row: { id, label, unit, used, limit,
  currencyCode?, unitLabel?, warnAt?, criticalAt?, group?, detail? }.
  `resourceUsageStatusSchema` — "loading" | "empty" | "error" | "ready" — is the
  panel's own state, independent of any row's tone.
- `unit` is the most important field: "bytes" | "bytesPerSecond" | "cores" |
  "count" | "currency" | "percent" | "seconds". It selects a FORMATTER, not just
  a suffix. Sharing one number formatter across units is how a usage panel
  starts lying (1023 B printed as "1 KiB", 90 MiB/s printed as "90 MiB",
  8940 seconds printed as "8,940").
- `limit: null` is unlimited and is a first-class case, not a missing value. A
  non-finite or non-positive limit is coerced to the same case, because a bar
  divided by zero can only be a lie.
- Panel props: items; status; label (titles the panel and names it for
  assistive tech); locale (default "en-US"); warnAt (0.8) / criticalAt (0.95)
  as fallbacks for rows without their own; defaultSort ("input" | "usage");
  sortable; defaultCollapsedGroups; ungroupedLabel ("Other"); skeletonRows
  (clamped 1–24); emptyState; onRetry. No onRetry means the error branch has
  no button rather than a dead one. Render never reads the clock, Math.random
  or any browser API, so SSR and hydration are byte-identical.

Behavior
- Four first-class branches on `status`: loading → skeleton rows copying the
  real row's two-line geometry plus one sr-only role="status"; empty → a
  nothing-metered slot replaceable via `emptyState`; error → message + "Try
  again"; ready → header + grouped or flat rows. Never cap the number of rows
  and never wrap them in a fixed-height overflow container: a usage panel that
  silently hides row 11 is worse than one that scrolls.
- Byte formatting walks the 1024 ladder (B, KiB, MiB, GiB, TiB, PiB) and picks
  the rung by floor(log). Two corrections matter:
  (a) Math.log is not exact at the powers of 1024, so the guessed exponent is
      re-checked against the mantissa in both directions;
  (b) rounding must never carry a value across a rung it has not reached —
      1048575 B is 1023.999 KiB and must print "1,023 KiB", never the
      non-existent "1024 KiB". When rounding would cross, pin the number to the
      largest value representable below the boundary.
  Precision is three significant digits: >= 100 → 0 decimals, >= 10 → 1, else 2;
  whole bytes never get decimals.
- The used/limit pair shares one unit — "1.64 / 2.00 GiB" — but only while the
  used value is worth at least one whole unit of the quota's rung. Below that
  the shared rung would eat the number it exists to show ("0.00 / 2.00 TiB" for
  4 MiB; "1.00 / 4.00 KiB" for 1023 B), so each side falls back to carrying its
  own unit: "4.00 MiB / 2.00 TiB", "1,023 B / 4.00 KiB".
- The percentage is always computed from the RAW values, never from the rounded
  labels, and it refuses two specific lies: it never reads "100%" while there is
  headroom left (99.97% → "99.9%") and never reads "100%" while the quota is
  already blown (100.04% → "100.1%"). Inside the 95–105 band it gains a decimal
  so it can tell the difference; below 0.1% it degrades to "<0.1%" instead of
  rounding a live resource down to "0%". A row whose unit is "percent" against a
  quota of 100 points prints ONE number (the ratio) rather than two that
  disagree in the last digit.
- Unlimited rows draw no track, no fill and no percentage — the lane says
  "no quota" and the readout shows the current value alone. A full bar would
  claim the reader is at their limit; a near-empty one would invent a ceiling.
- Over quota never draws outside the track. Instead the track rescales to
  `used`: the quota becomes a marker line at limit/used, the segment past it is
  a hatched wash, and the tone chip carries the overage itself ("+10.0 GiB")
  because three significant digits can round 97.66 and 97.70 KiB into the same
  label. role="progressbar" keeps aria-valuemax at 100 and puts the honest
  sentence in aria-valuetext ("110% — 110 of 100 GiB used, over quota by
  10.0 GiB"). If the overage is smaller than the unit's own precision the chip
  falls back to the word, never to a "+0.0%" that reads as "not over".
- Tone is ok / warn / critical / over, and it is never carried by colour alone:
  warn adds a diagonal texture to the fill AND a triangle icon AND the words
  "Near limit"; critical and over switch to the destructive token AND an icon
  AND a word. Below the @md container width the word collapses to sr-only so
  the icon still carries it visually and the text still carries it aurally.
- Grouping turns on the moment any item has a `group`. Each section is a
  disclosure button with aria-expanded; a collapsed section UNMOUNTS its rows
  (a zero-height container still holds real tab stops) and its header keeps the
  group's worst tone chip, so folding a section can never fold an alarm out of
  sight. Sorting by usage is an aria-pressed toggle: rows sort by ratio
  descending, unlimited rows sort last (no ceiling can never be "fullest"), and
  because group order follows first appearance the fullest group floats up too.

Rendering & styling
- Semantic tokens only: bg-card (panel), bg-muted (track, skeleton, hover),
  bg-primary (normal fill), bg-destructive (critical / over fill) with
  bg-destructive/10 + text-destructive chips, text-muted-foreground for
  secondary text, focus-visible:ring-2 ring-ring on every control. The two
  textures are color-mix over --background / --destructive, so they ride the
  theme instead of hardcoding a colour. Do NOT reach for var(--chart-1..5) to
  tell resources apart: in a monochrome palette they are a lightness ladder
  with identical light and dark values. cn() merges the consumer className.
- Every figure is tabular-nums, and the percentage sits in a fixed-width slot so
  the column lines up down the panel — empty on unlimited rows rather than
  filled with a placeholder.
- Each row is two lines: name (+ detail + tone chip) with the readout pushed
  right, then the full-width track. The header line is flex-wrap and the label
  carries a min-width floor, so on a narrow container the readout drops to its
  own right-aligned line instead of shaving the resource's name to nothing —
  a `shrink-0` readout beside a `min-w-0` label wins every pixel otherwise.
- Density keys off @container, not viewport breakpoints: the same panel is a
  page section in one app and a 320px sidebar card in another.
- Root is role="group" + aria-labelledby (a `section` would add a landmark to
  every panel on the page); rows are a real ul/li; each track is a
  role="progressbar" with aria-valuetext. Nothing needs an sr-only data table —
  every row already reads as a sentence.
- Only the fill width, the chevron rotation and the skeleton pulse animate, all
  with motion-reduce variants; the panel is fully usable with motion off.

Customization levers
- Unit set: add a rung to the ladder, switch to decimal 1000-based units (rename
  KiB→KB and swap the step; keep the boundary-safe rounding), or add a unit by
  adding one case to the formatter switch — never by widening an existing one.
- Thresholds: warnAt / criticalAt per panel or per row; drop `warnAt` to 0.7 for
  capacity planning, or set both to 1 to keep every row neutral until it blows.
- Chrome per surface: `label` names the panel, `detail` adds a per-row context
  line (hidden under @md), `unitLabel` names counted things ("seats",
  "requests"), `emptyState` replaces the whole zero-state, `skeletonRows` should
  match your real page size.
- Density: px-3 py-2.5 rows read as "comfortable"; h-2 → h-1.5 tracks and py-1.5
  give a tighter ops panel without touching the state machine.
- Duration style: `formatDuration` is a small ladder ("45s" / "29m" / "2h 29m" /
  "3d 4h") — swap it for Intl.DurationFormat where it is available, or for a
  decimal-hours reading if your billing page quotes hours.
- Sorting: the toggle is two states; add "name" or "headroom" comparators the
  same way, or set sortable={false} and keep the server's order.