@carlonicora/nextjs-jsonapi 1.142.0 → 1.143.0

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

@@ -0,0 +1,138 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { DateRangeSelector } from "../../../components/forms/DateRangeSelector";
+import { Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import type { Granularity, Metric } from "../data/tokenusage-admin.types";
+
+/** Sentinel for "no company filter" — Base UI Select cannot hold `undefined`. */
+const ALL_COMPANIES = "all";
+
+type FilterState = {
+  from: string;
+  to: string;
+  granularity: Granularity;
+  companyId?: string;
+  metric: Metric;
+};
+
+type Props = FilterState & {
+  companies: { id: string; label: string }[];
+  /** Receives ONLY the keys that changed. */
+  onChange: (next: Partial<FilterState>) => void;
+};
+
+/**
+ * The single control row above the KPI tiles.
+ *
+ * It is deliberately stateless: every control reports the one key it changed and
+ * the owning context re-fetches. Keeping the whole filter state in one place is
+ * what lets the page issue a single coordinated batch of requests instead of one
+ * per control.
+ */
+export function TokenUsageAdminFilterBar({ granularity, companyId, metric, companies, onChange }: Props) {
+  const t = useTranslations();
+
+  const companyItems: Record<string, string> = {
+    [ALL_COMPANIES]: t("token_usage.admin.all_companies"),
+    ...Object.fromEntries(companies.map((company) => [company.id, company.label])),
+  };
+
+  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() });
+        }}
+      />
+
+      <Segmented
+        ariaLabel={t("token_usage.admin.granularity.label")}
+        value={granularity}
+        options={[
+          { value: "day", label: t("token_usage.admin.granularity.day") },
+          { value: "week", label: t("token_usage.admin.granularity.week") },
+          { value: "month", label: t("token_usage.admin.granularity.month") },
+        ]}
+        onSelect={(value) => onChange({ granularity: value })}
+      />
+
+      <Segmented
+        ariaLabel={t("token_usage.admin.metric.label")}
+        value={metric}
+        options={[
+          { value: "cost", label: t("token_usage.admin.metric.cost") },
+          { value: "credits", label: t("token_usage.admin.metric.credits") },
+          { value: "tokens", label: t("token_usage.admin.metric.tokens") },
+        ]}
+        onSelect={(value) => onChange({ metric: value })}
+      />
+
+      <Select
+        items={companyItems}
+        value={companyId ?? ALL_COMPANIES}
+        onValueChange={(value) =>
+          onChange({ companyId: !value || value === ALL_COMPANIES ? undefined : (value as string) })
+        }
+      >
+        <SelectTrigger className="w-56">
+          <SelectValue placeholder={t("token_usage.admin.all_companies")} />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={ALL_COMPANIES}>{t("token_usage.admin.all_companies")}</SelectItem>
+          {companies.map((company) => (
+            <SelectItem key={company.id} value={company.id}>
+              {company.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+
+/**
+ * A segmented control built from plain Buttons.
+ *
+ * The design system has no ToggleGroup primitive, and Base UI triggers may never
+ * wrap a Button, so the segmented look is composed from Buttons directly — the
+ * selected segment takes the solid variant, the rest stay ghosts.
+ */
+function Segmented<T extends string>({
+  ariaLabel,
+  value,
+  options,
+  onSelect,
+}: {
+  ariaLabel: string;
+  value: T;
+  options: { value: T; label: string }[];
+  onSelect: (value: T) => void;
+}) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className="border-border inline-flex items-center gap-0.5 rounded-md border p-0.5"
+    >
+      {options.map((option) => {
+        const selected = option.value === value;
+        return (
+          <Button
+            key={option.value}
+            type="button"
+            size="sm"
+            variant={selected ? "default" : "ghost"}
+            aria-pressed={selected}
+            className={cn(!selected && "text-muted-foreground")}
+            onClick={() => onSelect(option.value)}
+          >
+            {option.label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,177 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+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";
+
+type Props = {
+  /** The six summary rows: {customer, platform, total} × {current, previous}. */
+  summary: TokenUsageAdminSummaryInterface[];
+  metric: Metric;
+  /** True when a company filter is applied — platform spend is then meaningless. */
+  singleCustomerMode: boolean;
+};
+
+const ZERO: TokenUsageMetrics = { cost: 0, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 0 };
+
+/**
+ * The KPI header of the administrative token-usage page.
+ *
+ * Two lead tiles carry the cost centres — customer spend and platform spend —
+ * each with its delta against the equal-length preceding window. Three
+ * supporting tiles below carry the totals that give those two numbers context.
+ *
+ * The backend always returns both windows, which is why no tile has to branch on
+ * a missing row: an absent scope is simply zero-filled here.
+ */
+export function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Props) {
+  const t = useTranslations();
+
+  const rowFor = (scope: string, window: string): TokenUsageMetrics =>
+    summary.find((r) => r.scope === scope && r.window === window) ?? ZERO;
+
+  const customerCurrent = rowFor("customer", "current");
+  const customerPrevious = rowFor("customer", "previous");
+  const platformCurrent = rowFor("platform", "current");
+  const platformPrevious = rowFor("platform", "previous");
+  const totalCurrent = rowFor("total", "current");
+  const totalPrevious = rowFor("total", "previous");
+
+  const averagePerCall = totalCurrent.calls ? totalCurrent.cost / totalCurrent.calls : 0;
+  const cacheHit = cacheHitPercentage(totalCurrent.cached, totalCurrent.tokensIn);
+
+  return (
+    <div className="grid gap-3">
+      <div className={cn("grid gap-3", singleCustomerMode ? "sm:grid-cols-1" : "sm:grid-cols-2")}>
+        <LeadTile
+          testId="tile-customer"
+          label={t("token_usage.admin.customer_spend")}
+          value={formatMetricValue(metricValue(customerCurrent, metric), metric)}
+          delta={percentageDelta(metricValue(customerCurrent, metric), metricValue(customerPrevious, metric))}
+          previousLabel={t("token_usage.admin.vs_previous")}
+        />
+        {!singleCustomerMode && (
+          <LeadTile
+            testId="tile-platform"
+            label={t("token_usage.admin.platform_spend")}
+            value={formatMetricValue(metricValue(platformCurrent, metric), metric)}
+            delta={percentageDelta(metricValue(platformCurrent, metric), metricValue(platformPrevious, metric))}
+            previousLabel={t("token_usage.admin.vs_previous")}
+          />
+        )}
+      </div>
+
+      <div className="grid gap-3 sm:grid-cols-3">
+        <SupportingTile
+          testId="tile-total"
+          label={t("token_usage.admin.total_cost")}
+          value={formatMetricValue(metricValue(totalCurrent, metric), metric)}
+          delta={percentageDelta(metricValue(totalCurrent, metric), metricValue(totalPrevious, metric))}
+        />
+        <SupportingTile
+          testId="tile-avg-per-call"
+          label={t("token_usage.admin.avg_per_call")}
+          value={`€ ${formatDecimal(averagePerCall, 4)}`}
+        />
+        <SupportingTile
+          testId="tile-cache-hit"
+          label={t("token_usage.admin.cache_hit")}
+          value={formatPercent(cacheHit)}
+        />
+      </div>
+    </div>
+  );
+}
+
+function LeadTile({
+  testId,
+  label,
+  value,
+  delta,
+  previousLabel,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta: number | undefined;
+  previousLabel: string;
+}) {
+  return (
+    <Card data-testid={testId}>
+      <CardContent className="grid gap-1">
+        <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} />
+          <span className="text-muted-foreground text-xs">{previousLabel}</span>
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+function SupportingTile({
+  testId,
+  label,
+  value,
+  delta,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta?: number | undefined;
+}) {
+  return (
+    <Card data-testid={testId} size="sm">
+      <CardContent className="grid gap-1">
+        <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} />}
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * 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 }) {
+  if (delta === undefined) {
+    return (
+      <span data-testid={testId} className="text-muted-foreground text-xs">
+        —
+      </span>
+    );
+  }
+
+  const increased = delta >= 0;
+  const Icon = increased ? ArrowUpIcon : ArrowDownIcon;
+
+  return (
+    <span
+      data-testid={testId}
+      className={cn(
+        "inline-flex items-center gap-0.5 text-xs tabular-nums",
+        increased ? "text-success" : "text-destructive",
+      )}
+    >
+      <Icon aria-hidden className="size-3" />
+      {formatDecimal(Math.abs(delta), 0)} %
+    </span>
+  );
+}

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>
+  );
+}