feat(usage): show when an organisation is over its plan limit

frontend/CLAUDE.md

@@ -13,13 +13,13 @@
 
 ## Rules
 1. **API Integration**: Use `npx ssg` CLI + check `../api` backend
-2. **Imports**: Use `common/`, `components/`, `project/` (NO relative imports)
+2. **Imports**: Use the `common/`, `components/`, `project/` aliases when the relative path would go up (`../`); use a relative path for same-folder or descendant imports. This is enforced by `@dword-design/import-alias/prefer-alias`, and `eslint --fix` will rewrite an alias back to relative inside its own alias root (e.g. `components/base/forms/X` becomes `./base/forms/X` in a file under `web/components/`).
 3. **State**: Redux Toolkit + RTK Query, store in `common/store.ts`
 4. **Feature Flags**: When user says "create a feature flag", you MUST: (1) Create it in Flagsmith using MCP tools (`mcp__flagsmith__create_feature`), (2) Implement code with `useFlags` hook. See `.claude/context/feature-flags/` for details
 5. **Linting**: ALWAYS run `npx eslint --fix <file>` on any files you modify
 6. **Type Enums**: Extract inline union types to named types (e.g., `type Status = 'A' | 'B'` instead of inline)
 7. **NO FETCH**: NEVER use `fetch()` directly - ALWAYS use RTK Query mutations/queries (inject endpoints into services in `common/services/`), see api-integration context
-8. **Component structure**: Each new component lives in its own folder with an `index.ts` barrel - `ComponentName/ComponentName.tsx`, co-located `ComponentName.scss`, any sub-components, and an `index.ts` that re-exports the default (and public types). Import via the folder (`components/.../ComponentName`), never the inner file. Keep files focused (~100 lines as a target); split by concern, not to hit a number. Data tables/constant maps are exempt.
+8. **Component structure**: A component with nothing to keep beside it is a single `ComponentName.tsx`. It gets a folder once it has a co-located `ComponentName.scss`, sub-components, tests or hooks: `ComponentName/ComponentName.tsx` plus an `index.ts` re-exporting the default (and public types). Import via `components/.../ComponentName` either way, never the inner file, so promoting a file to a folder changes no imports. Keep files focused (~100 lines as a target); split by concern, not to hit a number. Data tables/constant maps are exempt.
 
 ## Key Files
 - Store: `common/store.ts`

frontend/documentation/components/UsageDashboard.stories.tsx

@@ -1,18 +1,27 @@
 import { FC, useState } from 'react'
 import type { Meta, StoryObj } from 'storybook'
-import { UsageDashboard } from 'components/pages/usage'
+import UsagePageLayout from 'components/pages/usage/components/UsagePageLayout'
+import OverLimitBanner from 'components/pages/usage/components/OverLimitBanner'
+import SectionHeading from 'components/pages/usage/components/SectionHeading'
 import UsageBreakdown, {
   useUsageBreakdown,
 } from 'components/pages/usage/components/UsageBreakdown'
