@llmnative/react 1.36.0 → 1.37.0

package/dist/types/src/I18n.d.ts

@@ -352,6 +352,14 @@ export interface I18nDict {
         noAnswer: string;
         answered: string;
     };
+    /** CR-112 — the charts: empty state, totals, the scale of the heatmaps, the data table. */
+    charts: {
+        noData: string;
+        total: string;
+        less: string;
+        more: string;
+        dataTable: string;
+    };
 }
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
@@ -389,4 +397,13 @@ export declare function useI18n<P extends DotNestedKeyOf<I18nDict>>(namespace: P
  * like the root `ErrorBoundary` of `<App>`.
  */
 export declare function useI18nDictOrEnglish(): I18nDict;
+/**
+ * Internal (not exported from the package): the dictionary and the locale of the nearest
+ * `<I18nProvider>`, English when there is none — for the charts (CR-112), which format numbers in
+ * the locale and may render outside the provider.
+ */
+export declare function useI18nOrEnglish(): {
+    dict: I18nDict;
+    locale: string;
+};
 export {};

package/dist/types/src/components/charts/ChartParts.d.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import type { FocusEvent as ReactFocusEvent, PointerEvent as ReactPointerEvent, ReactNode } from 'react';
+export interface ChartLegendItem {
+    readonly label: string;
+    /** Theme token of the swatch, e.g. `'--rf-chart-1'`. */
+    readonly token: string;
+    readonly shape?: 'square' | 'line' | 'dashed' | 'dot';
+}
+/** The legend of a chart: swatch and label, the text in the text tokens (identity is never colour alone). */
+export declare function ChartLegend({ items }: {
+    items: readonly ChartLegendItem[];
+}): React.JSX.Element | null;
+export interface ChartTooltipRow {
+    readonly label: string;
+    readonly value: string;
+    /** Theme token of the series swatch, e.g. `'--rf-chart-1'`. */
+    readonly token?: string;
+}
+/**
+ * The tooltip of the charts: follows the pointer, or sits by the mark that has the keyboard focus;
+ * rendered in a portal so the overflow or transform of a card never clips it. Values use the text
+ * tokens; only the swatch carries colour.
+ */
+export declare function useChartTooltip(): {
+    readonly show: (event: ReactPointerEvent, title: string, rows: readonly ChartTooltipRow[]) => void;
+    readonly showAt: (event: ReactFocusEvent<Element>, title: string, rows: readonly ChartTooltipRow[]) => void;
+    readonly hide: () => void;
+    readonly element: ReactNode;
+};
+/**
+ * The data of a chart as a table only screen readers read: its text alternative. `rows` are the
+ * buckets (a label and one formatted value per column).
+ */
+export declare function ChartDataTable({ caption, columns, rows }: {
+    caption: string;
+    columns: readonly string[];
+    rows: ReadonlyArray<{
+        label: string;
+        values: readonly string[];
+    }>;
+}): React.JSX.Element | null;
+/** What a chart shows with nothing to draw. */
+export declare function ChartEmpty({ height }: {
+    height: number;
+}): React.JSX.Element;
+/** The handlers of a hit area: the pointer, and the keyboard while the chart has few of them. */
+export declare function hitHandlers(tooltip: ReturnType<typeof useChartTooltip>, title: string, rows: readonly ChartTooltipRow[], keyboard: boolean): {
+    tabIndex?: number | undefined;
+    role?: "img" | undefined;
+    'aria-label'?: string | undefined;
+    onFocus?: ((event: ReactFocusEvent<Element>) => void) | undefined;
+    onBlur?: (() => void) | undefined;
+    className?: string | undefined;
+    onPointerMove: (event: ReactPointerEvent) => void;
+    onPointerLeave: () => void;
+};

package/dist/types/src/components/charts/ColumnCharts.d.ts

@@ -0,0 +1,85 @@
+import React from 'react';
+import { type ChartColor } from './chartCore';
+import { type ChartTooltipRow } from './ChartParts';
+export interface ColumnChartColumn {
+    readonly label: string;
+    readonly value: number;
+    /** Its own colour (e.g. the critical bucket); otherwise the colour of the chart. */
+    readonly color?: ChartColor;
+    /** Rows of its tooltip; by default its value. */
+    readonly tooltip?: readonly ChartTooltipRow[];
+}
+export interface ColumnChartMarker {
+    /** Position in column units: 0 the left edge of the first column, n the right edge of the last. */
+    readonly position: number;
+    readonly label: string;
+    readonly dashed?: boolean;
+}
+export interface ColumnChartProps {
+    columns: readonly ColumnChartColumn[];
+    /** Text alternative of the chart, also the caption of its data table. */
+    ariaLabel: string;
+    color?: ChartColor;
+    format?: (value: number) => string;
+    /** Vertical markers (a median, a percentile). */
+    markers?: readonly ColumnChartMarker[];
+    /** Label at the end of the horizontal axis. */
+    axisLabel?: string;
+    /** The value on top of each column (default true). */
+    showValues?: boolean;
+    height?: number;
+    className?: string;
+    onColumnClick?: (column: ColumnChartColumn, index: number) => void;
+}
+/** CR-112 — one series of columns (a distribution, ordered buckets), value labels on top, optional markers. */
+export declare function ColumnChart({ columns, ariaLabel, color, format: formatProp, markers, axisLabel, showValues, height, className, onColumnClick }: ColumnChartProps): React.JSX.Element;
+export interface ChartSeries {
+    readonly id: string;
+    readonly label: string;
+    /** A slot of the palette (1…8) or a theme token; by default the slot of its position. */
+    readonly color?: ChartColor;
+    readonly values: readonly number[];
+}
+export interface StackedColumnChartProps {
+    series: readonly ChartSeries[];
+    /** One label per bucket, on the horizontal axis. */
+    labels: readonly string[];
+    ariaLabel: string;
+    /** Title of the tooltip per bucket; by default its label. */
+    titles?: readonly string[];
+    /** One axis label every N buckets (the last always shown). */
+    labelEvery?: number;
+    format?: (value: number) => string;
+    /** The total of a comparison period per bucket, drawn as a dashed tick. */
+    comparison?: readonly number[];
+    comparisonLabel?: string;
+    height?: number;
+    className?: string;
+}
+/** CR-112 — columns per bucket, stacked by series, gliding between periods; optional comparison tick per column. */
+export declare function StackedColumnChart({ series, labels, ariaLabel, titles, labelEvery, format: formatProp, comparison, comparisonLabel, height, className }: StackedColumnChartProps): React.JSX.Element;
+export interface DivergingBar {
+    readonly label: string;
+    /** Above the zero line; null: no data (nothing drawn). */
+    readonly up: number | null;
+    /** Below the zero line; null: no data. */
+    readonly down: number | null;
+}
+export interface DivergingBarChartProps {
+    bars: readonly DivergingBar[];
+    upLabel: string;
+    downLabel: string;
+    ariaLabel: string;
+    upColor?: ChartColor;
+    downColor?: ChartColor;
+    titles?: readonly string[];
+    labelEvery?: number;
+    format?: (value: number) => string;
+    height?: number;
+    className?: string;
+}
+/**
+ * CR-112 — two quantities per bucket around a zero line, one scale for both sides (charged above,
+ * drawn below; income and costs). Buckets without data stay empty, data at zero shows a hairline.
+ */
+export declare function DivergingBarChart({ bars, upLabel, downLabel, ariaLabel, upColor, downColor, titles, labelEvery, format: formatProp, height, className }: DivergingBarChartProps): React.JSX.Element;

package/dist/types/src/components/charts/LineCharts.d.ts

@@ -0,0 +1,76 @@
+import React from 'react';
+import { type ChartColor } from './chartCore';
+export interface LineSeries {
+    readonly id: string;
+    readonly label: string;
+    readonly color?: ChartColor;
+    /** One value per label; null breaks the line (no data). */
+    readonly values: ReadonlyArray<number | null>;
+    /** A filled area under the line. */
+    readonly area?: boolean;
+    /** A comparison series: dashed, muted, no area. */
+    readonly dashed?: boolean;
+    /** A min–max band around the line (null: no band there). */
+    readonly band?: {
+        readonly min: ReadonlyArray<number | null>;
+        readonly max: ReadonlyArray<number | null>;
+    };
+}
+export interface LineChartProps {
+    series: readonly LineSeries[];
+    labels: readonly string[];
+    ariaLabel: string;
+    titles?: readonly string[];
+    labelEvery?: number;
+    format?: (value: number) => string;
+    /** A dashed line with a faint band above it (a limit). */
+    threshold?: {
+        readonly value: number;
+        readonly label: string;
+    };
+    /** A plain reference line (e.g. zero). */
+    baseline?: number;
+    /** The vertical range; by default from 0 to a rounded maximum of the data. */
+    domain?: readonly [number, number];
+    height?: number;
+    className?: string;
+}
+/**
+ * CR-112 — lines over time with a crosshair tooltip. Gaps (null) break a line; optional areas, a
+ * min–max band per series, a threshold with its band, a reference line. The lines draw themselves
+ * left to right.
+ */
+export declare function LineChart({ series, labels, ariaLabel, titles, labelEvery, format: formatProp, threshold, baseline, domain, height, className }: LineChartProps): React.JSX.Element;
+export interface AreaChartProps {
+    series: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly color?: ChartColor;
+        readonly values: readonly number[];
+    }[];
+    labels: readonly string[];
+    ariaLabel: string;
+    titles?: readonly string[];
+    labelEvery?: number;
+    format?: (value: number) => string;
+    /** Each series on top of the previous ones (default true): a cumulative flow, a composition. */
+    stacked?: boolean;
+    height?: number;
+    className?: string;
+}
+/**
+ * CR-112 — areas over time, stacked by default: the cumulative flow of work through its stages, the
+ * composition of a total. A crosshair shows every series and the total at a point.
+ */
+export declare function AreaChart({ series, labels, ariaLabel, titles, labelEvery, format: formatProp, stacked, height, className }: AreaChartProps): React.JSX.Element;
+export interface SparklineProps {
+    /** The trend; null leaves a gap. */
+    values: ReadonlyArray<number | null>;
+    color?: ChartColor;
+    height?: number;
+    className?: string;
+    /** Text alternative; without it the sparkline is decorative (beside the number it illustrates). */
+    ariaLabel?: string;
+}
+/** CR-112 — the trend line of a KPI tile: a filled area, the last point marked, gaps skipped. */
+export declare function Sparkline({ values, color, height, className, ariaLabel }: SparklineProps): React.JSX.Element;

