@carlonicora/nextjs-jsonapi 1.141.3 → 1.143.0

package/src/features/tokenusage/data/tokenusage-admin-summary.interface.ts

@@ -0,0 +1,14 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageAdminSummaryInterface extends ApiDataInterface {
+  /** "customer" | "platform" | "total" */
+  get scope(): string;
+  /** "current" | "previous" */
+  get window(): string;
+  get cost(): number;
+  get credits(): number;
+  get tokensIn(): number;
+  get tokensOut(): number;
+  get cached(): number;
+  get calls(): number;
+}

package/src/features/tokenusage/data/tokenusage-admin-summary.ts

@@ -0,0 +1,90 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageAdminSummaryInterface } from "./tokenusage-admin-summary.interface";
+import { TokenUsageAdminSummaryInput } from "./tokenusage-admin.types";
+
+/**
+ * One row of the administrative summary: a cost centre observed over one time
+ * window. Six rows are returned per request — scope crossed with window — so the
+ * KPI tiles can render a value and its delta without a second call.
+ */
+export class TokenUsageAdminSummary extends AbstractApiData implements TokenUsageAdminSummaryInterface {
+  private _scope: string = "";
+  private _window: string = "";
+  private _cost: number = 0;
+  private _credits: number = 0;
+  private _tokensIn: number = 0;
+  private _tokensOut: number = 0;
+  private _cached: number = 0;
+  private _calls: number = 0;
+
+  get scope(): string {
+    return this._scope;
+  }
+
+  get window(): string {
+    return this._window;
+  }
+
+  get cost(): number {
+    return this._cost;
+  }
+
+  get credits(): number {
+    return this._credits;
+  }
+
+  get tokensIn(): number {
+    return this._tokensIn;
+  }
+
+  get tokensOut(): number {
+    return this._tokensOut;
+  }
+
+  get cached(): number {
+    return this._cached;
+  }
+
+  get calls(): number {
+    return this._calls;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._scope = attrs.scope ?? "";
+    this._window = attrs.window ?? "";
+    this._cost = attrs.cost ?? 0;
+    this._credits = attrs.credits ?? 0;
+    this._tokensIn = attrs.tokensIn ?? 0;
+    this._tokensOut = attrs.tokensOut ?? 0;
+    this._cached = attrs.cached ?? 0;
+    this._calls = attrs.calls ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: TokenUsageAdminSummaryInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageAdminSummary.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.scope !== undefined) response.data.attributes.scope = data.scope;
+    if (data.window !== undefined) response.data.attributes.window = data.window;
+    if (data.cost !== undefined) response.data.attributes.cost = data.cost;
+    if (data.credits !== undefined) response.data.attributes.credits = data.credits;
+    if (data.tokensIn !== undefined) response.data.attributes.tokensIn = data.tokensIn;
+    if (data.tokensOut !== undefined) response.data.attributes.tokensOut = data.tokensOut;
+    if (data.cached !== undefined) response.data.attributes.cached = data.cached;
+    if (data.calls !== undefined) response.data.attributes.calls = data.calls;
+
+    return response;
+  }
+}

package/src/features/tokenusage/data/tokenusage-admin-timeline.interface.ts

@@ -0,0 +1,13 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageAdminTimelineInterface extends ApiDataInterface {
+  /** Backend declares this `type: "date"`, so it is a Date in memory. */
+  get bucket(): Date;
+  get series(): string;
+  get cost(): number;
+  get credits(): number;
+  get tokensIn(): number;
+  get tokensOut(): number;
+  get cached(): number;
+  get calls(): number;
+}

package/src/features/tokenusage/data/tokenusage-admin-timeline.ts

