fix(spec): hold object-grid columns at z.unknown(): the grid draws an authored column's options, which ListColumn does not declare (#21464 stage 2)

Claude-Session: https://claude.ai/code/session_01YDt3PzwfrkuFzUBF89WPmM
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21464-component-props-list-family-typed.md

@@ -2,7 +2,7 @@
 '@objectstack/spec': minor
 ---
 
-feat(spec)!: the list members of an `object-grid`, `object-kanban` or `object-calendar` page block take the shape the block reads instead of any value — the grid's `columns`, `fields`, `selection`, `selectable`, `rowActions`, `bulkActions` and `batchActions`, the kanban's `columns` and the calendar's `calendar` (#21464)
+feat(spec)!: eight list members of an `object-grid`, `object-kanban` or `object-calendar` page block take the shape the block reads instead of any value — the grid's `fields`, `selection`, `selectable`, `rowActions`, `bulkActions` and `batchActions`, the kanban's `columns` and the calendar's `calendar` (#21464)
 
 Clause-②: yes (narrowing)
 
@@ -12,20 +12,17 @@ Clause-②: yes (narrowing)
 
 **`@objectstack/spec`**
 
-- **Nine members are typed.** `ComponentPropsMap['object-grid']`, `['object-kanban']` and `['object-calendar']` declared these members as `z.unknown()` (an array of it for the lists), although each renderer reads them with one shape. Any value passed, and an off-shape one was dropped or substituted with no report: a grid column keyed `accessorKey` or `name`, or a column list mixing strings and objects, drew no column; an object entry in `fields` named no field; a `{ name }` entry in `bulkActions` was skipped; a kanban lane list mixing objects and strings drew a blank lane; a calendar block with no `startDateField` placed no event.
-- **The list view's own members, by reference**, where a list view declares one: the grid's `columns` (all field-name strings, or all column entries `{ field, label?, width?, … }`), `selection` (`{ type }`, with `none`, `single` or `multiple`), `rowActions` and `bulkActions` (action-name strings), and the calendar's `calendar` (`{ startDateField, endDateField?, titleField?, colorField?, allDayField? }`). `batchActions`, the second spelling of `bulkActions` that the grid reads first, takes `bulkActions`'s def. Neither spelling is retired here.
+- **Eight members are typed.** `ComponentPropsMap['object-grid']`, `['object-kanban']` and `['object-calendar']` declared these members as `z.unknown()` (an array of it for the lists), although each renderer reads them with one shape. Any value passed, and an off-shape one was dropped or substituted with no report: an object entry in `fields` named no field; a `{ name }` entry in `bulkActions` was skipped; a kanban lane list mixing objects and strings drew a blank lane; a calendar block with no `startDateField` placed no event.
+- **The list view's own members, by reference**, where a list view declares one: the grid's `selection` (`{ type }`, with `none`, `single` or `multiple`), `rowActions` and `bulkActions` (action-name strings), and the calendar's `calendar` (`{ startDateField, endDateField?, titleField?, colorField?, allDayField? }`). `batchActions`, the second spelling of `bulkActions` that the grid reads first, takes `bulkActions`'s def. Neither spelling is retired here.
 - **The measured shape**, where no list view declares the member: the grid's `fields` (field-name strings), the grid's `selectable` (`true`, `false`, `'single'` or `'multiple'`), and the kanban's `columns` (all lanes `{ id, title, cards?, limit?, className?, collapsed? }`, or all bare value strings). A lane `id` and `title` are strings, a static card carries a string `id` and `title` beside its row's own values, and `limit` is a positive integer.
-- **`ObjectGridProps`, `ObjectKanbanProps` and `ObjectCalendarProps`** (and their `…Parsed` twins) carry these types on the nine members instead of `unknown`.
-- **The enumeration pin** loses the nine lines, and the list-family stage is done. One `z.unknown()` member is added and recorded: the rest of a static kanban card (its row's own values, beside the typed `id` and `title`).
+- **`ObjectGridProps`, `ObjectKanbanProps` and `ObjectCalendarProps`** (and their `…Parsed` twins) carry these types on the eight members instead of `unknown`.
+- **The grid's `columns` is not narrowed** and still accepts any value. The list view's column entry is its by-reference shape, and the grid's draw path reads exactly that, but the grid's group headers also draw the labels from an authored column's `options` (the column whose `field` is the grouping field, ahead of the field's own options). The list view's column entry declares no `options`, so typing `columns` now would refuse a value the grid draws. It is held until that read is ruled.
+- **The enumeration pin** loses eight lines and keeps the grid's `columns` as held for that ruling. One `z.unknown()` member is added and recorded: the rest of a static kanban card (its row's own values, beside the typed `id` and `title`).
 
 ## FROM → TO
 
 | you wrote | write instead |
 |:--|:--|
