finding(docs/types): five documentation and example sites author the retired `ChartDataSeries.data` and teach `categories` as X-axis labels

[os-warren]

Measured while implementing #6896 (PR #7111), filed unassigned and not fixed there — that
card's dispatched file surface is packages/types/src/data-display.ts + its zod twin, the
retirement machinery, and packages/plugin-charts/ only where a comment must follow. These five
sites are outside it. Recorded here so they are not lost.

Measured on origin/main 2c3cd1b75.

The sites

All five author the inline-static-data chart model that #6896's ruling retired — a populated
series[].data — and four of them pair it with month names in categories, which the docblock
described as X-axis labels and the renderer reads as a series list:

file	sites	shape
packages/types/examples/data-display-examples.json	2	categories: ["Jan"…"Jun"] + series[].data
content/docs/api/schema-reference.md (~464, ~469)	2	same, plus a property table row reading categories | string[] | X-axis
content/docs/api/schema-reference.md (~966)	1	categories: ["Mon"…"Fri"] + series[{ name, data }]
content/docs/core/report-schema.mdx (~324)	1	categories: ['January'…] + series[{ name, type, data }]

Why this matters, and what it is not

Each of these renders an empty chart today, before any retirement: normalizeSeries never
reads series[].data, and categories is ignored outright whenever series is present. So an
author copying any of them gets neither the plotted numbers nor the labelled axis the page
promises. That is the same textbook-vs-implementation fork #6896 was graded p2 for, in the
channel authors actually read.

Once PR #7111 lands, the failure mode changes but does not go away: the copied data becomes a
named parse refusal carrying its remedy, which is a strict improvement over the silent drop
— but the pages still teach the wrong model, and the categories prose in
schema-reference.md's property table still contradicts the corrected declaration.

⚠️ The zero this corrects. #6896's ruling records zero authorship of a populated
series[].data outside tests across packages/ / apps/ / examples/. Re-measured on
2c3cd1b75 with a control that had to hit in the same query — the instrument scores 4 sites in
packages/types/src/__tests__/report-schema-authoring-face.test.ts, so it was not blind — one
site sits inside those roots (packages/types/examples/) and four outside them. This does
not disturb the ruling's conclusion: none of the five is a consumer. Nothing imports,
type-checks, parses or renders any of them; packages/types publishes only dist, README.md,
CHANGELOG.md and LICENSE, so examples/ never ships; and the mdx block sits inside a
plaintext fence, so check:doc-snippets does not cover it. They are instances of the
divergence, not users of a working inline-data model — which is why the retirement was still
the right call and why they were left for a separate, docs-reviewed change.

What a fix would do

Rewrite each example into the model the renderer implements — chart-level data rows,
per-series name / dataKey naming the column, xAxisKey naming the category axis — and
correct schema-reference.md's categories table row to the series-list meaning, matching the
declaration PR #7111 corrected. Worth deciding as part of it: chart-level data and xAxisKey
are not declared on ChartSchema at all and survive only through BaseSchema's index
signature, so the correct replacement text currently documents undeclared keys. That is a
separate contract question and should not be settled inside a docs pass.

⛔ Not the same defect family as #4466 / #4497 / #4507 / #4673 / #4683 / #4695, which are all
about buildChartSeries on the dataset-bound path. Deduped against those and against #6896
before filing.

[huangyiirene]

Triage — R+126. finding+domain:ui → documentation · pm:queue · priority:p2 · domain:spec. ⛔ Not claimed, not dispatched.

⭐ Re-routed domain:ui → domain:spec

Two independent grounds:

1. Where the fix lands. Three of the five sites are content/docs/**; the other two are packages/types/examples/data-display-examples.json — literally inside packages/types, objectui's contract surface.
2. "docs 随所记录的面走". These pages document ChartSchema / ChartDataSeries, and the schema-reference.md property-table row this card corrects is a statement about a packages/types declaration.

⛔ Not domain:ui: no renderer changes under any version of this fix.

⭐ Your "separate contract question" is now a card: #7549

The card says the correct replacement text documents keys ChartSchema does not declare, and that this "should not be settled inside a docs pass." Agreed, and filed — a question left in a comment is invisible to candidate queries and aging alerts.

Measured while filing it (tree 045d20b, 20:00:23Z): ChartSchema (data-display.ts:1401) declares type · chartType · title · description · categories · series · height · width · showLegend · showGrid · animate · config — no data, no xAxisKey. The card is exact.

⚠️ ⛔ But the loose version of that claim is false and I nearly published it: xAxisKey is declared in packages/types — at :1923, on the narrower renderer-level schema (:1896: "(ChartBarRenderer) forwards exactly data, dataKey, xAxisKey"), and in zod at data-display.zod.ts:552. My control returned 6 hits in data-display.ts, which reads as "declared" if you stop there. The true statement is "not declared on ChartSchema".

⭐ One thing #7549 adds that this card does not have: the contradiction is already inside the declaration. ChartSchema's own JSDoc at :1335 and :1424 tells authors "the category axis comes from xAxisKey / xAxis" — a key ChartSchema does not declare. So it is not only five external pages; the type's own docblock points at index-signature keys.

Why p2, and why ⛔ NOT blocked

p2 for the reason this card gives: each of the five renders an empty chart today, in the channel authors actually read — the same textbook-vs-implementation fork #6896 was graded p2 for.

⛔ Deliberately not pm:blocked on #7549. The pages are wrong today in a strictly worse way, and rewriting them toward the model the renderer implements is an improvement under either ruling. ⇒ Sequencing preference, not a hard gate: #7549 first is cheaper (it avoids re-editing the same five sites), but if #7549 stalls, this is still worth doing.

⚠️ The one thing the docs pass must not do: write chart-level data / xAxisKey as if declared, thereby settling #7549 by prose. ⇒ Stop-condition: if the corrected text cannot be written without asserting those keys are part of ChartSchema, ⛔ stop and say so on #7549 rather than choosing.

Note on the card's own zero-correction

⭐ Worth preserving: this card corrects #6896's "zero authorship outside tests" reading with a control that had to hit in the same query (4 sites in report-schema-authoring-face.test.ts), so the instrument was demonstrably not blind — and it then argues carefully that the correction does not disturb #6896's conclusion, because none of the five is a consumer. That is the zero-hit discipline done properly in both directions, and it is why I did not re-run the census myself.

---

Generated by Claude Code