@tensor_1/react 2.37.0 → 2.39.0

package/dist/chart.cjs

@@ -77,6 +77,8 @@ function uixChartTokens(source) {
     event: t("chart-event"),
     partial: t("chart-partial"),
     comparison: t("chart-comparison"),
+    warning: t("warning"),
+    danger: t("danger"),
     surface: t("surface"),
     text: t("text"),
     textMuted: t("text-muted"),
@@ -159,7 +161,8 @@ function uixChartPalette() {
   return [1, 2, 3, 4, 5, 6, 7, 8].map((i) => readToken(`--uix-chart-${i}`));
 }
 function themed(option, theme, element) {
-  return theme === "none" ? option : mergeChartTheme(uixChartTheme(element), option);
+  const resolved = typeof option === "function" ? option(uixChartTokens(element)) : option;
+  return theme === "none" ? resolved : mergeChartTheme(uixChartTheme(element), resolved);
 }
 function motionSafe(option) {
   if (typeof matchMedia !== "undefined" && matchMedia("(prefers-reduced-motion: reduce)").matches) {
@@ -190,17 +193,22 @@ function ChartCore({
   loading = false,
   empty,
   labels: labelOverrides,
-  theme = "uix"
+  theme = "uix",
+  group,
+  onEvents,
+  tables
 }) {
   const labels = { ...DEFAULT_CHART_LABELS, ...labelOverrides };
   const containerRef = (0, import_react.useRef)(null);
   const chartRef = (0, import_react.useRef)(null);
   const appliedOptionRef = (0, import_react.useRef)(null);
+  const onEventsRef = (0, import_react.useRef)(onEvents);
+  onEventsRef.current = onEvents;
   const latestOptionRef = (0, import_react.useRef)(option);
   const onReadyRef = (0, import_react.useRef)(onReady);
   const tableId = (0, import_react.useId)();
   const hasEmpty = empty != null;
-  const hasTextAlternative = Boolean(ariaLabel || title || tableData?.length);
+  const hasTextAlternative = Boolean(ariaLabel || title || tableData?.length || tables?.length);
   const hasTextAlternativeRef = (0, import_react.useRef)(hasTextAlternative);
   const themeRef = (0, import_react.useRef)(theme);
   latestOptionRef.current = option;
@@ -252,6 +260,29 @@ function ChartCore({
       appliedOptionRef.current = null;
     };
   }, [engine, hasEmpty]);
+  const eventNames = Object.keys(onEvents ?? {}).sort().join("|");
+  (0, import_react.useEffect)(() => {
+    const chart = chartRef.current;
+    if (!chart || !eventNames) return;
+    const bound = eventNames.split("|").map((name) => {
+      const handler = (params) => onEventsRef.current?.[name]?.(params);
+      chart.on(name, handler);
+      return [name, handler];
+    });
+    return () => {
+      if (chart.isDisposed()) return;
+      for (const [name, handler] of bound) chart.off(name, handler);
+    };
+  }, [engine, hasEmpty, eventNames]);
+  (0, import_react.useEffect)(() => {
+    const chart = chartRef.current;
+    if (!chart || !group) return;
+    chart.group = group;
+    engine.connect?.(group);
+    return () => {
+      if (!chart.isDisposed()) chart.group = "";
+    };
+  }, [engine, hasEmpty, group]);
   (0, import_react.useEffect)(() => {
     const chart = chartRef.current;
     const element = containerRef.current;
@@ -262,6 +293,8 @@ function ChartCore({
   const heightValue = typeof height === "number" ? `${height}px` : height;
   const effectiveAriaLabel = ariaLabel ?? title ?? labels.chart;
   const hasTable = Boolean(tableData?.length && tableHeaders?.length);
+  const extraTables = (tables ?? []).filter((table) => table.headers.length && table.rows.length);
+  const describedBy = [hasTable ? tableId : null, ...extraTables.map((_, index) => `${tableId}-${index}`)].filter(Boolean).join(" ") || void 0;
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: cx("uix-chart", className), style, children: [
     title != null || subtitle != null || header != null || headerAction != null ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "uix-chart__header", children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "uix-chart__heading", children: [
@@ -280,7 +313,7 @@ function ChartCore({
           style: { height: heightValue },
           role: "img",
           "aria-label": effectiveAriaLabel,
-          "aria-describedby": hasTable ? tableId : void 0
+          "aria-describedby": describedBy
         }
       )
     ] }),
@@ -288,6 +321,10 @@ function ChartCore({
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("thead", { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { children: tableHeaders.map((label) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("th", { scope: "col", children: label }, label)) }) }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tbody", { children: tableData.map((row, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { children: tableHeaders.map((label) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("td", { children: row[label] }, label)) }, index)) })
     ] }) : null,
+    extraTables.map((table, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("table", { id: `${tableId}-${index}`, className: "uix-visually-hidden", "aria-label": table.caption, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("thead", { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { children: table.headers.map((label) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("th", { scope: "col", children: label }, label)) }) }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tbody", { children: table.rows.map((row, rowIndex) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("tr", { children: table.headers.map((label) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("td", { children: row[label] }, label)) }, rowIndex)) })
+    ] }, index)),
     footer != null && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "uix-chart__footer", children: footer })
   ] });
 }

