docs(types): ObjectChartSchema.series says its copy omits the per-series type and names chartType (objectui#10584)

.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.

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.
    */

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<value,color>
   // is an explicit value→color map. A select/lookup dimension's option colors —