@carlonicora/nextjs-jsonapi 2.3.0 → 2.5.0

package/src/features/tokenusage/index.ts

@@ -28,3 +28,21 @@ export {
 } from "./tokenusage-admin.module";
 
 export { TOKEN_USAGE_ADMIN_I18N_KEYS } from "./i18n-keys";
+
+// Self-service ("report") token-usage dashboard — the company-scoped mirror of
+// the administrative trio above, reusing its chart components verbatim.
+
+export { TokenUsageReportProvider, useTokenUsageReport } from "./contexts/TokenUsageReportContext";
+export type { TokenUsageReportContextType, TokenUsageReportFilterState } from "./contexts/TokenUsageReportContext";
+
+export { TokenUsageReportContainer } from "./components/TokenUsageReportContainer";
+export { TokenUsageReportFilterBar } from "./components/TokenUsageReportFilterBar";
+export { TokenUsageReportTiles } from "./components/TokenUsageReportTiles";
+export type { TokenUsageBalances } from "./components/TokenUsageReportTiles";
+
+export { tokenUsageModules } from "./tokenusage.modules";
+export { configureTokenUsage, getTokenUsageCurrency } from "./lib/config";
+export { createUsageFormatters, useUsageFormatters } from "./lib/formatters";
+export type { UsageFormatters } from "./lib/formatters";
+
+export { TOKEN_USAGE_REPORT_I18N_KEYS } from "./i18n-keys";

package/src/features/tokenusage/lib/config.ts

@@ -0,0 +1,22 @@
+/**
+ * The currency the token-usage surfaces render monetary values in.
+ *
+ * The package cannot infer this: the figures come from whatever per-million-token
+ * rates the consuming app configured, and those are denominated in whatever
+ * currency that app buys inference in — EUR for one consumer, USD for another
+ * whose rates are OpenRouter list prices. So the app declares it once at
+ * bootstrap, next to configureJsonApi().
+ *
+ * EUR is the default purely for backward compatibility: the previous
+ * implementation hard-coded a euro sign, so an app that never calls this keeps
+ * rendering exactly what it rendered before.
+ */
+let currency = "EUR";
+
+export function configureTokenUsage(config: { currency: string }): void {
+  currency = config.currency;
+}
+
+export function getTokenUsageCurrency(): string {
+  return currency;
+}

package/src/features/tokenusage/lib/formatters.ts

