@seed-ship/mcp-ui-solid 6.23.0 → 6.24.0

package/src/components/chart-missing-plugin.ts

@@ -0,0 +1,334 @@
+/**
+ * Missing values in a Chart.js chart (v6.24.0) — everything the renderer adds
+ * to its Chart.js config when a payload says a value is MISSING (`null`).
+ *
+ * The rule: absence is never zero. Chart.js already keeps the slot of a `null`
+ * (no label dropped) and draws nothing for it; what it does not do is make the
+ * absence READABLE. A null bar is a zero-height bar that is skipped when
+ * drawn, a null line point is a hole the line may bridge (`spanGaps`), and the
+ * legend, tooltip and axis know nothing of either. This module supplies:
+ *
+ * - {@link createMissingValuesPlugin} — a PER-CHART plugin (never
+ *   `Chart.register`ed, so it can leak into no other chart) that outlines a
+ *   dashed stub where a bar should have been (not on stacked or overlaid
+ *   bars, whose baseline belongs to another series), and says "no data" on a
+ *   chart with nothing to draw;
+ * - {@link createMissingLegendGenerator} — marks a fully-missing series in the
+ *   legend;
+ * - {@link createTooltipLabel} — names a missing value, and appends the unit;
+ * - {@link withDatasetsNoGapSpan} — the shallow-cloned data with
+ *   `spanGaps: false`;
+ * - {@link applyUnitAxisTitle} — the unit as the value axis title.
+ *
+ * Runtime-free on purpose (no `solid-js`, no `chart.js` import): the renderer
+ * hands in the Chart.js pieces it loaded and the chrome strings (lazily, as
+ * getters, so a late locale change is honoured at draw time). Every function
+ * is defensive — a drawing hook that throws would blank the whole chart.
+ *
+ * Chart.js 4.5.1 facts this relies on (verified in `dist/chart.js`):
+ * - a bar whose parsed value is `null` gets `base = head = vScale.getBasePixel()`
+ *   and no `skip` flag (BarController.updateElements), and `BarController.draw`
+ *   skips it (`getParsed(i)[vScale.axis] !== null`) — so nothing is painted;
+ * - the bar element still carries its true index-axis thickness (`width` for a
+ *   vertical bar, `height` for a horizontal one).
+ */
+
+import type { MCPUIStrings } from '../context/MCPUIStringsContext';
+import { formatMCPUIString } from '../utils/format-string';
+import { isMissingChartValue } from '../utils/missing-value';
+
+type Strings = Required<MCPUIStrings>;
+
+/** Length, in px along the value axis, of the dashed stub of a missing bar. */
+export const MISSING_BAR_STUB_LENGTH = 12;
+/** Stroke of the stub when the dataset names no border colour. */
+export const MISSING_BAR_FALLBACK_COLOR = '#9ca3af';
+/** Colour of the centred "no data" text. */
+export const NO_DATA_TEXT_COLOR = '#6b7280';
+const STUB_DASH = [4, 3];
+
+/** Chart types whose value axis is `y` and whose points are `{x, y}`. */
+const POINT_CHART_TYPES = new Set(['scatter', 'bubble']);
+
+/**
+ * The category of convention line a chart shows under its canvas:
+ * `'gaps'` (a line breaks), `'bars'` (a dashed outline stands in for the
+ * bar) or `'omitted'` (nothing is drawn: scatter, bubble, stacked bars).
+ */
+export type MissingNoteKind = 'gaps' | 'bars' | 'omitted';
+
+/**
+ * Whether a bar chart's bars are stacked or overlaid (`stacked` on either
+ * axis). A missing bar there has no slot of its own at the baseline — the
+ * baseline belongs to the series below — so no dashed outline is drawn.
+ */
+export function isStackedChart(options: any): boolean {
+  return Boolean(options?.scales?.x?.stacked || options?.scales?.y?.stacked);
+}
+
+/** Which convention note a chart gets: how ITS missing values are drawn. */
+export function missingNoteKind(chartType: string | undefined, options?: any): MissingNoteKind {
+  if (chartType === 'bar') return isStackedChart(options) ? 'omitted' : 'bars';
+  if (chartType === 'scatter' || chartType === 'bubble') return 'omitted';
+  return 'gaps';
+}
+
+// ─── Data ──────────────────────────────────────────────────────────────────
+
+/**
+ * Chart.js data with every dataset shallow-cloned and `spanGaps: false`, so a
+ * line breaks at a missing value instead of joining its neighbours. Never
+ * mutates its input; `labels` and every other key are carried by reference.
+ */
+export function withDatasetsNoGapSpan<D extends { datasets?: unknown }>(data: D): D {
+  const datasets = Array.isArray(data?.datasets) ? data.datasets : null;
+  if (!datasets) return data;
+  return {
+    ...data,
+    datasets: datasets.map((dataset: unknown) =>
+      dataset !== null && typeof dataset === 'object'
+        ? { ...(dataset as object), spanGaps: false }
+        : dataset
+    ),
+  };
+}
+
+// ─── Legend ────────────────────────────────────────────────────────────────
+
+type LegendGenerator = (chart: any) => any[];
+
+/**
+ * Wraps a Chart.js legend label generator so a fully-missing dataset reads
+ * `"{series} (no data)"` (`strings.chartLegendNoData`). Every other item is
+ * passed through untouched.
+ */
+export function createMissingLegendGenerator(
+  base: LegendGenerator,
+  fullyMissing: readonly boolean[],
+  getStrings: () => Strings
+): LegendGenerator {
+  return function generateLabels(this: unknown, chart: any) {
+    const items = base.call(this, chart);
+    if (!Array.isArray(items)) return items;
+    return items.map((item) => {
+      const index = item?.datasetIndex;
+      if (typeof index !== 'number' || !fullyMissing[index]) return item;
+      const text = typeof item.text === 'string' ? item.text : String(item.text ?? '');
+      return {
+        ...item,
+        text: formatMCPUIString(getStrings().chartLegendNoData, { series: text }),
+      };
+    });
+  };
+}
+
+// ─── Tooltip ───────────────────────────────────────────────────────────────
+
+/** Whether a Chart.js tooltip item stands for a missing value. */
+export function isMissingTooltipItem(item: any): boolean {
+  if (item === null || item === undefined) return false;
+  if (item.raw === null || item.raw === undefined || isMissingChartValue(item.raw)) return true;
+  const parsed = item.parsed;
+  if (parsed !== null && typeof parsed === 'object') {
+    const chartType = item.chart?.config?.type;
+    const valueKey =
+      chartType === 'radar' ? 'r' : item.chart?.options?.indexAxis === 'y' ? 'x' : 'y';
+    if (valueKey in parsed && parsed[valueKey] === null) return true;
+  }
+  return false;
+}
+
+/**
+ * Tooltip `label` callback: names a missing value (`"{series}: Missing
+ * value"`) and, with a `unit`, appends it to a present one. Otherwise it is
+ * Chart.js's default composition (dataset label, `": "`, formatted value) —
+ * including its `mode: 'dataset'` branch, which prefixes the CATEGORY label
+ * instead, since every item of that tooltip belongs to the same dataset.
+ * Hence a regular function: Chart.js calls it with the tooltip as `this`.
+ *
+ * `unit` is left off scatter and bubble tooltips: their formatted value is the
+ * pair `(x, y)`, to which one unit does not belong.
+ */
+export function createTooltipLabel(
+  getStrings: () => Strings,
+  unit: string | undefined,
+  chartType: string | undefined
+): (this: any, item: any) => string {
+  const applyUnit = unit !== undefined && !POINT_CHART_TYPES.has(chartType ?? '');
+  return function label(this: any, item: any) {
+    const strings = getStrings();
+    const prefixLabel = this?.options?.mode === 'dataset' ? item?.label : item?.dataset?.label;
+    const prefix = typeof prefixLabel === 'string' && prefixLabel !== '' ? `${prefixLabel}: ` : '';
+
+    if (isMissingTooltipItem(item)) return `${prefix}${strings.missingValue}`;
+
+    const formatted = item?.formattedValue;
+    if (formatted === null || formatted === undefined) return prefix;
+    const value = applyUnit
+      ? formatMCPUIString(strings.chartValueWithUnit, { value: formatted, unit: unit as string })
+      : String(formatted);
+    return `${prefix}${value}`;
+  };
+}
+
+// ─── Axis ──────────────────────────────────────────────────────────────────
+
+/**
+ * Sets the chart's `unit` as the title of its value axis, in place on the
+ * `options` object the renderer just built (never on the payload's).
+ *
+ * Only bar, line, scatter and bubble have a value axis to title. The value
+ * axis is `y`, or `x` when the index axis is `y` (a horizontal bar or line).
+ * An existing `scales[axis].title` is the payload's own word and is kept; the
+ * rest of the scale config (a `timeAxis` block sets `scales.x`) is kept too.
+ */
+export function applyUnitAxisTitle(
+  options: any,
+  chartType: string | undefined,
+  unit: string | undefined
+): void {
+  if (unit === undefined) return;
+  if (chartType !== 'bar' && chartType !== 'line' && !POINT_CHART_TYPES.has(chartType ?? '')) {
+    return;
+  }
+  const horizontal = (chartType === 'bar' || chartType === 'line') && options?.indexAxis === 'y';
+  const axis = horizontal ? 'x' : 'y';
+  if (options.scales?.[axis]?.title !== undefined) return;
+  options.scales = {
+    ...options.scales,
+    [axis]: { ...options.scales?.[axis], title: { display: true, text: unit } },
+  };
+}
+
+// ─── Plugin ────────────────────────────────────────────────────────────────
+
+export interface MissingValuesPluginOptions {
+  /** At least one dataset and every one of them has no observed value. */
+  allMissing: boolean;
+  /** Lazy: read at draw time. */
+  getNoDataText: () => string;
+  /** Lazy: `Chart.defaults.font.family`, when the build exposes it. */
+  getFontFamily?: () => string | undefined;
+}
+
+/** A dataset colour for entry `index`, as a string, or `undefined`. */
+function colorAt(color: unknown, index: number): string | undefined {
+  if (typeof color === 'string' && color !== '') return color;
+  if (Array.isArray(color) && color.length > 0) {
+    const picked = color[index % color.length];
+    return typeof picked === 'string' && picked !== '' ? picked : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Draws a dashed outline stub for every missing bar of every visible,
+ * non-stacked bar dataset, so a missing value is a visible mark, not a bar
+ * that "is" zero.
+ *
+ * The stub sits on the value-axis base, as thick as the bar would have been,
+ * and runs {@link MISSING_BAR_STUB_LENGTH}px toward the middle of the chart
+ * area (up from a bottom baseline, down from a top one, right from a left
+ * one). Clipped to the chart area.
+ */
+export function drawMissingBarStubs(chart: any): void {
+  const ctx = chart?.ctx;
+  const area = chart?.chartArea;
+  const datasets = chart?.data?.datasets;
+  if (!ctx || !area || !Array.isArray(datasets)) return;
+
+  const left = area.left;
+  const top = area.top;
+  const right = area.right ?? left + (area.width ?? 0);
+  const bottom = area.bottom ?? top + (area.height ?? 0);
+
+  let saved = false;
+  datasets.forEach((dataset: any, datasetIndex: number) => {
+    const meta = chart.getDatasetMeta?.(datasetIndex);
+    if (!meta) return;
+    const isBar = meta.type === 'bar' || meta.controller?.constructor?.id === 'bar';
+    if (!isBar) return;
+    // Stacked or overlaid bars: the baseline under a missing segment is the
+    // series below, so an outline there would point at the wrong series.
+    if (meta.vScale?.options?.stacked || meta.iScale?.options?.stacked) return;
+    if (typeof chart.isDatasetVisible === 'function' && !chart.isDatasetVisible(datasetIndex)) {
+      return;
+    }
+    const values: unknown[] = Array.isArray(dataset?.data) ? dataset.data : [];
+    const elements: any[] = Array.isArray(meta.data) ? meta.data : [];
+
+    values.forEach((value, index) => {
+      if (!isMissingChartValue(value)) return;
+      const element = elements[index];
+      if (!element) return;
+      const props = element.getProps?.(['x', 'y', 'base', 'width', 'height'], true) ?? element;
+      const { x, y, base, width, height } = props;
+      if (![x, y, base].every((n) => Number.isFinite(n))) return;
+      const horizontal = element.horizontal === true;
+      const thickness = horizontal ? height : width;
+      if (!Number.isFinite(thickness) || thickness <= 0) return;
+
+      let rect: [number, number, number, number];
+      if (horizontal) {
+        const dir = base < (left + right) / 2 ? 1 : -1;
+        rect = [Math.min(base, base + dir * MISSING_BAR_STUB_LENGTH), y - thickness / 2, MISSING_BAR_STUB_LENGTH, thickness];
+      } else {
+        const dir = base > (top + bottom) / 2 ? -1 : 1;
+        rect = [x - thickness / 2, Math.min(base, base + dir * MISSING_BAR_STUB_LENGTH), thickness, MISSING_BAR_STUB_LENGTH];
+      }
+
+      if (!saved) {
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(left, top, right - left, bottom - top);
+        ctx.clip();
+        saved = true;
+      }
+      ctx.strokeStyle = colorAt(dataset?.borderColor, index) ?? MISSING_BAR_FALLBACK_COLOR;
+      ctx.lineWidth = 1;
+      ctx.setLineDash(STUB_DASH);
+      ctx.strokeRect(...rect);
+    });
+  });
+  if (saved) {
+    ctx.setLineDash?.([]);
+    ctx.restore();
+  }
+}
+
+/** Draws `text` centred in the chart area (a chart with nothing to plot). */
+export function drawNoDataText(chart: any, text: string, fontFamily?: string): void {
+  const ctx = chart?.ctx;
+  const area = chart?.chartArea;
+  if (!ctx || !area || !text) return;
+  const cx = (area.left + (area.right ?? area.left + (area.width ?? 0))) / 2;
+  const cy = (area.top + (area.bottom ?? area.top + (area.height ?? 0))) / 2;
+  ctx.save();
+  ctx.font = `12px ${fontFamily || 'sans-serif'}`;
+  ctx.fillStyle = NO_DATA_TEXT_COLOR;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(text, cx, cy);
+  ctx.restore();
+}
+
+/**
+ * The per-chart plugin object. Passed as `config.plugins = [plugin]`: Chart.js
+ * scopes it to that one chart. Both hooks swallow their own errors — a
+ * decoration must never take the chart down.
+ */
+export function createMissingValuesPlugin(options: MissingValuesPluginOptions) {
+  return {
+    id: 'mcpuiMissingValues',
+    afterDatasetsDraw(chart: any) {
+      try {
+        drawMissingBarStubs(chart);
+        if (options.allMissing) {
+          drawNoDataText(chart, options.getNoDataText(), options.getFontFamily?.());
+        }
+      } catch {
+        // Cosmetic layer: never break the chart.
+      }
+    },
+  };
+}

package/src/context/MCPUIStringsContext.tsx

@@ -823,6 +823,70 @@ export interface MCPUIStrings {
   sizeKilobytes?: string
   /** ArtifactRenderer file size in megabytes. Template — `{size}`. */
   sizeMegabytes?: string
+
+  // ── Missing values (tables, chart data views, charts) ──────
+  /**
+   * Accessible name of a value that is explicitly missing: read by screen
+   * readers in place of the `-` a table cell shows, and the tooltip value of
+   * a bar whose value is `null`.
+   * @since 6.24.0
+   */
+  missingValue?: string
+  /**
+   * Legend under a table or data view that contains at least one missing
+   * value. Template — `{marker}` = the glyph the cells show (`-`).
+   * @since 6.24.0
+   */
+  missingValueLegend?: string
+  /**
+   * Note under a line or radar chart with a missing value: the line is broken
+   * there rather than drawn through, or down to zero.
+   * @since 6.24.0
+   */
+  chartMissingGaps?: string
+  /**
+   * Note under a bar chart with a missing value, which the chart draws as a
+   * dashed outline at the baseline so it cannot be read as a zero bar.
+   * @since 6.24.0
+   */
+  chartMissingBars?: string
+  /**
+   * Note under a chart that draws nothing for a missing value — a scatter or
+   * bubble chart, or a stacked bar chart (whose baseline belongs to the series
+   * below, so no outline can stand in for the bar).
+   * @since 6.24.0
+   */
+  chartMissingPoints?: string
+  /**
+   * Note naming the series whose values are ALL missing.
+   * Template — `{series}` = the series names, joined as a list in the locale.
+   * @since 6.24.0
+   */
+  chartSeriesNoData?: string
+  /**
+   * Legend entry of a series whose values are all missing.
+   * Template — `{series}` = the series name.
+   * @since 6.24.0
+   */
+  chartLegendNoData?: string
+  /**
+   * A value followed by the chart's `unit`, in tooltips.
+   * Template — `{value}` (already formatted), `{unit}`.
+   * @since 6.24.0
+   */
+  chartValueWithUnit?: string
+  /**
+   * A column header followed by the chart's `unit`, in the chart data view
+   * and the degraded tables. Template — `{label}`, `{unit}`.
+   * @since 6.24.0
+   */
+  chartLabelWithUnit?: string
+  /**
+   * Shown instead of a pie, doughnut or polar-area chart that received a
+   * missing value: those types would draw it as a zero share.
+   * @since 6.24.0
+   */
+  chartMissingUnsupported?: string
 }
 
 /**
@@ -1125,6 +1189,18 @@ export const DEFAULT_MCPUI_STRINGS: Required<MCPUIStrings> = {
   zoomOut: 'Zoom out',
   zoomReset: 'Reset zoom',
   zoomLevel: 'Zoom {percent}%',
+
+  // ── 6.24.0 — missing values ────────────────────────────────
+  missingValue: 'Missing value',
+  missingValueLegend: '“{marker}” marks a missing value.',
+  chartMissingGaps: 'Breaks in a line mark missing values.',
+  chartMissingBars: 'Dashed outlines mark missing values.',
+  chartMissingPoints: 'Missing values are not plotted.',
+  chartSeriesNoData: 'No data for {series}.',
+  chartLegendNoData: '{series} (no data)',
+  chartValueWithUnit: '{value} {unit}',
+  chartLabelWithUnit: '{label} ({unit})',
+  chartMissingUnsupported: 'This chart type cannot show missing values.',
 }
 
 /**

package/src/services/component-registry.ts

@@ -50,14 +50,15 @@ export const QuickchartRegistry: ComponentRegistryEntry = {
                 data: {
                   // Empty arrays match both branches; mirror Zod's inclusive union.
                   anyOf: [
-                    { type: 'array', items: { type: 'number' } },
+                    // `null` is an explicit MISSING value (v6.24.0): never a zero.
+                    { type: 'array', items: { type: ['number', 'null'] } },
                     {
                       type: 'array',
                       items: {
                         type: 'object',
                         properties: {
                           x: { oneOf: [{ type: 'string' }, { type: 'number' }] },
-                          y: { type: 'number' },
+                          y: { type: ['number', 'null'] },
                           r: { type: 'number', minimum: 0 },
                         },
                         required: ['x', 'y'],
@@ -110,6 +111,13 @@ export const QuickchartRegistry: ComponentRegistryEntry = {
           max: { type: 'string' },
         },
       },
+      unit: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 32,
+        description:
+          'Unit of the values (e.g. "°C", "%"): shown on the value axis, in tooltips and in the data view',
+      },
       height: { type: 'string', description: 'Chart container height as a CSS value' },
       className: { type: 'string' },
     },

package/src/services/validation.ts

@@ -45,6 +45,8 @@ import type {
 // Runtime-free template helper: `src/validation.ts` (the SSR-safe subpath)
 // re-exports this module, so it must stay free of any solid-js import.
 import { formatMCPUIString } from '../utils/format-string';
+// Runtime-free as well (v6.24.0): the missing-value rules shared with the renderers.
+import { PART_TO_WHOLE_CHART_TYPES } from '../utils/missing-value';
 
 /**
  * All known ComponentType values — used to distinguish known-but-unvalidated
@@ -477,38 +479,71 @@ export function validateChartComponent(
     }
   }
 
-  // Data type validation — numbers for categorical, {x,y} objects for point charts
+  // Data type validation — numbers for categorical, {x,y} objects for point charts.
+  //
+  // `null` is an explicit missing value (v6.24.0): a number slot, or a point's
+  // `y`, that exists but was not observed. Line, bar, radar, scatter and bubble
+  // charts keep its slot and mark it. Pie, doughnut and polar-area charts
+  // cannot: Chart.js parses a null share as `0`, so the other shares and the
+  // wedge itself would all be drawn wrong — those types refuse it.
+  const missingUnsupported = PART_TO_WHOLE_CHART_TYPES.has(chartType);
   for (const [index, dataset] of params.data.datasets.entries()) {
     if (!Array.isArray(dataset.data)) continue;
     const datasetIsPointChart = chartType === 'scatter' || chartType === 'bubble' || usesPoints(dataset.data);
     for (const [dataIndex, value] of dataset.data.entries()) {
+      const path = `params.data.datasets[${index}].data[${dataIndex}]`;
       if (datasetIsPointChart) {
         const vObj = value as any;
         if (
           typeof value !== 'object' ||
           value === null ||
           vObj.x == null ||
-          typeof vObj.y !== 'number' ||
+          (vObj.y !== null && typeof vObj.y !== 'number') ||
           (vObj.r !== undefined && (typeof vObj.r !== 'number' || !Number.isFinite(vObj.r) || vObj.r < 0))
         ) {
           errors.push({
-            path: `params.data.datasets[${index}].data[${dataIndex}]`,
-            message: `Invalid point data: expected {x, y} object`,
+            path,
+            message: `Invalid point data: expected {x, y} object (y may be null for a missing value)`,
             code: 'INVALID_POINT_DATA',
           });
+        } else if (missingUnsupported && vObj.y === null) {
+          errors.push({
+            path,
+            message: `Missing value (null) is not supported by '${chartType}' charts, which would draw it as a zero share — use a bar or line chart, or a table`,
+            code: 'MISSING_VALUE_UNSUPPORTED',
+          });
         }
-      } else {
-        if (typeof value !== 'number' || !Number.isFinite(value)) {
+      } else if (value === null) {
+        if (missingUnsupported) {
           errors.push({
-            path: `params.data.datasets[${index}].data[${dataIndex}]`,
-            message: `Invalid data value: ${value} (must be finite number)`,
-            code: 'INVALID_DATA_TYPE',
+            path,
+            message: `Missing value (null) is not supported by '${chartType}' charts, which would draw it as a zero share — use a bar or line chart, or a table`,
+            code: 'MISSING_VALUE_UNSUPPORTED',
           });
         }
+      } else if (typeof value !== 'number' || !Number.isFinite(value)) {
+        errors.push({
+          path,
+          message: `Invalid data value: ${value} (must be a finite number, or null for a missing value)`,
+          code: 'INVALID_DATA_TYPE',
+        });
       }
     }
   }
 
+  // `unit` (v6.24.0) ends up in the value-axis title, in every tooltip and in
+  // the data-view headers: a short string, or nothing. An empty string is
+  // tolerated — the renderer treats it as "no unit" — so a producer that
+  // emits `unit: ''` does not lose its whole chart over it.
+  const unit = (params as { unit?: unknown }).unit;
+  if (unit !== undefined && (typeof unit !== 'string' || unit.length > 32)) {
+    errors.push({
+      path: 'params.unit',
+      message: 'Invalid unit: expected a string of at most 32 characters',
+      code: 'INVALID_UNIT',
+    });
+  }
+
   return {
     valid: errors.length === 0,
     errors: errors.length > 0 ? errors : undefined,

package/src/types/index.ts

@@ -81,7 +81,13 @@ export interface ChartComponentParams {
     labels: string[]
     datasets: Array<{
       label: string
-      data: number[] | Array<{ x: string | number; y: number; r?: number }>
+      /**
+       * `null` is an explicit missing value (v6.24.0): its label keeps its
+       * slot, a line breaks there, a bar shows a dashed outline — never a
+       * zero. Pie, doughnut and polar-area charts reject it, since they
+       * would draw it as a zero share.
+       */
+      data: Array<number | null> | Array<{ x: string | number; y: number | null; r?: number }>
       backgroundColor?: string | string[]
       borderColor?: string | string[]
       borderWidth?: number
@@ -135,6 +141,12 @@ export interface ChartComponentParams {
    * Custom CSS class (Sprint 7)
    */
   className?: string
+  /**
+   * Unit of every value in the chart (`'mm'`, `'km/h'`), shown as the value
+   * axis title (unless `options.scales` already sets one), after each tooltip
+   * value, and in the data-view column headers (v6.24.0). One unit per chart.
+   */
+  unit?: string
 }
 
 /**

package/src/utils/degraded-projections.ts

@@ -12,6 +12,7 @@
  */
 
 import { formatMCPUIString } from './format-string';
+import { isMissingChartValue } from './missing-value';
 
 /**
  * Column headers and series names of the degraded tables.
@@ -46,10 +47,17 @@ export interface DegradedProjectionLabels {
   feature: string;
   /** Chart table — fallback dataset name. Template — `{n}`. */
   series: string;
+  /**
+   * Chart table — a dataset column header followed by the chart's `unit`.
+   * Template — `{label}`, `{unit}`. Only applied when the chart has a unit.
+   * Optional so that a complete labels table written for 6.20.0–6.23.0 still
+   * type-checks. @since v6.24.0
+   */
+  withUnit?: string;
 }
 
 /** English defaults for {@link DegradedProjectionLabels}. */
-export const DEGRADED_PROJECTION_LABELS: DegradedProjectionLabels = {
+export const DEGRADED_PROJECTION_LABELS: Required<DegradedProjectionLabels> = {
   source: 'Source',
   target: 'Target',
   label: 'Label',
@@ -61,6 +69,7 @@ export const DEGRADED_PROJECTION_LABELS: DegradedProjectionLabels = {
   marker: 'marker',
   feature: 'feature',
   series: 'Series {n}',
+  withUnit: '{label} ({unit})',
 };
 
 const withLabels = (labels?: Partial<DegradedProjectionLabels>): DegradedProjectionLabels => ({
@@ -73,6 +82,12 @@ export interface DegradedTable {
   rows: Array<Array<string | number>>;
 }
 
+/** A degraded chart table: its cells, plus which of them are missing values. */
+export interface DegradedChartTable extends DegradedTable {
+  /** Same shape as `rows`; `true` for a dataset entry that is missing. @since v6.24.0 */
+  missing: boolean[][];
+}
+
 const MAX_PROJECTED_ROWS = 200;
 
 /** Compact a value to a single table cell string. */
@@ -188,25 +203,50 @@ export function mapToDegradedTable(params: {
  * Chart → a series table: one row per label, one column per dataset. So a
  * chart that can't draw still shows its numbers. Point/object data (scatter,
  * bubble, time series) is stringified per cell.
+ *
+ * `missing` flags the cells whose dataset entry is a missing value (`null`
+ * or non-finite) so the table can mark them instead of showing an empty
+ * cell. A slot past the end of a shorter or empty dataset has no entry and is
+ * not flagged; a point object keeps its JSON text (where a `"y":null` reads
+ * as such) and is not flagged either. With a `unit`, dataset column headers
+ * become `labels.withUnit`.
  */
 export function chartToDegradedTable(params: {
+  unit?: string;
   data?: {
     labels?: Array<string | number>;
     datasets?: Array<{ label?: string; data?: unknown[] }>;
   };
-}, labels?: Partial<DegradedProjectionLabels>): DegradedTable {
+}, labels?: Partial<DegradedProjectionLabels>): DegradedChartTable {
   const l = withLabels(labels);
+  const unit = typeof params.unit === 'string' && params.unit !== '' ? params.unit : undefined;
   const datasets = params.data?.datasets ?? [];
   const dataLabels = params.data?.labels ?? [];
   const rowCount = Math.max(dataLabels.length, ...datasets.map((d) => d.data?.length ?? 0), 0);
 
   const columns = [
     '',
-    ...datasets.map((d, i) => d.label ?? formatMCPUIString(l.series, { n: i + 1 })),
+    ...datasets.map((d, i) => {
+      const name = d.label ?? formatMCPUIString(l.series, { n: i + 1 });
+      return unit === undefined
+        ? name
+        : formatMCPUIString(l.withUnit ?? DEGRADED_PROJECTION_LABELS.withUnit, { label: name, unit });
+    }),
   ];
   const rows: Array<Array<string | number>> = [];
+  const missing: boolean[][] = [];
   for (let r = 0; r < Math.min(rowCount, MAX_PROJECTED_ROWS); r++) {
     rows.push([cell(dataLabels[r] ?? r + 1), ...datasets.map((d) => cell(d.data?.[r]))]);
+    missing.push([
+      false,
+      ...datasets.map((d) => {
+        // Past the end of a shorter or empty dataset there is no entry, so
+        // nothing to flag (the cell stays empty, as before 6.24.0).
+        if (r >= (d.data?.length ?? 0)) return false;
+        const entry = d.data?.[r];
+        return (entry === null || typeof entry !== 'object') && isMissingChartValue(entry);
+      }),
+    ]);
   }
-  return { columns, rows };
+  return { columns, rows, missing };
 }