+import UsageMeter from 'components/pages/usage/components/UsageMeter'
+import UsageOverTime from 'components/pages/usage/components/UsageOverTime'
 import {
-  allowanceWindow,
   contributionNote,
+  overLimitNote,
+  planSectionCopy,
+} from 'components/pages/usage/copy'
+import { overLimitOf } from 'components/pages/usage/overLimit'
+import {
+  allowanceWindow,
   isBilledOnAPeriod,
   isBillingPeriodSelected,
+  isChargedForOverages,
   periodLabel,
   periodsFor,
   PeriodSelection,
-  planSectionCopy,
   resolvePeriod,
   showsContribution,
   showsPlanCeiling,
@@ -23,6 +32,10 @@ import { PlanLimit } from 'components/shared/UsageBar/utils'
 import { Subscription } from 'common/types/responses'
 import { toUsageResponse, USAGE_SCENARIOS } from './fixtures/usage'
 
+// UsageFilters sets this in its stylesheet, which the harness never loads:
+// it fakes the project select rather than rendering the real component.
+const FILTER_WIDTH = { minWidth: 210 }
+
 const PROJECTS = [
   'All Projects',
   'Checkout',
@@ -69,6 +82,7 @@ type HarnessProps = {
   empty?: boolean
   isLoading?: boolean
   isError?: boolean
+  isRestricted?: boolean
 }
 
 /**
@@ -79,6 +93,7 @@ const UsagePage: FC<HarnessProps> = ({
   empty,
   isError,
   isLoading,
+  isRestricted,
   limit,
   scale = 1,
   subscription,
@@ -99,10 +114,20 @@ const UsagePage: FC<HarnessProps> = ({
     scenarioFor(billingPeriod, !!empty, isFreePlan),
     share * scale,
   )
-  const allowanceTotal = toUsageResponse(
+  const allowance = toUsageResponse(
     scenarioFor(allowanceWindow(basis), !!empty, isFreePlan),
     scale,
-  ).totals.total
+  )
+  const allowanceTotal = allowance.totals.total
+  const exceeded = overLimitOf(allowanceTotal, limit, allowance)
+
+  const contribution = showsContribution(
+    basis,
+    billingPeriod,
+    filtered ? 1 : undefined,
+  )
+    ? contributionNote(project, scoped.totals.total, allowanceTotal)
+    : undefined
 
   // The note needs the organisation over the period on screen, not over the
   // allowance window, or a project can read as more than all of it.
@@ -114,53 +139,79 @@ const UsagePage: FC<HarnessProps> = ({
   )}`
 
   return (
-    <UsageDashboard
-      breakdown={
-        <UsageBreakdown
-          {...breakdown}
-          onChangeDimension={setDimension}
-          scope={scope}
-        />
-      }
-      data={scoped}
-      filters={
-        <Row className='gap-2'>
-          <div style={{ minWidth: 210 }}>
-            <Select
-              aria-label='Period'
-              onChange={(option: PeriodOption) => setChosenPeriod(option.value)}
-              options={periods}
-              value={periods.find((option) => option.value === billingPeriod)}
-            />
-          </div>
-          <div style={{ minWidth: 210 }}>
-            <Select
-              aria-label='Project'
-              onChange={(option: { value: string }) => setProject(option.value)}
-              options={PROJECTS.map((name) => ({ label: name, value: name }))}
-              value={{ label: project, value: project }}
-            />
-          </div>
-        </Row>
-      }
-      hasBillingPeriod={isBillingPeriodSelected(billingPeriod)}
+    <UsagePageLayout
       isError={isError}
       isLoading={isLoading}
-      limit={limit}
-      meterNote={
-        showsContribution(basis, billingPeriod, filtered ? 1 : undefined)
-          ? contributionNote(project, scoped.totals.total, allowanceTotal)
-          : undefined
+      alert={
+        (exceeded || isRestricted) && (
+          <OverLimitBanner
+            over={exceeded}
+            basis={basis}
+            canUpgrade
+            isRestricted={isRestricted}
+            mayBeCharged={
+              isBilledOnAPeriod(basis) && isChargedForOverages(subscription)
+            }
+          />
+        )
       }
+      // Nothing to refetch here; passed so FailedToLoad renders its button.
       onRetry={() => {}}
-      periodLabel={periodLabel(periods, billingPeriod)}
-      planCopy={planSectionCopy(basis, limit)}
-      showPlanCeiling={showsPlanCeiling(
-        billingPeriod,
-        filtered ? 1 : undefined,
-      )}
-      total={allowanceTotal}
-    />
+    >
+      <SectionHeading {...planSectionCopy(basis, limit)} />
+
+      <UsageMeter
+        total={allowanceTotal}
+        limit={limit}
+        note={exceeded ? overLimitNote(exceeded) : contribution}
+      />
+
+      <SectionHeading
+        title='Explore usage'
+        hint='Narrow the chart and the breakdown by period or project.'
+        action={
+          <Row className='gap-2'>
+            <div style={FILTER_WIDTH}>
+              <Select
+                aria-label='Period'
+                onChange={(option: PeriodOption) =>
+                  setChosenPeriod(option.value)
+                }
+                options={periods}
+                value={periods.find((option) => option.value === billingPeriod)}
+              />
+            </div>
+            <div style={FILTER_WIDTH}>
+              <Select
+                aria-label='Project'
+                onChange={(option: { value: string }) =>
+                  setProject(option.value)
+                }
+                options={PROJECTS.map((name) => ({ label: name, value: name }))}
+                value={{ label: project, value: project }}
+              />
+            </div>
+          </Row>
+        }
+      />
+
+      <UsageOverTime
+        data={scoped}
+        limit={
+          showsPlanCeiling(billingPeriod, filtered ? 1 : undefined)
+            ? limit
+            : undefined
+        }
+        isBillingPeriod={isBillingPeriodSelected(billingPeriod)}
+        periodLabel={periodLabel(periods, billingPeriod)}
+      />
+
+      <UsageBreakdown
+        {...breakdown}
+        onChangeDimension={setDimension}
+        scope={scope}
+      />
+    </UsagePageLayout>
   )
 }
 
@@ -183,10 +234,30 @@ export const PaidApproachingTheLimit: Story = {
   args: { limit: 1400000, subscription: billed },
 }
 
+// Billed on a term, so the banner mentions charges.
 export const PaidOverTheLimit: Story = {
   args: { limit: 900000, subscription: billed },
 }
 
+// Only free plans are ever restricted, and this is where they are sent.
+export const FreeAndRestricted: Story = {
+  args: {
+    isRestricted: true,
+    limit: 50000,
+    subscription: subscriptionOf({ plan: 'free' }),
+  },
+}
+
+// The block outlives the overage, and support can set it by hand, so with
+// nothing in evidence the banner promises nothing.
+export const RestrictedWithNoOverageInEvidence: Story = {
+  args: {
+    isRestricted: true,
+    limit: 5000000,
+    subscription: subscriptionOf({ plan: 'free' }),
+  },
+}
+
 export const FreeOnARollingWindow: Story = {
   args: { limit: 50000, subscription: subscriptionOf({ plan: 'free' }) },
 }
@@ -203,6 +274,17 @@ export const EnterpriseWithoutABillingPeriod: Story = {
   },
 }
 
+// Invoiced outside Chargebee, so no charge line.
+export const EnterpriseOverTheLimit: Story = {
+  args: {
+    limit: 1000000,
+    subscription: subscriptionOf({
+      payment_method: 'XERO',
+      plan: 'enterprise',
+    }),
+  },
+}
+
 // On Chargebee, but no period has arrived. Reads differently from invoiced,
 // because this one may resolve itself.
 export const ChargebeeWithoutAPeriodYet: Story = {

frontend/jest.config.js

@@ -13,6 +13,8 @@ module.exports = {
     '^common/(.*)$': '<rootDir>/common/$1',
     '^components/(.*)$': '<rootDir>/web/components/$1',
     '^project/(.*)$': '<rootDir>/web/project/$1',
+    // webpack resolves this one too; without it jest cannot follow the app.
+    '^web/(.*)$': '<rootDir>/web/$1',
   },
   preset: 'ts-jest',
   roots: ['<rootDir>'],

frontend/web/__tests__/routePaths.test.ts

@@ -0,0 +1,28 @@
+import { isAllowedWhileBlocked } from 'web/routePaths'
+
+// App renders <Blocked /> wherever this is false, so a wrong answer either
+// locks a blocked organisation out, or lets it back in.
+describe('isAllowedWhileBlocked', () => {
+  it.each`
+    pathname                                 | allowed
+    ${'/organisation/7528/usage'}            | ${true}
+    ${'/organisations'}                      | ${true}
+    ${'/organisation/7528/projects'}         | ${false}
+    ${'/organisation/7528/settings'}         | ${false}
+    ${'/organisation-settings'}              | ${false}
+    ${'/project/1/environment/abc/features'} | ${false}
+    ${'/account'}                            | ${false}
+  `(
+    '$pathname is reachable while blocked: $allowed',
+    ({ allowed, pathname }) => {
+      expect(isAllowedWhileBlocked(pathname)).toBe(allowed)
+    },
+  )
+
+  // Allowed by pattern, not by prefix.
+  it('does not open anything nested under the usage page', () => {
+    expect(isAllowedWhileBlocked('/organisation/7528/usage/breakdown')).toBe(
+      false,
+    )
+  })
+})

frontend/web/components/App.js

@@ -30,7 +30,9 @@ import Announcement from './Announcement'
 import { getBuildVersion } from 'common/services/useBuildVersion'
 import AccountProvider from 'common/providers/AccountProvider'
 import Nav from './navigation/Nav'
+import { isAllowedWhileBlocked } from 'web/routePaths'
 import 'project/darkMode'
+
 const App = class extends Component {
   static propTypes = {
     children: propTypes.element.isRequired,
@@ -271,9 +273,8 @@ const App = class extends Component {
     const environmentId = this.getEnvironmentId(this.props)
 
     if (
-      AccountStore.getOrganisation() &&
-      AccountStore.getOrganisation().block_access_to_admin &&
-      pathname !== '/organisations'
+      AccountStore.getOrganisation()?.block_access_to_admin &&
+      !isAllowedWhileBlocked(pathname)
     ) {
       return <Blocked />
     }

frontend/web/components/BlockedOrgInfo.tsx

@@ -7,6 +7,11 @@ export default function BlockedOrgInfo() {
     <div className='text-nowrap'>
       <div>Organisation name: {AccountStore.getOrganisation().name}</div>
       <div>Organisation ID: {AccountStore.getOrganisation().id}</div>
+      <div>
+        <a href={`/organisation/${AccountStore.getOrganisation().id}/usage`}>
+          See your usage
+        </a>
+      </div>
       <div>
         <a href='/organisations'>Switch to a different organisation</a>
       </div>