@@ -0,0 +1,100 @@
+"use client";
+
+import { useLocale } from "next-intl";
+import { useMemo } from "react";
+import type { Metric } from "../data/tokenusage-admin.types";
+import { getTokenUsageCurrency } from "./config";
+
+export type UsageFormatters = {
+  /** Locale-aware fixed-decimal number, e.g. 9.46 → "9,46" in it-IT. */
+  decimal(value: number, decimals: number): string;
+  /** Currency for cost, 2 decimals for credits, whole numbers for tokens. */
+  metricValue(value: number, metric: Metric): string;
+  /** Currency with an explicit decimal count — the per-call tile needs 4. */
+  currency(value: number, decimals: number): string;
+  /** Percentage with one decimal by default, e.g. 60 → "60,0 %" in it-IT. */
+  percent(value: number, decimals?: number): string;
+  /** Compact notation for axis ticks, e.g. 1500000 → "1,5 Mln" in it-IT. */
+  compact(value: number): string;
+  /** A "YYYY-MM-DD" bucket key rendered as an axis or tooltip label, in UTC. */
+  bucketDate(iso: string, granularity: "day" | "week" | "month"): string;
+  /** Locale collation for client-side table sorting. */
+  compare(a: string, b: string): number;
+};
+
+/**
+ * Builds every formatter the token-usage surfaces need, for one locale and one
+ * currency.
+ *
+ * A pure factory on purpose: it takes no React context, so the arithmetic and
+ * the formatting are unit-testable without rendering, and a server component or
+ * a test can construct a set for an arbitrary locale.
+ *
+ * The currency symbol is placed with a space rather than through
+ * `style: "currency"`, which is what the previous hard-coded implementation
+ * rendered ("€ 9,46"). Keeping that shape means a consuming app on EUR sees
+ * byte-identical output after this refactor.
+ *
+ * `bucketDate` formats in UTC, always. The wire value is a `type: "date"` — a
+ * calendar day — parsed to UTC midnight; reading it back with local getters
+ * would shift the label a day early west of UTC.
+ */
+export function createUsageFormatters(locale: string, currency: string): UsageFormatters {
+  const symbol =
+    new Intl.NumberFormat(locale, { style: "currency", currency, currencyDisplay: "narrowSymbol" })
+      .formatToParts(0)
+      .find((part) => part.type === "currency")?.value ?? currency;
+
+  const decimal = (value: number, decimals: number): string =>
+    value.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+
+  const dayFormat = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", timeZone: "UTC" });
+  const monthFormat = new Intl.DateTimeFormat(locale, { month: "short", year: "numeric", timeZone: "UTC" });
+  const compactFormat = new Intl.NumberFormat(locale, { notation: "compact", maximumFractionDigits: 1 });
+  const collator = new Intl.Collator(locale);
+
+  return {
+    decimal,
+
+    metricValue(value, metric) {
+      if (metric === "cost") return `${symbol} ${decimal(value, 2)}`;
+      // Credits are stored to 4 decimals (round4(cost / creditCost)), but that
+      // precision is noise to a reader comparing rows: one decimal is enough to
+      // separate two values and keeps the columns narrow enough to scan.
+      if (metric === "credits") return decimal(value, 1);
+      return decimal(value, 0);
+    },
+
+    currency(value, decimals) {
+      return `${symbol} ${decimal(value, decimals)}`;
+    },
+
+    percent(value, decimals = 1) {
+      return `${decimal(value, decimals)} %`;
+    },
+
+    compact(value) {
+      return compactFormat.format(value);
+    },
+
+    bucketDate(iso, granularity) {
+      const date = new Date(`${iso}T00:00:00.000Z`);
+      return granularity === "month" ? monthFormat.format(date) : dayFormat.format(date);
+    },
+
+    compare(a, b) {
+      return collator.compare(a, b);
+    },
+  };
+}
+
+/**
+ * The formatter set for the current request's locale and the app's configured
+ * currency. Memoised on both, so the Intl objects are built once per locale
+ * rather than on every render.
+ */
+export function useUsageFormatters(): UsageFormatters {
+  const locale = useLocale();
+  const currency = getTokenUsageCurrency();
+  return useMemo(() => createUsageFormatters(locale, currency), [locale, currency]);
+}

package/src/features/tokenusage/lib/metrics.ts

@@ -1,5 +1,13 @@
 import type { Metric } from "../data/tokenusage-admin.types";
 
