docs(schema-reference,skills): object-grid columns key off field, not name (#5352)

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

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

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
 {