@carlonicora/nextjs-jsonapi 6.0.0 → 6.1.0

package/messages/en.json

@@ -1776,17 +1776,40 @@
       "empty": "No usage recorded in this period"
     },
     "types": {
+      "analyser": "Analysis",
+      "blogSummary": "Blog summaries",
+      "blogTranslation": "Blog translations",
       "communitySummariser": "Community overviews",
+      "counterpartIdentificator": "Counterpart identification",
       "customer": "Customer",
       "embedding": "Search indexing",
+      "ethicist": "Ethics review",
       "graphCreator": "Connection mapping",
+      "imageAnalysis": "Image analysis",
       "imageGeneration": "Image generation",
       "operator": "Assistant actions",
       "platform": "Platform",
       "responder": "Assistant answers",
+      "retrievalEval": "Search quality tests",
+      "strategy": "Strategy",
       "summariser": "Summarisation",
       "textGeneration": "Text generation",
       "transcription": "Transcription"
+    },
+    "type_descriptions": {
+      "blogSummary": "Writes the summary of each blog post.",
+      "blogTranslation": "Translates blog posts and their categories into the other languages.",
+      "communitySummariser": "Writes an overview of each group of related content.",
+      "embedding": "Turns content into search vectors, so search and the assistant can find it.",
+      "graphCreator": "Reads new content and extracts its facts and the connections between the people, places and things it mentions.",
+      "imageAnalysis": "Reads the images inside uploaded documents so their content can be searched.",
+      "imageGeneration": "Creates images from a written description.",
+      "operator": "Actions the assistant carries out, such as searching or changing content.",
+      "responder": "The assistant's answers to questions.",
+      "retrievalEval": "Grades search quality during internal tests. Never started by customers.",
+      "summariser": "Writes summaries of processed content.",
+      "textGeneration": "AI writing in the editor, plus any AI call that does not record a more specific category.",
+      "transcription": "Turns recorded audio into text."
     }
   },
   "ui": {

package/messages/it.json

@@ -1776,17 +1776,40 @@
       "empty": "Nessun utilizzo registrato in questo periodo"
     },
     "types": {
+      "analyser": "Analisi",
+      "blogSummary": "Riassunti del blog",
+      "blogTranslation": "Traduzioni del blog",
       "communitySummariser": "Panoramiche delle comunità",
+      "counterpartIdentificator": "Identificazione delle controparti",
       "customer": "Cliente",
       "embedding": "Indicizzazione per la ricerca",
+      "ethicist": "Revisione etica",
       "graphCreator": "Mappatura dei collegamenti",
+      "imageAnalysis": "Analisi delle immagini",
       "imageGeneration": "Generazione di immagini",
       "operator": "Azioni dell'assistente",
       "platform": "Piattaforma",
       "responder": "Risposte dell'assistente",
+      "retrievalEval": "Test di qualità della ricerca",
+      "strategy": "Strategia",
       "summariser": "Riassunti",
       "textGeneration": "Generazione di testo",
       "transcription": "Trascrizione"
+    },
+    "type_descriptions": {
+      "blogSummary": "Scrive il riassunto di ogni articolo del blog.",
+      "blogTranslation": "Traduce gli articoli del blog e le loro categorie nelle altre lingue.",
+      "communitySummariser": "Scrive una panoramica di ogni gruppo di contenuti collegati.",
+      "embedding": "Trasforma i contenuti in vettori di ricerca, così la ricerca e l'assistente possono trovarli.",
+      "graphCreator": "Legge i nuovi contenuti ed estrae i fatti e i collegamenti tra le persone, i luoghi e le cose citate.",
+      "imageAnalysis": "Legge le immagini dentro i documenti caricati, così il loro contenuto diventa ricercabile.",
+      "imageGeneration": "Crea immagini a partire da una descrizione scritta.",
+      "operator": "Le azioni svolte dall'assistente, come cercare o modificare contenuti.",
+      "responder": "Le risposte dell'assistente alle domande.",
+      "retrievalEval": "Valuta la qualità della ricerca durante i test interni. Mai avviato dai clienti.",
+      "summariser": "Scrive i riassunti dei contenuti elaborati.",
+      "textGeneration": "La scrittura con l'AI nell'editor, più ogni chiamata AI che non registra una categoria più specifica.",
+      "transcription": "Trasforma l'audio registrato in testo."
     }
   },
   "ui": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/scripts/validate-messages.mjs

@@ -35,7 +35,10 @@ export const APP_PROVIDED_KEYS = [
   // Token-usage operation types an app backend defines (operation-label.ts: the
   // app supplies this vocabulary, unknown types render raw). Only the types the
   // backend library emits, plus its customer/platform scopes, ship.
-  /^token_usage\.types\.(?!(?:analyser|communitySummariser|counterpartIdentificator|customer|embedding|ethicist|graphCreator|imageAnalysis|imageGeneration|operator|platform|responder|strategy|summariser|textGeneration|transcription)$)/,
+  /^token_usage\.types\.(?!(?:analyser|blogSummary|blogTranslation|communitySummariser|counterpartIdentificator|customer|embedding|ethicist|graphCreator|imageAnalysis|imageGeneration|operator|platform|responder|retrievalEval|strategy|summariser|textGeneration|transcription)$)/,
+  // Their optional explanations (operation-label.ts operationDescription): same
+  // rule, only the library-emitted types ship one.
+  /^token_usage\.type_descriptions\.(?!(?:analyser|blogSummary|blogTranslation|communitySummariser|counterpartIdentificator|embedding|ethicist|graphCreator|imageAnalysis|imageGeneration|operator|responder|retrievalEval|strategy|summariser|textGeneration|transcription)$)/,
 ];
 
 // Values the app-word rule would flag although the word is the library's own

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