package/dist/chart.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { C as ChartProps } from './chart-theme-Cl0IrkKQ.cjs';
-export { a as ChartLabels, b as ChartLegend, c as ChartLegendItem, d as ChartLegendItemProps, e as ChartLegendProps, f as ChartMetric, g as ChartMetricProps, h as ChartTableRow, i as ChartTokenSource, D as DEFAULT_CHART_LABELS, U as UixChartTokens, m as mergeChartTheme, u as uixChartAreaGradient, j as uixChartPalette, k as uixChartTheme, l as uixChartTokens } from './chart-theme-Cl0IrkKQ.cjs';
+import { a as ChartProps } from './ChartCore-BKK2HEfi.cjs';
+export { c as ChartEventHandler, C as ChartLabels, d as ChartLegend, e as ChartLegendItem, f as ChartLegendItemProps, g as ChartLegendProps, h as ChartMetric, i as ChartMetricProps, j as ChartOption, k as ChartTable, l as ChartTableRow, m as ChartTokenSource, D as DEFAULT_CHART_LABELS, U as UixChartTokens, n as mergeChartTheme, u as uixChartAreaGradient, o as uixChartPalette, p as uixChartTheme, q as uixChartTokens } from './ChartCore-BKK2HEfi.cjs';
 import 'echarts';
 
 /** Full-compatibility adapter. Use `@tensor_1/react/chart/preset` for the lean preset. */

package/dist/chart.d.ts

@@ -1,5 +1,5 @@
 export { Chart } from './components/Chart.js';
-export { ChartLabels, ChartLegend, ChartLegendItem, ChartLegendItemProps, ChartLegendProps, ChartMetric, ChartMetricProps, ChartProps, ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette } from './components/ChartCore.js';
+export { ChartEventHandler, ChartLabels, ChartLegend, ChartLegendItem, ChartLegendItemProps, ChartLegendProps, ChartMetric, ChartMetricProps, ChartOption, ChartProps, ChartTable, ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette } from './components/ChartCore.js';
 export { ChartTokenSource, UixChartTokens, mergeChartTheme, uixChartAreaGradient, uixChartTheme, uixChartTokens } from './chart-theme.js';
 import 'react';
 import 'echarts';

package/dist/components/Chart.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ChartProps } from './ChartCore.js';
-export { ChartLabels, ChartLegend, ChartLegendItem, ChartLegendItemProps, ChartLegendProps, ChartMetric, ChartMetricProps, ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette } from './ChartCore.js';
+export { ChartEventHandler, ChartLabels, ChartLegend, ChartLegendItem, ChartLegendItemProps, ChartLegendProps, ChartMetric, ChartMetricProps, ChartOption, ChartTable, ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette } from './ChartCore.js';
 export { ChartTokenSource, UixChartTokens, mergeChartTheme, uixChartAreaGradient, uixChartTheme, uixChartTokens } from '../chart-theme.js';
 import 'echarts';
 

package/dist/components/ChartCore.d.ts

@@ -1,12 +1,25 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode, HTMLAttributes } from 'react';
 import { EChartsOption, ECharts } from 'echarts';
+import { UixChartTokens } from '../chart-theme.js';
 
 interface ChartEngine {
     init(element: HTMLElement, theme?: string | null, options?: {
         renderer?: 'svg' | 'canvas';
     }): ECharts;
+    /** Optional: links charts that share a `group` (one crosshair and tooltip across cards). */
+    connect?(group: string): void;
 }