@@ -0,0 +1,94 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageAdminTimelineInterface } from "./tokenusage-admin-timeline.interface";
+import { TokenUsageAdminTimelineInput } from "./tokenusage-admin.types";
+
+/**
+ * One (bucket, series) cell of the usage-over-time chart. Rows arrive flat; the
+ * chart pivots them into stacked columns.
+ */
+export class TokenUsageAdminTimeline extends AbstractApiData implements TokenUsageAdminTimelineInterface {
+  private _bucket: Date = new Date(0);
+  private _series: string = "";
+  private _cost: number = 0;
+  private _credits: number = 0;
+  private _tokensIn: number = 0;
+  private _tokensOut: number = 0;
+  private _cached: number = 0;
+  private _calls: number = 0;
+
+  get bucket(): Date {
+    return this._bucket;
+  }
+
+  get series(): string {
+    return this._series;
+  }
+
+  get cost(): number {
+    return this._cost;
+  }
+
+  get credits(): number {
+    return this._credits;
+  }
+
+  get tokensIn(): number {
+    return this._tokensIn;
+  }
+
+  get tokensOut(): number {
+    return this._tokensOut;
+  }
+
+  get cached(): number {
+    return this._cached;
+  }
+
+  get calls(): number {
+    return this._calls;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    // Wire format is "YYYY-MM-DD"; the interface promises a Date.
+    this._bucket = attrs.bucket ? new Date(attrs.bucket) : new Date(0);
+    this._series = attrs.series ?? "";
+    this._cost = attrs.cost ?? 0;
+    this._credits = attrs.credits ?? 0;
+    this._tokensIn = attrs.tokensIn ?? 0;
+    this._tokensOut = attrs.tokensOut ?? 0;
+    this._cached = attrs.cached ?? 0;
+    this._calls = attrs.calls ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: TokenUsageAdminTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageAdminTimeline.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // `bucket` is type: "date" on the backend descriptor. formatLocalDate is
+    // mandatory — passing the raw Date lets JSON.stringify call .toISOString(),
+    // which UTC-shifts and can move the bucket a day. Imported from the package
+    // core, never reimplemented inline.
+    if (data.bucket !== undefined) response.data.attributes.bucket = formatLocalDate(data.bucket);
+    if (data.series !== undefined) response.data.attributes.series = data.series;
+    if (data.cost !== undefined) response.data.attributes.cost = data.cost;
+    if (data.credits !== undefined) response.data.attributes.credits = data.credits;
+    if (data.tokensIn !== undefined) response.data.attributes.tokensIn = data.tokensIn;
+    if (data.tokensOut !== undefined) response.data.attributes.tokensOut = data.tokensOut;
+    if (data.cached !== undefined) response.data.attributes.cached = data.cached;
+    if (data.calls !== undefined) response.data.attributes.calls = data.calls;
+
+    return response;
+  }
+}

package/src/features/tokenusage/data/tokenusage-admin.types.ts

@@ -0,0 +1,56 @@
+export type Granularity = "day" | "week" | "month";
+export type StackBy = "scope" | "type" | "company";
+export type Dimension = "company" | "user" | "operation";
+export type Scope = "customer" | "platform";
+export type Metric = "cost" | "credits" | "tokens";
+
+export type TokenUsageAdminFilters = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+  companyId?: string;
+};
+
+// Input types for createJsonApi(). `id` is always required — JSON:API resource
+// objects are identified.
+
+export type TokenUsageAdminSummaryInput = {
+  id: string;
+  scope: string;
+  window: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};
+
+export type TokenUsageAdminTimelineInput = {
+  id: string;
+  /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+  bucket: Date;
+  series: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};
+
+export type TokenUsageAdminBreakdownInput = {
+  id: string;
+  label: string;
+  sublabel?: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+  activeUsers?: number;
+  monthlyCredits?: number;
+  availableMonthlyCredits?: number;
+};

package/src/features/tokenusage/i18n-keys.ts

