feat(usage): say what the breakdown is showing

The section changed scope with the page filters and never said so, and
the control that changes it sits at the top of the page rather than
beside the numbers it affects. The header now names the project and the
period.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: talissoncosta

frontend/documentation/components/UsageBreakdown.stories.tsx

@@ -79,6 +79,23 @@ export const BySdk: Story = {
   },
 }
 
+/** The section states what it is showing, so a filter is never silently applied. */
+export const ScopedToAProject: Story = {
+  args: {
+    dimension: 'request-type',
+    rows: [
+      { colour: colorChart1, key: 'flags', label: 'Flags', value: 620_000 },
+      {
+        colour: colorChart3,
+        key: 'identities',
+        label: 'Identities',
+        value: 180_000,
+      },
+    ],
+    scope: 'Checkout · Last 30 days',
+  },
+}
+
 export const NoUsageRecorded: Story = {
   args: { dimension: 'request-type', rows: [] },
 }

frontend/web/components/pages/usage/UsageDashboardPage.tsx

@@ -11,6 +11,7 @@ import UsageBreakdown, { useUsageBreakdown } from './components/UsageBreakdown'
 import UsageDashboard from './UsageDashboard'
 import {
   isBillingPeriodSelected,
+  periodLabel,
   periodsFor,
   PeriodSelection,
   planHasBillingPeriod,
@@ -26,6 +27,7 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
   organisationId,
 }) => {
   const [project, setProject] = useState<string | undefined>()
+  const [projectName, setProjectName] = useState<string | undefined>()
   const selectedProjectId = project ? Number(project) : undefined
 
   const {
@@ -65,6 +67,13 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
 
   const { setDimension, ...breakdown } = useUsageBreakdown({ data })
 
+  const scope = [
+    selectedProjectId ? projectName : 'All projects',
+    periodLabel(periods, billingPeriod),
+  ]
+    .filter(Boolean)
+    .join(' · ')
+
   if (!organisationId) {
     return null
   }
@@ -76,7 +85,11 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
       limit={subscriptionMeta?.max_api_calls}
       hasBillingPeriod={isBillingPeriodSelected(billingPeriod)}
       breakdown={
-        <UsageBreakdown {...breakdown} onChangeDimension={setDimension} />
+        <UsageBreakdown
+          {...breakdown}
+          onChangeDimension={setDimension}
+          scope={scope}
+        />
       }
       isError={organisationFailed || usageFailed}
       isLoading={loadingOrganisation || loadingUsage || loadingLimit}
@@ -97,7 +110,10 @@ const UsageDashboardPage: FC<UsageDashboardPageProps> = ({
               inputId='usage-project'
               showAll
               organisationId={organisationId}
-              onChange={setProject}
+              onChange={(id: string, name: string) => {
+                setProject(id)
+                setProjectName(name)
+              }}
               value={project}
             />
           </div>

frontend/web/components/pages/usage/components/UsageBreakdown/UsageBreakdown.tsx

@@ -8,6 +8,7 @@ export type UsageBreakdownProps = {
   dimension: BreakdownDimension
   onChangeDimension: (dimension: BreakdownDimension) => void
   rows: BreakdownRow[]
+  scope?: string
 }
 
 type DimensionOption = (typeof BREAKDOWN_DIMENSIONS)[number]
@@ -16,10 +17,14 @@ const UsageBreakdown: FC<UsageBreakdownProps> = ({
   dimension,
   onChangeDimension,
   rows,
+  scope,
 }) => (
   <div className='p-4 mt-3 border border-default rounded-lg bg-surface-default'>
     <div className='d-flex align-items-end justify-content-between gap-3 mb-3'>
-      <strong>Where the usage came from</strong>
+      <div>
+        <strong>Where the usage came from</strong>
+        {scope && <div className='fs-captionSmall text-secondary'>{scope}</div>}
+      </div>
       <div className='usage-breakdown__dimension'>
         <FieldLabel htmlFor='usage-breakdown-dimension'>
           Break down by

frontend/web/components/pages/usage/utils.ts

@@ -26,5 +26,10 @@ export const resolvePeriod = (
 export const isBillingPeriodSelected = (period: BillingPeriod): boolean =>
   period === 'current_billing_period' || period === 'previous_billing_period'
 
+export const periodLabel = (
+  periods: PeriodOption[],
+  period: BillingPeriod,
+): string => periods.find((option) => option.value === period)?.label ?? ''
+
 export const periodsFor = (billingPeriodAvailable: boolean): PeriodOption[] =>
   billingPeriodAvailable ? periodOptions : rollingPeriodOptions