@carlonicora/nextjs-jsonapi 1.141.3 → 1.143.0

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

@@ -0,0 +1,160 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo, useState } from "react";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../shadcnui";
+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";
+
+type Props = {
+  rows: TokenUsageAdminBreakdownInterface[];
+  metric: Metric;
+};
+
+type SortKey =
+  "label" | "sublabel" | "activeUsers" | "calls" | "tokensIn" | "tokensOut" | "cacheHit" | "cost" | "credits" | "share";
+
+type SortState = { key: SortKey; direction: "asc" | "desc" };
+
+/**
+ * The numeric detail behind the ranked bars: every row, every metric column.
+ *
+ * The bars answer "who is biggest"; this answers "why". Sorting is client-side
+ * because the whole ranked set — top-N plus the "other" rollup — is already in
+ * memory, so a round trip would buy nothing.
+ */
+export function TokenUsageBreakdownTable({ rows, metric }: Props) {
+  const t = useTranslations();
+  const [sort, setSort] = useState<SortState | undefined>(undefined);
+
+  // The company dimension is the only one that reports active users. Rather than
+  // render an empty column on user/operation breakdowns, the column disappears.
+  const showActiveUsers = rows.some((row) => row.activeUsers !== undefined);
+
+  const total = useMemo(() => rows.reduce((sum, row) => sum + metricValue(row, metric), 0), [rows, metric]);
+
+  const sortValue = (row: TokenUsageAdminBreakdownInterface, key: SortKey): number | string => {
+    switch (key) {
+      case "label":
+        return row.label ?? "";
+      case "sublabel":
+        return row.sublabel ?? "";
+      case "activeUsers":
+        return row.activeUsers ?? 0;
+      case "cacheHit":
+        return cacheHitPercentage(row.cached, row.tokensIn);
+      case "share":
+        return metricValue(row, metric);
+      default:
+        return row[key];
+    }
+  };
+
+  const sortedRows = useMemo(() => {
+    if (!sort) return rows;
+
+    const factor = sort.direction === "desc" ? -1 : 1;
+    return [...rows].sort((a, b) => {
+      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 (left - right) * factor;
+    });
+  }, [rows, sort, metric]);
+
+  // First click on a column sorts descending: on a spend table the interesting
+  // end of every numeric column is the top one.
+  const toggleSort = (key: SortKey) =>
+    setSort((current) =>
+      current?.key === key
+        ? { key, direction: current.direction === "desc" ? "asc" : "desc" }
+        : { key, direction: "desc" },
+    );
+
+  const columns: { key: SortKey; label: string; numeric: boolean }[] = [
+    { key: "label", label: t("token_usage.admin.columns.label"), numeric: false },
+    { key: "sublabel", label: t("token_usage.admin.columns.sublabel"), numeric: false },
+    ...(showActiveUsers
+      ? [{ key: "activeUsers" as const, label: t("token_usage.admin.columns.active_users"), numeric: true }]
+      : []),
+    { key: "calls", label: t("token_usage.admin.columns.calls"), numeric: true },
+    { key: "tokensIn", label: t("token_usage.admin.columns.tokens_in"), numeric: true },
+    { key: "tokensOut", label: t("token_usage.admin.columns.tokens_out"), numeric: true },
+    // Reuses the tile's key rather than minting a column-specific one — same
+    // metric, same words.
+    { key: "cacheHit", label: t("token_usage.admin.cache_hit"), numeric: true },
+    { key: "cost", label: t("token_usage.admin.columns.cost"), numeric: true },
+    { key: "credits", label: t("token_usage.admin.columns.credits"), numeric: true },
+    { key: "share", label: t("token_usage.admin.columns.share"), numeric: true },
+  ];
+
+  return (
+    // The package's <Table> wraps itself in an `overflow-x-clip` container, which
+    // would swallow the overflow before this scroller ever saw it — hence the
+    // child override. Wide metric tables must scroll, never widen the page.
+    <div className="overflow-x-auto [&_[data-slot=table-container]]:overflow-x-visible">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            {columns.map((column) => (
+              <TableHead key={column.key} className={cn(column.numeric && "text-right")}>
+                <button
+                  type="button"
+                  onClick={() => toggleSort(column.key)}
+                  className={cn(
+                    "hover:text-primary inline-flex items-center gap-1 text-xs font-medium",
+                    column.numeric && "flex-row-reverse",
+                  )}
+                >
+                  {column.label}
+                  {sort?.key === column.key &&
+                    (sort.direction === "desc" ? (
+                      <ArrowDownIcon aria-hidden className="size-3" />
+                    ) : (
+                      <ArrowUpIcon aria-hidden className="size-3" />
+                    ))}
+                </button>
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {sortedRows.map((row) => {
+            const value = metricValue(row, metric);
+            const share = total > 0 ? (value / total) * 100 : 0;
+
+            return (
+              <TableRow key={row.id} data-testid={`breakdown-row-${row.id}`}>
+                <TableCell className="text-xs">
+                  {row.id === "other" ? t("token_usage.admin.other") : row.label}
+                </TableCell>
+                <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)}
+                  </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">
+                  {formatPercent(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>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

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

@@ -0,0 +1,99 @@
+"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 { operationLabel } from "../lib/operation-label";
+import { SEQUENTIAL_RAMP } from "../lib/palette";
+
+type Props = {
+  /** Ranked rows, already ordered descending by the backend, "other" last. */
+  rows: TokenUsageAdminBreakdownInterface[];
+  metric: Metric;
+  /** Italian copy shown when there is nothing to rank. */
+  emptyLabel: string;
+  /**
+   * Whether `row.label` is an operation TYPE (vocabulary the consuming app
+   * translates) rather than an entity NAME (data, rendered verbatim).
+   *
+   * Company and user rows carry names — translating them would be nonsense — so
+   * this defaults to false and only the platform-by-operation panel opts in.
+   */
+  labelsAreOperationTypes?: boolean;
+};
+
+/**
+ * A ranked horizontal bar list — "who spent the most".
+ *
+ * This does a MAGNITUDE job, not a categorical one, so colour comes from a
+ * single sequential ramp indexed by RANK POSITION, never from a categorical
+ * palette keyed by entity. That is deliberate: a filter change reorders the
+ * rows, and rank-indexed colour simply re-shades them instead of repainting a
+ * company into another company's identity hue.
+ *
+ * There is exactly one series, so there is no legend: every bar is
+ * direct-labelled with its value and its share of the total.
+ */
+export function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperationTypes = false }: Props) {
+  const t = useTranslations();
+
+  const renderLabel = (row: TokenUsageAdminBreakdownInterface): string => {
+    if (row.id === "other") return t("token_usage.admin.other");
+    if (!labelsAreOperationTypes) return row.label;
+    return operationLabel(
+      row.label,
+      (key) => t(key),
+      (key) => t.has(key),
+    );
+  };
+
+  if (rows.length === 0) {
+    return <p className="text-muted-foreground py-6 text-center text-sm">{emptyLabel}</p>;
+  }
+
+  const values = rows.map((row) => metricValue(row, metric));
+  const total = values.reduce((sum, value) => sum + value, 0);
+  const max = Math.max(...values, 0);
+
+  return (
+    <div className="grid gap-0.5">
+      {rows.map((row, index) => {
+        const value = values[index];
+        // The backend folds everything past the limit into one "other" row; it
+        // gets the most recessive ramp step so it never out-shouts a real entity.
+        const isOther = row.id === "other";
+        const step = isOther ? SEQUENTIAL_RAMP.length - 1 : Math.min(index, SEQUENTIAL_RAMP.length - 1);
+        const width = max > 0 ? (value / max) * 100 : 0;
+        // Shares are taken against the supplied rows, which already include
+        // "other" — so the column sums to 100 %.
+        const share = total > 0 ? (value / total) * 100 : 0;
+
+        return (
+          <div key={row.id} className="grid grid-cols-[minmax(0,1fr)_auto_auto] items-center gap-x-3 gap-y-0.5 py-0.5">
+            <div className="grid min-w-0 gap-0.5">
+              <span className="text-muted-foreground truncate text-xs">{renderLabel(row)}</span>
+              <div className="bg-muted h-2 w-full overflow-hidden rounded-r-[4px]">
+                <div
+                  data-testid={`ranked-fill-${row.id}`}
+                  data-ramp-step={String(step)}
+                  className="h-full rounded-r-[4px]"
+                  style={{ width: `${width}%`, backgroundColor: SEQUENTIAL_RAMP[step] }}
+                />
+              </div>
+            </div>
+            <span data-testid={`ranked-value-${row.id}`} className="text-right text-xs tabular-nums">
+              {formatMetricValue(value, metric)}
+            </span>
+            <span
+              data-testid={`ranked-share-${row.id}`}
+              className="text-muted-foreground w-16 text-right text-xs tabular-nums"
+            >
+              {formatPercent(share)}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,225 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from "recharts";
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../../../shadcnui";
+import { TokenUsageAdminTimelineInterface } from "../data/tokenusage-admin-timeline.interface";
+import { Metric, StackBy } from "../data/tokenusage-admin.types";
+import { operationLabel } from "../lib/operation-label";
+import { CATEGORICAL_CEILING, ChartMode, OTHER_COLOR, seriesColor } from "../lib/palette";
+
+/** The rollup series every series past the colour ceiling folds into. */
+const OTHER_SERIES = "other";
+
+type TokenUsageTimelineChartProps = {
+  rows: TokenUsageAdminTimelineInterface[];
+  metric: Metric;
+  stackBy: StackBy;
+  className?: string;
+};
+
+type TimelineBucket = { bucket: string } & Record<string, number | string>;
+
+/**
+ * The bucket key, derived with UTC getters.
+ *
+ * The backend field is `type: "date"` — a calendar day with no time — and the
+ * model parses the `YYYY-MM-DD` wire value with `new Date(...)`, which lands on
+ * UTC midnight. Reading it back with local getters would shift the bucket a day
+ * early west of UTC, so the key (and every label built from it) stays in UTC.
+ */
+const bucketKey = (date: Date): string => {
+  const y = date.getUTCFullYear();
+  const m = `${date.getUTCMonth() + 1}`.padStart(2, "0");
+  const d = `${date.getUTCDate()}`.padStart(2, "0");
+  return `${y}-${m}-${d}`;
+};
+
+const metricValue = (row: TokenUsageAdminTimelineInterface, metric: Metric): number => {
+  if (metric === "cost") return row.cost;
+  if (metric === "credits") return row.credits;
+  return row.tokensIn + row.tokensOut;
+};
+
+/**
+ * The granularity the data was bucketed at, inferred from the spacing between
+ * consecutive buckets. The backend chooses the granularity and the rows carry
+ * the consequence, so the axis reads it off the data rather than taking a prop
+ * that could disagree with what was actually fetched.
+ */
+const inferGranularity = (buckets: string[]): "day" | "week" | "month" => {
+  if (buckets.length < 2) return "day";
+
+  const dayMs = 24 * 60 * 60 * 1000;
+  let smallestGap = Number.POSITIVE_INFINITY;
+  for (let i = 1; i < buckets.length; i += 1) {
+    const gap = (Date.parse(buckets[i]) - Date.parse(buckets[i - 1])) / dayMs;
+    if (gap > 0 && gap < smallestGap) smallestGap = gap;
+  }
+
+  if (smallestGap >= 28) return "month";
+  if (smallestGap >= 7) return "week";
+  return "day";
+};
+
+const bucketFormatter = (granularity: "day" | "week" | "month"): Intl.DateTimeFormat =>
+  granularity === "month"
+    ? new Intl.DateTimeFormat("it-IT", { month: "short", year: "numeric", timeZone: "UTC" })
+    : new Intl.DateTimeFormat("it-IT", { day: "numeric", month: "short", timeZone: "UTC" });
+
+const compactNumber = new Intl.NumberFormat("it-IT", { notation: "compact", maximumFractionDigits: 1 });
+
+/**
+ * Usage over time as a stacked bar chart.
+ *
+ * Colour does an IDENTITY job here — each stacked segment is a series, not a
+ * magnitude — so it draws the fixed categorical order from `../lib/palette` and
+ * never generates or cycles a hue: series past the ceiling are summed into a
+ * single "other" segment painted in the palette's neutral.
+ *
+ * The palette's light-mode validator run carries a sub-3:1 contrast WARN on
+ * three slots, which obliges a relief channel. That is why the legend and the
+ * value-carrying tooltip below are not optional decoration: they are what makes
+ * the low-contrast fills readable.
+ */
+export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: TokenUsageTimelineChartProps) {
+  const t = useTranslations();
+  const { resolvedTheme } = useTheme();
+  const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
+
+  const { chartData, seriesKeys } = useMemo(() => {
+    if (rows.length === 0) return { chartData: [] as TimelineBucket[], seriesKeys: [] as string[] };
+
+    // Totals per raw series decide who keeps an identity colour: the biggest
+    // seven do, everything else is summed into "other". Ranking by total (not by
+    // first appearance) keeps the assignment stable while a filter changes which
+    // series are present.
+    const totals = new Map<string, number>();
+    for (const row of rows) totals.set(row.series, (totals.get(row.series) ?? 0) + metricValue(row, metric));
+
+    const ranked = [...totals.entries()].sort((a, b) => b[1] - a[1]).map(([series]) => series);
+    const named = ranked.slice(0, CATEGORICAL_CEILING);
+    const folded = new Set(ranked.slice(CATEGORICAL_CEILING));
+
+    const keys = folded.size > 0 ? [...named, OTHER_SERIES] : named;
+
+    const byBucket = new Map<string, TimelineBucket>();
+    for (const row of rows) {
+      const key = bucketKey(row.bucket);
+      let entry = byBucket.get(key);
+      if (!entry) {
+        entry = { bucket: key };
+        for (const series of keys) entry[series] = 0;
+        byBucket.set(key, entry);
+      }
+      const series = folded.has(row.series) ? OTHER_SERIES : row.series;
+      entry[series] = (entry[series] as number) + metricValue(row, metric);
+    }
+
+    return {
+      chartData: [...byBucket.values()].sort((a, b) => a.bucket.localeCompare(b.bucket)),
+      seriesKeys: keys,
+    };
+  }, [rows, metric]);
+
+  const seriesLabel = (series: string): string => {
+    if (series === OTHER_SERIES) {
+      const key = "token_usage.series.other";
+      return t.has(key) ? t(key) : "Altro";
+    }
+    // Stacking by company makes the series a company NAME, which is data, not
+    // vocabulary — it is never looked up. Scope and type keys are vocabulary the
+    // consuming app supplies, with the raw key as the fallback.
+    if (stackBy === "company") return series;
+    return operationLabel(
+      series,
+      (key) => t(key),
+      (key) => t.has(key),
+    );
+  };
+
+  const chartConfig = useMemo(
+    () => Object.fromEntries(seriesKeys.map((series) => [series, { label: seriesLabel(series) }])) as ChartConfig,
+    [seriesKeys, stackBy],
+  );
+
+  if (chartData.length === 0) {
+    const key = "token_usage.timeline.empty";
+    return (
+      <p className={className ? `text-muted-foreground text-sm ${className}` : "text-muted-foreground text-sm"}>
+        {t.has(key) ? t(key) : "Nessun dato nel periodo selezionato"}
+      </p>
+    );
+  }
+
+  const granularity = inferGranularity(chartData.map((entry) => entry.bucket));
+  const formatBucket = bucketFormatter(granularity);
+  const seriesColorFor = (series: string, index: number) =>
+    series === OTHER_SERIES ? OTHER_COLOR : seriesColor(index, mode);
+
+  return (
+    <div className={className}>
+      {/* The pivot, exposed for assertions and for screen readers that would
+          otherwise get nothing from the SVG. */}
+      <span className="sr-only" data-testid="timeline-data">
+        {JSON.stringify(chartData)}
+      </span>
+      <span className="sr-only" data-testid="timeline-series">
+        {JSON.stringify(seriesKeys)}
+      </span>
+
+      <ChartContainer config={chartConfig} className="aspect-auto h-72 w-full">
+        <BarChart accessibilityLayer data={chartData} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} />
+          <XAxis
+            dataKey="bucket"
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            minTickGap={16}
+            tickFormatter={(value: string) => formatBucket.format(new Date(`${value}T00:00:00.000Z`))}
+          />
+          <YAxis
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            width={48}
+            tickFormatter={(value: number) => compactNumber.format(value)}
+          />
+          <ChartTooltip
+            content={
+              <ChartTooltipContent
+                labelFormatter={(value) => formatBucket.format(new Date(`${String(value)}T00:00:00.000Z`))}
+              />
+            }
+          />
+          {seriesKeys.length >= 2 ? <ChartLegend content={<ChartLegendContent />} /> : null}
+          {seriesKeys.map((series, index) => (
+            <Bar
+              key={series}
+              dataKey={series}
+              stackId="usage"
+              maxBarSize={28}
+              fill={seriesColorFor(series, index)}
+              // A 2px stroke in the surface colour is the gap between stacked
+              // segments and between neighbouring bars — the palette's own
+              // secondary-encoding channel, not a border.
+              stroke="var(--background)"
+              strokeWidth={2}
+              radius={index === seriesKeys.length - 1 ? [4, 4, 0, 0] : 0}
+            />
+          ))}
+        </BarChart>
+      </ChartContainer>
+    </div>
+  );
+}

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

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageAdminTiles } from "../TokenUsageAdminTiles";
+
+const row = (scope: string, window: string, cost: number, calls = 1) =>
+  ({ id: `${scope}|${window}`, scope, window, cost, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls }) as any;
+
+const summary = [
+  row("customer", "current", 9.46, 2956),
+  row("platform", "current", 9.47, 7681),
+  row("total", "current", 18.93, 10637),
+  row("customer", "previous", 8.0, 2000),
+  row("platform", "previous", 10.0, 8000),
+  row("total", "previous", 18.0, 10000),
+];
+
+describe("TokenUsageAdminTiles", () => {
+  it("shows both cost centres with their deltas against the previous window", () => {
+    render(<TokenUsageAdminTiles summary={summary} metric="cost" singleCustomerMode={false} />);
+
+    expect(screen.getByTestId("tile-customer")).toHaveTextContent("9,46");
+    expect(screen.getByTestId("tile-platform")).toHaveTextContent("9,47");
+    // customer 9.46 vs 8.00 => +18%
+    expect(screen.getByTestId("tile-customer-delta")).toHaveTextContent("18");
+    // platform 9.47 vs 10.00 => -5%
+    expect(screen.getByTestId("tile-platform-delta")).toHaveTextContent("5");
+  });
+
+  it("hides the platform tile in single-customer mode", () => {
+    render(<TokenUsageAdminTiles summary={summary} metric="cost" singleCustomerMode />);
+
+    expect(screen.getByTestId("tile-customer")).toBeInTheDocument();
+    expect(screen.queryByTestId("tile-platform")).not.toBeInTheDocument();
+  });
+
+  it("suppresses the delta rather than showing Infinity when the previous window is zero", () => {
+    const zeroPrev = summary.map((r) => (r.window === "previous" ? { ...r, cost: 0 } : r));
+    render(<TokenUsageAdminTiles summary={zeroPrev as any} metric="cost" singleCustomerMode={false} />);
+
+    expect(screen.getByTestId("tile-customer-delta")).toHaveTextContent("—");
+  });
+});

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

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageRankedBar } from "../TokenUsageRankedBar";
+
+const row = (id: string, label: string, cost: number) =>
+  ({ id, label, cost, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 1 }) as any;
+
+describe("TokenUsageRankedBar", () => {
+  it("direct-labels each row with its value and its share of the total", () => {
+    render(
+      <TokenUsageRankedBar
+        rows={[row("a", "Studio Rossi", 6), row("b", "Studio Bianchi", 4)]}
+        metric="cost"
+        emptyLabel="nessun dato"
+      />,
+    );
+
+    expect(screen.getByTestId("ranked-value-a")).toHaveTextContent("6,00");
+    expect(screen.getByTestId("ranked-share-a")).toHaveTextContent("60");
+    expect(screen.getByTestId("ranked-share-b")).toHaveTextContent("40");
+  });
+
+  it("renders the empty label when there are no rows", () => {
+    render(<TokenUsageRankedBar rows={[]} metric="cost" emptyLabel="nessun dato" />);
+    expect(screen.getByText("nessun dato")).toBeInTheDocument();
+  });
+
+  it("assigns colour by rank position from one ramp, so no two rows share an identity hue by accident", () => {
+    render(
+      <TokenUsageRankedBar
+        rows={[row("a", "A", 3), row("b", "B", 2), row("c", "C", 1)]}
+        metric="cost"
+        emptyLabel="nessun dato"
+      />,
+    );
+
+    const colours = ["a", "b", "c"].map((id) => screen.getByTestId(`ranked-fill-${id}`).getAttribute("data-ramp-step"));
+    expect(new Set(colours).size).toBe(3);
+    expect(colours).toEqual(["0", "1", "2"]);
+  });
+});

package/src/features/tokenusage/components/__tests__/TokenUsageTimelineChart.spec.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageTimelineChart } from "../TokenUsageTimelineChart";
+
+const row = (bucket: string, series: string, cost: number) =>
+  ({
+    id: `${bucket}|${series}`,
+    bucket: new Date(bucket),
+    series,
+    cost,
+    credits: 0,
+    tokensIn: 0,
+    tokensOut: 0,
+    cached: 0,
+    calls: 1,
+  }) as any;
+
+describe("TokenUsageTimelineChart", () => {
+  it("pivots flat rows into one entry per bucket with a key per series", () => {
+    render(
+      <TokenUsageTimelineChart
+        rows={[row("2026-08-01", "customer", 1), row("2026-08-01", "platform", 2), row("2026-08-02", "customer", 3)]}
+        metric="cost"
+        stackBy="scope"
+      />,
+    );
+
+    const data = JSON.parse(screen.getByTestId("timeline-data").textContent!);
+    expect(data).toHaveLength(2);
+    expect(data[0]).toMatchObject({ customer: 1, platform: 2 });
+    expect(data[1]).toMatchObject({ customer: 3 });
+  });
+
+  it("folds series beyond the 7-colour ceiling into a single 'other' series", () => {
+    const rows = Array.from({ length: 10 }, (_, i) => row("2026-08-01", `type${i}`, 10 - i));
+    render(<TokenUsageTimelineChart rows={rows} metric="cost" stackBy="type" />);
+
+    const series = JSON.parse(screen.getByTestId("timeline-series").textContent!);
+    expect(series).toHaveLength(8);
+    expect(series[7]).toBe("other");
+  });
+
+  it("renders the empty state without a chart when there are no rows", () => {
+    render(<TokenUsageTimelineChart rows={[]} metric="cost" stackBy="scope" />);
+    expect(screen.queryByTestId("timeline-data")).not.toBeInTheDocument();
+  });
+});