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

Commit 3faaa7d

Browse files
claude[bot]claude
andauthored
docs(plugin-charts): mark normalizeSeries' chartType limb internal-only and pin the split (objectui#7744) (#7815)
`normalizeSeries` resolves the per-series family as `str(raw.chartType) ?? str(raw.type)` — the INTERNAL spelling first. That limb is correct and lit: `chartType` is the carrier of the renderer's internal `dataKey` series shape, which `ChartRenderer`'s `series?` union declares on that arm and on no other, and which `DashboardRenderer` / `ObjectView` / the dataset path write. But the same function normalizes authored spec-shape series too, and by the time `raw` arrives it is a bag of keys with nothing on it naming its producer. So an author who skips validation still gets `chartType` honoured at runtime — over the declared `type`, read second — while the authoring face refuses that same key by name (`ChartDataSeriesSchema`, objectui#7694 / PR #7737). The two faces disagree, and nothing said so anywhere. This annotates and pins that split rather than retiring the limb: retiring it would change what the internal producers render, a reader-side decision of its own. No behaviour changes — `normalizeSeries` returns byte-identical output for 336 input cases before and after, and the probe is sensitive (a reader reorder moves 49 of them). - the `normalizeSeries` docblock names which face owns which spelling, DELEGATES the refusal's rule and remedy to `ChartDataSeriesSchema` rather than copying them, and records why a green ablation on the first limb is not a licence to delete it; - `chartType-internal-only-7744.test.ts` pins the RELATIONSHIP the two existing files each held only half of: the key the validator refuses is the key the reader prefers. It reads one fixture writing BOTH spellings with DIFFERENT values, so a reorder is observable and not just a deletion; and it carries a compile-time half over `ChartRenderer`'s `series?` union arms. Claude-Session: https://claude.ai/code/session_01KbJQ1y1J12nZxYzFWhP8Q3 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 52cac38 commit 3faaa7d

3 files changed

Lines changed: 212 additions & 2 deletions

File tree

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
---
3+
4+
`@object-ui/plugin-charts`: documentation and a pin only — no published behaviour changes.
5+
`normalizeSeries` returns the identical output for the identical input (measured: 336 input
6+
cases, byte-identical JSON before and after; the probe was itself shown sensitive — a reader
7+
reorder moves 49 of those 336).
8+
9+
`normalizeSeries` resolves the per-series family as `str(raw.chartType) ?? str(raw.type)` —
10+
the internal spelling FIRST. `chartType` is the carrier of the renderer's internal `dataKey`
11+
series shape (`ChartRenderer`'s `series?` union declares it on that arm and on no other);
12+
the AUTHORING face refuses it by name via `ChartDataSeriesSchema` (objectui#7694 / PR #7737).
13+
Because the one function normalizes both shapes, an author who skips validation still gets
14+
`chartType` honoured at runtime while the validator refuses that same key — the two faces
15+
disagree.
16+
17+
objectui#7744 ruled that the split is annotated and pinned, NOT retired at the reader:
18+
retiring the limb would change what the internal producers (`DashboardRenderer`, `ObjectView`,
19+
the dataset path) render, which is a reader-side decision of its own. So the limb keeps its
20+
behaviour and gains a docblock that delegates the refusal's rule to where it lives, plus
21+
`chartType-internal-only-7744.test.ts`, which pins the RELATIONSHIP the two files each held
22+
half of: the key the validator refuses is the key the reader prefers. Bringing the faces into
23+
agreement from either side now goes red and names the side that moved.
Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
/**
2+
* ObjectUI
3+
* Copyright (c) 2024-present ObjectStack Inc.
4+
*
5+
* This source code is licensed under the MIT license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*/
8+
9+
/**
10+
* objectui#7744 — `chartType` on a series is the INTERNAL spelling only, and
11+
* the authoring face and the reader disagree about it ON PURPOSE.
12+
*
13+
* Two facts, each already true, each already load-bearing:
14+
*
15+
* - the AUTHORING face refuses `chartType` BY NAME — `ChartDataSeriesSchema`
16+
* (`@object-ui/types`, objectui#7694 / PR #7737). Its rule, its message and
17+
* its remedy are pinned in that package's
18+
* `chart-series-chart-type-alias-refusal-7694.test.ts`; this file does not
19+
* restate them, it only asks WHICH key is refused;
20+
* - the READER honours it, and reads it FIRST — `normalizeSeries`'
21+
* `str(raw.chartType) ?? str(raw.type)` — because the internal `dataKey`
22+
* shape carries the per-series family under that name and
23+
* `normalizeChartSchema` translates BOTH shapes through the one function.
24+
*
25+
* Neither fact is a defect, and until now NEITHER FILE PINNED THE PAIR — which
26+
* is how the split survived to be found in the contract review of PR #7737.
27+
* What this file pins is the RELATIONSHIP: the key the validator refuses is
28+
* the key the reader prefers. Bring the two faces into agreement from either
29+
* side — make the refusal accept, or reorder or delete the reader's first limb
30+
* — and this goes red naming the side that moved.
31+
*
32+
* ⚠️ It is deliberately not written as "`chartType` is honoured somehow": an
33+
* assertion loose enough to stay green under both behaviours pins nothing.
34+
*
35+
* ⛔ A green ablation on the reader's first limb is not a licence to delete it;
36+
* the `normalizeSeries` docblock carries that measurement and why.
37+
*/
38+
39+
import { describe, it, expect } from 'vitest';
40+
import { ChartDataSeriesSchema } from '@object-ui/types/zod';
41+
42+
import { normalizeChartSchema, type NormalizedSeries } from '../normalizeChartSchema';
43+
import type { ChartRendererProps } from '../ChartRenderer';
44+
45+
/**
46+
* ONE document, read by every assertion below, so the two faces are measured
47+
* against the same input instead of against two fixtures free to drift apart.
48+
*
49+
* It writes BOTH spellings with DIFFERENT values, and that is what makes the
50+
* reader's precedence observable at all: with only `chartType` written, a
51+
* reordered reader returns the identical answer and a pin on the value alone
52+
* stays green straight through the change it exists to catch.
53+
*/
54+
const AUTHORED = { name: 'margin', type: 'area', chartType: 'line' } as const;
55+
56+
/** The same document with the refused spelling dropped — the accept control. */
57+
const AUTHORED_WITHOUT_ALIAS = { name: AUTHORED.name, type: AUTHORED.type } as const;
58+
59+
/** `null` when the document parses; the refused paths otherwise. */
60+
const issuePathsOf = (input: unknown): string[] | null => {
61+
const r = ChartDataSeriesSchema.safeParse(input);
62+
return r.success ? null : r.error.issues.map((i) => i.path.join('.'));
63+
};
64+
65+
const seriesOf = (raw: unknown): NormalizedSeries | undefined =>
66+
normalizeChartSchema({ series: [raw] }).series?.[0];
67+
68+
describe('objectui#7744 — the `chartType` split between the authoring face and the reader', () => {
69+
it('the AUTHORING face refuses `chartType`, and that is the ONLY thing wrong with the document', () => {
70+
expect(
71+
issuePathsOf(AUTHORED),
72+
'objectui#7744: `ChartDataSeriesSchema` no longer refuses `chartType` by name on an authored '
73+
+ 'series (objectui#7694 / PR #7737) — the AUTHORING face moved. If that is intended, the '
74+
+ 'reader half of this split and the `normalizeSeries` docblock are the other half of the edit.',
75+
).toEqual(['chartType']);
76+
});
77+
78+
it('CONTROL — the same series is ACCEPTED once `chartType` is dropped', () => {
79+
expect(
80+
issuePathsOf(AUTHORED_WITHOUT_ALIAS),
81+
'objectui#7744: the fixture is refused for something other than `chartType`, so the refusal '
82+
+ 'asserted above is not measuring the key it names.',
83+
).toBeNull();
84+
});
85+
86+
it('the READER honours `chartType`, and takes it OVER the declared `type`', () => {
87+
expect(
88+
seriesOf(AUTHORED)?.chartType,
89+
'objectui#7744: `normalizeSeries` no longer resolves the per-series family from `chartType` '
90+
+ 'first. `"area"` here means the limb was REORDERED; `undefined` means it was DELETED. '
91+
+ 'Either one changes what the internal `dataKey`-shape producers render (DashboardRenderer / '
92+
+ 'ObjectView / the dataset path) — that is a reader-side decision, not a doc fix.',
93+
).toBe('line');
94+
});
95+
96+
it('THE SPLIT — the key the validator refuses is the key the reader prefers', () => {
97+
const [refused] = issuePathsOf(AUTHORED) ?? [];
98+
const written = AUTHORED as unknown as Record<string, unknown>;
99+
100+
expect(refused, 'objectui#7744: nothing on this fixture is refused by name any more').toBe('chartType');
101+
expect(
102+
written[refused],
103+
'the fixture must write the refused key and the declared key with DIFFERENT values, or the '
104+
+ 'reader\'s precedence between them is not observable and this case pins nothing.',
105+
).not.toBe(written.type);
106+
107+
expect(
108+
seriesOf(AUTHORED)?.chartType,
109+
'objectui#7744: the reader no longer prefers the very key the authoring face refuses. The two '
110+
+ 'faces have converged, and the `normalizeSeries` docblock now describes a split that is gone.',
111+
).toBe(written[refused]);
112+
});
113+
114+
it('the internal `dataKey` shape is the limb\'s LEGITIMATE carrier — it is not the defect', () => {
115+
expect(
116+
seriesOf({ dataKey: 'margin', chartType: 'line' })?.chartType,
117+
'objectui#7744: the internal-shape producers lost their per-series family override.',
118+
).toBe('line');
119+
});
120+
});
121+
122+
/* -------------------------------------------------------------------------- */
123+
/* Compile-time half — this package's tsconfig.json includes its tests, so */
124+
/* `type-check` compiles these (the `spec-symbol-batch7.test.ts` precedent). */
125+
/* -------------------------------------------------------------------------- */
126+
127+
type Assert<T extends true> = T;
128+
type HasKey<T, K extends string> = K extends keyof T ? true : false;
129+
130+
type SeriesArm = NonNullable<ChartRendererProps['schema']['series']>[number];
131+
type InternalArm = Extract<SeriesArm, { dataKey: string }>;
132+
type AuthoredArm = Extract<SeriesArm, { name: string }>;
133+
134+
describe('objectui#7744 — `ChartRenderer` states the same split in TypeScript', () => {
135+
it('is pinned at compile time (the assertion IS the compile)', () => {
136+
// `series?` is a union of the two shapes. `chartType` is a member of the
137+
// INTERNAL arm and of no other; the authored arm carries `type` instead.
138+
// Move `chartType` onto the authored arm and these stop compiling.
139+
type _ChartTypeIsInternal = Assert<HasKey<InternalArm, 'chartType'>>;
140+
type _ChartTypeIsNotAuthored = Assert<HasKey<AuthoredArm, 'chartType'> extends false ? true : false>;
141+
type _AuthoredArmDeclaresType = Assert<HasKey<AuthoredArm, 'type'>>;
142+
143+
expect(true).toBe(true);
144+
});
145+
});

‎packages/plugin-charts/src/normalizeChartSchema.ts‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -226,8 +226,48 @@ function normalizeAxis(raw: unknown): NormalizedAxis | undefined {
226226
* Merge one series entry from either shape.
227227
*
228228
* Internal (`dataKey`) wins over spec (`name`) so a caller that already speaks
229-
* the internal contract is untouched. `type` (spec, a ChartType) and
230-
* `chartType` (internal) both name the per-series family in a combo chart.
229+
* the internal contract is untouched.
230+
*
231+
* ## `chartType` is the INTERNAL spelling, and only that (objectui#7744)
232+
*
233+
* The two spellings of the per-series family are NOT two authoring keys:
234+
*
235+
* - `type` is the AUTHORING face's key — spec `ChartSeries.type`, declared on
236+
* the mirror as `ChartDataSeriesSchema.type` (`'bar' | 'line' | 'area'`).
237+
* - `chartType` is the RENDERER-INTERNAL carrier. It rides on the `dataKey`-
238+
* shaped series that `DashboardRenderer`, `ObjectView` and the dataset path
239+
* hand straight to `ChartRenderer`, which is where it is declared
240+
* (`ChartRenderer.tsx:65`, on the internal series shape) and where
241+
* {@link NormalizedSeries.chartType} is the output half of the same
242+
* contract. On the AUTHORING face it is not a member at all: it is a named
243+
* alias refusal — `ChartDataSeriesSchema.chartType`
244+
* (`packages/types/src/zod/data-display.zod.ts`, objectui#7694 / PR #7737),
245+
* pinned in that package's
246+
* `__tests__/chart-series-chart-type-alias-refusal-7694.test.ts`. Read the
247+
* rule and its remedy THERE. Restating either here would be a second copy of
248+
* a rule that only one of the two files is ever edited with.
249+
*
250+
* ## The split this limb carries, deliberately (objectui#7744)
251+
*
252+
* This function normalizes BOTH shapes, and the `family` limb below cannot
253+
* tell them apart: by the time `raw` arrives it is a bag of keys with nothing
254+
* on it naming its producer. So an AUTHORED series that skipped validation
255+
* still gets `chartType` honoured at runtime — and honoured OVER the declared
256+
* `type`, which the limb reads second — while the validator refuses that same
257+
* key by name. The two faces disagree, and that is the state this comment
258+
* exists to make legible rather than to fix: the objectui#7744 ruling was to
259+
* annotate and pin, NOT to retire the limb at the reader, because retiring it
260+
* would change what the internal producers above render — a reader-side
261+
* decision of its own.
262+
*
263+
* ⛔ Do not delete the limb on the strength of a green ablation. Deleting
264+
* `str(raw.chartType) ??` left the repo fully green when it was measured
265+
* (304 files / 5817 tests) while deleting its ` ?? str(raw.type)` sibling went
266+
* 2 red — green there means only that no test PINNED it, never that no
267+
* producer depends on it. Both halves of the split, and the precedence between
268+
* them, are now pinned in `__tests__/chartType-internal-only-7744.test.ts`;
269+
* that case is what goes red if the two faces are ever brought into agreement,
270+
* from either side.
231271
*/
232272
function normalizeSeries(raw: unknown): NormalizedSeries | undefined {
233273
if (!isRec(raw)) {
@@ -241,6 +281,8 @@ function normalizeSeries(raw: unknown): NormalizedSeries | undefined {
241281
const out: NormalizedSeries = { dataKey };
242282
const lbl = label(raw.label);
243283
if (lbl) out.label = lbl;
284+
// INTERNAL spelling FIRST, authored `type` second — see the docblock above.
285+
// The order is load-bearing and pinned; neither limb is dead.
244286
const family = str(raw.chartType) ?? str(raw.type);
245287
if (family === 'bar' || family === 'line' || family === 'area') out.chartType = family;
246288
const variant = str(raw.variant);

0 commit comments

Comments
 (0)