package/dist/types/src/components/charts/ListCharts.d.ts

@@ -0,0 +1,73 @@
+import React from 'react';
+import { type ChartColor } from './chartCore';
+import { type ChartLegendItem, type ChartTooltipRow } from './ChartParts';
+export interface BarListRow {
+    readonly id: string;
+    readonly label: string;
+    readonly value: number;
+    /** A lighter bar behind the main one (e.g. the delivered behind the active). */
+    readonly background?: number;
+    readonly color?: ChartColor;
+    /** The text after the bar; by default the formatted value. */
+    readonly valueText?: string;
+    /** A note on the right with its own tone (a change over the previous period). */
+    readonly trailing?: {
+        readonly text: string;
+        readonly tone: 'good' | 'bad' | 'neutral';
+    };
+    readonly tooltip?: readonly ChartTooltipRow[];
+}
+export interface BarListProps {
+    rows: readonly BarListRow[];
+    ariaLabel: string;
+    color?: ChartColor;
+    format?: (value: number) => string;
+    /** The value of a full bar; by default the largest. */
+    max?: number;
+    /** Room for the labels, in px. */
+    labelWidth?: number;
+    legend?: readonly ChartLegendItem[];
+    className?: string;
+    onRowClick?: (row: BarListRow) => void;
+}
+/** CR-112 — horizontal bars, label on the left and value at the end: rankings, funnels, averages per group. */
+export declare function BarList({ rows, ariaLabel, color, format: formatProp, max: fixedMax, labelWidth, legend, className, onRowClick }: BarListProps): React.JSX.Element;
+export interface HeatmapProps {
+    /** values[row][column]. */
+    values: ReadonlyArray<readonly number[]>;
+    rowLabels: readonly string[];
+    /** One label per column; shown every `columnLabelEvery` columns. */
+    columnLabels: readonly string[];
+    columnLabelEvery?: number;
+    ariaLabel: string;
+    color?: ChartColor;
+    format?: (value: number) => string;
+    /** The title of a cell in its tooltip; by default its row and column. */
+    cellTitle?: (row: number, column: number) => string;
+    cellHeight?: number;
+    className?: string;
+}
+/** CR-112 — a grid of rows × columns (weekday × hour, agent × stage), one hue: darker is more. Cells light up in turn. */
+export declare function Heatmap({ values, rowLabels, columnLabels, columnLabelEvery, ariaLabel, color, format: formatProp, cellTitle, cellHeight, className }: HeatmapProps): React.JSX.Element;
+export interface CalendarHeatmapProps {
+    /** One entry per day (ISO date `YYYY-MM-DD`); null: no data that day. Days left out count as no data. */
+    days: ReadonlyArray<{
+        readonly date: string;
+        readonly value: number | null;
+    }>;
+    ariaLabel: string;
+    color?: ChartColor;
+    format?: (value: number) => string;
+    className?: string;
+}
+/** CR-112 — one square per day, weeks as columns from Monday: darker is more, a scale from less to more. */
+export declare function CalendarHeatmap({ days, ariaLabel, color, format: formatProp, className }: CalendarHeatmapProps): React.JSX.Element;
+/**
+ * CR-112 — a number that counts from the previous value (0 on first mount) to `value` with an
+ * ease-out, then shows `format(value)` exactly. Server rendering and reduced motion show it at once.
+ */
+export declare function AnimatedNumber({ value, format: formatProp, duration }: {
+    value: number;
+    format?: (value: number) => string;
+    duration?: number;
+}): React.JSX.Element;

