@carlonicora/nextjs-jsonapi 2.3.0 → 2.5.0

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

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

@@ -14,6 +14,7 @@ import {
 } from "../../../shadcnui";
 import { TokenUsageAdminTimelineInterface } from "../data/tokenusage-admin-timeline.interface";
 import { Metric, StackBy } from "../data/tokenusage-admin.types";
+import { useUsageFormatters } from "../lib/formatters";
 import { operationLabel } from "../lib/operation-label";
 import { CATEGORICAL_CEILING, ChartMode, OTHER_COLOR, seriesColor } from "../lib/palette";
 
@@ -71,13 +72,6 @@ const inferGranularity = (buckets: string[]): "day" | "week" | "month" => {
   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.
  *
@@ -93,6 +87,7 @@ const compactNumber = new Intl.NumberFormat("it-IT", { notation: "compact", maxi
  */
 export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: TokenUsageTimelineChartProps) {
   const t = useTranslations();
+  const { compact, bucketDate, metricValue: formatValue } = useUsageFormatters();
   const { resolvedTheme } = useTheme();
   const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
 
@@ -134,7 +129,7 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
   const seriesLabel = (series: string): string => {
     if (series === OTHER_SERIES) {
       const key = "token_usage.series.other";
-      return t.has(key) ? t(key) : "Altro";
+      return t.has(key) ? t(key) : "Other";
     }
     // 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
@@ -156,13 +151,12 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
     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"}
+        {t.has(key) ? t(key) : "No data in the selected period"}
       </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);
 
@@ -186,19 +180,27 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
             axisLine={false}
             tickMargin={8}
             minTickGap={16}
-            tickFormatter={(value: string) => formatBucket.format(new Date(`${value}T00:00:00.000Z`))}
+            tickFormatter={(value: string) => bucketDate(value, granularity)}
           />
           <YAxis
             tickLine={false}
             axisLine={false}
             tickMargin={8}
             width={48}
-            tickFormatter={(value: number) => compactNumber.format(value)}
+            tickFormatter={(value: number) => compact(value)}
           />
           <ChartTooltip
             content={
               <ChartTooltipContent
-                labelFormatter={(value) => formatBucket.format(new Date(`${String(value)}T00:00:00.000Z`))}
+                labelFormatter={(value) => bucketDate(String(value), granularity)}
+                // Without this the tooltip falls back to toLocaleString() and
+                // prints the raw stored precision (credits carry 4 decimals),
+                // which disagrees with every other number on the page.
+                valueFormatter={(value) => formatValue(Number(value), metric)}
+                // Every series appears in every bucket's payload, so a day with
+                // one active operation would otherwise list the whole vocabulary
+                // as zeros and bury the one number that matters.
+                hideZeroValues
               />
             }
           />

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

@@ -18,8 +18,10 @@ 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");
+    // The suite mocks useLocale() as "en", and formatting now honours the
+    // locale instead of a hard-coded it-IT, so the separator is a point.
+    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%

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

@@ -15,7 +15,9 @@ describe("TokenUsageRankedBar", () => {
       />,
     );
 
-    expect(screen.getByTestId("ranked-value-a")).toHaveTextContent("6,00");
+    // The suite mocks useLocale() as "en", and formatting now honours the
+    // locale instead of a hard-coded it-IT, so the separator is a point.
+    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");
   });

package/src/features/tokenusage/contexts/TokenUsageAdminContext.tsx

@@ -13,8 +13,8 @@ import type { Granularity, Metric, StackBy } from "../data/tokenusage-admin.type
 import { TokenUsageAdminService } from "../data/TokenUsageAdminService";
 
 /**
- * Route the breadcrumb links back to. The page itself lives in the consuming
- * app (a360ai mounts it at `/administration/token-usage`); the constant is here
+ * Default route the breadcrumb links back to. A host app that mounts the page
+ * elsewhere overrides it with the `pageUrl` prop — the constant stays here
  * because the breadcrumb is built by this provider, not by the app.
  */
 const TOKEN_USAGE_ADMIN_PAGE_URL = "/administration/token-usage";
@@ -72,6 +72,8 @@ type TokenUsageAdminProviderProps = {
   initialTo?: string;
   /** Rows per ranked panel. Defaults to 10. */
   topN?: number;
+  /** Route the breadcrumb links back to. */
+  pageUrl?: string;
 };
 
 /**
@@ -89,6 +91,7 @@ export const TokenUsageAdminProvider = ({
   initialFrom,
   initialTo,
   topN = DEFAULT_TOP_N,
+  pageUrl = TOKEN_USAGE_ADMIN_PAGE_URL,
 }: TokenUsageAdminProviderProps) => {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
@@ -185,7 +188,7 @@ export const TokenUsageAdminProvider = ({
   const breadcrumb = (): BreadcrumbItemData[] => [
     {
       name: t("token_usage.admin.title"),
-      href: generateUrl({ page: TOKEN_USAGE_ADMIN_PAGE_URL }),
+      href: generateUrl({ page: pageUrl }),
     },
   ];