docs(spec): correct ReportChart xAxis/yAxis semantics; mark dead report surface (#1890) (#3441)

Closes the report residual of the ADR-0021 analytics migration. The
dataset-bound report chart already renders (objectui DatasetReportRenderer
plots chart.xAxis/yAxis as the bound dataset's dimension/measure via
useDatasetRows; Studio ReportDefaultInspector picks them from the dataset
catalogs), but the spec describe() still called them raw fields.

- ReportChart.xAxis/yAxis describe now states dataset dimension/measure names.
- ReportChart.groupBy marked [EXPERIMENTAL — not enforced] (dataset renderer
  never reads it; only the legacy ReportViewer fallback did).
- ReportColumnSchema/ReportGroupingSchema marked @deprecated — unreferenced by
  the single-form report shape; kept only as public type exports pending a
  governed prune.

Docs regenerated. No shape/parse-behavior change; no export removed.


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

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

Author: os-zhuang

.changeset/report-chart-dataset-describe.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): correct ReportChart `xAxis`/`yAxis` semantics; mark dead report surface (#1890)
+
+Closes the report residual of the ADR-0021 analytics migration (#1890). The
+dataset-bound report chart already renders — objectui's `DatasetReportRenderer`
+plots `chart.xAxis`/`yAxis` as the bound dataset's **dimension**/**measure** via
+`useDatasetRows`, and the Studio `ReportDefaultInspector` picks them from the
+dataset's dimension/measure catalogs — but the spec `.describe()` still called
+them raw "Grouping field" / "Summary field", misleading an author (or AI) into
+naming object fields instead of dataset dimension/measure names.
+
+- `ReportChart.xAxis`/`yAxis` describe now states they are dataset
+  dimension/measure names (matching the live renderer + inspector).
+- `ReportChart.groupBy` marked `[EXPERIMENTAL — not enforced]` — the
+  dataset-bound renderer plots a single `xAxis`×`yAxis` series and never reads
+  it; only the legacy `ReportViewer` fallback did.
+- `ReportColumnSchema` / `ReportGroupingSchema` marked `@deprecated` — the
+  single-form report shape expresses columns/grouping as dataset
+  measure/dimension name arrays, so these objects are unreferenced; they remain
+  only as public type exports (objectui re-exports them) pending a governed
+  prune.
+
+Docs regenerated (`ui/report.mdx`). No shape or parse-behavior change; no
+export removed.

content/docs/references/ui/report.mdx

@@ -85,8 +85,8 @@ const result = JoinedReportBlock.parse(data);
 | **title** | `string` | optional | Chart title |
 | **subtitle** | `string` | optional | Chart subtitle |
 | **description** | `string` | optional | Accessibility description |
-| **xAxis** | `string` | ✅ | Grouping field for X-Axis |
-| **yAxis** | `string` | ✅ | Summary field for Y-Axis |
+| **xAxis** | `string` | ✅ | Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field) |
+| **yAxis** | `string` | ✅ | Dataset measure name for the Y-axis (bound-dataset measure, not a raw field) |
 | **series** | `{ name: string; label?: string; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; color?: string; … }[]` | optional | Defined series configuration |
 | **colors** | `string[] \| Record<string, string>` | optional | Color palette (string[]) or value→color map (`{ value: color }`) |
 | **height** | `number` | optional | Fixed height in pixels |
@@ -95,7 +95,7 @@ const result = JoinedReportBlock.parse(data);
 | **annotations** | `{ type: Enum<'line' \| 'region'>; axis: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional |  |
 | **interaction** | `{ tooltips: boolean; zoom: boolean; brush: boolean; clickAction?: string }` | optional |  |
 | **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes |
-| **groupBy** | `string` | optional | Additional grouping field |
+| **groupBy** | `string` | optional | [EXPERIMENTAL — not enforced] Additional series-split grouping; not read by the dataset-bound report renderer (liveness #1878/#1890) |
 
 
 ---

packages/spec/src/ui/report.zod.ts

@@ -22,6 +22,12 @@ export const ReportType = z.enum([
 
 /**
  * Report Column Schema
+ *
+ * @deprecated Unreferenced by the single-form (ADR-0021) report shape — a
+ * dataset-bound report selects `values` (measure names) and `rows`/`columns`
+ * (dimension names) as `z.array(z.string())`, not `ReportColumn` objects. Kept
+ * only as a public type export (objectui re-exports it as `SpecReportColumn`);
+ * slated for removal in a future governed prune (liveness #1878/#1890).
  */
 export const ReportColumnSchema = lazySchema(() => z.object({
   field: z.string().describe('Field name'),
@@ -33,6 +39,11 @@ export const ReportColumnSchema = lazySchema(() => z.object({
 
 /**
  * Report Grouping Schema
+ *
+ * @deprecated Unreferenced by the single-form (ADR-0021) report shape —
+ * grouping is expressed by dataset dimension names in `rows`/`columns`. Kept
+ * only as a public type export (objectui re-exports it as `SpecReportGrouping`);
+ * slated for removal in a future governed prune (liveness #1878/#1890).
  */
 export const ReportGroupingSchema = lazySchema(() => z.object({
   field: z.string().describe('Field to group by'),
@@ -42,13 +53,24 @@ export const ReportGroupingSchema = lazySchema(() => z.object({
 
 /**
  * Report Chart Schema
- * Embedded visualization configuration using unified chart taxonomy.
+ *
+ * A dataset-bound report chart (ADR-0021): `xAxis`/`yAxis` name the report's
+ * bound-dataset **dimension** and **measure** (NOT raw object fields) — the
+ * Studio inspector picks them from the dataset's dimension/measure catalogs
+ * and objectui's `DatasetReportRenderer` plots them via `useDatasetRows`.
  */
 export const ReportChartSchema = lazySchema(() => ChartConfigSchema.extend({
-  /** Report-specific chart configuration */
-  xAxis: z.string().describe('Grouping field for X-Axis'),
-  yAxis: z.string().describe('Summary field for Y-Axis'),
-  groupBy: z.string().optional().describe('Additional grouping field'),
+  /** Dataset **dimension** name for the X-axis (from the report's bound dataset). */
+  xAxis: z.string().describe('Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field)'),
+  /** Dataset **measure** name for the Y-axis (from the report's bound dataset). */
+  yAxis: z.string().describe('Dataset measure name for the Y-axis (bound-dataset measure, not a raw field)'),
+  /**
+   * ⚠️ EXPERIMENTAL — NOT ENFORCED (liveness #1878/#1890). An additional
+   * series-split grouping. The dataset-bound `DatasetReportRenderer` plots a
+   * single `xAxis`×`yAxis` series and does not read this; only the legacy
+   * `ReportViewer` fallback consumed a top-level `groupBy`.
+   */
+  groupBy: z.string().optional().describe('[EXPERIMENTAL — not enforced] Additional series-split grouping; not read by the dataset-bound report renderer (liveness #1878/#1890)'),
 }));
 
 /**