package/dist/types/src/components/charts/ScatterChart.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { type ChartColor } from './chartCore';
+import { type ChartTooltipRow } from './ChartParts';
+export interface ScatterPoint {
+    readonly id: string;
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+    /** A third quantity as the area of the point (e.g. how many turns); all points the same without it. */
+    readonly size?: number;
+    /** The id of its series (its colour and legend); the first series without it. */
+    readonly series?: string;
+    /** Rows of its tooltip; by default its x, y and size. */
+    readonly tooltip?: readonly ChartTooltipRow[];
+}
+export interface ScatterChartProps {
+    points: readonly ScatterPoint[];
+    ariaLabel: string;
+    /** The groups of points: their label and colour, in the legend. */
+    series?: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly color?: ChartColor;
+    }[];
+    xLabel: string;
+    yLabel: string;
+    sizeLabel?: string;
+    formatX?: (value: number) => string;
+    formatY?: (value: number) => string;
+    formatSize?: (value: number) => string;
+    /** The label of each point next to it (default true with few points). */
+    showLabels?: boolean;
+    height?: number;
+    className?: string;
+    onPointClick?: (point: ScatterPoint) => void;
+}
+/**
+ * CR-112 — points by two quantities, an optional third as their area, coloured by series: cost against
+ * rework per model, speed against size. Axes from zero to rounded maxima; points fade in.
+ */
+export declare function ScatterChart({ points, ariaLabel, series, xLabel, yLabel, sizeLabel, formatX: formatXProp, formatY: formatYProp, formatSize: formatSizeProp, showLabels, height, className, onPointClick, }: ScatterChartProps): React.JSX.Element;