+/**
+ * Locale-free arithmetic for the token-usage surfaces.
+ *
+ * Everything that turns a number into a STRING lives in `./formatters` instead,
+ * because it depends on the request's locale and the app's configured currency.
+ * This file stays pure arithmetic so it needs neither.
+ */
+
 /**
  * The metric field set every admin token-usage resource carries. Declared
  * structurally so it accepts the summary, timeline and breakdown interfaces
@@ -14,9 +22,6 @@ export type TokenUsageMetrics = {
   calls: number;
 };
 
-/** UI copy is Italian, so every figure is formatted with the Italian locale. */
-const LOCALE = "it-IT";
-
 /** Reads the single number a row contributes for the currently selected metric. */
 export function metricValue(row: TokenUsageMetrics, metric: Metric): number {
   if (metric === "cost") return row.cost;
@@ -24,29 +29,6 @@ export function metricValue(row: TokenUsageMetrics, metric: Metric): number {
   return row.tokensIn + row.tokensOut;
 }
 
-/** Locale-aware fixed-decimal number, e.g. 9.46 → "9,46". */
-export function formatDecimal(value: number, decimals: number): string {
-  return value.toLocaleString(LOCALE, {
-    minimumFractionDigits: decimals,
-    maximumFractionDigits: decimals,
-  });
-}
-
-/**
- * Formats a metric value for display: euros carry a "€ " prefix and 2 decimals,
- * credits 2 decimals, token counts are whole numbers.
- */
-export function formatMetricValue(value: number, metric: Metric): string {
-  if (metric === "cost") return `€ ${formatDecimal(value, 2)}`;
-  if (metric === "credits") return formatDecimal(value, 2);
-  return formatDecimal(value, 0);
-}
-
-/** Percentage with one decimal, e.g. 60 → "60,0 %". */
-export function formatPercent(value: number, decimals = 1): string {
-  return `${formatDecimal(value, decimals)} %`;
-}
-
 /**
  * Share of cached input tokens. Returns 0 rather than NaN when the window holds
  * no input tokens at all, so the tile renders "0,0 %" instead of "NaN %".

package/src/features/tokenusage/lib/palette.ts

@@ -3,16 +3,29 @@
  *
  * Every value here is a documented step of the dataviz skill's reference ramps —
  * nothing was eyeballed, nothing was hand-mixed. The palette was run through the
- * skill's validator against THIS application's real chart surfaces (from
- * `apps/web/src/app/globals.css`: light `oklch(1 0 0)` = `#ffffff`, dark
- * `oklch(0.145 0 0)` = `#0a0a0a`) in both modes. The verbatim output is below.
+ * skill's validator against THIS application's real chart surfaces in both modes.
+ * The verbatim output is below.
+ *
+ * The surface is `--card`, NOT `--background`. Every chart that uses this palette
+ * is painted inside a `<Card>`, so the card is the surface the marks actually sit
+ * on — and in dark mode it is the *lighter* of the two (`oklch(0.205 0 0)` vs the
+ * background's `oklch(0.145 0 0)`), which is the harder case for contrast. Taken
+ * from `apps/web/src/app/globals.css` (narr8 declares two `:root`/`.dark` pairs;
+ * the LATER pair wins, and it is the one read here) — light `oklch(1 0 0)`, dark
+ * `oklch(0.205 0 0)`. a360ai declares the same two values.
+ *
+ * oklch→hex conversion: the algebraic inverse of the Björn Ottosson OKLab
+ * matrices — the same matrices the validator applies in the forward direction —
+ * giving light `#ffffff` and dark `#171717`. Cross-checked by feeding it the
+ * previously recorded background value, which it reproduces exactly:
+ * `oklch(0.145 0 0)` → `#0a0a0a`. ✓
  *
  * Light and dark are two SELECTED sets of steps, chosen for their own surface —
  * never one set with its lightness flipped at runtime. Consumers pick a set from
  * the resolved theme (`seriesColor(i, mode)` / `sequentialColor(i, mode)`).
  *
  * ---------------------------------------------------------------------------
- * VALIDATOR OUTPUT — dataviz `scripts/validate_palette.js`, run 2026-08-07
+ * VALIDATOR OUTPUT — dataviz `scripts/validate_palette.js`, run 2026-08-15
  * ---------------------------------------------------------------------------
  *
  * $ node scripts/validate_palette.js "#2a78d6,#eb6834,#1baf7a,#eda100,#e87ba4,#008300,#4a3aa7" --mode light --surface "#ffffff"
@@ -27,9 +40,9 @@
  *   → ALL CHECKS PASS  (CVD in the 6–8 floor band is legal ONLY with secondary encoding: direct labels, gaps, or texture)
  *   scope: categorical palettes only. For a lone status/text color check WCAG text contrast; for a sequential ramp, lightness monotonicity.
  *
- * $ node scripts/validate_palette.js "#3987e5,#d95926,#199e70,#c98500,#d55181,#008300,#9085e9" --mode dark --surface "#0a0a0a"
+ * $ node scripts/validate_palette.js "#3987e5,#d95926,#199e70,#c98500,#d55181,#008300,#9085e9" --mode dark --surface "#171717"
  *
- * Palette (dark, surface #0a0a0a, categorical): 7 slots
+ * Palette (dark, surface #171717, categorical): 7 slots
  *   [PASS] Lightness band         all 7 inside L 0.48–0.67
  *   [PASS] Chroma floor           all 7 >= 0.1
  *   [PASS] CVD separation         worst adjacent #c98500↔#199e70 ΔE 8.4 (protan) · tritan 8.7
@@ -49,29 +62,39 @@
  *
  *   → ALL CHECKS PASS  (ordinal: one hue, monotone L, visible step gaps, light end clears surface)
  *
- * $ node scripts/validate_palette.js "#9ec5f4,#6da7ec,#3987e5,#256abf,#184f95" --mode dark --surface "#0a0a0a" --ordinal
+ * $ node scripts/validate_palette.js "#9ec5f4,#6da7ec,#3987e5,#256abf,#184f95" --mode dark --surface "#171717" --ordinal
  *
- * Palette (dark, surface #0a0a0a, ordinal ramp): 5 slots
+ * Palette (dark, surface #171717, ordinal ramp): 5 slots
  *   [PASS] Lightness monotone     steps read light→dark
  *   [PASS] Adjacent ΔL            all gaps >= 0.06
- *   [PASS] Light-end contrast     #184f95 at 2.44:1 vs surface
+ *   [PASS] Light-end contrast     #184f95 at 2.21:1 vs surface
  *   [PASS] Single hue             hue spread 3°
  *
  *   → ALL CHECKS PASS  (ordinal: one hue, monotone L, visible step gaps, light end clears surface)
  *
  * OTHER_COLOR is achromatic, so the categorical checks (which gate hue identity)
  * do not apply to it; it was gated on contrast alone with the validator's own
- * `contrast()` export: 3.59:1 on `#ffffff`, 5.51:1 on `#0a0a0a` — both clear 3:1.
+ * `contrast()` export: 3.59:1 on `#ffffff`, 4.99:1 on `#171717` — both clear 3:1.
  *
  * ---------------------------------------------------------------------------
  * WHAT THE RESULTS OBLIGE US TO DO
  * ---------------------------------------------------------------------------
  *
+ * - NO COLOUR VALUE CHANGED in the move from `--background` to `--card`. Every
+ *   gate that passed on the background still passes on the card, so re-stepping
+ *   a hue would have been churn, not a fix. Only the recorded surface, the
+ *   recorded numbers and this prose changed.
+ * - The dark set still clears 3:1 on the LIGHTER card surface: the worst slot is
+ *   green `#008300` at 3.63:1, and the ordinal ramp's surface-nearest step lands
+ *   at 2.21:1 (down from 2.44:1 on the background) — still above the 2:1 gate.
+ *   That headroom is thin, so a future card-surface lightening MUST re-run these
+ *   four commands rather than assume the set still holds.
  * - The light-mode contrast WARN is NOT dismissable. Three slots (aqua, yellow,
  *   magenta) sit below 3:1 on white, so every surface that paints with this
  *   palette MUST ship the relief channel: a visible legend, direct labels and a
  *   tooltip carrying the value in text. The timeline chart and the breakdown
- *   table both do.
+ *   table both do. The light card is `#ffffff`, identical to the light
+ *   background, so this WARN is unchanged rather than newly incurred.
  * - CVD separation is measured on ADJACENT pairs, which is the correct pairlist
  *   for stacked bars, grouped bars and lines — the only forms this palette paints.
  *   A scatter / bubble / small-multiples chart would need `--pairs all`, which
@@ -82,10 +105,14 @@
 /** Which surface the colours are being painted on. */
 export type ChartMode = "light" | "dark";
 
-/** The chart surfaces the palette was validated against (globals.css). */
+/**
+ * The chart surfaces the palette was validated against (globals.css `--card`).
+ *
+ * `--card`, never `--background`: the charts are painted inside a `<Card>`.
+ */
 export const CHART_SURFACE: Readonly<Record<ChartMode, string>> = {
   light: "#ffffff",
-  dark: "#0a0a0a",
+  dark: "#171717",
 };
 
 /**
@@ -133,7 +160,7 @@ export const CATEGORICAL_CEILING = CATEGORICAL_LIGHT.length;
 /**
  * The "other" rollup colour: deliberately achromatic so it reads as "not an
  * identity" beside the seven hues. Same step in both modes — it clears 3:1 on
- * both surfaces (3.59:1 light, 5.51:1 dark).
+ * both card surfaces (3.59:1 on `#ffffff`, 4.99:1 on `#171717`).
  */
 export const OTHER_COLOR = "#898781";
 

package/src/features/tokenusage/tokenusage-admin.module.ts

@@ -11,6 +11,10 @@ import { TokenUsageAdminTimeline } from "./data/tokenusage-admin-timeline";
  * Distinct from the consuming app's own TokenUsage module (name "tokenusages",
  * pageUrl "/tokenusage") — that one is an AppModuleDefinitions entry the package
  * cannot reference, which is why these three exist.
