From ca53fe28b407304785592d5cdc56d0907340af48 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 02:08:40 +0000 Subject: [PATCH] docs(charts): rewrite the inline-series chart examples into the model the renderer implements Four chart nodes across three documentation and example sites authored the retired inline-data model -- a populated `series[].data` -- and paired it with month names in `categories`, which the renderer reads as a series list, not as axis labels. Every one of them rendered an empty chart: `normalizeSeries` has never read `series[].data`, and `categories` is ignored outright whenever `series` is present. Each is rewritten into the model `normalizeChartSchema` actually implements: rows on the chart node's own chart-level `data`, each series' `name` naming the column it plots within those rows, and `xAxisKey` naming the category column. The numbers and the visible intent of every example are preserved. `schema-reference.md`'s property table is corrected on the same reading: the `categories` row said "X-axis category labels" and now states the alternative-series-list meaning; the `series` row no longer advertises a `data` array and names the type correctly as `ChartDataSeries[]` (it had said `ChartSeries[]`, which `@objectstack/spec/ui` owns for the dataset-bound descriptor); and `data` / `xAxisKey` are added as the declared members they became. Measured, not assumed: all four corrected documents pass `ChartSchema.safeParse`, and both documents they replace are refused by name on `series[].data`'s retirement tombstone -- so the instrument was not blind. The corrected example also normalizes through `normalizeChartSchema` to `xAxisKey: 'month'` and series `['Revenue', 'Expenses']`, each a real column in every row, while the document it replaced resolved no axis at all. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0114Ytxr5sM1vdW19Y9WAx6E --- content/docs/api/schema-reference.md | 35 +++++++++++++++---- content/docs/core/report-schema.mdx | 10 ++++-- .../types/examples/data-display-examples.json | 12 +++++-- 3 files changed, 44 insertions(+), 13 deletions(-) diff --git a/content/docs/api/schema-reference.md b/content/docs/api/schema-reference.md index 5f36bd0247..f10051ebc8 100644 --- a/content/docs/api/schema-reference.md +++ b/content/docs/api/schema-reference.md @@ -457,29 +457,43 @@ A chart visualization supporting multiple chart types. "showLegend": true, "showGrid": true, "animate": true, - "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], + "xAxisKey": "month", + "data": [ + { "month": "Jan", "Revenue": 4200, "Expenses": 3100 }, + { "month": "Feb", "Revenue": 5100, "Expenses": 3400 }, + { "month": "Mar", "Revenue": 4800, "Expenses": 3200 }, + { "month": "Apr", "Revenue": 6200, "Expenses": 3800 }, + { "month": "May", "Revenue": 5800, "Expenses": 3600 }, + { "month": "Jun", "Revenue": 7100, "Expenses": 4000 } + ], "series": [ { "name": "Revenue", - "data": [4200, 5100, 4800, 6200, 5800, 7100], "color": "#3b82f6" }, { "name": "Expenses", - "data": [3100, 3400, 3200, 3800, 3600, 4000], "color": "#ef4444" } ] } ``` +The rows live on the chart node's own `data`, one object per row keyed by column +name. Each series' `name` (or `dataKey`) selects the column it plots within those +rows, and `xAxisKey` names the column on the category axis. A series carries no +numbers of its own: `ChartDataSeries.data` is a retirement tombstone +(objectui#6896) and an authored array is refused by name at parse. + | Property | Type | Description | |----------|------|-------------| | `chartType` | `ChartType` | **Required.** `"bar"`, `"line"`, `"area"`, `"pie"`, `"donut"`, `"radar"`, `"scatter"`, `"heatmap"`. | | `title` | `string` | Chart title. | | `description` | `string` | Chart description / subtitle. | -| `categories` | `string[]` | X-axis category labels. | -| `series` | `ChartSeries[]` | Data series, each with `name`, `data` array, and optional `color`. | +| `categories` | `string[]` | An **alternative series list** — column names to plot, read only when `series` is absent, and ignored outright when it is present. Not axis labels: the category axis comes from `xAxisKey`. | +| `series` | `ChartDataSeries[]` | Data series. Each entry's `name` (or `dataKey`) names the column it plots within a `data` row; optional `color` and a per-series `type` (`"bar"`, `"line"`, `"area"`) for combo charts. | +| `data` | `Array>` | Rows to plot — one object per row, keyed by column name. | +| `xAxisKey` | `string` | Row key holding the category (x) axis. The bare-string `xAxis: "month"` spelling folds onto this key at parse. | | `height` / `width` | `string \| number` | Chart dimensions. | | `showLegend` | `boolean` | Display the legend. | | `showGrid` | `boolean` | Display grid lines. | @@ -961,8 +975,15 @@ A widget-based dashboard with configurable grid layout and auto-refresh. "body": { "type": "chart", "chartType": "area", - "categories": ["Mon", "Tue", "Wed", "Thu", "Fri"], - "series": [{ "name": "Sales", "data": [120, 180, 150, 210, 190] }] + "xAxisKey": "day", + "data": [ + { "day": "Mon", "Sales": 120 }, + { "day": "Tue", "Sales": 180 }, + { "day": "Wed", "Sales": 150 }, + { "day": "Thu", "Sales": 210 }, + { "day": "Fri", "Sales": 190 } + ], + "series": [{ "name": "Sales" }] } }, { diff --git a/content/docs/core/report-schema.mdx b/content/docs/core/report-schema.mdx index f2548e3598..b808362741 100644 --- a/content/docs/core/report-schema.mdx +++ b/content/docs/core/report-schema.mdx @@ -318,12 +318,16 @@ const comprehensiveReport: ReportComponentSchema = { chart: { type: 'chart', chartType: 'line', - categories: ['January', 'February', 'March'], + xAxisKey: 'month', + data: [ + { month: 'January', Revenue: 120000 }, + { month: 'February', Revenue: 145000 }, + { month: 'March', Revenue: 132000 } + ], series: [ { name: 'Revenue', - type: 'line', - data: [120000, 145000, 132000] + type: 'line' } ] } diff --git a/packages/types/examples/data-display-examples.json b/packages/types/examples/data-display-examples.json index 6df723b2d4..73e3e63dd1 100644 --- a/packages/types/examples/data-display-examples.json +++ b/packages/types/examples/data-display-examples.json @@ -130,16 +130,22 @@ "chartType": "bar", "title": "Monthly Sales", "description": "Revenue breakdown by month", - "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], + "data": [ + { "month": "Jan", "Revenue": 12000, "Expenses": 8000 }, + { "month": "Feb", "Revenue": 15000, "Expenses": 9000 }, + { "month": "Mar", "Revenue": 18000, "Expenses": 11000 }, + { "month": "Apr", "Revenue": 14000, "Expenses": 10000 }, + { "month": "May", "Revenue": 22000, "Expenses": 13000 }, + { "month": "Jun", "Revenue": 25000, "Expenses": 14000 } + ], + "xAxisKey": "month", "series": [ { "name": "Revenue", - "data": [12000, 15000, 18000, 14000, 22000, 25000], "color": "#3b82f6" }, { "name": "Expenses", - "data": [8000, 9000, 11000, 10000, 13000, 14000], "color": "#ef4444" } ],