package/dist/types/src/components/charts/chartCore.d.ts

@@ -0,0 +1,36 @@
+import { type RefObject } from 'react';
+/**
+ * CR-112 — the shared parts of the charts: scales, colours, motion, width, number format.
+ * Colours are theme tokens: a series names one (`'--rf-chart-1'`, `'--rf-primary'`) or a slot of the
+ * categorical palette (`1…8`, `--rf-chart-N`); marks read them as `hsl(var(--token))`, so every chart
+ * follows the theme and its dark mode.
+ */
+/** A theme token (`'--rf-chart-2'`, `'--rf-success'`) or a slot of the categorical palette (1…8). */
+export type ChartColor = string | number;
+/** The CSS custom property of a chart colour; slots cycle through the eight of the palette. */
+export declare function chartToken(color: ChartColor | undefined, fallbackSlot?: number): string;
+/** `hsl(var(--token))`, with an optional alpha. */
+export declare const chartFill: (token: string, alpha?: number) => string;
+export declare const AXIS_TEXT = "hsl(var(--rf-muted-foreground))";
+export declare const GRID_LINE = "hsl(var(--rf-border))";
+/** Rounded axis maximum (1, 2, 2.5, 5 × 10ⁿ) at or above `value`. */
+export declare function niceMax(value: number): number;
+/** Evenly spaced ticks from `min` to `max`, both included. */
+export declare function ticks(min: number, max: number, count?: number): number[];
+/** The number format of the current locale (up to two decimals), the default of every chart. */
+export declare function useChartFormat(format?: (value: number) => string): (value: number) => string;
+/**
+ * Values that glide from what was shown before to `target` (from 0 on first mount), each mark
+ * `stagger` ms after the previous one, ease-out cubic. Reduced motion shows `target` at once.
+ */
+export declare function useAnimatedValues(target: readonly number[], duration?: number, stagger?: number): number[];
+/** 0 → 1 once per `key` change: for fades and lines that draw themselves. */
+export declare function useReveal(key: string, duration?: number, delay?: number): number;
+/**
+ * The rendered width of a chart's container in CSS pixels, kept current with a ResizeObserver: the
+ * charts use it as the width of their SVG viewBox, so text and marks keep their real size in a narrow
+ * card and in a wide one. `fallback` is used before the first measure (and in server rendering).
+ */
+export declare function useChartWidth<T extends HTMLElement = HTMLElement>(fallback: number): [RefObject<T | null>, number];
+/** Hit areas take the keyboard while there are few of them; with many, the data table stands in. */
+export declare const KEYBOARD_LIMIT = 40;

