feat(component): UsageBreakdown — Ranked Resource Consumption List

[bntvllnt]

Summary

Ranked list of resource consumers (models, projects, services, users) with metric columns showing calls, tokens/units, cost, and share percentage. Used for "top N by usage" views in analytics dashboards. A generic breakdown pattern that works for any measurable resource.

Proposed API

<UsageBreakdown
  title="Model usage"
  items={[
    { id: "gpt-4", label: "gpt-4o", metrics: [
      { label: "calls", value: "1,234" },
      { label: "tokens", value: "2.5M" },
    ], value: "$12.34", share: 0.65 },
    { id: "claude", label: "claude-sonnet-4-20250514", metrics: [
      { label: "calls", value: "567" },
      { label: "tokens", value: "800K" },
    ], value: "$5.67", share: 0.35 },
  ]}
  emptyMessage="No model usage in this billing period"
  action={<Button size="sm" variant="ghost">Export</Button>}
/>

Requirements

• Generic item shape: { id, label, metrics: { label, value }[], value: string, share?: number }
• Primary value displayed right-aligned (typically cost)
• Secondary metrics inline: "X calls · Y tokens · Z% of spend"
• Optional share percentage for relative comparison
• Title + optional action slot (export button, filter, etc.)
• Empty state with configurable message
• Compact row layout: label + metrics left, primary value right
• Truncation on long labels
• Dark mode: bordered rows with subtle backgrounds
• Accessible: list semantics, metrics readable in linear order

Layout

┌──────────────────────────────────────────────────┐
│  Model usage                         [Export]    │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │ gpt-4o                            $12.34   │  │
│  │ 1,234 calls · 2.5M tokens · 65% of spend  │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │ claude-sonnet-4-20250514                    $5.67   │  │
│  │ 567 calls · 800K tokens · 35% of spend    │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Use Cases

• AI platform model usage breakdown
• Cloud dashboard service consumption
• API analytics endpoint usage ranking
• Team/user resource consumption leaderboard
• Project cost breakdown

Composes

• Card, Button

Origin

Extracted from ModelBreakdown, ProjectBreakdown, and ModelLeaderboardSection in apps/web-ai-os/app/account/usage/ in vllnt/vllnt monorepo. Pattern duplicated 3x across project-usage, workspace-usage, and usage-client.

[bntvllnt]

Shipped and merged in PR #112: #112