Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 49f7672

Browse files
fix(plugin-report): a matrix report with columns draws its declared chart beside the cross-tab (objectui#10964) (#11043)
Fixes #10964 Clause-②: no ## What A `matrix` report that declares `columns` now draws its declared `chart` below the cross-tab. `ReportSchema` accepts that shape, but the cross-tab branch of `DatasetReportRenderer` returned `DatasetMatrixTable` before the only `report.chart` read, so the chart parsed and drew nothing. The non-joined presentations now share one wrapper and one chart slot. `DatasetReportChart` runs its own `chart.xAxis` × `chart.yAxis` dataset query, so it binds the same way next to a cross-tab as next to a grouped table: `xAxis` names a dataset dimension (a matrix `rows` or `columns` dimension) and `yAxis` a dataset measure. The chart still comes before a tabular or summary table (and before a matrix without `columns`, which degrades to the grouped table), and it comes after the cross-tab. The ruling on objectstack-ai/objectstack#20293 places it "beside or below the cross-tab", and below needs no new layout option. Landing site: `packages/plugin-report/src/DatasetReportRenderer.tsx`, as the card and the claim name it. ## Premises measured on objectui `origin/main` `3ad61001b` - Mechanism assumption 1 holds: the `presentation === 'matrix' && across.length > 0` branch returned before the `chartCfg` / `report.chart` read. - Mechanism assumption 2 holds, so the stop valve did not fire. `DatasetReportChart` queries `[chart.xAxis]` × `[chart.yAxis]` over `report.dataset` through `useDatasetRows`, independent of the table next to it, and `scopeOrder` already narrows `report.order` to that pair. No new binding rule is involved. On the spec side, objectstack's `validate-chart-bindings` (`packages/lint`) already treats a chart on every non-`joined` report as drawn (`drawsChart` is `report.type !== 'joined'`) and binds `chart.xAxis` to a dataset dimension and `chart.yAxis` to a dataset measure: the binding this renderer now honours on the matrix arm too. - Mechanism assumption 3 holds: no example carries a matrix report with both `columns` and a `chart`, so the pin builds its own document. ## Also changed, because this round made it false - The out-of-spec chart-type notice said "the grouped table below carries this report's numbers". On a matrix the notice now sits after the cross-tab, so it names no position: "the report's table carries its numbers". Code comments that said the table sits "beneath" the chart slot now say "beside". - The matrix wrapper now carries the same `flex flex-col gap-3` classes and `data-report-presentation` attribute the other non-joined presentations carry. `git grep` finds no reader of `data-report-presentation` outside the renderer. - Docs (AGENTS.md commandment 2): the "Embedded chart" sections of `packages/plugin-report/README.md` and `content/docs/plugins/plugin-report.mdx` say where the chart draws for each type. Prose only, no fenced block. ## Tests New pin `packages/plugin-report/src/__tests__/DatasetReportRenderer.matrixChart-10964.test.tsx`: - a matrix report with `columns` and a `chart` draws both, with the chart after the cross-tab in document order, from its own `['status']` × `['est_hours']` query; - the control, the same report without `chart`, draws the cross-tab only and issues exactly one query (the cross-tab's); - an `xAxis` naming the ACROSS dimension binds the same way; - an out-of-spec chart type on a matrix reaches the visible notice, after the cross-tab. Reverse verification. The implementation was committed first (`cad6b4745`). The renderer file was then checked out from BASE `3ad61001b` with the pin kept, under a trap-guarded restore. After the mutation the on-disk blob equals the BASE blob `c362912eb` and the fix-marker count went from 3 to 0. The run gave `Tests 3 failed | 1 passed (4)`: the three chart cases red and the control green, as predicted in the pin's header. After the restore the on-disk blob equals the HEAD blob `9560f4d4b` and `git diff HEAD` is 0 bytes. Gates, at HEAD `ec7caad07`: - `pnpm exec vitest run packages/plugin-report/`: `Test Files 23 passed (23)`, `Tests 232 passed | 7 skipped (239)`. The 7 skips are the `describe.runIf(DRIVEN)` blocks of `formatValue.dateOnlyZone-10844.test.ts`. - `pnpm --filter @object-ui/plugin-report type-check` (`tsc --noEmit && tsc -p tsconfig.test.json`): exit 0. `tsc -p tsconfig.test.json --listFilesOnly` includes the pin. The dependency closure was built first with `turbo run build --filter='@object-ui/plugin-report^...'`. - `pnpm exec eslint` on the two changed `.tsx` files: 2 files linted, 0 errors, 5 warnings. The BASE renderer carries the same 5 warnings under the same rules, shifted 3 lines by the new doc lines, so none is new. - Exit 0: `check-changeset-presence`, `check-control-bytes`, `check-new-cross-file-line-citations`, `check-changeset-no-major`, `check-changeset-fixed`, `check-changeset-claims`, `check-changeset-overwrite`, `check-pending-changeset-literals`, `check-doc-links`, `check-doc-fence-languages`, `check-test-path-roots`, `check-unreferenced-sources`, `check-vi-mock-specifiers`. - `check-readme-exports`: exit 1 on this checkout because 24 unrelated packages are unbuilt and it cannot judge them. With plugin-report built, its README has 0 findings. - NOT MEASURED: `check-sdui-registration-pins`, reason: it needs a console build (`apps/console/dist/assets`), and the diff touches no registration and no `sideEffects`. Declared to CI. ESLint narrowing, declared. (1) The population is read from eslint itself: the `.md` / `.mdx` files in this diff answer "File ignored because no matching configuration was supplied". (2) The file count is read from `--format json`: 2. (3) Invariance: `eslint.config.js` enables no type-aware linting (no `projectService`, no `parserOptions.project`), so this diff cannot move a verdict on an untouched file. The repo-wide `pnpm lint` is CI's. ## Acceptance notes - objectstack `packages/spec/src/ui/report.zod.ts`: the doc comment on `ReportSchema.chart` says the chart is plotted "above the report's table". That still holds for tabular and summary reports. On a matrix with `columns` the chart now draws below the cross-tab, per the ruling. It is a doc-comment word with no accept-set change, so it is not filed. Carrier: the spec seat on objectstack-ai/objectstack#20293, when that coordination card wraps up. - The notice and "Loading chart…" strings in `DatasetReportChart` are English literals outside the i18n catalogue. That predates this PR and is unchanged in kind. Not filed; carrier: none. --- _Generated by [Claude Code](https://claude.ai/code/session_011p7ikEivgXefNDaE5S5Uec)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 99878d8 commit 49f7672

5 files changed

Lines changed: 261 additions & 51 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@object-ui/plugin-report': patch
3+
---
4+
5+
A `matrix` report that declares `columns` now draws its declared `chart` below the cross-tab
6+
(objectui#10964). `ReportSchema` has always accepted a matrix report carrying both `columns` and
7+
a `chart`, but the renderer's cross-tab branch returned before the chart was read, so the chart
8+
parsed and was never drawn. It binds the way the summary report's chart does: `chart.xAxis` names
9+
a dataset dimension (a `rows` or a `columns` dimension of the matrix) and `chart.yAxis` a dataset
10+
measure, plotted from the chart's own dataset query. Summary, tabular and matrix-without-`columns`
11+
reports keep the chart above their table, as before.
12+
13+
The notice an out-of-spec chart type shows no longer says the table is "below" it, since on a
14+
matrix report the table sits above the notice.

‎content/docs/plugins/plugin-report.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,11 @@ paths and not expressions. `title`, `subtitle`, `series`, `colors`, `height`,
201201
through as authored. See the [package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-report)
202202
for a complete `chart` block.
203203

204+
The chart runs its own `xAxis` × `yAxis` dataset query, so it binds the same way
205+
on every non-`joined` type. It draws above a `tabular` or `summary` table, and
206+
below the cross-tab of a `matrix` that declares `columns`; there `xAxis` may name
207+
a `rows` or a `columns` dimension.
208+
204209
## Drill-down
205210

206211
Drill-down is a **host callback**, not a registered handler. Pass `onDrill` and

‎packages/plugin-report/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,11 @@ defineReport({
256256
`series`, `colors`, `height`, `showDataLabels`, `annotations` and `interaction`
257257
are passed through to the chart as authored.
258258

259+
The chart runs its own `xAxis` × `yAxis` dataset query, so it binds the same way
260+
on every non-`joined` type. It draws above a `tabular` or `summary` table, and
261+
below the cross-tab of a `matrix` that declares `columns`; there `xAxis` may name
262+
a `rows` or a `columns` dimension.
263+
259264
## Server-side aggregation + drill-down
260265

261266
A dataset-bound report selects its dimensions (`rows`, and for `matrix` also

‎packages/plugin-report/src/DatasetReportRenderer.tsx‎

Lines changed: 70 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@
2626
* so an older server that returns no `totals` renders the plain cross-tab
2727
* with no totals row/column. A matrix without `columns` degrades to the
2828
* flat grouped table.
29+
* - `chart` (any non-joined type) → the embedded chart, its own
30+
* `chart.xAxis` × `chart.yAxis` dataset query: above the grouped / flat
31+
* table, below the matrix cross-tab (objectui#10964).
2932
* - `joined` → a vertical stack of blocks, each its own dataset-bound table,
3033
* with the report-level `runtimeFilter` merged into every block.
3134
*
@@ -741,7 +744,7 @@ export type ReportChartPlan =
741744
| { kind: 'series'; chartType: string }
742745
/** Single-value family — one dimensionless dataset query, shown as a number. */
743746
| { kind: 'single_value' }
744-
/** Tabular family — the grouped table beneath IS the rendering; no duplicate chart. */
747+
/** Tabular family — the report's own table beside it IS the rendering; no duplicate chart. */
745748
| { kind: 'tabular' }
746749
/** Out-of-spec value (stored dialect / typo) — surfaced, never a silent bar. */
747750
| { kind: 'unsupported'; type: string };
@@ -758,8 +761,8 @@ export type ReportChartPlan =
758761
* - the single-value families (`gauge` / `solid-gauge` / `metric` / `kpi` /
759762
* `bullet`) render the measure as a number — the spec's own comment calls
760763
* them "honest single-value variants pending a real dial/target renderer";
761-
* - `table` / `pivot` add no duplicate chart: the grouped table that always
762-
* renders beneath the chart slot is exactly the tabular presentation;
764+
* - `table` / `pivot` add no duplicate chart: the table that always renders
765+
* beside the chart slot is exactly the tabular presentation;
763766
* - anything else is out-of-spec and gets a visible notice.
764767
*
765768
* `combo` joined `ChartTypeSchema` in spec 17.0.0-rc.1 and routes as a series
@@ -933,7 +936,7 @@ function DatasetReportChart({
933936
const xAxis = typeof chart.xAxis === 'string' ? chart.xAxis : '';
934937
const yAxis = typeof chart.yAxis === 'string' ? chart.yAxis : '';
935938
const plan = planReportChart(chart.type);
936-
// The chart plots a NARROWER selection than the table beneath it (one
939+
// The chart plots a NARROWER selection than the table beside it (one
937940
// dimension × one measure), so `useDatasetRows` scopes the report's order to
938941
// those two columns — a "biggest first" on the plotted measure still sorts
939942
// the bars; a key naming some other row dimension is simply not applicable
@@ -974,7 +977,7 @@ function DatasetReportChart({
974977
// zh limb of a translated label.
975978
const { language } = useObjectTranslation();
976979
// objectui#4330 — the embedded chart plots the SAME dimension the table
977-
// beneath it groups by, so it takes the same label map. Leaving it out would
980+
// beside it groups by, so it takes the same label map. Leaving it out would
978981
// put the two spellings of one value on one screen, which is the defect this
979982
// family exists to close.
980983
const chartDimensions = React.useMemo(() => (xAxis ? [xAxis] : []), [xAxis]);
@@ -1032,18 +1035,20 @@ function DatasetReportChart({
10321035
// its own frame.
10331036
const title = pickLocalized(chart.title, language) || undefined;
10341037

1035-
// `table` / `pivot`: the grouped table rendered beneath this slot IS the
1038+
// `table` / `pivot`: the report's own table rendered beside this slot IS the
10361039
// tabular presentation — a duplicate chart would say nothing new.
10371040
if (plan.kind === 'tabular') return null;
10381041
if (plan.kind === 'unsupported') {
10391042
// Out-of-spec chart type in stored metadata: say so instead of drawing a
1040-
// silently wrong bar (#2941). The table beneath still carries the numbers.
1043+
// silently wrong bar (#2941). The report's table still carries the numbers.
1044+
// The notice names no position: this slot sits ABOVE a grouped table and
1045+
// BELOW a matrix cross-tab (objectui#10964).
10411046
return (
10421047
<div
10431048
className="rounded-md border border-dashed bg-muted/20 px-3 py-2 text-xs text-muted-foreground"
10441049
data-testid="dataset-report-chart-unsupported"
10451050
>
1046-
Chart type &ldquo;{plan.type}&rdquo; is not a spec chart type — the grouped table below carries this report&rsquo;s numbers.
1051+
Chart type &ldquo;{plan.type}&rdquo; is not a spec chart type — the report&rsquo;s table carries its numbers.
10471052
</div>
10481053
);
10491054
}
@@ -1058,7 +1063,7 @@ function DatasetReportChart({
10581063
</div>
10591064
);
10601065
}
1061-
// On error or empty, fall back silently to the table beneath.
1066+
// On error or empty, fall back silently to the report's table.
10621067
if (state.status === 'error' || state.rows.length === 0) return null;
10631068

10641069
// objectui#7534 — resolve a BUILT-IN default measure's caption through the
@@ -1104,7 +1109,7 @@ function DatasetReportChart({
11041109
}
11051110

11061111
// The chart component is registered lazily; until it resolves render nothing
1107-
// (the grouped table beneath still shows the exact numbers).
1112+
// (the report's table beside it still shows the exact numbers).
11081113
if (!ChartComponent) return null;
11091114

11101115
// ── The DATA half: derived from the selection, never authored (#4229) ─────
@@ -1613,60 +1618,74 @@ export const DatasetReportRenderer: React.FC<DatasetReportRendererProps> = ({
16131618
const reportOrder = readOrder(report.order);
16141619
// Matrix with an across dimension → true cross-tab; without one it
16151620
// degrades to the grouped (summary) table (pre-`columns` stored JSON).
1616-
if (presentation === 'matrix' && across.length > 0) {
1617-
return (
1618-
<div className={className} data-testid="dataset-report" data-report-name={report.name}>
1619-
<DatasetMatrixTable
1620-
dataset={String(report.dataset ?? '')}
1621-
rows={readNames(report.rows)}
1622-
columnsAcross={across}
1623-
values={readNames(report.values)}
1624-
runtimeFilter={outerFilter}
1625-
dataSource={dataSource}
1626-
onDrill={drillSink}
1627-
order={reportOrder}
1628-
/>
1629-
</div>
1630-
);
1631-
}
1621+
const crossTab = presentation === 'matrix' && across.length > 0;
16321622

1633-
// summary → grouped table with the server-computed totals footer;
1634-
// tabular → the same selection as a simple list, no totals (the declared
1635-
// type is what separates them, #2941). A matrix without `columns` degrades
1636-
// to the summary presentation — it is a grouped type. Either is preceded by
1637-
// the embedded chart visualization when the report declares one (ADR-0021:
1623+
// The embedded chart visualization, when the report declares one (ADR-0021:
16381624
// the chart plots the dataset's yAxis measure across the xAxis dimension;
1639-
// the table beneath always carries the exact numbers).
1625+
// the table always carries the exact numbers). ONE slot for every non-joined
1626+
// presentation, the cross-tab included: `DatasetReportChart` runs its OWN
1627+
// `chart.xAxis` × `chart.yAxis` dataset query, so it binds the same way
1628+
// whichever table sits next to it — a matrix's rows and columns are dataset
1629+
// dimensions like a summary's rows, and the chart's axes name them.
1630+
//
1631+
// objectui#10964 — the cross-tab used to RETURN before this read, so a matrix
1632+
// report with `columns` parsed its `chart` and drew nothing. The spec accepts
1633+
// that shape, so the renderer now draws it (ENFORCE, objectstack-ai/objectstack#20293).
16401634
const chartCfg =
16411635
report.chart && typeof report.chart === 'object' && (report.chart as { type?: unknown }).type
16421636
? (report.chart as Record<string, unknown>)
16431637
: null;
1638+
const chart = chartCfg ? (
1639+
<DatasetReportChart
1640+
dataset={String(report.dataset ?? '')}
1641+
chart={chartCfg}
1642+
runtimeFilter={outerFilter}
1643+
dataSource={dataSource}
1644+
order={reportOrder}
1645+
/>
1646+
) : null;
1647+
1648+
// summary → grouped table with the server-computed totals footer;
1649+
// tabular → the same selection as a simple list, no totals (the declared
1650+
// type is what separates them, #2941). A matrix without `columns` degrades
1651+
// to the summary presentation — it is a grouped type.
1652+
const table = crossTab ? (
1653+
<DatasetMatrixTable
1654+
dataset={String(report.dataset ?? '')}
1655+
rows={readNames(report.rows)}
1656+
columnsAcross={across}
1657+
values={readNames(report.values)}
1658+
runtimeFilter={outerFilter}
1659+
dataSource={dataSource}
1660+
onDrill={drillSink}
1661+
order={reportOrder}
1662+
/>
1663+
) : (
1664+
<DatasetReportTable
1665+
dataset={String(report.dataset ?? '')}
1666+
rows={readNames(report.rows)}
1667+
values={readNames(report.values)}
1668+
runtimeFilter={outerFilter}
1669+
dataSource={dataSource}
1670+
onDrill={drillSink}
1671+
order={reportOrder}
1672+
withTotals={presentation === 'summary' || presentation === 'matrix'}
1673+
/>
1674+
);
1675+
1676+
// The chart precedes the grouped / flat table, and follows the cross-tab:
1677+
// the ruling on objectstack-ai/objectstack#20293 draws a matrix's chart
1678+
// "beside or below the cross-tab", and below is the one placement that needs
1679+
// no new layout option.
16441680
return (
16451681
<div
16461682
className={`${className ?? ''} flex flex-col gap-3`}
16471683
data-testid="dataset-report"
16481684
data-report-name={report.name}
16491685
data-report-presentation={presentation}
16501686
>
1651-
{chartCfg ? (
1652-
<DatasetReportChart
1653-
dataset={String(report.dataset ?? '')}
1654-
chart={chartCfg}
1655-
runtimeFilter={outerFilter}
1656-
dataSource={dataSource}
1657-
order={reportOrder}
1658-
/>
1659-
) : null}
1660-
<DatasetReportTable
1661-
dataset={String(report.dataset ?? '')}
1662-
rows={readNames(report.rows)}
1663-
values={readNames(report.values)}
1664-
runtimeFilter={outerFilter}
1665-
dataSource={dataSource}
1666-
onDrill={drillSink}
1667-
order={reportOrder}
1668-
withTotals={presentation === 'summary' || presentation === 'matrix'}
1669-
/>
1687+
{crossTab ? table : chart}
1688+
{crossTab ? chart : table}
16701689
</div>
16711690
);
16721691
};

0 commit comments

Comments
 (0)