package/dist/types/src/components/charts/index.d.ts

@@ -0,0 +1,12 @@
+export { ColumnChart, StackedColumnChart, DivergingBarChart } from './ColumnCharts';
+export type { ColumnChartColumn, ColumnChartMarker, ColumnChartProps, ChartSeries, StackedColumnChartProps, DivergingBar, DivergingBarChartProps } from './ColumnCharts';
+export { LineChart, AreaChart, Sparkline } from './LineCharts';
+export type { LineSeries, LineChartProps, AreaChartProps, SparklineProps } from './LineCharts';
+export { ScatterChart } from './ScatterChart';
+export type { ScatterPoint, ScatterChartProps } from './ScatterChart';
+export { BarList, Heatmap, CalendarHeatmap, AnimatedNumber } from './ListCharts';
+export type { BarListRow, BarListProps, HeatmapProps, CalendarHeatmapProps } from './ListCharts';
+export { ChartLegend, ChartDataTable, useChartTooltip } from './ChartParts';
+export type { ChartLegendItem, ChartTooltipRow } from './ChartParts';
+export { chartToken, chartFill, niceMax, ticks, useAnimatedValues, useReveal, useChartWidth, useChartFormat } from './chartCore';
+export type { ChartColor } from './chartCore';

package/dist/types/src/components/index.d.ts

@@ -32,6 +32,7 @@ export * from './ui/GridSystem';
 export { default as Image } from './ui/Image';
 export { default as ImageAvatar } from './ui/ImageAvatar';
 export { default as Identicon, identiconPattern } from './ui/Identicon';
+export * from './charts';
 export { default as Loader } from './ui/Loader';
 export { default as LocaleSwitcher } from './ui/LocaleSwitcher';
 export type { LocaleSwitcherProps } from './ui/LocaleSwitcher';

