# Spend at a glance: a pill that opens the detail

Money an agent spends should be quiet but always in reach. Put a `UsageMeter` with `variant="pill"` in the header: a small ring filling with the share of the budget used, then "$18.82 / $50 · Nov". Within budget the ring is the accent, not green; from 75 % it is drawn in the warning colour and from 90 % in the danger colour, with an icon, and the level is in its words for screen readers, never colour alone.

Give the pill a `popover` and it becomes a button that opens it. Inside, show the same usage as a bar (with when it resets), the three items that cost most, the rest as one "Others" line, and two worded links: "See all spend" and "Edit budget…". Which period or scope the pill counts (this month, one round of work) is your choice of `Usage`.

Give the usage a `currency` and its figures are written as money. When the figure used so far is your own estimate (work on a subscription that reports no cost), set `basis: "estimated"`: the pill shows "est." and its words say "estimated". With no budget the pill says "no cap yet" and draws no ring.

Web page: https://candor.themethodic.com/patterns/spend-at-a-glance

## Components

- **Usage meters** (`usage-meters`, Pro; https://candor.themethodic.com/docs/usage-meters.md): The pill in the header, and the same usage as a bar inside the popover.
- **Money** (`money`, Pro; https://candor.themethodic.com/docs/money.md): Each item's cost, and the Others total, written in the locale.
- **Popover** (`popover`, free; https://candor.themethodic.com/docs/popover.md): What the pill opens; the pill names it with the usage's label.

## Install

```bash
npx candor-ui@4 add usage-meters money popover
```

## Code

`spend-at-a-glance.tsx`: The pill and its popover: the bar, the top three by cost, Others, and links to all spend and the budget.

```tsx
"use client"

import { UsageMeter } from "@/components/candor/usage-meters"
import { Money } from "@/components/candor/money"
import type { Usage } from "@/lib/candor/ops"

/** One thing spend went on this period, from your server. `cost` is null while it isn't measured yet. */
type SpendItem = { id: string; name: string; cost: number | null }

export function SpendAtAGlance({ spend, period, items, seeAllHref, budgetHref }: {
  /** This period's spend against the budget, with `currency` (and `basis: "estimated"` when it is your estimate). */
  spend: Usage
  /** The period in your words: "Nov", "Round 2". */
  period: string
  items: SpendItem[]
  seeAllHref: string
  budgetHref: string
}) {
  // Your figures, sorted here: the three that cost most, then everything else as one "Others" line.
  const measured = items.flatMap((item) => (item.cost === null ? [] : [{ ...item, cost: item.cost }]))
  const byCost = [...measured].sort((a, b) => b.cost - a.cost)
  const topThree = byCost.slice(0, 3)
  const rest = byCost.slice(3)
  const othersTotal = rest.reduce((sum, item) => sum + item.cost, 0)
  // An item whose cost isn't known yet is said, never dropped from the sum without a word.
  const notMeasured = items.length - measured.length

  return (
    <UsageMeter
      variant="pill"
      surface="header"
      usage={spend}
      period={period}
      popover={
        <div className="flex flex-col gap-3">
          {/* The same usage as a bar: the figure, its limit and when it resets. */}
          <UsageMeter usage={spend} className="border-0 p-0" />
          <ul aria-label="Top costs" className="flex flex-col gap-1 text-sm">
            {topThree.map((item) => (
              <li key={item.id} className="flex justify-between gap-3">
                <span className="truncate">{item.name}</span>
                <Money amount={item.cost} currency={spend.currency} />
              </li>
            ))}
            {rest.length > 0 && (
              <li className="flex justify-between gap-3 text-muted-foreground">
                <span>Others ({rest.length})</span>
                <Money amount={othersTotal} currency={spend.currency} />
              </li>
            )}
          </ul>
          {notMeasured > 0 && <p className="text-xs text-muted-foreground">{notMeasured} not measured yet, so not in the list.</p>}
          <div className="flex justify-between gap-3 text-sm">
            <a href={seeAllHref} className="underline underline-offset-2">See all spend</a>
            <a href={budgetHref} className="underline underline-offset-2">Edit budget…</a>
          </div>
        </div>
      }
    />
  )
}

```

## Notes

- "Others" is the sum of the measured costs after the top three, worked out by your app. When an item's cost isn't known yet, say so under the list; don't drop it from the sum without a word.
- Inside a card that is one link, such as PortfolioCard, the pill is static: use `usageVariant="pill"` there and put the detail on the page the card opens.
- Pass the pill's `level` from the same source as your budget alerts, so the colour and your notifications agree.
