feat: scope billing usage card to the selected time range

[daviddanialy]

What

The billing page's usage card previously always showed the full billing cycle's position, even when the page was scoped to a custom date range (typed, calendar-picked, or bar-click drill-down). It now follows the selected range:

• Full cycle (picker selection, or a range matching a cycle's exact boundaries): unchanged — allowance, overage, % of allowance, and the two-segment meter.
• Custom range: the title becomes the range (Jul 10 – Jul 20 · July Billing Cycle, or the picker's parse label like "Last 7 days"; the cycle suffix drops when the range spans cycles). Tokens Managed is the range's billed total, Overage is time-attributed — tokens recorded after the cycle's cumulative billed usage crossed the allowance, crossing day prorated — with an info tooltip. The per-unit average uses the range window. Allowance, percentage, and meter hide: they're cycle-level concepts and comparing days of traffic against a monthly number would mislead.
• Ranges the billed daily series can't answer (outside known cycles, non-day-aligned) fall back to the analytics total and show — for overage with an explanatory tooltip.

The details table's Overage column adopts the same attribution for custom ranges (it previously showed —), and its Total row pins to the usage card's figure exactly, so the two surfaces always agree to the token.

Code organization

The TUM billing module is split by responsibility so this is easier to extend:

• billing-cycles.ts — pure domain logic: cycle/period types, billed-daily-series normalization (billedDaysFromCycles), the allowance-crossing overage walk (overageDaysFromBilled, shared by card and table), coverage checks, label formatting.
• use-billing-period.ts — new hook owning all period-selection state (cycle pick, range override, bar drill-down, reset).
• tum-token-breakdown.tsx / tum-admin-section.tsx — extracted from the section file.
• tum-usage-card.tsx — the card view plus its data-resolving PeriodUsageCard wrapper.
• tum-section.tsx — thin composition only (~160 lines, was ~520).

Seed

seed.mts now boosts days inside the active billing cycle so the current cycle lands clearly past the seeded 50M allowance (~190% of allowance), making the overage rendering visible in local dev regardless of when the seed runs.

Testing

• Verified in the local dashboard end-to-end: full cycle → calendar-picked range → card re-scopes (title, tokens, attributed overage, hidden meter) → details table Total row matches the card exactly → Reset returns to the full cycle.
• pnpm -F dashboard type-check, lint, and lint:format pass.

🤖 Generated with Claude Code

---

Summary by cubic

Scopes the billing usage card and details table to the selected time range so tokens and overage reflect the view; full-cycle behavior is unchanged. All surfaces (card, chart headline, table) now resolve shared billed figures and overage consistently, with clear fallbacks and failure states.

• New Features

  • Range-aware card: titles show the range label/dates with a cycle suffix; Tokens Managed uses billed totals in-range; Overage is time-attributed with a prorated crossing day; allowance, % used, and meter hide on partial ranges. Average rate uses the selected window, shows skeletons while loading, and displays "—" with an explanation if the fallback total fails.
  • Coverage and fallbacks: billed normalization and overage attribution apply to full cycles and day-aligned ranges fully covered by billed data; otherwise the UI falls back to analytics totals and shows "—" for overage with a tooltip. The breakdown chart now renders a distinct failure message when details fail.
  • Details table: reads the same resolved figures, pins its Total to the card, attributes overage via per‑day billed fractions, and shows "—" when overage is not attributable (no allowance, uncovered range, or no tokens in-window). Tooltips clarify billed-normalized vs analytics totals and overage meaning.

• Refactors

  • Centralized period logic and figures: added PeriodUsageCard, use-billing-period.ts (DST-safe range parsing, drill‑down, reset), and new helpers in billing-cycles.ts (billedDaysFromCycles, overageDaysFromBilled, resolvePeriodFigures, formatPeriodLabel). Extracted tum-token-breakdown.tsx and tum-admin-section.tsx; tum-section.tsx simplified.
  • Chart/table share the same details query; TokenUsagePanel accepts failed to distinguish outages from empty ranges. Seed script boosts active-cycle usage with a weekend-aware multiplier to reliably surface overage in local dev.

^{Written for commit f7a85a5. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: f7a85a5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
dashboard	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[daviddanialy]

https://linear.app/speakeasy/issue/DNO-722/make-billing-page-cumulative-panel-honor-date-range

[daviddanialy]

Demo: usage card follows the selected range

1. Full July cycle: allowance, overage, % of allowance, and the two-segment meter (unchanged).
2. Calendar-pick Jul 10 – Jul 20.
3. The card re-scopes: title gains the range + cycle context, Tokens Managed becomes the range total, Overage becomes the time-attributed in-range figure (with an explainer tooltip), and the allowance/meter hide. Reset returns to the cycle.

Demo: bar-click drill-down

1. Clicking a chart bar narrows the page to that day.
2. The card follows: single-day title, that day's tokens, and Overage 0 — the day precedes the allowance crossing, so none of its tokens are attributed as overage.

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>