+ *
+ * PREFER `tokenUsageModules(factory)` from `./tokenusage.modules` — it returns
+ * these three plus the three self-service report modules as one spreadable
+ * object. These individual factories are kept for backward compatibility.
  */
 export const TokenUsageAdminSummaryModule = (factory: ModuleFactory) =>
   factory({ name: "tokenusages/administration/summary", model: TokenUsageAdminSummary });

package/src/features/tokenusage/tokenusage.modules.ts

@@ -0,0 +1,40 @@
+import { ModuleFactory, ModuleWithPermissions } from "../../permissions";
+import { TokenUsageAdminBreakdown } from "./data/tokenusage-admin-breakdown";
+import { TokenUsageAdminSummary } from "./data/tokenusage-admin-summary";
+import { TokenUsageAdminTimeline } from "./data/tokenusage-admin-timeline";
+import { TokenUsageReportBreakdown } from "./data/tokenusage-report-breakdown";
+import { TokenUsageReportSummary } from "./data/tokenusage-report-summary";
+import { TokenUsageReportTimeline } from "./data/tokenusage-report-timeline";
+
+/**
+ * Every read-only reporting resource behind the two token-usage pages, as one
+ * object a consuming app spreads into its `allModules`.
+ *
+ * A bundle rather than six separate factories because registration is the APP'S
+ * job — `allModules` is also the source of `AllModuleDefinitions` and what
+ * `DataClassRegistry.bootstrap()` reads, so the package cannot self-register.
+ * Six names is six chances to forget one, and a forgotten name is not a compile
+ * error: `FoundationModuleDefinitions` declares them all, so `Modules.X`
+ * typechecks and is `undefined` at runtime. One spread cannot be partially done.
+ *
+ * `name` is the endpoint path EndpointCreator builds URLs from. None has a
+ * pageUrl — these are not navigable resources.
+ *
+ * The return type is the six named keys, NOT `Record<string,
+ * ModuleWithPermissions>`: the consuming app derives `AllModuleDefinitions`
+ * from `typeof allModules`, so spreading an index-signature type in would give
+ * that object a string index signature and make every `Modules.<anything>`
+ * lookup typecheck. `satisfies` keeps the constraint without widening.
+ */
+export const tokenUsageModules = (factory: ModuleFactory) =>
+  ({
+    TokenUsageAdminSummary: factory({ name: "tokenusages/administration/summary", model: TokenUsageAdminSummary }),
+    TokenUsageAdminTimeline: factory({ name: "tokenusages/administration/timeline", model: TokenUsageAdminTimeline }),
+    TokenUsageAdminBreakdown: factory({
+      name: "tokenusages/administration/breakdown",
+      model: TokenUsageAdminBreakdown,
+    }),
+    TokenUsageReportSummary: factory({ name: "tokenusages/reports/summary", model: TokenUsageReportSummary }),
+    TokenUsageReportTimeline: factory({ name: "tokenusages/reports/timeline", model: TokenUsageReportTimeline }),
+    TokenUsageReportBreakdown: factory({ name: "tokenusages/reports/breakdown", model: TokenUsageReportBreakdown }),
+  }) satisfies Record<string, ModuleWithPermissions>;

