fix(charts): say so when rows carry no category key, instead of drawing an empty axis (#3007)

Rows that carry the measures but NOT the key the chart was told to plot
rendered an axis frame with ZERO marks — no throw, no console warning, no
legend. Measured before changing anything: `data: [{count:2},{count:8}]` with
`xAxisKey="issued"` produced an <svg> whose only text was the Y ticks
("02468") and 0 bar rectangles.

That output is indistinguishable from "the query matched nothing", and it is
the wrong conclusion. In framework#4033 an analytics bucket was grouped by but
never projected, so every trend widget silently drew nothing while the numbers
were right the whole time; the backend fix landed there, but nothing on this
side would have caught the next producer that drops a column.
framework#3701 was the same shape one layer over — a fieldless count keyed its
value `undefined` and the chart plotted nothing. Twice is a pattern.

The chart now renders an explanatory placeholder naming the missing key, and
warns once with BOTH halves of the mismatch (the key expected, the keys the
rows actually carry) — that pair is the whole diagnosis, and its absence is
what made #4033 expensive to find.

Deliberate choices:
- Not a throw. A dashboard widget must not take the page down over its own
  data, and an honest empty state is more actionable than a stack trace.
- Absence, not nullishness: `key in row` is false only when the producer never
  projected the column. A present-but-null value is a legitimate bucket (rows
  whose grouped dimension is empty collapse into one), and testing `== null`
  would condemn a working chart. Pinned by its own case.
- Category-axis chart types only. scatter plots two measures; treemap/sankey
  read hierarchy/link fields — flagging those would be a false alarm.
- The guard lives in a thin wrapper around the renderer. The condition depends
  on `data`, which arrives asynchronously, so an early return inside the
  renderer would change its hook count between renders.

plugin-charts: 98/98.

Refs objectstack-ai/objectstack#4033


Claude-Session: https://claude.ai/code/session_01TPxNwPnjcn599ujXpU3ibJ

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

packages/plugin-charts/src/AdvancedChartImpl.missingCategoryKey.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Unreadable-data guard (framework#4033).
+ *
+ * Rows that carry the measures but NOT the category key used to render an axis
+ * frame with ZERO marks: no throw, no console warning, no legend. Measured, not
+ * assumed — `data: [{count:2},{count:8}]` with `xAxisKey="issued"` produced an
+ * `<svg>` containing only the Y tick text `"02468"` and `0` bar rectangles.
+ *
+ * That is indistinguishable from "the query matched nothing", and it is the
+ * wrong conclusion: framework#4033's analytics bucket was grouped by but never
+ * projected, so trend widgets drew nothing while the numbers were right the
+ * whole time. framework#3701 was the same shape one layer over (a fieldless
+ * count keyed its value `undefined` and "the chart plotted nothing"). Twice is
+ * a pattern; the chart now says so instead of failing silently a third time.
+ */
+import React from 'react';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+
+vi.mock('recharts', async () => {
+  const actual = await vi.importActual<any>('recharts');
+  return {
+    ...actual,
+    ResponsiveContainer: ({ children }: any) =>
+      React.cloneElement(children, { width: 480, height: 320 }),
+  };
+});
+
+import AdvancedChartImpl from './AdvancedChartImpl';
+
+afterEach(cleanup);
+
+/** The #4033 shape: measures present, category key never projected. */
+const UNREADABLE = [{ count: 2 }, { count: 8 }];
+const READABLE = [
+  { issued: '2026-01', count: 2 },
+  { issued: '2026-02', count: 8 },
+];
+const SERIES = [{ dataKey: 'count', label: 'Count' }];
+
+const renderChart = (props: Record<string, unknown>) =>
+  render(<AdvancedChartImpl series={SERIES as any} {...(props as any)} />);
+
+describe('AdvancedChartImpl — unreadable-data guard (framework#4033)', () => {
+  it('explains itself instead of drawing an empty axis', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { container } = renderChart({
+      chartType: 'bar', data: UNREADABLE, xAxisKey: 'issued',
+    });
+
+    const placeholder = container.querySelector('[data-chart-error="missing-category-key"]');
+    expect(placeholder, 'renders the explanatory placeholder').not.toBeNull();
+    expect(placeholder?.textContent).toContain('issued');
+    // The old behaviour: an <svg> axis frame with no marks. Anything that still
+    // paints a plot here would be the silent failure this guard replaces.
+    expect(container.querySelector('svg')).toBeNull();
+    warn.mockRestore();
+  });
+
+  it('warns once, naming both the expected key and the keys actually present', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    renderChart({ chartType: 'bar', data: UNREADABLE, xAxisKey: 'issued' });
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = String(warn.mock.calls[0]?.[0] ?? '');
+    // Both halves of the mismatch — without the pair the author is left diffing
+    // a dataset against a chart spec by hand.
+    expect(msg).toContain('issued');
+    expect(msg).toContain('count');
+    warn.mockRestore();
+  });
+
+  it('stays out of the way when the category key IS present', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { container } = renderChart({
+      chartType: 'bar', data: READABLE, xAxisKey: 'issued',
+    });
+
+    expect(container.querySelector('[data-chart-error="missing-category-key"]')).toBeNull();
+    expect(container.querySelector('svg')).not.toBeNull();
+    expect(container.textContent).toContain('2026-01');
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('treats a present-but-NULL bucket as real data, not as breakage', () => {
+    // A grouped query legitimately buckets rows whose dimension is empty. The
+    // key is projected, the value is null — testing `== null` instead of
+    // `key in row` would have condemned a working chart.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { container } = renderChart({
+      chartType: 'bar',
+      data: [{ issued: null, count: 3 }, { issued: '2026-02', count: 8 }],
+      xAxisKey: 'issued',
+    });
+
+    expect(container.querySelector('[data-chart-error="missing-category-key"]')).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('says nothing about an empty result set — that is a legitimate answer', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { container } = renderChart({ chartType: 'bar', data: [], xAxisKey: 'issued' });
+
+    expect(container.querySelector('[data-chart-error="missing-category-key"]')).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('leaves scatter/treemap/sankey alone — they do not read a category axis', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    for (const chartType of ['scatter', 'treemap', 'sankey'] as const) {
+      const { container } = renderChart({ chartType, data: UNREADABLE, xAxisKey: 'issued' });
+      expect(
+        container.querySelector('[data-chart-error="missing-category-key"]'),
+        `${chartType} must not be flagged`,
+      ).toBeNull();
+      cleanup();
+    }
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('guards every category-axis chart type', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    for (const chartType of ['bar', 'column', 'horizontal-bar', 'line', 'area', 'pie', 'donut', 'radar', 'funnel', 'combo'] as const) {
+      const { container } = renderChart({ chartType, data: UNREADABLE, xAxisKey: 'issued' });
+      expect(
+        container.querySelector('[data-chart-error="missing-category-key"]'),
+        `${chartType} must be flagged`,
+      ).not.toBeNull();
+      cleanup();
+    }
+    warn.mockRestore();
+  });
+});

packages/plugin-charts/src/AdvancedChartImpl.tsx

@@ -184,6 +184,19 @@ export interface AdvancedChartImplProps {
   isAnimationActive?: boolean;
 }
 
+/**
+ * Chart types that plot a CATEGORY axis keyed by `xAxisKey`, and are therefore
+ * unreadable when no row carries that key (see the guard in the component).
+ *
+ * `scatter` is excluded on purpose: both of its axes are numeric measures, so a
+ * missing `xAxisKey` there is a different question. `treemap` and `sankey` are
+ * excluded because they read hierarchy/link fields, not a category axis — a
+ * guard that fired on them would be a false alarm on a working chart.
+ */
+const CATEGORY_AXIS_CHART_TYPES: ReadonlySet<string> = new Set([
+  'bar', 'horizontal-bar', 'line', 'area', 'pie', 'donut', 'radar', 'funnel', 'combo',
+]);
+
 /**
  * Treemap leaf cell — paints each leaf rect with its palette fill + label.
  * Hoisted to module scope so it is a stable component reference rather than one
@@ -228,7 +241,7 @@ function ChartFrame({ title, subtitle, children }: { title?: string; subtitle?:
  * AdvancedChartImpl - The heavy implementation that imports Recharts with full features
  * This component is lazy-loaded to avoid including Recharts in the initial bundle
  */
-export default function AdvancedChartImpl({
+function AdvancedChartImplInner({
   chartType: rawChartType = 'bar',
   data: rawData = [],
   config = {},
@@ -255,6 +268,7 @@ export default function AdvancedChartImpl({
   // 'column' is the spec-level alias for vertical bars; 'horizontal-bar' stays as-is.
   const chartType = rawChartType === 'column' ? 'bar' : rawChartType;
   const data = Array.isArray(rawData) ? rawData : [];
+
   // Only emit the prop when explicitly disabled, so the default (animated)
   // behavior is byte-for-byte unchanged for every existing caller.
   const animProps = isAnimationActive === false ? { isAnimationActive: false as const } : {};
@@ -1066,3 +1080,65 @@ export default function AdvancedChartImpl({
     </ChartFrame>
   );
 }
+
+
+/**
+ * Detect the framework#4033 shape from props alone: rows are present, the chart
+ * plots a category axis, and NOT ONE row carries the key it was told to plot.
+ */
+function hasNoCategoryKey(props: AdvancedChartImplProps): boolean {
+  const chartType = props.chartType === 'column' ? 'bar' : (props.chartType ?? 'bar');
+  const rows = Array.isArray(props.data) ? props.data : [];
+  const key = props.xAxisKey ?? 'name';
+  return (
+    CATEGORY_AXIS_CHART_TYPES.has(chartType) &&
+    rows.length > 0 &&
+    !rows.some((row) => row != null && typeof row === 'object' && key in row)
+  );
+}
+
+/**
+ * Public entry point. A THIN wrapper purely so the unreadable-data guard can
+ * short-circuit without breaking the rules of hooks: the condition depends on
+ * `data`, which arrives asynchronously, so an early return inside the renderer
+ * would change its hook count between renders. The wrapper's own hook list is
+ * fixed, and the renderer below is reached with data it can actually plot.
+ */
+export default function AdvancedChartImpl(props: AdvancedChartImplProps) {
+  const missingCategoryKey = hasNoCategoryKey(props);
+  const xAxisKey = props.xAxisKey ?? 'name';
+  const firstRowKeys = React.useMemo(
+    () => Object.keys((Array.isArray(props.data) ? props.data[0] : undefined) ?? {}),
+    [props.data],
+  );
+
+  React.useEffect(() => {
+    if (!missingCategoryKey) return;
+    // Names BOTH halves of the mismatch — the key the chart was told to plot and
+    // the keys the rows actually carry. That pair is the whole diagnosis;
+    // without it an author is left diffing a dataset against a chart spec by
+    // hand, which is exactly what made framework#4033 expensive to find.
+    console.warn(
+      `[chart] no row has the category key "${xAxisKey}" — rendering an explanatory ` +
+      `placeholder instead of an empty axis. Row keys: ${JSON.stringify(firstRowKeys)}. ` +
+      `A dataset query must PROJECT the dimension it groups by (framework#4033).`,
+    );
+  }, [missingCategoryKey, xAxisKey, firstRowKeys]);
+
+  if (missingCategoryKey) {
+    return (
+      <div
+        className={`flex h-full min-h-[120px] w-full items-center justify-center p-4 text-center text-sm text-muted-foreground ${props.className ?? ''}`}
+        role="status"
+        data-chart-error="missing-category-key"
+      >
+        <span>
+          This chart cannot plot its category axis: no row has a{' '}
+          <code className="font-mono">{xAxisKey}</code> field.
+        </span>
+      </div>
+    );
+  }
+
+  return <AdvancedChartImplInner {...props} />;
+}