package/llms-full.txt

@@ -867,6 +867,37 @@ utile quando un comando cambia famiglia sintattica (per esempio da `{{ ... }}` a
 <LayoutBuilder components={...} />
 ```
 
+### Charts (CR-112)
+Grafici SVG senza dipendenze, dal modulo `charts`. Colori come token del tema: `color` è uno slot della
+palette categoriale (`1…8` → `--rf-chart-N`, definiti in `globals.css` con la variante scura e
+sovrascrivibili dal consumer) o un token (`'--rf-success'`); le serie senza colore prendono lo slot
+della loro posizione. Larghezza dal contenitore (ResizeObserver), animazioni spente con
+`prefers-reduced-motion`, tooltip che segue il puntatore e la tastiera (le aree prendono il focus
+finché sono al massimo 40), tabella dei dati `sr-only` con `ariaLabel` come didascalia, stato vuoto
+`charts.noData`. `format` è facoltativo: di default il numero nella locale dell'app.
+
+```tsx
+<ColumnChart ariaLabel="CR chiuse al giorno" columns={[{ label: 'lun', value: 4 }]} markers={[{ position: 3.5, label: 'mediana', dashed: true }]} onColumnClick={(column) => {}} />
+<StackedColumnChart ariaLabel="Ore per agente" labels={days} labelEvery={2} format={(v) => `${v} h`}
+  series={[{ id: 'dev', label: 'Developer', values: dev }, { id: 'qa', label: 'Tester', values: qa, color: 3 }]}
+  comparison={previousTotals} comparisonLabel="periodo precedente" />
+<LineChart ariaLabel="Lead time" labels={days} threshold={{ value: 6.5, label: 'obiettivo' }} baseline={0} domain={[0, 10]}
+  series={[{ id: 'now', label: 'Ora', values: [3, null, 5], area: true, band: { min, max } }, { id: 'before', label: 'Prima', values: prev, dashed: true }]} />
+<AreaChart ariaLabel="Flusso cumulativo" labels={days} stacked series={[{ id: 'closed', label: 'Chiuse', values: closed }]} />
+<ScatterChart ariaLabel="Costo contro rework" xLabel="Costo" yLabel="Rework" sizeLabel="Turni"
+  series={[{ id: 'sonnet', label: 'Sonnet' }]} points={[{ id: '1', label: 'Developer', x: 0.04, y: 0.3, size: 30, series: 'sonnet' }]} onPointClick={(point) => {}} />
+<DivergingBarChart ariaLabel="Valore e costo" upLabel="Valore" downLabel="Costo" bars={[{ label: 'lun', up: 120, down: null }]} />
+<BarList ariaLabel="Costo per agente" rows={[{ id: 'dev', label: 'Developer', value: 1.84, trailing: { text: '+12%', tone: 'bad' } }]} />
+<Heatmap ariaLabel="Turni per ora" rowLabels={agents} columnLabels={hours} columnLabelEvery={2} values={matrix} />
+<CalendarHeatmap ariaLabel="Turni per giorno" days={[{ date: '2026-11-02', value: 4 }, { date: '2026-11-03', value: null }]} />
+<Sparkline values={[1, 3, null, 2]} ariaLabel="Andamento" />   // senza ariaLabel è decorativa
+<AnimatedNumber value={3.85} format={(v) => `$${v.toFixed(2)}`} />
+```
+
+Parti comuni per grafici propri: `useChartTooltip()` (`show`, `showAt`, `hide`, `element`), `ChartLegend`,
+`ChartDataTable`, `useChartWidth(fallback)`, `useAnimatedValues(values)`, `useReveal(key)`,
+`useChartFormat(format?)`, `chartToken(color)`, `chartFill(token, alpha?)`, `niceMax`, `ticks`.
+
 ---
 
 ## Blocks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnative/react",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "LLM-native React framework for deterministic UI generation. Data-driven by default, schema-driven optional. Ultra-low token consumption — built for AI agents, not just humans.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",