docs(types): correct the series and route-overview docblocks PRs #10802 and #10821 made false (objectui#10905)

.changeset/10905-types-stale-docblocks.md

@@ -0,0 +1,20 @@
+---
+---
+
+Comment-only correction in `@object-ui/types`; releases nothing (objectui#10905).
+
+Two source docblocks still described shapes that objectui#10770 and objectui#7928
+changed earlier in this same unreleased batch. The `ObjectChartSchema.series`
+docblock said a `type` written on the `{ dataKey }` arm is an excess property on
+a literal typed by the interface; since the `{ name }` arm is the spec's
+`ChartSeries`, which declares `type`, that literal compiles, and only the zod
+mirror still strips the key. The zod route overview headed "WHERE THIS ARM IS
+INSTALLED" said a named view's `listViews` is unmirrored and named a `custom`
+issue under `options.kanban` there; `listViews` is the protocol's strict record
+by reference, which refuses a named view's `options` bag whole, and the named-view
+check reports at `listViews.KEY.kanban.groupBy` only.
+
+No behaviour, type, accept set or `.describe()` string moves. Both docblocks reach
+the build output only as comment text (the `series` one in the emitted `.d.ts`,
+the route overview in the zod module's JavaScript), so there is nothing for a
+consumer to act on.

packages/types/src/objectql.ts

@@ -4821,11 +4821,14 @@ export interface ObjectChartSchema extends BaseSchema {
    * that writes `type` on a `{ dataKey }` entry of an `object-chart` node;
    * none was named. Until one is, the per-series family override on this arm
    * is `chartType`, the renderer-internal spelling of `type`, which wins when
-   * an entry writes both. A `type` written on this arm 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.
+   * an entry writes both. A `type` written on this arm anyway is NOT refused
+   * on a literal typed by this interface: the `{ name }` arm declares `type`,
+   * and excess-property checking on this union accepts a key that either arm
+   * declares when its value fits that declaration, so
+   * `{ dataKey: 'amount', type: 'line' }` compiles. The zod mirror's element
+   * for this arm is a plain `z.object`, which strips it: it parses clean and
+   * is dropped. The mirror's `.describe()` names the same omission, because
+   * that string is what an author-facing tool renders.
    *
    * An entry with neither `name` nor `dataKey` matches no arm and is refused;
    * `normalizeChartSchema` would drop it from the chart.

packages/types/src/zod/objectql.zod.ts

@@ -919,7 +919,7 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
 );
 
 /**
- * WHERE THIS ARM IS INSTALLED — TWO ROUTES, TWO NESTINGS EACH, ONE STRING.
+ * WHERE THIS ARM IS INSTALLED — TWO ROUTES, THREE NESTINGS, ONE STRING.
  *
  * `ListView` merges `{ ...schema.options?.kanban, ...schema.kanban }` before it
  * reads anything, so a stored view can carry the stray key under EITHER. The
@@ -930,11 +930,13 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
  * `options.kanban.groupBy`) — see `ListViewSchema.options` below.
  *
  * The second route is a named view on an `object-view` document, whose
- * `listViews` is unmirrored: nothing `ListViewSchema` declares reaches it, and
- * `generateViewSchema` merges the same two nestings. It takes the SAME guidance
- * through the named-view door (`custom` at `listViews.KEY.kanban.groupBy` and
- * `listViews.KEY.options.kanban.groupBy`, objectui#10321) — see
- * `checkNamedViewKanbanStrayGroupBy` below.
+ * `listViews` is the protocol's strict record by reference (objectui#7928), so
+ * nothing `ListViewSchema` declares reaches it, and it has ONE nesting: the
+ * record refuses a named view's `options` bag whole (`unrecognized_keys` naming
+ * `options`), and `generateViewSchema` no longer reads that bag. The `kanban`
+ * block takes the SAME guidance through the named-view door (`custom` at
+ * `listViews.KEY.kanban.groupBy`, objectui#10321, beside the protocol's own
+ * `unrecognized_keys`) — see `checkNamedViewKanbanStrayGroupBy` below.
  *
  * ⚠️ Covering the legacy nesting is not optional politeness: the retired
  * producer (`app-shell`'s `kanbanViewOptions`, objectui#8213) wrote into
@@ -943,8 +945,8 @@ const KanbanStrayGroupByRefusal = aliasKeyRefusal(
  * population re-grouped in silence — option A, which the ruling did not take.
  *
  * ⛔ Every channel takes ONE string, read off this arm's own `.description`,
- * so the message an author meets cannot depend on which route or nesting they
- * wrote.
+ * so the message an author meets at the key cannot depend on which of those
+ * three nestings they wrote it in.
  */
 
 const KanbanConfig = stripImportedDefaults(SpecKanbanConfigSchema).partial().extend({