From e8714f782728452703eed992b1520d711f853999 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 00:37:03 +0000 Subject: [PATCH] docs(schema-reference,skills): object-grid columns key off `field`, not `name` (#5352) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two published corpora authored `object-grid` columns in a `name` spelling that `ObjectGrid` does not read. `ListColumnSchema` (`@objectstack/spec/ui`) is a strict object whose column-identity key is `field`; `{ name, label }` is refused by name (`unrecognized_keys: ["name"]`) and contributes no rendered column. Measured by rendering the doc bytes themselves, before and after: schema-reference.md headers ["#","Name","Email","Company","Phone","Actions"] -> headers ["#","Name","Email","Company","Phone","Status","Actions"] page-builder.md headers ["#"] (row-number column only, zero data columns) -> headers ["#","Name","Price","Status"] The schema-reference example needed more than a key rename: it authored a MIXED array, and `normalizeColumns` dispatches the whole array on `columns[0]`, so a column object standing behind a bare string is dropped whatever it spells. It is now uniformly `ListColumn` objects. The property table names `field` and states the no-mixing rule. The adjacent `object-form` example is deliberately untouched — `FormField.name` is that layer's real key, and that adjacency is the documented cause of this defect family (`packages/core/src/utils/column-identity.ts`). Renderer behaviour is unchanged; this is the docs half only, per triage. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01RV6yuVCxymHYE16PL9vQkE --- .changeset/grid-column-spelling-docs-5352.md | 30 ++++++++++++++++++++ content/docs/api/schema-reference.md | 12 ++++---- skills/objectui/guides/page-builder.md | 12 ++++++-- 3 files changed, 45 insertions(+), 9 deletions(-) create mode 100644 .changeset/grid-column-spelling-docs-5352.md diff --git a/.changeset/grid-column-spelling-docs-5352.md b/.changeset/grid-column-spelling-docs-5352.md new file mode 100644 index 0000000000..d80cdfb618 --- /dev/null +++ b/.changeset/grid-column-spelling-docs-5352.md @@ -0,0 +1,30 @@ +--- +--- + +Docs and skills only — this publishes nothing, declared explicitly with an empty +frontmatter rather than left undeclared. No package `src/` is touched, so no +`@object-ui/*` package changes behaviour and there is nothing here for a consumer +to upgrade to. + +Corrects the two published corpora that taught `object-grid` columns in a `name` +spelling `ObjectGrid` does not read. `ListColumnSchema` (`@objectstack/spec/ui`) is a +strict object whose column-identity key is `field`; `{ "name": ... }` is refused by +name (`unrecognized_keys: ["name"]`) and, at runtime, contributes no column. + +- `content/docs/api/schema-reference.md` — the `ObjectGridSchema` example authored a + MIXED array (four bare strings followed by one column object). Two defects in one + array: the object entry spelled `name`, and mixing forms is itself unsupported — + `normalizeColumns` dispatches the whole array on `columns[0]`, so a column object + standing behind a bare string is dropped whatever it spells. Renaming the key alone + does not fix it; the example is now uniformly `ListColumn` objects. The `columns` + row of the property table now names `field` and states the no-mixing rule. +- `skills/objectui/guides/page-builder.md` — the grid example's three columns were + all-object in the `name` spelling, so the grid rendered its row-number column and no + data columns at all. Now spelled `field`. A note was added between the grid and form + examples, which sit adjacent and mean the OPPOSITE thing by the same pair of words: + `ListColumn.field` names the object field a column shows, while `FormField.name` + names the field a form input writes. That adjacency is the documented cause of this + defect family (`packages/core/src/utils/column-identity.ts`). + +The adjacent `object-form` example is unchanged and was never wrong — `FormField.name` +is that layer's real key. diff --git a/content/docs/api/schema-reference.md b/content/docs/api/schema-reference.md index 38cd3a77bf..64af7bcc3e 100644 --- a/content/docs/api/schema-reference.md +++ b/content/docs/api/schema-reference.md @@ -747,11 +747,11 @@ A data grid that auto-fetches from an ObjectQL object definition. Includes searc "resizableColumns": true, "striped": true, "columns": [ - "name", - "email", - "company", - "phone", - { "name": "status", "label": "Status", "sortable": true } + { "field": "name" }, + { "field": "email" }, + { "field": "company" }, + { "field": "phone" }, + { "field": "status", "label": "Status", "sortable": true } ], "defaultSort": { "field": "name", "order": "asc" }, "operations": { @@ -777,7 +777,7 @@ A data grid that auto-fetches from an ObjectQL object definition. Includes searc | Property | Type | Description | |----------|------|-------------| | `objectName` | `string` | **Required.** ObjectQL object API name. | -| `columns` | `string[] \| ListColumn[]` | Columns to display. Strings auto-resolve from object metadata. | +| `columns` | `string[] \| ListColumn[]` | Columns to display. Either a plain array of field names (`["name", "email"]`), which auto-resolve from object metadata, or an array of `ListColumn` objects whose identity key is `field` (`{ "field": "status", "label": "Status" }`) — never `name`. **Do not mix the two forms in one array:** the array is dispatched on its first entry, so column objects sitting behind a bare string are dropped. | | `filter` | `any[]` | Pre-applied filter conditions. | | `sort` | `string \| SortConfig[]` | Default sort configuration. | | `searchableFields` | `string[]` | Fields included in search. | diff --git a/skills/objectui/guides/page-builder.md b/skills/objectui/guides/page-builder.md index cc2b16b279..2e1e86498c 100644 --- a/skills/objectui/guides/page-builder.md +++ b/skills/objectui/guides/page-builder.md @@ -302,14 +302,20 @@ renderers do (`schema.objectName`, `schema.columns`, `schema.fields`, "type": "object-grid", "objectName": "products", "columns": [ - { "name": "name", "label": "Name", "type": "text" }, - { "name": "price", "label": "Price", "type": "currency" }, - { "name": "status", "label": "Status", "type": "select" } + { "field": "name", "label": "Name", "type": "text" }, + { "field": "price", "label": "Price", "type": "currency" }, + { "field": "status", "label": "Status", "type": "select" } ], "bind": "products" } ``` +> **Grid columns key off `field`; form fields key off `name`.** The two layers sit +> next to each other here and use the same pair of words for opposite things: +> `ListColumn.field` names the object field a column shows, while `FormField.name` +> names the field a form input writes. A grid column written as `{ "name": ... }` +> names no field, so `ObjectGrid` drops it. + **Form plugin example:** ```json {