@carlonicora/nextjs-jsonapi 2.4.0 → 3.0.0

package/src/features/tokenusage/components/TokenUsageAdminContainer.tsx

@@ -49,6 +49,21 @@ export function TokenUsageAdminContainer() {
     error,
   } = useTokenUsageAdmin();
 
+  // narr8-shaped deployments record essentially no platform spend (usage with no
+  // owning company), which would leave the platform tile and the
+  // platform-by-operation panel as permanent zeros. Treat "nothing to show" the
+  // same way a company filter is treated — the customer half then takes full
+  // width. a360ai is unaffected: it has real platform spend.
+  const platformIsEmpty = useMemo(
+    () =>
+      summary
+        .filter((row) => row.scope === "platform")
+        .every((row) => row.cost === 0 && row.credits === 0 && row.tokensIn === 0 && row.tokensOut === 0),
+    [summary],
+  );
+
+  const hidePlatform = singleCustomerMode || platformIsEmpty;
+
   const stackByItems = useMemo(
     () => ({
       scope: t("token_usage.admin.stack.scope"),
@@ -81,7 +96,7 @@ export function TokenUsageAdminContainer() {
   return (
     <RoundPageContainer fullWidth forceHeader>
       <div className="flex w-full flex-col gap-4 p-4">
-        <TokenUsageAdminTiles summary={summary} metric={filters.metric} singleCustomerMode={singleCustomerMode} />
+        <TokenUsageAdminTiles summary={summary} metric={filters.metric} singleCustomerMode={hidePlatform} />
 
         <Card>
           <CardHeader>
@@ -142,8 +157,9 @@ export function TokenUsageAdminContainer() {
             Platform spend has no owning company, so a company filter makes that
             half meaningless: the provider skips the request and the card is
             hidden rather than rendered empty, leaving the customer half full
-            width. */}
-        <div className={cn("grid gap-4", !singleCustomerMode && "md:grid-cols-2")}>
+            width. The same holds when the window records no platform spend at
+            all — see `hidePlatform` above. */}
+        <div className={cn("grid gap-4", !hidePlatform && "md:grid-cols-2")}>
           <Card>
             <CardHeader>
               <CardTitle>{t("token_usage.admin.customer_by_operation")}</CardTitle>
@@ -158,7 +174,7 @@ export function TokenUsageAdminContainer() {
             </CardContent>
           </Card>
 
-          {!singleCustomerMode && (
+          {!hidePlatform && (
             <Card>
               <CardHeader>
                 <CardTitle>{t("token_usage.admin.platform_by_operation")}</CardTitle>

package/src/features/tokenusage/components/TokenUsageAdminTiles.tsx

@@ -6,15 +6,8 @@ import { Card, CardContent } from "../../../shadcnui";
 import { cn } from "../../../utils";
 import type { TokenUsageAdminSummaryInterface } from "../data/tokenusage-admin-summary.interface";
 import type { Metric } from "../data/tokenusage-admin.types";
-import {
-  cacheHitPercentage,
-  formatDecimal,
-  formatMetricValue,
-  formatPercent,
-  metricValue,
-  percentageDelta,
-  type TokenUsageMetrics,
-} from "../lib/metrics";
+import { useUsageFormatters } from "../lib/formatters";
+import { cacheHitPercentage, metricValue, percentageDelta, type TokenUsageMetrics } from "../lib/metrics";
 
 type Props = {
   /** The six summary rows: {customer, platform, total} × {current, previous}. */
@@ -38,6 +31,7 @@ const ZERO: TokenUsageMetrics = { cost: 0, credits: 0, tokensIn: 0, tokensOut: 0
  */
 export function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Props) {
   const t = useTranslations();
+  const { decimal, metricValue: formatValue, currency, percent } = useUsageFormatters();
 
   const rowFor = (scope: string, window: string): TokenUsageMetrics =>
     summary.find((r) => r.scope === scope && r.window === window) ?? ZERO;
@@ -58,17 +52,19 @@ export function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Pr
         <LeadTile
           testId="tile-customer"
           label={t("token_usage.admin.customer_spend")}
-          value={formatMetricValue(metricValue(customerCurrent, metric), metric)}
+          value={formatValue(metricValue(customerCurrent, metric), metric)}
           delta={percentageDelta(metricValue(customerCurrent, metric), metricValue(customerPrevious, metric))}
           previousLabel={t("token_usage.admin.vs_previous")}
+          decimal={decimal}
         />
         {!singleCustomerMode && (
           <LeadTile
             testId="tile-platform"
             label={t("token_usage.admin.platform_spend")}
-            value={formatMetricValue(metricValue(platformCurrent, metric), metric)}
+            value={formatValue(metricValue(platformCurrent, metric), metric)}
             delta={percentageDelta(metricValue(platformCurrent, metric), metricValue(platformPrevious, metric))}
             previousLabel={t("token_usage.admin.vs_previous")}
+            decimal={decimal}
           />
         )}
       </div>
@@ -77,18 +73,21 @@ export function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Pr
         <SupportingTile
           testId="tile-total"
           label={t("token_usage.admin.total_cost")}
-          value={formatMetricValue(metricValue(totalCurrent, metric), metric)}
+          value={formatValue(metricValue(totalCurrent, metric), metric)}
           delta={percentageDelta(metricValue(totalCurrent, metric), metricValue(totalPrevious, metric))}
+          decimal={decimal}
         />
         <SupportingTile
           testId="tile-avg-per-call"
           label={t("token_usage.admin.avg_per_call")}
-          value={`€ ${formatDecimal(averagePerCall, 4)}`}
+          value={currency(averagePerCall, 4)}
+          decimal={decimal}
         />
         <SupportingTile
           testId="tile-cache-hit"
           label={t("token_usage.admin.cache_hit")}
-          value={formatPercent(cacheHit)}
+          value={percent(cacheHit)}
+          decimal={decimal}
         />
       </div>
     </div>
@@ -101,12 +100,15 @@ function LeadTile({
   value,
   delta,
   previousLabel,
+  decimal,
 }: {
   testId: string;
   label: string;
   value: string;
   delta: number | undefined;
   previousLabel: string;
+  /** Passed down because `Delta` is a plain function, not a component: it cannot call the hook itself. */
+  decimal: (value: number, decimals: number) => string;
 }) {
   return (
     <Card data-testid={testId}>
@@ -114,7 +116,7 @@ function LeadTile({
         <span className="text-muted-foreground text-xs">{label}</span>
         <span className="text-primary text-xl font-semibold tabular-nums">{value}</span>
         <span className="flex items-center gap-1">
-          <Delta testId={`${testId}-delta`} delta={delta} />
+          <Delta testId={`${testId}-delta`} delta={delta} decimal={decimal} />
           <span className="text-muted-foreground text-xs">{previousLabel}</span>
         </span>
       </CardContent>
@@ -127,11 +129,14 @@ function SupportingTile({
   label,
   value,
   delta,
+  decimal,
 }: {
   testId: string;
   label: string;
   value: string;
   delta?: number | undefined;
+  /** Passed down because `Delta` is a plain function, not a component: it cannot call the hook itself. */
+  decimal: (value: number, decimals: number) => string;
 }) {
   return (
     <Card data-testid={testId} size="sm">
@@ -139,7 +144,7 @@ function SupportingTile({
         <span className="text-muted-foreground text-xs">{label}</span>
         <span className="flex items-center gap-2">
           <span className="text-sm font-medium tabular-nums">{value}</span>
-          {delta !== undefined && <Delta testId={`${testId}-delta`} delta={delta} />}
+          {delta !== undefined && <Delta testId={`${testId}-delta`} delta={delta} decimal={decimal} />}
         </span>
       </CardContent>
     </Card>
@@ -150,7 +155,15 @@ function SupportingTile({
  * The delta slot. An undefined delta means the previous window was zero: an
  * em dash says "not comparable" where a percentage would say "infinite growth".
  */
-function Delta({ testId, delta }: { testId: string; delta: number | undefined }) {
+function Delta({
+  testId,
+  delta,
+  decimal,
+}: {
+  testId: string;
+  delta: number | undefined;
+  decimal: (value: number, decimals: number) => string;
+}) {
   if (delta === undefined) {
     return (
       <span data-testid={testId} className="text-muted-foreground text-xs">
@@ -171,7 +184,7 @@ function Delta({ testId, delta }: { testId: string; delta: number | undefined })
       )}
     >
       <Icon aria-hidden className="size-3" />
-      {formatDecimal(Math.abs(delta), 0)} %
+      {decimal(Math.abs(delta), 0)} %
     </span>
   );
 }

package/src/features/tokenusage/components/TokenUsageBreakdownTable.tsx

@@ -7,7 +7,8 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from ".
 import { cn } from "../../../utils";
 import type { TokenUsageAdminBreakdownInterface } from "../data/tokenusage-admin-breakdown.interface";
 import type { Metric } from "../data/tokenusage-admin.types";
-import { cacheHitPercentage, formatDecimal, formatMetricValue, formatPercent, metricValue } from "../lib/metrics";
+import { useUsageFormatters } from "../lib/formatters";
+import { cacheHitPercentage, metricValue } from "../lib/metrics";
 
 type Props = {
   rows: TokenUsageAdminBreakdownInterface[];
@@ -28,6 +29,7 @@ type SortState = { key: SortKey; direction: "asc" | "desc" };
  */
 export function TokenUsageBreakdownTable({ rows, metric }: Props) {
   const t = useTranslations();
+  const { decimal, metricValue: formatValue, percent, compare } = useUsageFormatters();
   const [sort, setSort] = useState<SortState | undefined>(undefined);
 
   // The company dimension is the only one that reports active users. Rather than
@@ -61,11 +63,11 @@ export function TokenUsageBreakdownTable({ rows, metric }: Props) {
       const left = sortValue(a, sort.key);
       const right = sortValue(b, sort.key);
       if (typeof left === "string" || typeof right === "string") {
-        return String(left).localeCompare(String(right), "it-IT") * factor;
+        return compare(String(left), String(right)) * factor;
       }
       return (left - right) * factor;
     });
-  }, [rows, sort, metric]);
+  }, [rows, sort, metric, compare]);
 
   // First click on a column sorts descending: on a spend table the interesting
   // end of every numeric column is the top one.
@@ -136,20 +138,18 @@ export function TokenUsageBreakdownTable({ rows, metric }: Props) {
                 <TableCell className="text-muted-foreground text-xs">{row.sublabel ?? ""}</TableCell>
                 {showActiveUsers && (
                   <TableCell className="text-right text-xs tabular-nums">
-                    {row.activeUsers === undefined ? "" : formatDecimal(row.activeUsers, 0)}
+                    {row.activeUsers === undefined ? "" : decimal(row.activeUsers, 0)}
                   </TableCell>
                 )}
-                <TableCell className="text-right text-xs tabular-nums">{formatDecimal(row.calls, 0)}</TableCell>
-                <TableCell className="text-right text-xs tabular-nums">{formatDecimal(row.tokensIn, 0)}</TableCell>
-                <TableCell className="text-right text-xs tabular-nums">{formatDecimal(row.tokensOut, 0)}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{decimal(row.calls, 0)}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{decimal(row.tokensIn, 0)}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{decimal(row.tokensOut, 0)}</TableCell>
                 <TableCell className="text-right text-xs tabular-nums">
-                  {formatPercent(cacheHitPercentage(row.cached, row.tokensIn))}
+                  {percent(cacheHitPercentage(row.cached, row.tokensIn))}
                 </TableCell>
-                <TableCell className="text-right text-xs tabular-nums">{formatMetricValue(row.cost, "cost")}</TableCell>
-                <TableCell className="text-right text-xs tabular-nums">
-                  {formatMetricValue(row.credits, "credits")}
-                </TableCell>
-                <TableCell className="text-right text-xs tabular-nums">{formatPercent(share)}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{formatValue(row.cost, "cost")}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{formatValue(row.credits, "credits")}</TableCell>
+                <TableCell className="text-right text-xs tabular-nums">{percent(share)}</TableCell>
               </TableRow>
             );
           })}

package/src/features/tokenusage/components/TokenUsageRankedBar.tsx

@@ -1,17 +1,33 @@
 "use client";
 
 import { useTranslations } from "next-intl";
-import type { TokenUsageAdminBreakdownInterface } from "../data/tokenusage-admin-breakdown.interface";
 import type { Metric } from "../data/tokenusage-admin.types";
-import { formatMetricValue, formatPercent, metricValue } from "../lib/metrics";
+import { useUsageFormatters } from "../lib/formatters";
+import { metricValue, type TokenUsageMetrics } from "../lib/metrics";
 import { operationLabel } from "../lib/operation-label";
 import { SEQUENTIAL_RAMP } from "../lib/palette";
 
+/**
+ * Everything this component actually reads from a row.
+ *
+ * Declared STRUCTURALLY rather than as one of the breakdown interfaces on
+ * purpose: the same list ranks administrative rows (which additionally carry
+ * activeUsers / monthlyCredits / availableMonthlyCredits) and self-service
+ * report rows (which do not). Narrowing this to the administrative interface
+ * would force every self-service caller into a cast, and duplicating the
+ * component would fork the ramp and the share arithmetic.
+ */
+export type TokenUsageRankedRow = TokenUsageMetrics & {
+  /** Row identity; the literal "other" marks the folded tail. */
+  id: string;
+  label: string;
+};
+
 type Props = {
   /** Ranked rows, already ordered descending by the backend, "other" last. */
-  rows: TokenUsageAdminBreakdownInterface[];
+  rows: TokenUsageRankedRow[];
   metric: Metric;
-  /** Italian copy shown when there is nothing to rank. */
+  /** Copy shown when there is nothing to rank, already translated by the caller. */
   emptyLabel: string;
   /**
    * Whether `row.label` is an operation TYPE (vocabulary the consuming app
@@ -37,8 +53,9 @@ type Props = {
  */
 export function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperationTypes = false }: Props) {
   const t = useTranslations();
+  const { metricValue: formatValue, percent } = useUsageFormatters();
 
-  const renderLabel = (row: TokenUsageAdminBreakdownInterface): string => {
+  const renderLabel = (row: TokenUsageRankedRow): string => {
     if (row.id === "other") return t("token_usage.admin.other");
     if (!labelsAreOperationTypes) return row.label;
     return operationLabel(
@@ -83,13 +100,13 @@ export function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperati
               </div>
             </div>
             <span data-testid={`ranked-value-${row.id}`} className="text-right text-xs tabular-nums">
-              {formatMetricValue(value, metric)}
+              {formatValue(value, metric)}
             </span>
             <span
               data-testid={`ranked-share-${row.id}`}
               className="text-muted-foreground w-16 text-right text-xs tabular-nums"
             >
-              {formatPercent(share)}
+              {percent(share)}
             </span>
           </div>
         );

package/src/features/tokenusage/components/TokenUsageReportContainer.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { RoundPageContainer } from "../../../components";
+import { Card, CardContent, CardHeader, CardTitle } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import { useTokenUsageReport } from "../contexts/TokenUsageReportContext";
+import { TokenUsageRankedBar } from "./TokenUsageRankedBar";
+import { TokenUsageReportTiles, type TokenUsageBalances } from "./TokenUsageReportTiles";
+import { TokenUsageTimelineChart } from "./TokenUsageTimelineChart";
+
+type Props = {
+  /**
+   * The caller's own credit balances. Supplied by the host app, which reads them
+   * from its CurrentUserContext — the package has no access to that context.
+   */
+  balances?: TokenUsageBalances | null;
+};
+
+/**
+ * Page body for the self-service token-usage dashboard.
+ *
+ * Stateless by design — every value comes from useTokenUsageReport(). The filter
+ * bar is deliberately NOT here: it belongs to the page title bar, which
+ * RoundPageContainer fills from SharedContext, so the provider publishes it.
+ *
+ * The timeline and the ranked bars are the PACKAGE'S EXISTING components, used
+ * verbatim. They take the same six metric getters the report interfaces were
+ * given, which is what makes that reuse possible.
+ */
+export function TokenUsageReportContainer({ balances = null }: Props) {
+  const t = useTranslations();
+  const { summary, timeline, byOperation, byTarget, isLoading, error, targetPanelTitleKey } = useTokenUsageReport();
+
+  if (error) {
+    return (
+      <RoundPageContainer fullWidth forceHeader>
+        <div className="p-4">
+          <Card>
+            <CardContent>
+              <p className="text-destructive text-xs/relaxed">{error}</p>
+            </CardContent>
+          </Card>
+        </div>
+      </RoundPageContainer>
+    );
+  }
+
+  // Loading renders nothing in the body: the title bar (with the filter bar) is
+  // already mounted, so a spinner would only make the controls jump on arrival.
+  if (isLoading) return <RoundPageContainer fullWidth forceHeader />;
+
+  const emptyLabel = t("token_usage.report.no_data");
+  // The panel needs both a title the host app owns and rows to put under it.
+  const targetTitle = targetPanelTitleKey && byTarget.length > 0 ? t(targetPanelTitleKey) : undefined;
+
+  return (
+    <RoundPageContainer fullWidth forceHeader>
+      <div className="flex w-full flex-col gap-4 p-4">
+        <TokenUsageReportTiles summary={summary} metric="credits" balances={balances} />
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("token_usage.report.usage_over_time")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <TokenUsageTimelineChart rows={timeline} metric="credits" stackBy="type" />
+          </CardContent>
+        </Card>
+
+        <div className={cn("grid gap-4", targetTitle && "md:grid-cols-2")}>
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.report.by_operation")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              {/* Operation types are vocabulary the host app translates, unlike
+                  the target panel's rows, which carry entity NAMES. */}
+              <TokenUsageRankedBar
+                rows={byOperation}
+                metric="credits"
+                emptyLabel={emptyLabel}
+                labelsAreOperationTypes
+              />
+            </CardContent>
+          </Card>
+
+          {targetTitle && (
+            <Card>
+              <CardHeader>
+                <CardTitle>{targetTitle}</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <TokenUsageRankedBar rows={byTarget} metric="credits" emptyLabel={emptyLabel} />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+      </div>
+    </RoundPageContainer>
+  );
+}

package/src/features/tokenusage/components/TokenUsageReportFilterBar.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { DateRangeSelector } from "../../../components/forms/DateRangeSelector";
+
+type Props = {
+  /** Receives ONLY the keys that changed. */
+  onChange: (next: { from?: string; to?: string }) => void;
+};
+
+/**
+ * The single control row above the KPI tiles.
+ *
+ * Deliberately stateless: the control reports the keys it changed and the owning
+ * context re-fetches, which is what lets the page issue a single coordinated
+ * batch of requests instead of one per control.
+ *
+ * There is NO metric selector. A game master is billed in credits, so credits
+ * are the only unit this surface speaks: cost would leak platform margin (the
+ * controller rejects metric=cost outright) and a raw token count is an
+ * implementation detail nobody is charged for. There is no company selector
+ * either — a self-service caller has exactly one company.
+ */
+export function TokenUsageReportFilterBar({ onChange }: Props) {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <DateRangeSelector
+        onDateChange={(range) => {
+          if (!range?.from || !range?.to) return;
+          onChange({ from: range.from.toISOString(), to: range.to.toISOString() });
+        }}
+      />
+    </div>
+  );
+}

package/src/features/tokenusage/components/TokenUsageReportTiles.tsx

@@ -0,0 +1,161 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { Card, CardContent } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import type { TokenUsageReportSummaryInterface } from "../data/tokenusage-report-summary.interface";
+import type { ReportMetric } from "../data/tokenusage-report.types";
+import { useUsageFormatters } from "../lib/formatters";
+import { metricValue, percentageDelta, type TokenUsageMetrics } from "../lib/metrics";
+
+/**
+ * The caller's own credit position, as the host app reads it from its
+ * CurrentUserContext. The package has no access to that context, so the numbers
+ * arrive as a prop.
+ */
+export type TokenUsageBalances = {
+  monthlyCredits: number;
+  availableMonthlyCredits: number;
+  availableExtraCredits: number;
+};
+
+type Props = {
+  /** Two rows: window "current" and "previous". */
+  summary: TokenUsageReportSummaryInterface[];
+  metric: ReportMetric;
+  /** The caller's own balances, read from CurrentUserContext by the container. */
+  balances: TokenUsageBalances | null;
+};
+
+const ZERO: TokenUsageMetrics = { cost: 0, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 0 };
+
+/**
+ * The KPI header of the self-service token-usage page.
+ *
+ * One lead tile carries the number the page exists to answer — how much was
+ * spent in the period — with its delta against the equal-length preceding
+ * window. Three supporting tiles give it context: what is left this month, what
+ * extra sits behind that, and how many calls produced the spend.
+ *
+ * Credits are fractional. Customer-facing BALANCES are floored to whole credits
+ * (Math.max(0, Math.floor(v))) so nobody is told they have 715.4 of something
+ * indivisible; the percentage arithmetic behind the colour keeps the raw floats.
+ * Spend is NOT floored — it is a measurement, not a wallet.
+ */
+export function TokenUsageReportTiles({ summary, metric, balances }: Props) {
+  const t = useTranslations();
+  const { decimal, metricValue: formatValue } = useUsageFormatters();
+
+  const rowFor = (window: string): TokenUsageMetrics => summary.find((row) => row.window === window) ?? ZERO;
+
+  const current = rowFor("current");
+  const previous = rowFor("previous");
+
+  const monthlyPercentage =
+    balances && balances.monthlyCredits > 0 ? (balances.availableMonthlyCredits / balances.monthlyCredits) * 100 : 0;
+
+  // Three bands, not four: the previous implementation had a dead branch where
+  // >= 25 and >= 5 both returned the same class.
+  const monthlyColor =
+    monthlyPercentage > 75 ? "text-success" : monthlyPercentage >= 5 ? "text-warning" : "text-destructive";
+
+  const whole = (value: number) => decimal(Math.max(0, Math.floor(value)), 0);
+
+  return (
+    <div className="grid gap-3">
+      <Card data-testid="tile-used">
+        <CardContent className="grid gap-1">
+          <span className="text-muted-foreground text-xs">{t("token_usage.report.used_in_period")}</span>
+          <span className="text-primary text-xl font-semibold tabular-nums">
+            {formatValue(metricValue(current, metric), metric)}
+          </span>
+          <span className="flex items-center gap-1">
+            <Delta
+              testId="tile-used-delta"
+              delta={percentageDelta(metricValue(current, metric), metricValue(previous, metric))}
+              decimal={decimal}
+            />
+            <span className="text-muted-foreground text-xs">{t("token_usage.report.vs_previous")}</span>
+          </span>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-3 sm:grid-cols-3">
+        {balances && (
+          <Card data-testid="tile-monthly" size="sm">
+            <CardContent className="grid gap-1">
+              <span className="text-muted-foreground text-xs">{t("token_usage.report.monthly_left")}</span>
+              <span className="flex items-baseline gap-1">
+                <span data-testid="tile-monthly-value" className={cn("text-sm font-medium tabular-nums", monthlyColor)}>
+                  {whole(balances.availableMonthlyCredits)}
+                </span>
+                <span className="text-muted-foreground text-xs tabular-nums">/ {whole(balances.monthlyCredits)}</span>
+              </span>
+            </CardContent>
+          </Card>
+        )}
+
+        {balances && (
+          <Card data-testid="tile-extra" size="sm">
+            <CardContent className="grid gap-1">
+              <span className="text-muted-foreground text-xs">{t("token_usage.report.extra_credits")}</span>
+              <span className="text-sm font-medium tabular-nums">{whole(balances.availableExtraCredits)}</span>
+            </CardContent>
+          </Card>
+        )}
+
+        <Card data-testid="tile-calls" size="sm">
+          <CardContent className="grid gap-1">
+            <span className="text-muted-foreground text-xs">{t("token_usage.report.calls")}</span>
+            <span className="text-sm font-medium tabular-nums">{decimal(current.calls, 0)}</span>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The delta slot. An undefined delta means the previous window was zero: an em
+ * dash says "not comparable" where a percentage would say "infinite growth".
+ *
+ * `decimal` arrives as a prop rather than from the hook because this is a
+ * module-level function, not a component — calling a hook here would break the
+ * rules of hooks.
+ */
+function Delta({
+  testId,
+  delta,
+  decimal,
+}: {
+  testId: string;
+  delta: number | undefined;
+  decimal: (value: number, decimals: number) => string;
+}) {
+  if (delta === undefined) {
+    return (
+      <span data-testid={testId} className="text-muted-foreground text-xs">
+        —
+      </span>
+    );
+  }
+
+  const increased = delta >= 0;
+  const Icon = increased ? ArrowUpIcon : ArrowDownIcon;
+
+  // On a SPEND page more is not better, so the semantics are inverted relative
+  // to the administrative tiles: rising spend reads as a warning, not a success.
+  return (
+    <span
+      data-testid={testId}
+      className={cn(
+        "inline-flex items-center gap-0.5 text-xs tabular-nums",
+        increased ? "text-warning" : "text-success",
+      )}
+    >
+      <Icon aria-hidden className="size-3" />
+      {decimal(Math.abs(delta), 0)} %
+    </span>
+  );
+}