@@ -0,0 +1,65 @@
+/**
+ * The fixed namespace of i18n keys the administrative token-usage feature reads
+ * via useTranslations/getTranslations. Consuming apps must define each entry in
+ * their messages/<locale>.json — this list is the contract between the package
+ * and the app.
+ *
+ * One key is NOT listed because it is resolved from data rather than from a
+ * fixed string: the timeline chart labels each series through
+ * `token_usage.types.<camelCase>` and falls back to the raw series key when the
+ * app has no entry, so that namespace stays the app's own vocabulary.
+ */
+export const TOKEN_USAGE_ADMIN_I18N_KEYS = [
+  // Page + KPI tiles
+  "token_usage.admin.title",
+  "token_usage.admin.customer_spend",
+  "token_usage.admin.platform_spend",
+  "token_usage.admin.total_cost",
+  "token_usage.admin.avg_per_call",
+  "token_usage.admin.cache_hit",
+  "token_usage.admin.vs_previous",
+
+  // Panel titles
+  "token_usage.admin.usage_over_time",
+  "token_usage.admin.by_company",
+  "token_usage.admin.by_user",
+  "token_usage.admin.customer_by_operation",
+  "token_usage.admin.platform_by_operation",
+  "token_usage.admin.detail",
+
+  // Shared states
+  "token_usage.admin.other",
+  "token_usage.admin.no_data",
+
+  // Filter bar
+  "token_usage.admin.all_companies",
+  "token_usage.admin.granularity.label",
+  "token_usage.admin.granularity.day",
+  "token_usage.admin.granularity.week",
+  "token_usage.admin.granularity.month",
+  "token_usage.admin.metric.label",
+  "token_usage.admin.metric.cost",
+  "token_usage.admin.metric.credits",
+  "token_usage.admin.metric.tokens",
+
+  // Timeline stacking control
+  "token_usage.admin.stack_by",
+  "token_usage.admin.stack.scope",
+  "token_usage.admin.stack.type",
+  "token_usage.admin.stack.company",
+
+  // Breakdown table columns
+  "token_usage.admin.columns.label",
+  "token_usage.admin.columns.sublabel",
+  "token_usage.admin.columns.calls",
+  "token_usage.admin.columns.tokens_in",
+  "token_usage.admin.columns.tokens_out",
+  "token_usage.admin.columns.cost",
+  "token_usage.admin.columns.credits",
+  "token_usage.admin.columns.share",
+  "token_usage.admin.columns.active_users",
+
+  // Timeline chart
+  "token_usage.series.other",
+  "token_usage.timeline.empty",
+] as const;

package/src/features/tokenusage/index.ts

@@ -0,0 +1,30 @@
+// Client-only public barrel for the administrative token-usage feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/tokenusage`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Deliberately NOT re-exported from `src/index.ts` — keeping the feature off the
+// main barrel is what keeps its chart (recharts) out of the main client bundle,
+// exactly as the `help` feature does.
+//
+// Pair this with `@carlonicora/nextjs-jsonapi/tokenusage/server` for the ready
+// made server page (default export + generateMetadata).
+
+export { TokenUsageAdminProvider, useTokenUsageAdmin } from "./contexts/TokenUsageAdminContext";
+export type { TokenUsageAdminContextType, TokenUsageAdminFilterState } from "./contexts/TokenUsageAdminContext";
+
+export { TokenUsageAdminContainer } from "./components/TokenUsageAdminContainer";
+export { TokenUsageAdminFilterBar } from "./components/TokenUsageAdminFilterBar";
+export { TokenUsageAdminTiles } from "./components/TokenUsageAdminTiles";
+export { TokenUsageRankedBar } from "./components/TokenUsageRankedBar";
+export { TokenUsageBreakdownTable } from "./components/TokenUsageBreakdownTable";
+export { TokenUsageTimelineChart } from "./components/TokenUsageTimelineChart";
+
+export * from "./data";
+
+export {
+  TokenUsageAdminBreakdownModule,
+  TokenUsageAdminSummaryModule,
+  TokenUsageAdminTimelineModule,
+} from "./tokenusage-admin.module";
+
+export { TOKEN_USAGE_ADMIN_I18N_KEYS } from "./i18n-keys";

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