@@ -1,10 +1,11 @@
 "use client";
 
 import { useTranslations } from "next-intl";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../../shadcnui";
 import type { Metric } from "../data/tokenusage-admin.types";
 import { useUsageFormatters } from "../lib/formatters";
 import { metricValue, type TokenUsageMetrics } from "../lib/metrics";
-import { operationLabel } from "../lib/operation-label";
+import { operationDescription, operationLabel } from "../lib/operation-label";
 import { SEQUENTIAL_RAMP } from "../lib/palette";
 
 /**
@@ -65,6 +66,37 @@ export function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperati
     );
   };
 
+  const renderDescription = (row: TokenUsageRankedRow): string | undefined => {
+    if (row.id === "other" || !labelsAreOperationTypes) return undefined;
+    return operationDescription(
+      row.label,
+      (key) => t(key),
+      (key) => t.has(key),
+    );
+  };
+
+  // An operation type the app explains gets its explanation on hover; every
+  // other label (names, the folded "other" row) renders as plain text.
+  const renderLabelCell = (row: TokenUsageRankedRow) => {
+    const label = <span className="text-muted-foreground truncate text-xs">{renderLabel(row)}</span>;
+    const description = renderDescription(row);
+    if (!description) return label;
+    return (
+      <Tooltip>
+        <TooltipTrigger
+          data-testid={`ranked-description-${row.id}`}
+          className="min-w-0 cursor-help justify-self-start truncate"
+          render={<div />}
+        >
+          {label}
+        </TooltipTrigger>
+        <TooltipContent side="top" className="max-w-xs">
+          <p className="text-xs">{description}</p>
+        </TooltipContent>
+      </Tooltip>
+    );
+  };
+
   if (rows.length === 0) {
     return <p className="text-muted-foreground py-6 text-center text-sm">{emptyLabel}</p>;
   }
@@ -89,7 +121,7 @@ export function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperati
         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>
+              {renderLabelCell(row)}
               {/* The bar itself is a magnitude drawn on an axis, not prose: it always grows
                   rightward and only its trailing corner is rounded, so the track and its fill
                   stay an LTR island. The label, value and share around it mirror normally.

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

@@ -40,4 +40,26 @@ describe("TokenUsageRankedBar", () => {
     expect(new Set(colours).size).toBe(3);
     expect(colours).toEqual(["0", "1", "2"]);
   });
+
+  it("puts the operation description behind a tooltip on operation rows, never on the folded tail", () => {
+    render(
+      <TokenUsageRankedBar
+        rows={[row("blog_translation", "blog_translation", 3), row("other", "other", 1)]}
+        metric="cost"
+        emptyLabel="nessun dato"
+        labelsAreOperationTypes
+      />,
+    );
+
+    expect(screen.getByTestId("ranked-description-blog_translation")).toHaveTextContent(
+      "token_usage.types.blogTranslation",
+    );
+    expect(screen.queryByTestId("ranked-description-other")).not.toBeInTheDocument();
+  });
+
+  it("renders entity names without a tooltip", () => {
+    render(<TokenUsageRankedBar rows={[row("a", "Studio Rossi", 1)]} metric="cost" emptyLabel="nessun dato" />);
+    expect(screen.queryByTestId("ranked-description-a")).not.toBeInTheDocument();
+    expect(screen.getByText("Studio Rossi")).toBeInTheDocument();
+  });
 });

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

@@ -8,6 +8,13 @@
  */
 export const OPERATION_LABEL_NAMESPACE = "token_usage.types";
 
+/**
+ * Sibling namespace for an optional one-line explanation of each operation
+ * type, keyed exactly like `OPERATION_LABEL_NAMESPACE`. A type without an entry
+ * simply has no explanation — nothing falls back to the raw key here.
+ */
+export const OPERATION_DESCRIPTION_NAMESPACE = "token_usage.type_descriptions";
+
 /**
  * `snake_case` / `kebab-case` → `camelCase`, the shape the i18n keys use.
  *
@@ -39,3 +46,16 @@ export const operationLabel = (
   const key = `${OPERATION_LABEL_NAMESPACE}.${toCamelCase(type)}`;
   return has(key) ? translate(key) : type;
 };
+
+/**
+ * Resolves an operation type to its explanation, or `undefined` when the
+ * consuming app (or the package) provides none.
+ */
+export const operationDescription = (
+  type: string,
+  translate: (key: string) => string,
+  has: (key: string) => boolean,
+): string | undefined => {
+  const key = `${OPERATION_DESCRIPTION_NAMESPACE}.${toCamelCase(type)}`;
+  return has(key) ? translate(key) : undefined;
+};