diff --git a/.changeset/10584-object-chart-series-describe.md b/.changeset/10584-object-chart-series-describe.md new file mode 100644 index 0000000000..b3c3e1e135 --- /dev/null +++ b/.changeset/10584-object-chart-series-describe.md @@ -0,0 +1,19 @@ +--- +'@object-ui/types': patch +--- + +docs(types): the `ObjectChartSchema.series` description says the copy omits the per-series `type`, and names `chartType` as its override + +The zod mirror's `.describe()` on `ObjectChartSchema.series` called the element +"the arm ChartRendererProps declares". Since objectui#8086 that arm also carries +a per-series `type`, which this copy does not declare, so the sentence was no +longer true member for member. It now says the copy is that `{ dataKey }` arm +minus its per-series `type`, and that the per-series family override on an +`object-chart` node is `chartType` (`bar` | `line` | `area`). + +The TypeScript docblock on the same member now says the omission is deliberate +rather than a lag: taking `type` up would widen a published accept set, and +that waits for a named producer that writes it on an `object-chart` node. + +Wording only. The accepted shape does not move on either face: the element +type, its members and the mirror's parse result are what they were. diff --git a/packages/types/src/objectql.ts b/packages/types/src/objectql.ts index c0b236a90d..9e9514bd04 100644 --- a/packages/types/src/objectql.ts +++ b/packages/types/src/objectql.ts @@ -4447,9 +4447,22 @@ export interface ObjectChartSchema extends BaseSchema { * * The element type is `ChartRendererProps.schema.series`' internal arm — * that is the read this value ends at, and the ruling on objectui#7946 asked - * for the reads rather than a copy of any producer's literal — every member - * of it except `type`, which that arm gained under objectui#8086 and this - * copy has not taken up. The spec's AUTHOR-facing `ChartSeriesSchema` is the other arm + * for the reads rather than a copy of any producer's literal — with every + * member of it EXCEPT the per-series `type` that arm gained under + * objectui#8086. + * + * ⛔ The omission is deliberate, not a lag (objectui#10584). Taking `type` + * up widens a published accept set, and that waits for a named producer + * that writes `type` on an `object-chart` node; none was named. Until one + * is, the per-series family override on this node is `chartType` — the + * renderer-internal spelling of `type`, which wins when an entry writes + * both. A `type` written here anyway is an excess property on a literal + * typed by this interface, and the zod mirror's element is a plain + * `z.object`, which strips it: it parses clean and is dropped. The mirror's + * `.describe()` says the same, because that string is what an author-facing + * tool renders. + * + * The spec's AUTHOR-facing `ChartSeriesSchema` is the other arm * (`{ name }`), and it refuses `dataKey` by name; `normalizeChartSchema` is * the one translation between them. */ diff --git a/packages/types/src/zod/objectql.zod.ts b/packages/types/src/zod/objectql.zod.ts index 7c49432cba..8ac7380af6 100644 --- a/packages/types/src/zod/objectql.zod.ts +++ b/packages/types/src/zod/objectql.zod.ts @@ -2537,6 +2537,13 @@ export const ObjectChartSchema = BaseSchema.extend({ aggregate: stripImportedDefaults(SpecChartAggregateSchema).optional() .describe('AUTHORABLE — inline aggregation for the legacy objectName path. @objectstack/spec ChartAggregateSchema ({ field?, function, groupBy }), the same schema the react-page publish gate parses: function and groupBy are REQUIRED, field is optional because only count counts rows rather than a column, and unknown keys are refused rather than dropped'), xAxisKey: z.string().optional().describe('INTERNAL (relay-composed) — the category column the renderer binds the x axis to. Authors write the spec xAxis: { field }; all five producers compute this key'), + // `series` copies the `{ dataKey }` arm of `ChartRendererProps.schema.series` + // WITHOUT that arm's per-series `type` (objectui#8086), deliberately + // (objectui#10584): widening a published accept set waits for a named + // producer that writes `type` on this node. The `.describe()` says so and + // names `chartType` as this copy's override, because that string is what an + // author-facing tool renders. The TS twin in `../objectql.ts` carries the + // ground. series: z.array(z.object({ dataKey: z.string().describe('Result column this series plots'), label: z.string().optional().describe('Series display label'), @@ -2547,7 +2554,7 @@ export const ObjectChartSchema = BaseSchema.extend({ stack: z.string().optional().describe('Stack identifier to group series'), yAxis: z.enum(['left', 'right']).optional().describe('Bind to a specific Y axis'), color: z.string().optional().describe('Series color (hex/rgb/token)'), - })).optional().describe("INTERNAL (relay-composed) — plotted series in the renderer's internal { dataKey } contract, the arm ChartRendererProps declares. The spec's author-facing ChartSeriesSchema is the { name } arm and refuses dataKey by name; normalizeChartSchema is the one translation"), + })).optional().describe("INTERNAL (relay-composed) — plotted series in the renderer's internal { dataKey } contract: the { dataKey } arm ChartRendererProps declares, minus that arm's per-series type, which this copy does not declare. The per-series family override here is chartType (bar | line | area). The spec's author-facing ChartSeriesSchema is the { name } arm and refuses dataKey by name; normalizeChartSchema is the one translation"), // Colors are overloaded kanban-style: a string[] is the positional palette // (applied per category in order; fallback only), while a Record // is an explicit value→color map. A select/lookup dimension's option colors —