docs(spec): ReportSchema.chart says the chart draws below a matrix cross-tab (#20837)

Closes #20293

Clause-②: no

The `ReportSchema.chart` doc comment now says where the chart is drawn
for each report shape, as `DatasetReportRenderer` draws it at the
objectui pin `db11afd4967c`: above the table for `tabular`, `summary`
and a `matrix` without `columns`, and below the cross-tab for a `matrix`
with `columns`. The `joined` sentence drops its past-tense "parsed and
plotted nothing", because the key is refused today. The prose is 2 words
shorter than before. Doc comment only: the accept set, the `.describe()`
text and every generated artifact are unchanged. `liveness/report.json`
is unchanged, because its `chart` row says nothing about the matrix
branch.

Local runs at `e974c16441`: the `@objectstack/spec` build,
`check:generated` (all 15 up to date) and the full spec vitest run (578
files, 17065 passed, 1 todo). Of the 78 derived gates, 75 exit 0. The
other 3 exit 3 and are not measured, because a prerequisite package is
not built: `check:doc-formula-expressions`, `check:dual-build-cjs-loads`
and `check:lean-entry-closure`. The spec typecheck passed at
`e57c38f375`; the merge brought only JSON into `packages/spec`.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1)_

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

Author: objectstack-fleet[bot]

.changeset/report-chart-matrix-placement-comment.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the `ReportSchema.chart` doc comment says the chart is drawn below the table of a `matrix` report with `columns`
+
+Clause-②: no
+
+The doc comment on `ReportSchema.chart` said the embedded chart is plotted above the report's
+table. That holds for a `tabular` or `summary` report, and for a `matrix` report without
+`columns`, which renders as a grouped table. A `matrix` report with `columns` renders as a
+cross-tab, and objectui's `DatasetReportRenderer` draws the chart below it. The comment now
+says so. It also drops a clause saying a chart on a `joined` report "parsed and plotted
+nothing": the schema refuses that key today, so the clause no longer described it.
+
+Doc comment only: the schema accepts and refuses the same reports, and no `.describe()` text
+or export changes.

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

@@ -462,11 +462,11 @@ export const ReportSchema = lazySchema(() => strictObject({
 
   /**
    * Visualization — an embedded chart plotted from the bound dataset
-   * (`xAxis` names a dimension, `yAxis` a measure) above the report's table.
+   * (`xAxis` names a dimension, `yAxis` a measure) above the report's table,
+   * or below it for a `matrix` report with `columns`.
    *
-   * Refused on a `joined` report (#20161): a joined report draws each block
-   * as a table and never reads `chart`, and a block has no `chart` key — so a
-   * chart there parsed and plotted nothing.
+   * Refused on a `joined` report (#20161), which draws each block as a table
+   * and never reads `chart`; a block has no `chart` key.
    */
   chart: ReportChartSchema.optional().describe('Embedded chart configuration (refused on a joined report, which draws tables only)'),