+/** An option, or a function that builds it from the chart tokens of the current theme (re-run on a theme flip). */
+type ChartOption = EChartsOption | ((tokens: UixChartTokens) => EChartsOption);
+/** A further text alternative: one visually hidden table (ChartPanels gives one per panel). */
+interface ChartTable {
+    caption: string;
+    headers: string[];
+    rows: ChartTableRow[];
+}
+/** An ECharts event handler; `params` is ECharts' event object. */
+type ChartEventHandler = (params: unknown) => void;
 declare function uixChartPalette(): string[];
 interface ChartTableRow {
     [key: string]: string | number;
@@ -25,7 +38,8 @@ interface ChartLabels {
 }
 declare const DEFAULT_CHART_LABELS: ChartLabels;
 interface ChartProps {
-    option: EChartsOption;
+    /** The ECharts option, or a function of the theme's chart tokens (re-run when the theme flips). */
+    option: ChartOption;
     title?: string;
     subtitle?: string;
     height?: string | number;
@@ -47,12 +61,18 @@ interface ChartProps {
      * grid and the UIx tooltip — and re-applies it when the page theme changes. `'none'` renders `option` as is.
      */
     theme?: 'uix' | 'none';
+    /** Charts with the same group share one crosshair and tooltip (`echarts.connect`). */
+    group?: string;
+    /** ECharts event handlers by event name (`click` for drill-down). */
+    onEvents?: Record<string, ChartEventHandler>;
+    /** Further hidden data tables (after `tableData`), each named in the chart's description. */
+    tables?: ChartTable[];
 }
 interface ChartCoreProps extends ChartProps {
     engine: ChartEngine;
 }
 /** Shared chart lifecycle. Runtime adapters only choose the ECharts build. */
-declare function ChartCore({ engine, option, title, subtitle, height, className, style, ariaLabel, tableData, tableHeaders, onReady, header, headerAction, footer, loading, empty, labels: labelOverrides, theme, }: ChartCoreProps): react.JSX.Element;
+declare function ChartCore({ engine, option, title, subtitle, height, className, style, ariaLabel, tableData, tableHeaders, onReady, header, headerAction, footer, loading, empty, labels: labelOverrides, theme, group, onEvents, tables, }: ChartCoreProps): react.JSX.Element;
 interface ChartMetricProps extends HTMLAttributes<HTMLDivElement> {
     value: ReactNode;
     label?: ReactNode;
@@ -71,4 +91,4 @@ interface ChartLegendItemProps extends HTMLAttributes<HTMLLIElement> {
 }
 declare function ChartLegendItem({ label, color, swatch, className, style, ...props }: ChartLegendItemProps): react.JSX.Element;
 
-export { ChartCore, type ChartEngine, type ChartLabels, ChartLegend, ChartLegendItem, type ChartLegendItemProps, type ChartLegendProps, ChartMetric, type ChartMetricProps, type ChartProps, type ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette };
+export { ChartCore, type ChartEngine, type ChartEventHandler, type ChartLabels, ChartLegend, ChartLegendItem, type ChartLegendItemProps, type ChartLegendProps, ChartMetric, type ChartMetricProps, type ChartOption, type ChartProps, type ChartTable, type ChartTableRow, DEFAULT_CHART_LABELS, uixChartPalette };

package/dist/components/ChartCore.js

@@ -2,7 +2,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef } from "react";
 import { cx } from "../cx.js";
-import { mergeChartTheme, uixChartTheme } from "../chart-theme.js";
+import { mergeChartTheme, uixChartTheme, uixChartTokens } from "../chart-theme.js";
 function readToken(name) {
   if (typeof getComputedStyle === "undefined") return "";
   return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
@@ -11,7 +11,8 @@ function uixChartPalette() {
   return [1, 2, 3, 4, 5, 6, 7, 8].map((i) => readToken(`--uix-chart-${i}`));
 }
 function themed(option, theme, element) {
-  return theme === "none" ? option : mergeChartTheme(uixChartTheme(element), option);
+  const resolved = typeof option === "function" ? option(uixChartTokens(element)) : option;
+  return theme === "none" ? resolved : mergeChartTheme(uixChartTheme(element), resolved);
 }
 function motionSafe(option) {
   if (typeof matchMedia !== "undefined" && matchMedia("(prefers-reduced-motion: reduce)").matches) {
@@ -42,17 +43,22 @@ function ChartCore({
   loading = false,
   empty,
   labels: labelOverrides,
-  theme = "uix"
+  theme = "uix",
+  group,
+  onEvents,
+  tables
 }) {
   const labels = { ...DEFAULT_CHART_LABELS, ...labelOverrides };
   const containerRef = useRef(null);
   const chartRef = useRef(null);
   const appliedOptionRef = useRef(null);
+  const onEventsRef = useRef(onEvents);
+  onEventsRef.current = onEvents;
   const latestOptionRef = useRef(option);
   const onReadyRef = useRef(onReady);
   const tableId = useId();
   const hasEmpty = empty != null;
-  const hasTextAlternative = Boolean(ariaLabel || title || tableData?.length);
+  const hasTextAlternative = Boolean(ariaLabel || title || tableData?.length || tables?.length);
   const hasTextAlternativeRef = useRef(hasTextAlternative);
   const themeRef = useRef(theme);
   latestOptionRef.current = option;
@@ -104,6 +110,29 @@ function ChartCore({
       appliedOptionRef.current = null;
     };
   }, [engine, hasEmpty]);
+  const eventNames = Object.keys(onEvents ?? {}).sort().join("|");
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart || !eventNames) return;
+    const bound = eventNames.split("|").map((name) => {
+      const handler = (params) => onEventsRef.current?.[name]?.(params);
+      chart.on(name, handler);
+      return [name, handler];
+    });
+    return () => {
+      if (chart.isDisposed()) return;
+      for (const [name, handler] of bound) chart.off(name, handler);
+    };
+  }, [engine, hasEmpty, eventNames]);
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart || !group) return;
+    chart.group = group;
+    engine.connect?.(group);
+    return () => {
+      if (!chart.isDisposed()) chart.group = "";
+    };
+  }, [engine, hasEmpty, group]);
   useEffect(() => {
     const chart = chartRef.current;
     const element = containerRef.current;
@@ -114,6 +143,8 @@ function ChartCore({
   const heightValue = typeof height === "number" ? `${height}px` : height;
   const effectiveAriaLabel = ariaLabel ?? title ?? labels.chart;
   const hasTable = Boolean(tableData?.length && tableHeaders?.length);
+  const extraTables = (tables ?? []).filter((table) => table.headers.length && table.rows.length);
+  const describedBy = [hasTable ? tableId : null, ...extraTables.map((_, index) => `${tableId}-${index}`)].filter(Boolean).join(" ") || void 0;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-chart", className), style, children: [
     title != null || subtitle != null || header != null || headerAction != null ? /* @__PURE__ */ jsxs("div", { className: "uix-chart__header", children: [
       /* @__PURE__ */ jsxs("div", { className: "uix-chart__heading", children: [
@@ -132,7 +163,7 @@ function ChartCore({
           style: { height: heightValue },
           role: "img",
           "aria-label": effectiveAriaLabel,
-          "aria-describedby": hasTable ? tableId : void 0
+          "aria-describedby": describedBy
         }
       )
     ] }),
@@ -140,6 +171,10 @@ function ChartCore({
       /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", { children: tableHeaders.map((label) => /* @__PURE__ */ jsx("th", { scope: "col", children: label }, label)) }) }),
       /* @__PURE__ */ jsx("tbody", { children: tableData.map((row, index) => /* @__PURE__ */ jsx("tr", { children: tableHeaders.map((label) => /* @__PURE__ */ jsx("td", { children: row[label] }, label)) }, index)) })
     ] }) : null,
+    extraTables.map((table, index) => /* @__PURE__ */ jsxs("table", { id: `${tableId}-${index}`, className: "uix-visually-hidden", "aria-label": table.caption, children: [
+      /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", { children: table.headers.map((label) => /* @__PURE__ */ jsx("th", { scope: "col", children: label }, label)) }) }),
+      /* @__PURE__ */ jsx("tbody", { children: table.rows.map((row, rowIndex) => /* @__PURE__ */ jsx("tr", { children: table.headers.map((label) => /* @__PURE__ */ jsx("td", { children: row[label] }, label)) }, rowIndex)) })
+    ] }, index)),
     footer != null && /* @__PURE__ */ jsx("div", { className: "uix-chart__footer", children: footer })
   ] });
 }

package/dist/components/ChartPanels.d.ts

@@ -0,0 +1,52 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ChartLabels, ChartEngine } from './ChartCore.js';
+import { ChartPanelsSpec, ChartPanelsLabels } from '../chart-panels-model.js';
+import { ChartX, ChartEvent } from '../chart-analytic-model.js';
+import { CorrelationScatterSpec, CorrelationScatterLabels, CorrelationPoint } from '../correlation-scatter-model.js';
+import 'echarts';
+import '../chart-theme.js';
+import '../chart-stats.js';
+
+interface ChartFrameProps {
+    /** Accessible name of the whole chart. Required: a chart without one tells a screen reader nothing. */
+    ariaLabel: string;
+    title?: string;
+    subtitle?: string;
+    header?: ReactNode;
+    headerAction?: ReactNode;
+    footer?: ReactNode;
+    loading?: boolean;
+    empty?: ReactNode;
+    className?: string;
+    /** Charts with the same group share one crosshair across cards. */
+    group?: string;
+}
+interface ChartPanelsProps extends ChartPanelsSpec, ChartFrameProps {
+    labels?: Partial<ChartPanelsLabels> & Partial<ChartLabels>;
+    /** A click on a panel's point. */
+    onPointClick?: (panelId: string, x: ChartX) => void;
+    /** A click on an event pin. Without a handler, an event with `href` navigates there. */
+    onEventClick?: (event: ChartEvent) => void;
+    /** Show the legend (series of multi-series panels, comparison, projection). Default: when there is one. */
+    legend?: boolean;
+}
+/** Aligned panels on one time axis with one crosshair (HAR-1554). Different units never share an axis. */
+declare function ChartPanelsCore({ engine, x, panels, events, partialLast, zoom, ariaLabel, title, subtitle, header, headerAction, footer, loading, empty, className, group, labels, onPointClick, onEventClick, legend, }: ChartPanelsProps & {
+    engine: ChartEngine;
+}): react.JSX.Element;
+interface CorrelationScatterProps extends CorrelationScatterSpec, ChartFrameProps {
+    labels?: Partial<CorrelationScatterLabels> & Partial<ChartLabels>;
+    /** Show r, n and "association, not cause" under the plot. Default true. */
+    showStats?: boolean;
+    /** Plot height in px. Default 280. */
+    height?: number;
+    /** A click on a point. Without a handler, a point with `href` navigates there. */
+    onPointClick?: (point: CorrelationPoint) => void;
+}
+/** How two variables move together: dots, a trend line, r and n, and an optional breaking point (HAR-1554). */
+declare function CorrelationScatterCore({ engine, points, xLabel, yLabel, trend, percentiles, thresholds, breakpoint, minPoints, ariaLabel, title, subtitle, header, headerAction, footer, loading, empty, className, group, labels, showStats, height, onPointClick, }: CorrelationScatterProps & {
+    engine: ChartEngine;
+}): react.JSX.Element;
+
+export { ChartPanelsCore, type ChartPanelsProps, CorrelationScatterCore, type CorrelationScatterProps };

package/dist/components/ChartPanels.js

@@ -0,0 +1,170 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { ChartCore, ChartLegend, ChartLegendItem } from "./ChartCore.js";
+import { chartPanelsModel } from "../chart-panels-model.js";
+import { DEFAULT_CORRELATION_SCATTER_LABELS, correlationScatterModel } from "../correlation-scatter-model.js";
+const CSS_VAR_TOKENS = {
+  palette: [1, 2, 3, 4, 5, 6, 7, 8].map((i) => `var(--uix-chart-${i})`),
+  neutral: "var(--uix-chart-neutral)",
+  grid: "var(--uix-chart-grid)",
+  axis: "var(--uix-chart-axis)",
+  reference: "var(--uix-chart-reference)",
+  zoneWarning: "var(--uix-chart-zone-warning)",
+  zoneDanger: "var(--uix-chart-zone-danger)",
+  forecastBand: "var(--uix-chart-forecast-band)",
+  event: "var(--uix-chart-event)",
+  partial: "var(--uix-chart-partial)",
+  comparison: "var(--uix-chart-comparison)",
+  warning: "var(--uix-warning)",
+  danger: "var(--uix-danger)",
+  surface: "var(--uix-surface)",
+  text: "var(--uix-text)",
+  textMuted: "var(--uix-text-muted)",
+  border: "var(--uix-border-strong)",
+  fontSans: "inherit",
+  fontMono: "inherit"
+};
+function ChartPanelsCore({
+  engine,
+  x,
+  panels,
+  events,
+  partialLast,
+  zoom,
+  ariaLabel,
+  title,
+  subtitle,
+  header,
+  headerAction,
+  footer,
+  loading,
+  empty,
+  className,
+  group,
+  labels,
+  onPointClick,
+  onEventClick,
+  legend
+}) {
+  const spec = useMemo(() => ({ x, panels, events, partialLast, zoom }), [x, panels, events, partialLast, zoom]);
+  const layout = useMemo(() => chartPanelsModel(spec, CSS_VAR_TOKENS, labels), [spec, labels]);
+  const option = useMemo(() => (tokens) => chartPanelsModel(spec, tokens, labels).option, [spec, labels]);
+  const onEvents = useMemo(() => ({
+    click: (raw) => {
+      const params = raw;
+      const value = Array.isArray(params.value) ? params.value : [];
+      if (params.seriesId && params.seriesId === layout.laneSeriesId) {
+        const event = spec.events?.[Number(value[2])];
+        if (!event) return;
+        if (onEventClick) onEventClick(event);
+        else if (event.href && typeof window !== "undefined") window.location.assign(event.href);
+        return;
+      }
+      const panelId = params.seriesId ? layout.seriesPanel[params.seriesId] : void 0;
+      if (panelId && onPointClick) onPointClick(panelId, value[0] ?? params.name);
+    }
+  }), [layout, spec.events, onEventClick, onPointClick]);
+  const showLegend = legend ?? layout.legend.length > 0;
+  const legendNode = showLegend && layout.legend.length ? /* @__PURE__ */ jsx(ChartLegend, { children: layout.legend.map((item) => /* @__PURE__ */ jsx(ChartLegendItem, { label: item.label, color: item.color, swatch: item.swatch }, `${item.swatch}:${item.label}`)) }) : null;
+  const footerNode = legendNode || footer != null ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    legendNode,
+    footer
+  ] }) : void 0;
+  return /* @__PURE__ */ jsx(
+    ChartCore,
+    {
+      engine,
+      option,
+      height: layout.height,
+      ariaLabel,
+      title,
+      subtitle,
+      header,
+      headerAction,
+      footer: footerNode,
+      loading,
+      empty,
+      className,
+      group,
+      labels,
+      onEvents,
+      tables: layout.tables
+    }
+  );
+}
+function CorrelationScatterCore({
+  engine,
+  points,
+  xLabel,
+  yLabel,
+  trend,
+  percentiles,
+  thresholds,
+  breakpoint,
+  minPoints,
+  ariaLabel,
+  title,
+  subtitle,
+  header,
+  headerAction,
+  footer,
+  loading,
+  empty,
+  className,
+  group,
+  labels,
+  showStats = true,
+  height = 280,
+  onPointClick
+}) {
+  const spec = useMemo(
+    () => ({ points, xLabel, yLabel, trend, percentiles, thresholds, breakpoint, minPoints }),
+    [points, xLabel, yLabel, trend, percentiles, thresholds, breakpoint, minPoints]
+  );
+  const layout = useMemo(() => correlationScatterModel(spec, CSS_VAR_TOKENS, labels), [spec, labels]);
+  const option = useMemo(() => (tokens) => correlationScatterModel(spec, tokens, labels).option, [spec, labels]);
+  const usable = useMemo(() => spec.points.filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y)), [spec.points]);
+  const onEvents = useMemo(() => ({
+    click: (raw) => {
+      const params = raw;
+      if (params.seriesId !== layout.hitSeriesId || !Array.isArray(params.value)) return;
+      const point = usable[Number(params.value[2])];
+      if (!point) return;
+      if (onPointClick) onPointClick(point);
+      else if (point.href && typeof window !== "undefined") window.location.assign(point.href);
+    }
+  }), [layout.hitSeriesId, usable, onPointClick]);
+  const notEnough = !layout.enough ? /* @__PURE__ */ jsx("span", { className: "uix-chart__insufficient", children: (labels?.notEnough ?? DEFAULT_CORRELATION_SCATTER_LABELS.notEnough)(layout.n, layout.minPoints) }) : null;
+  const stats = showStats && layout.enough ? /* @__PURE__ */ jsx("p", { className: "uix-chart__stats", children: layout.statsText }) : null;
+  const footerNode = stats || footer != null ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    stats,
+    footer
+  ] }) : void 0;
+  return /* @__PURE__ */ jsx(
+    ChartCore,
+    {
+      engine,
+      option,
+      height,
+      ariaLabel,
+      title,
+      subtitle,
+      header,
+      headerAction,
+      footer: footerNode,
+      loading,
+      empty: empty ?? notEnough ?? void 0,
+      className,
+      group,
+      labels,
+      onEvents,
+      tableHeaders: layout.table.headers,
+      tableData: layout.table.rows
+    }
+  );
+}
+export {
+  ChartPanelsCore,
+  CorrelationScatterCore
+};