package/src/features/user/components/containers/PlatformUsersContainer.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { UserProvider } from "../../contexts/UserContext";
+import { PlatformUsersList } from "../lists/PlatformUsersList";
+
+/**
+ * Page container for the platform-wide (cross-company) user list.
+ *
+ * Client component by necessity: `module={Modules.User}` is a registry entry
+ * with an icon component and methods, which a Server Component cannot pass
+ * across the boundary.
+ */
+export function PlatformUsersContainer() {
+  return (
+    <UserProvider>
+      <RoundPageContainer module={Modules.User} fullWidth>
+        <PlatformUsersList fullWidth />
+      </RoundPageContainer>
+    </UserProvider>
+  );
+}

package/src/features/user/components/containers/index.ts

@@ -1,4 +1,5 @@
 export * from "./AllUsersListContainer";
+export * from "./PlatformUsersContainer";
 export * from "./UserContainer";
 export * from "./UserIndexContainer";
 export * from "./UsersListContainer";

package/src/features/user/components/lists/PlatformUsersList.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { ContentListTable } from "../../../../components";
+import { Modules } from "../../../../core";
+import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
+import { UserFields, UserInterface } from "../../data";
+import { UserService } from "../../data/user.service";
+
+type PlatformUsersListProps = {
+  includeDeleted?: boolean;
+  fullWidth?: boolean;
+};
+
+/**
+ * Every user on the platform, across all companies.
+ *
+ * Deliberately NOT company-scoped: `CompanyUsersList` and `AdminUsersList` both
+ * build `/companies/{id}/users` and need a company in context, so they render
+ * nothing for a system administrator — who has no Company. This one calls
+ * `UserService.findMany`, which hits `GET /users`; that controller widens the
+ * result set itself when the caller holds Administrator or CompanyAdministrator
+ * (see the backend user controller's `isAdmin` flag), so the same component is
+ * safe for both.
+ */
+export function PlatformUsersList({ includeDeleted, fullWidth }: PlatformUsersListProps) {
+  const t = useTranslations();
+
+  const data: DataListRetriever<UserInterface> = useDataListRetriever({
+    retriever: (params) => UserService.findMany(params),
+    retrieverParams: { includeDeleted: includeDeleted },
+    module: Modules.User,
+  }) as DataListRetriever<UserInterface>;
+
+  return (
+    <ContentListTable
+      data={data}
+      fields={[UserFields.name, UserFields.email, UserFields.company]}
+      tableGeneratorType={Modules.User}
+      fullWidth={fullWidth}
+      allowSearch
+      title={t(`entities.users`, { count: 2 })}
+    />
+  );
+}