@@ -0,0 +1,69 @@
+import type { Metric } from "../data/tokenusage-admin.types";
+
+/**
+ * The metric field set every admin token-usage resource carries. Declared
+ * structurally so it accepts the summary, timeline and breakdown interfaces
+ * alike — all three expose exactly these getters.
+ */
+export type TokenUsageMetrics = {
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  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;
+  if (metric === "credits") return row.credits;
+  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 %".
+ */
+export function cacheHitPercentage(cached: number, tokensIn: number): number {
+  if (!tokensIn) return 0;
+  return (cached / tokensIn) * 100;
+}
+
+/**
+ * Percentage change of `current` against `previous`, rounded to a whole number.
+ *
+ * Returns `undefined` when the previous window is zero — there is no meaningful
+ * percentage change from nothing, and rendering Infinity would be worse than
+ * rendering nothing. Callers show an em dash in that slot.
+ */
+export function percentageDelta(current: number, previous: number): number | undefined {
+  if (!previous) return undefined;
+  return Math.round(((current - previous) / previous) * 100);
+}

package/src/features/tokenusage/lib/operation-label.ts

@@ -0,0 +1,41 @@
+/**
+ * The i18n namespace under which a consuming app supplies its own vocabulary for
+ * token-usage operation types (`summariser`, `massima_extraction`, …).
+ *
+ * The set of operations is application-specific — the package cannot know that
+ * a360ai calls `massima_extraction` "Estrazione Massime" — so the package looks
+ * the copy up here and falls back to the raw key when the app has no entry.
+ */
+export const OPERATION_LABEL_NAMESPACE = "token_usage.types";
+
+/**
+ * `snake_case` / `kebab-case` → `camelCase`, the shape the i18n keys use.
+ *
+ * Shared by every surface that renders an operation type — the timeline chart's
+ * series labels and the ranked bar's operation rows — so the two can never
+ * disagree about which key a given type maps to.
+ */
+export const toCamelCase = (value: string): string => {
+  const parts = value.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+  if (parts.length === 0) return value;
+  return parts
+    .map((part, index) =>
+      index === 0 ? part.charAt(0).toLowerCase() + part.slice(1) : part.charAt(0).toUpperCase() + part.slice(1),
+    )
+    .join("");
+};
+
+/**
+ * Resolves an operation type to its Italian label, falling back to the raw key.
+ *
+ * `has` is passed rather than the whole translator so this stays a pure function
+ * and both callers can share it regardless of how they obtained `t`.
+ */
+export const operationLabel = (
+  type: string,
+  translate: (key: string) => string,
+  has: (key: string) => boolean,
+): string => {
+  const key = `${OPERATION_LABEL_NAMESPACE}.${toCamelCase(type)}`;
+  return has(key) ? translate(key) : type;
+};

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

@@ -0,0 +1,197 @@
+/**
+ * Chart palette for the administrative token-usage dashboard.
+ *
+ * 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.
+ *
+ * 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
+ * ---------------------------------------------------------------------------
+ *
+ * $ node scripts/validate_palette.js "#2a78d6,#eb6834,#1baf7a,#eda100,#e87ba4,#008300,#4a3aa7" --mode light --surface "#ffffff"
+ *
+ * Palette (light, surface #ffffff, categorical): 7 slots
+ *   [PASS] Lightness band         all 7 inside L 0.43–0.77
+ *   [PASS] Chroma floor           all 7 >= 0.1
+ *   [PASS] CVD separation         worst adjacent #eda100↔#1baf7a ΔE 9.1 (protan) · tritan 5.8
+ *   [PASS] Normal-vision floor    worst adjacent #e87ba4↔#eda100 ΔE 19.6 (normal)
+ *   [WARN] Contrast vs surface    below 3:1 — relief required (visible labels or table view): [["#1baf7a",2.82],["#eda100",2.17],["#e87ba4",2.69]]
+ *
+ *   → 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"
+ *
+ * Palette (dark, surface #0a0a0a, 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
+ *   [PASS] Normal-vision floor    worst adjacent #d55181↔#c98500 ΔE 19.3 (normal)
+ *   [PASS] Contrast vs surface    all 7 >= 3:1
+ *
+ *   → 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 "#104281,#1c5cab,#2a78d6,#5598e7,#86b6ef" --mode light --surface "#ffffff" --ordinal
+ *
+ * Palette (light, surface #ffffff, ordinal ramp): 5 slots
+ *   [PASS] Lightness monotone     steps read light→dark
+ *   [PASS] Adjacent ΔL            all gaps >= 0.06
+ *   [PASS] Light-end contrast     #86b6ef at 2.11:1 vs surface
+ *   [PASS] Single hue             hue spread 3°
+ *
+ *   → 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
+ *
+ * Palette (dark, surface #0a0a0a, 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] 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.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT THE RESULTS OBLIGE US TO DO
+ * ---------------------------------------------------------------------------
+ *
+ * - 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.
+ * - 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
+ *   caps the usable slot count at three; do not reuse this array there without
+ *   re-running the validator with that flag.
+ */
+
+/** Which surface the colours are being painted on. */
+export type ChartMode = "light" | "dark";
+
+/** The chart surfaces the palette was validated against (globals.css). */
+export const CHART_SURFACE: Readonly<Record<ChartMode, string>> = {
+  light: "#ffffff",
+  dark: "#0a0a0a",
+};
+
+/**
+ * Categorical slots, in FIXED order. Slot n is series n — the order is the
+ * CVD-safety mechanism, not decoration, so it is never re-ordered and never
+ * cycled. The two-series default (customer / platform) takes slots 0 and 1.
+ *
+ * Hues, in order: blue, orange, aqua, yellow, magenta, green, violet.
+ */
+const CATEGORICAL_LIGHT: readonly string[] = [
+  "#2a78d6",
+  "#eb6834",
+  "#1baf7a",
+  "#eda100",
+  "#e87ba4",
+  "#008300",
+  "#4a3aa7",
+];
+
+/** The same seven hues, re-stepped for the dark surface. Not a lightness flip. */
+const CATEGORICAL_DARK: readonly string[] = [
+  "#3987e5",
+  "#d95926",
+  "#199e70",
+  "#c98500",
+  "#d55181",
+  "#008300",
+  "#9085e9",
+];
+
+/**
+ * The default (light-surface) categorical set.
+ *
+ * Prefer `seriesColor(index, mode)` — this array exists for consumers that only
+ * need the documented default order.
+ */
+export const CATEGORICAL: readonly string[] = CATEGORICAL_LIGHT;
+
+/**
+ * How many series may carry their own identity hue. An 8th series is NEVER a
+ * generated hue: it folds into `other`.
+ */
+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).
+ */
+export const OTHER_COLOR = "#898781";
+
+/**
+ * Sequential (single-hue, blue) ramp for MAGNITUDE, indexed by rank position:
+ * index 0 is rank 1 — the largest value — so the strongest step leads.
+ *
+ * On the light surface "strongest" is the darkest step; on the dark surface it
+ * is the lightest. The anchor flips with the surface, which is why there are two
+ * selected sets rather than one array reversed at runtime.
+ *
+ * Five steps, not eight: with the adjacent-ΔL ≥ 0.06 gate and the ≥ 2:1
+ * surface-contrast gate on the step nearest the surface, the blue ramp fits
+ * exactly five distinguishable steps. Consumers clamp past the end.
+ */
+const SEQUENTIAL_RAMP_LIGHT: readonly string[] = ["#104281", "#1c5cab", "#2a78d6", "#5598e7", "#86b6ef"];
+
+const SEQUENTIAL_RAMP_DARK: readonly string[] = ["#9ec5f4", "#6da7ec", "#3987e5", "#256abf", "#184f95"];
+
+/**
+ * The default (light-surface) sequential ramp.
+ *
+ * Prefer `sequentialColor(index, mode)` — this array exists for consumers that
+ * only need the documented default.
+ */
+export const SEQUENTIAL_RAMP: readonly string[] = SEQUENTIAL_RAMP_LIGHT;
+
+const categoricalSet = (mode: ChartMode): readonly string[] => (mode === "dark" ? CATEGORICAL_DARK : CATEGORICAL_LIGHT);
+
+const sequentialSet = (mode: ChartMode): readonly string[] =>
+  mode === "dark" ? SEQUENTIAL_RAMP_DARK : SEQUENTIAL_RAMP_LIGHT;
+
+/**
+ * The identity colour for series `index`.
+ *
+ * Never generates a hue and never cycles: anything at or past the ceiling gets
+ * `OTHER_COLOR`, because a series past the ceiling should already have been
+ * folded into the "other" bucket by the caller.
+ */
+export function seriesColor(index: number, mode: ChartMode = "light"): string {
+  if (index < 0 || index >= CATEGORICAL_CEILING) return OTHER_COLOR;
+  return categoricalSet(mode)[index];
+}
+
+/**
+ * Both mode steps for series `index`, shaped for a shadcn `ChartConfig` entry's
+ * `theme` field.
+ */
+export function seriesTheme(index: number): { light: string; dark: string } {
+  return { light: seriesColor(index, "light"), dark: seriesColor(index, "dark") };
+}
+
+/**
+ * The magnitude colour for rank position `index`, clamped to the last step so a
+ * long list keeps its weakest step rather than falling off the ramp.
+ */
+export function sequentialColor(index: number, mode: ChartMode = "light"): string {
+  const ramp = sequentialSet(mode);
+  const clamped = Math.min(Math.max(index, 0), ramp.length - 1);
+  return ramp[clamped];
+}