package/dist/components/InsightCard.d.ts

@@ -0,0 +1,86 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+type InsightStatusTone = 'ok' | 'warning' | 'critical' | 'unknown';
+interface InsightStatus {
+    tone: InsightStatusTone;
+    /** The words: the status is always readable without its colour or icon. */
+    label: string;
+}
+interface InsightComparison {
+    text: ReactNode;
+    /** Direction × whether that direction is good; `neutral` when it is neither. */
+    tone?: 'neutral' | 'positive' | 'negative' | 'warning';
+}
+interface InsightTarget {
+    actual: number;
+    target: number;
+    /** Qualitative bands from the start of the scale, e.g. [[0, 10], [10, 15], [15, 24]]. */
+    ranges?: [number, number][];
+    /** The scale's end. Default: the larger of the last range, the actual and the target, plus 10 %. */
+    max?: number;
+}
+interface InsightKpi {
+    value: ReactNode;
+    label: ReactNode;
+    comparison?: InsightComparison;
+    target?: InsightTarget;
+}
+interface InsightCoverage {
+    covered: number;
+    total: number;
+    /** What was counted, e.g. "changes classified". */
+    note: ReactNode;
+    /** Shown when the last period is still filling up. */
+    partialPeriod?: ReactNode;
+}
+/** Every word the card writes itself. English defaults in {@link DEFAULT_INSIGHT_CARD_LABELS}. */
+interface InsightCardLabels {
+    /** "412 of 431 changes classified (96%)". */
+    coverage: (covered: number, total: number, percent: number, note: ReactNode) => ReactNode;
+    /** The bullet's accessible description. */
+    bullet: (actual: string, target: string) => string;
+    source: string;
+    updated: string;
+    kpis: string;
+    formatNumber: (value: number) => string;
+}
+declare const DEFAULT_INSIGHT_CARD_LABELS: InsightCardLabels;
+interface InsightCardProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    eyebrow?: ReactNode;
+    /** The answer, as a sentence (≤ 10 words reads best). */
+    headline: ReactNode;
+    /** The implication and the suggested decision. */
+    sowhat?: ReactNode;
+    status?: InsightStatus;
+    kpis?: InsightKpi[];
+    coverage?: InsightCoverage;
+    /** One drill-down action (a link or button). */
+    actions?: ReactNode;
+    source?: ReactNode;
+    updated?: ReactNode;
+    /** `split` puts the aside on the right when the card is ≥ 60rem (960 px) wide; below, it stacks. */
+    layout?: 'stack' | 'split';
+    /**
+     * `card` (default) draws its own border and surface. `plain` draws none, for a card that sits
+     * inside another frame (a dashboard widget), so there is no card inside a card.
+     */
+    variant?: 'card' | 'plain';
+    aside?: ReactNode;
+    /** The headline's heading level. Default 3. */
+    headingLevel?: 2 | 3 | 4;
+    labels?: Partial<InsightCardLabels>;
+    children?: ReactNode;
+}
+declare function InsightCard({ eyebrow, headline, sowhat, status, kpis, coverage, actions, source, updated, layout, variant, aside, headingLevel, labels: labelOverrides, className, children, ...props }: InsightCardProps): react.JSX.Element;
+interface BulletProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'>, InsightTarget {
+    /** The accessible description, e.g. "18.7 h against a target of 15 h". */
+    label: string;
+}
+/**
+ * A bullet graph (Few): grey qualitative bands, a dark bar for the actual, a tick for the target.
+ * It replaces a gauge: the comparison is a length on one scale, not an angle.
+ */
+declare function Bullet({ actual, target, ranges, max, label, className, style, ...props }: BulletProps): react.JSX.Element;
+
+export { Bullet, type BulletProps, DEFAULT_INSIGHT_CARD_LABELS, InsightCard, type InsightCardLabels, type InsightCardProps, type InsightComparison, type InsightCoverage, type InsightKpi, type InsightStatus, type InsightStatusTone, type InsightTarget };