package/src/features/user/components/lists/index.ts

@@ -1,5 +1,6 @@
 export * from "./AdminUsersList";
 export * from "./CompanyUsersList";
+export * from "./PlatformUsersList";
 export * from "./ContributorsList";
 export * from "./RelevantUsersList";
 export * from "./RoleUsersList";

package/src/features/user/data/user.fields.ts

@@ -2,6 +2,7 @@ export enum UserFields {
   userId = "userId",
   name = "name",
   email = "email",
+  company = "company",
   relevance = "relevance",
   createdAt = "createdAt",
   updatedAt = "updatedAt",

package/src/features/user/hooks/useUserTableStructure.tsx

@@ -68,6 +68,23 @@ export const useUserTableStructure: UseTableStructureHook<UserInterface, UserFie
       enableSorting: false,
       enableHiding: false,
     }),
+    // Only meaningful on a platform-wide list (PlatformUsersList), where users
+    // from every company sit in one table; a company-scoped list would repeat
+    // the same value on every row.
+    [UserFields.company]: () => ({
+      id: "company",
+      accessorKey: "company",
+      header: t(`entities.companies`, { count: 1 }),
+      cell: ({ row }: { row: Row<TableContent<UserInterface>> }) => {
+        const company = (row.original.jsonApiData as UserInterface).company;
+
+        if (!company) return <span className="text-muted-foreground text-xs">—</span>;
+
+        return <Link href={generateUrl({ page: Modules.Company, id: company.id })}>{company.name}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
     [UserFields.relevance]: () => ({
       id: "relevance",
       accessorKey: "relevance",

package/src/shadcnui/ui/chart.tsx

@@ -115,6 +115,8 @@ function ChartTooltipContent({
   labelFormatter,
   labelClassName,
   formatter,
+  valueFormatter,
+  hideZeroValues = false,
   color,
   nameKey,
   labelKey,
@@ -124,6 +126,21 @@ function ChartTooltipContent({
   label?: string | number;
   labelFormatter?: (label: unknown, payload: PayloadItem[]) => React.ReactNode;
   formatter?: (value: unknown, name: string, item: PayloadItem, index: number, payload: unknown) => React.ReactNode;
+  /**
+   * Formats the VALUE half of a row while keeping the default layout — colour
+   * swatch, series name, alignment. `formatter` replaces the whole row, so it
+   * is the wrong tool when all a chart needs is its own number formatting.
+   * Defaults to `toLocaleString()`, which is what every existing caller gets.
+   */
+  valueFormatter?: (value: number | string) => React.ReactNode;
+  /**
+   * Drops rows whose value is zero. On a stacked chart every series appears in
+   * every bucket's payload, so a bucket with one active series still lists all
+   * of them — the reader has to scan a column of zeros to find the one number
+   * that matters. Off by default: a chart comparing a fixed set of series may
+   * want the zeros visible.
+   */
+  hideZeroValues?: boolean;
   hideLabel?: boolean;
   hideIndicator?: boolean;
   indicator?: "line" | "dot" | "dashed";
@@ -173,6 +190,7 @@ function ChartTooltipContent({
       <div className="grid gap-1.5">
         {payload
           .filter((item) => item.type !== "none")
+          .filter((item) => !hideZeroValues || Number(item.value) !== 0)
           .map((item, index) => {
             const key = `${nameKey || item.name || item.dataKey || "value"}`;
             const itemConfig = getPayloadConfigFromPayload(config, item, key);
@@ -212,7 +230,11 @@ function ChartTooltipContent({
                     )}
                     <div
                       className={cn(
-                        "flex flex-1 justify-between leading-none",
+                        // gap-4 is load-bearing: without it a long series name
+                        // runs straight into its value ("Decision suggestions0")
+                        // because justify-between leaves no room once the row
+                        // fills. The gap also widens the tooltip to fit.
+                        "flex flex-1 justify-between gap-4 leading-none",
                         nestLabel ? "items-end" : "items-center",
                       )}
                     >
@@ -220,8 +242,13 @@ function ChartTooltipContent({
                         {nestLabel ? tooltipLabel : null}
                         <span className="text-muted-foreground">{itemConfig?.label || item.name}</span>
                       </div>
-                      {item.value && (
-                        <span className="text-foreground font-medium tabular-nums">{item.value.toLocaleString()}</span>
+                      {item.value !== undefined && item.value !== null && (
+                        // Tested against undefined/null rather than truthiness:
+                        // a value of exactly 0 is falsy, and the old guard
+                        // dropped the number while still drawing its row.
+                        <span className="text-foreground font-medium tabular-nums">
+                          {valueFormatter ? valueFormatter(item.value) : item.value.toLocaleString()}
+                        </span>
                       )}
                     </div>
                   </>