-| `object-grid` `columns: [{ accessorKey: 'amount', header: 'Amount' }]` | `columns: [{ field: 'amount', label: 'Amount' }]` |
-| `object-grid` `columns: [{ name: 'amount' }]` | `columns: [{ field: 'amount' }]` |
-| `object-grid` `columns: ['name', { field: 'amount', width: 120 }]` | one spelling per list: `columns: [{ field: 'name' }, { field: 'amount', width: 120 }]` |
-| `object-grid` a column key the grid never reads, such as `editable` or `options` | delete the key (inline editing is the grid's `editable`) |
 | `object-grid` `fields: [{ field: 'name', width: 240 }]` | `fields: ['name']`, or the entry on `columns` |
 | `object-grid` `selection: 'multiple'` | `selection: { type: 'multiple' }` |
 | `object-grid` `selectable: 'none'` | `selectable: false`, or `selection: { type: 'none' }` |
@@ -41,6 +38,6 @@ The one-line fix: write each member as the list view declares it, or as the tabl
 
 A writer is a page-component node: an object literal naming the type, a literal annotated with the block's type, a `schema={{…}}` on the block's React component, a call into a local helper that builds the node, or a direct parse through the row. Each member's value is read through same-file constants, and the control is `objectName` on the same nodes.
 
-- **objectstack** at `49161683fb`, over `examples/`, `packages/` (with `packages/apps/`), `content/`, `skills/` and `apps/`: 57 `object-grid`, 30 `object-kanban` and 5 `object-calendar` nodes (the control on 47 / 27 / 4 of them). The authored values are 5 grid `columns` (field-name strings, the showcase's two grids among them) and 1 kanban `columns` (lanes, in the protocol docs); every one parses. No node authors another of the nine members.
-- **objectui** at the `.objectui-sha` pin `89cad75d55`: 689 `object-grid`, 240 `object-kanban` and 160 `object-calendar` nodes (the control on 293 / 108 / 98). 551 member values are static, and 503 of them parse. Each of the 48 that do not is a test fixture whose value the renderer drops, skips or refuses: 17 grid columns keyed `accessorKey` / `header` and 5 keyed `name` (the grid draws neither, and its own column diagnostic names both), 16 column keys the grid never reads (`editable` 14, `options` 2), a numeric `columns` and a column with no `field`, 2 object entries in `bulkActions` (the renderer skips them, and the tests assert the skip), 3 object entries in `fields` that copy the hand-off the list view makes to the grid at run time (not an authored page), a lane `color` (retired in the console; the test marks it an undeclared member), and 2 uses of the calendar's retired `dateField` / `endField` aliases (the test asserts their refusal). No refused value is one the renderer draws. 44 values are not static (helper parameters, `.map` results and the run-time hand-offs); none of them is an authored page.
+- **objectstack** at `49161683fb`, over `examples/`, `packages/` (with `packages/apps/`), `content/`, `skills/` and `apps/`: 57 `object-grid`, 30 `object-kanban` and 5 `object-calendar` nodes (the control on 47 / 27 / 4 of them). The one authored value among the eight members is a kanban `columns` (lanes, in the protocol docs), and it parses. No node authors another of the eight.
+- **objectui** at the `.objectui-sha` pin `89cad75d55`: 689 `object-grid`, 240 `object-kanban` and 160 `object-calendar` nodes (the control on 293 / 108 / 98). Across the eight members, 241 values are static, and 233 of them parse. Each of the 8 that do not is a test fixture whose value the renderer drops, skips or refuses: 2 object entries in `bulkActions` (the renderer skips them, and the tests assert the skip), 3 object entries in `fields` that copy the hand-off the list view makes to the grid at run time (not an authored page), a lane `color` (retired in the console; the test marks it an undeclared member), and 2 uses of the calendar's retired `dateField` / `endField` aliases (the test asserts their refusal). No refused value is one the renderer draws. 24 values are not static (helper parameters, `.map` results and the run-time hand-offs); none of them is an authored page. The grid's `columns` (310 static values) is held because 2 of them author a column `options` the grid draws in its group headers, a fixture written to pin that behaviour.
 - **Deployed metadata** was not measured.

packages/spec/src/migrations/entries/semantic/18.ui-object-grid-kanban-calendar-list-members-typed.ts

@@ -2,44 +2,45 @@
 
 import type { SemanticMigration } from '../../types.js';
 
-// #21464 — the list members of the `object-grid`, `object-kanban` and
+// #21464 — eight list members of the `object-grid`, `object-kanban` and
 // `object-calendar` page blocks were `z.unknown()` (an array of it for the
 // lists) although each renderer reads them with a fixed shape, so an off-shape
 // value passed the component-props gate and the block dropped or substituted it
 // in silence. The rows now take the list view's own members by reference where
-// a list view declares one, and the measured shape otherwise. D3 only:
+// a list view declares one, and the measured shape otherwise. The grid's
+// `columns` is held at `z.unknown()`: the grid draws a column's `options`,
+// which the list view's column entry does not declare. D3 only:
 // page-component `properties` is not parsed on the metadata save or load path,
 // so a stored page is never refused; an off-shape value has no rewrite that
 // says what the author meant; and the authored census found no authored value
 // to respell — the refused values are fixtures probing that the renderer drops
 // them.
 export const entry: SemanticMigration = {
   id: 'ui-object-grid-kanban-calendar-list-members-typed',
-  surface: 'page `object-grid` components — `properties.columns`, `.fields`, `.selection`, `.selectable`, '
+  surface: 'page `object-grid` components — `properties.fields`, `.selection`, `.selectable`, '
     + '`.rowActions`, `.bulkActions` and `.batchActions`; page `object-kanban` components — '
     + '`properties.columns`; page `object-calendar` components — `properties.calendar` (which used to '
     + 'accept any value)',
-  replacement: 'the shape each block reads, the list view\'s own where it has one: `object-grid` `columns` '
-    + 'all field-name strings or all column entries `{ field, label?, width?, … }` (never mixed); `fields` '
+  replacement: 'the shape each block reads, the list view\'s own where it has one: `object-grid` `fields` '
     + 'field-name strings; `selection` `{ type }` with `none` / `single` / `multiple`; `selectable` `true`, '
     + '`false`, `\'single\'` or `\'multiple\'`; `rowActions`, `bulkActions` and `batchActions` action-name '
     + 'strings. `object-kanban` `columns` all lanes `{ id, title, cards?, limit?, className?, collapsed? }` '
     + 'or all bare value strings (never mixed), a lane `id` a string. `object-calendar` `calendar` '
-    + '`{ startDateField, endDateField?, titleField?, colorField?, allDayField? }`. Rewrite a grid column '
-    + 'written `{ accessorKey, header }` or `{ name }` as `{ field, label }`; move an object entry of '
-    + '`fields` to `columns`; move a `{ name }` entry of `bulkActions` to `bulkActionDefs` or write the '
+    + '`{ startDateField, endDateField?, titleField?, colorField?, allDayField? }`. Move an object entry '
+    + 'of `fields` to `columns`; move a `{ name }` entry of `bulkActions` to `bulkActionDefs` or write the '
     + 'bare name; style a lane with `className` instead of `color`; rename `dateField` / `endField` to '
     + '`startDateField` / `endDateField`.',
   reason: 'Each renderer reads these members with one shape, and the page-component rows declared them '
     + '`z.unknown()`, so any value passed the component-props gate and the block answered an off-shape one '
-    + 'with a silent default: a grid column keyed `accessorKey` or `name`, or an array mixing strings and '
-    + 'column objects, drew no column; an object entry of `fields` named no field; a `{ name }` entry of '
+    + 'with a silent default: an object entry of `fields` named no field; a `{ name }` entry of '
     + '`bulkActions` was skipped; a kanban lane list mixing objects and strings drew a blank lane and swept '
     + 'its records into the trailing lane; and a calendar block without `startDateField` placed no event. The rows '
-    + 'now take the list view\'s own `columns`, `selection`, `rowActions`, `bulkActions` (for `batchActions` '
+    + 'now take the list view\'s own `selection`, `rowActions`, `bulkActions` (for `batchActions` '
     + 'too, the spelling the grid reads first) and `calendar` members by reference, and the measured shape '
     + 'for the grid\'s `fields` and `selectable` and the kanban lane, so one value is judged the same way '
-    + 'on every door that carries it. It is read where every page component\'s props are: the '
+    + 'on every door that carries it. The grid\'s `columns` is not narrowed: its group-header labels read '
+    + 'an authored column\'s `options`, which the list view\'s column entry does not declare, so it stays '
+    + 'open until that read is ruled. It is read where every page component\'s props are: the '
     + 'component-props gate reports a refused value as an advisory `component-props-invalid` / '
     + '`component-props-unknown-key` finding on `objectstack validate`, `objectstack build` and '
     + '`objectstack lint`, and a stored page still saves and loads, because a page component\'s '
@@ -49,7 +50,7 @@ export const entry: SemanticMigration = {
     + 'the upgrader. Deployed metadata NOT MEASURED.',
   acceptanceCriteria: 'Every `object-grid`, `object-kanban` and `object-calendar` node validates: '
     + '`objectstack validate` reports no `component-props-invalid` / `component-props-unknown-key` '
-    + 'finding under the nine members\' paths. Each block that set one of them now shows it: the declared '
-    + 'grid columns, the selection mode, the row and bulk actions, the kanban lanes with their records, and '
+    + 'finding under the eight members\' paths. Each block that set one of them now shows it: the grid\'s '
+    + 'field fallback, the selection mode, the row and bulk actions, the kanban lanes with their records, and '
     + 'the calendar events placed by `startDateField`.',
 };