Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 6aa029b

Browse files
feat(types)!: an authored object-grid takes its props in the spec's properties bag; the flat spelling is refused by name (objectui#11276) (#11399)
Part of #11276 Clause-②: yes `Clause-②: yes`, copied from the PM claim `5936810446`: the strict face starts accepting the `properties` bag on an authored `object-grid`, which widens it, while the flat spelling narrows. This is objectui's narrowing-as-`minor` rule with a **BREAKING (authoring)** banner in the changeset, as in PR objectui#11328 and objectui#10859 batch 5. The `object-grid` batch of objectui#11276. It executes triage's answer `5922517855` Q2 ("**`object-grid`** comes next, in the shape PR objectui#11291 set for `object-form`. A block schema takes the `properties` bag, while the flat mirror keeps the `object-view` table slot.") under routing call A (`5921136804`). The card stays open: `flex` is the next batch (the maintainer's ruling A on objectui#11300). ## What changed - `packages/types/src/zod/objectql.zod.ts`: new `ObjectGridBlockSchema`, the construct of `ObjectFormBlockSchema` / `ObjectMapBlockSchema` / `ObjectGanttBlockSchema`: `BaseSchema` + the `object-grid` literal + `NODE_ENVELOPE` + `properties = propsBag('object-grid', stripImportedDefaults(SpecObjectGridPropsSchema))`, the installed 17.5.0 row by reference, no copy. Beside it: - `flatPropRefusals('object-grid', …)`, the shared helper `object-metric` / `object-master-detail-form` / `object-timeline` already spread. It refuses every row member written flat by name ("Did you mean `KEY` → `properties.KEY`?"), and it already encodes the two exceptions this row needs: `label` (also a node-level key of the spec's page component) stays on the node, and `defaultSort` (a `z.never` member of the row) keeps the row's own retirement. Chosen over a fourth per-arm map: it is the one copy, and the per-arm maps exist only because they predate it. - `dataSource`, the spec's `ElementDataSourceSchema` by reference (the registration is `elementDataSourceBlock`-wrapped). - the flat mirror's own tombstones for keys the row does not declare, by reference: `operators` (objectui#9739), `rowSpecActions`, `bulkSpecActions`, `name`, `placeholder`, `showFilters` (objectui#11068). `name` and `placeholder` are `BaseSchema` keys, so without them they would parse again. - `onNavigate` as the objectui#6124 runtime slot, spelled as the helper call the mirror uses (as `ObjectFormBlockSchema` spells its five), so `check:handler-key-reads` reads the disposition off this arm. - `body` / `children`, the mirror's objectui#9256 refusals by reference. - the record-source rule (objectui#11117) read in the bag: `requireRecordSource('object-grid', ['objectName'], 'properties')`. - The arm joins `ObjectQLPublicBlockComponentSchema` (`object-grid` is in `PUBLIC_BLOCKS`). `ObjectGridSchema` (the flat mirror) leaves `ObjectQLComponentSchema` (8 to 7 arms), stays exported and paired with its TypeScript twin, and **still builds the `object-view` `table` slot** (unchanged, pinned). - `packages/types/src/objectql.ts`: the TypeScript `ObjectGridSchema` is **re-declared, not retired** (docblock only: the node as `ObjectGrid` reads it after the hoist, and as code composes it); the union docblock names the count. - `index.zod.ts` (one barrel export), `public-blocks.zod.ts` (one docblock sentence naming the new spreader of `flatPropRefusals`), `zod/README.md`. - objectui's authored flat producers, rewritten to the bag (census below). - New pins: `packages/types/src/__tests__/object-grid-properties-bag-11276.test.ts` (88 rows + a type-level block) and `packages/plugin-grid/src/__tests__/ObjectGrid.propertiesBag-11276.test.tsx` (render through the real registry: the bag and a **stored flat node** make the identical `find` call and paint the same row; `SchemaRenderer`'s hoist is untouched). - Two changesets: `.changeset/11276-object-grid-properties-bag.md` (`@object-ui/types` minor, BREAKING (authoring) banner) and `.changeset/11276-plugin-grid-properties-bag-docs.md` (`@object-ui/plugin-grid` patch: README and two `src/` test files, no runtime change). **Files beyond the claimed surface, each forced:** - census rows the new export forces: `zod-mirror-parity.test.ts` (one `EXCLUSIONS` row; `EXPECTED_MIRROR_PAIRS` and the `ObjectGridSchema` drift ledger untouched), `imported-defaults-8317.test.ts` (one `IMPORTED` row), `objectql-union-arms-7363.test.ts` (7 arms), `registered-type-arms-10859-b2.test.ts` (literal list), `public-block-responsive-styles-10872.test.ts` (`object-grid` joins `DECLARES_DATA_SOURCE` and the smallest-bag table), `flat-arm-responsive-styles-10872.test.ts` (the flat population is `flex` alone; a row pins the mirror keeps the member), `flat-props-refusal-10872.test.ts` (one `VALID_BAG` row: the arm spreads that helper), `grouping-field-padded-refused-7347.test.ts` (a `NOT_COVERED` row: the row types `grouping` as unknown, see notes), `any-component-union-fanout.test.ts` (its literal control reads `object-view`); - fixture triage where a face now judges the bag (mirror rows keep the post-hoist spelling): `content-channel-e3-residual-9256.test.ts`, `strict-face-read-keys-11070.test.ts`, `object-grid-show-filters-retired-11068.test.ts`, `packages/cli/src/__tests__/validate-union-arm-selection.test.ts` (paths now `properties → objectName` and `properties → data → provider`; not a PR objectui#11069 file), `packages/plugin-grid/src/__tests__/guideCrudAppRenders.test.tsx` (reads the guide's bag). ## Zone 2, measured first 1. **Held.** At base `063119f`, through the built faces: the showcase's two `object-grid` nodes (bag) were refused by `safeValidateSchema` (`objectName` custom, "has no record source") and by the strict face (`unrecognized_keys [properties]` plus the same); the flat control passed both. The spec's `PageComponentSchema` accepted both bag nodes and refused the flat one (`unrecognized_keys [objectName, columns]`); control: flat `action:button` `actionType` refused the same way. 2. **Construct reused:** PR objectui#11291's (`object-form`, a spec row) rather than PR objectui#11328's (`object-chart`, no row, bag = mirror members), because `object-grid` has a row; refusals via the shared `flatPropRefusals` (as batch 10's arms), the record source as batches 5/6. 3. **`ComponentPropsMap['object-grid']` exists** in installed `@objectstack/spec` 17.5.0: it is the exported `ObjectGridPropsSchema` (`ComponentPropsMap['object-grid'] === ObjectGridPropsSchema`, 37 keys, strict). So the bag is that row by reference; no row invented, no mirror members used. 4. **Census** (instrument: `git grep -lE` for a `type` key equal to `object-grid` in any quoting, at base `063119f`, minus tests/snapshots/e2e; 27 files): | class | files | action | |:--|:--|:--| | authored, rewritten to the bag (42 nodes) | root `README.md`, `content/docs/api/schema-reference.md` (3, one in a `view-switcher` `views[].schema` slot, which the faces judge as a node), `content/docs/fields/grid.mdx`, `content/docs/guide/building-crud-app.md` (2 of 3; the third binds through `dataSource` only), `content/docs/guide/objectos-integration.mdx` (5), `content/docs/plugins/plugin-grid.mdx` (13), `content/docs/utilities/data-objectstack.mdx` (1 of 3; two bind through `dataSource` only), `content/docs/utilities/index.md`, `packages/plugin-grid/README.md` (13), both `examples/schema-catalog` `plugin-grid` entries | rewritten (11 files) | | authored, held by another PR | `content/docs/guide/layout.md` (1 node) | **not edited**: the file is in parked PR objectui#11069's diff (see Deviations) | | authored, governed | `skills/objectui/guides/page-builder.md` ("Grid plugin example", `os:check`-marked) | **listed, not edited**; needs a governed PR | | component mounts (`ObjectGrid` mounted directly with its flat `schema` prop, no hoist) | the `rowOperations` and TypeScript-support examples in `plugin-grid.mdx` and the plugin-grid README | kept flat, now said so in the text | | code composers / dev / demo (never meet a zod face) | `apps/console/src/dev/DevRowActions.tsx`, plugin-designer `FieldDesigner.tsx` / `ObjectManager.tsx`, `packages/plugin-grid/demo/bulk-actions.tsx`, plugin-list `ListView.tsx`, plugin-view `ObjectView.tsx` | kept flat | | comments only | fields `RecordPickerDialog.tsx`, plugin-calendar `ObjectCalendar.tsx`, `scripts/check-doc-component-types.mjs`, `scripts/regenerate-known-schema-types.mjs` | none | | declarations / pending changesets | `objectql.ts`, `objectql.zod.ts`; `.changeset/11117-…`, `.changeset/7762-…` | this change / records | Triage's "12 authored docs and 2 catalog documents" re-derives as 11 rewritten files (9 docs + 2 catalog) plus `layout.md` (held) and the governed skill. TS-typed doc nodes handed to `SchemaRenderer` were authored documents: their annotation moves to `BaseSchema`, and each bag is checked with `satisfies ObjectGridProps` (the spec's row type), so the examples keep a key-checking annotation. **Stop line: not tripped.** The zod `ObjectGridSchema` object's readers are the union (left) and the `object-view` `table` slot, which the ruling keeps on the mirror; every other flat context reads the TypeScript twin. 5. **Showcase.** objectstack `origin/main` `862f12c` has **two** `object-grid` nodes, not one: `command-center.page.ts` (`cc_queue_g`, with `responsiveStyles`) and `my-work.page.ts` (with a `ViewFilterRule` filter). Both pass `safeValidateSchema` and `StrictAnyComponentSchema` (the face PR objectui#11069 wires), pinned verbatim. PR objectui#11069's own census script is not in the tree, so its count is NOT MEASURED; its verdict is the strict face's, which accepts them. ## Tests (heavy runs through `os-verify-lock.sh`, slot `issue-11276-grid`; Node v22.22.2 from `/opt/nvm`) - **Red first** at the arm commit `a63b228d`: `pnpm exec vitest run packages/types/` gave `Tests 23 failed | 8369 passed (8392)`, 12 files, exactly the census and fixture rows above. - **Union at `e4927b7d`:** `pnpm exec vitest run packages/types/ packages/cli/ examples/schema-catalog/`: `Test Files 379 passed (379)`, `Tests 11090 passed (11090)`, VERDICT 0. `scripts/__tests__/`: `Test Files 177 passed | 2 skipped (179)`, `Tests 5417 passed | 2 skipped (5419)`, VERDICT 0. - **Consumer sweep at `e4927b7d`:** 414 test files outside `packages/types` / `packages/cli` / `scripts` / the catalog that name `AnyComponentSchema`, `StrictAnyComponentSchema`, `safeValidateSchema`, either ObjectQL union, `ObjectGridSchema`, `object-grid`, `plugin-grid`, `PUBLIC_BLOCKS`, `ComponentPropsMap`, `validateSchema` or a moved doc; three chunks: `135 / 2219`, `141 / 1230`, `138 / 1586` (files / tests), each VERDICT 0. - The later head `9f45be6d` only returns one line of `layout.md` to `main`'s bytes; its 10 reader test files re-ran there: `Tests 107 passed (107)`. - **Type-check:** `pnpm --filter @object-ui/types type-check` VERDICT 0, the pin in `tsconfig.test.json`'s program (`--listFilesOnly`). `pnpm --filter @object-ui/plugin-grid type-check` VERDICT 0 after building its closure (13 tasks). - **Runtime ablation** (objectstack `scripts/ablation-replace.mjs`, two nested legs, plus an EXIT/INT/TERM trap restoring by absolute path): `ObjectGridBlockSchema` out of the public union (anchor x1 to x0, blob `b3fb5a65` to `fb23a21b`) and `ObjectGridSchema` back into `ObjectQLComponentSchema` (x1 to x0, blob to `e277bcf6`); on disk 0 / 1. Over 13 files: `Tests 84 failed | 761 passed (845)`: red = 69 rows of the new pin + 15 census/triage rows; green = the untouched `object-gantt` b6 and `object-chart` pins and the pin's arm-independent rows. Restored: blob == HEAD `b3fb5a65`, `git diff HEAD` empty. A first attempt was refused by the tool (ANCHOR MISS on a quoting error) and ran nothing. - **Type-level reverse validation** (same tool): the `flatPropRefusals` spread deleted gave `tsc -p tsconfig.test.json` exit 2 with exactly 8 errors, all on the pin's flat-key and every-row-key rows (TS2339 x6, TS2344 x2). Restored, blob == HEAD. - **Doc sweep** (a scratch instrument, not committed): every JSON document under `*.md` / `*.mdx` / `*.json` that holds an `object-grid` node (23) through both faces: refused = 2, `layout.md` (held) and the governed skill; that refusal is the instrument's lit control. - **Changed TS doc blocks** (`check:doc-snippets` needs the whole tree built, below): the 13 `BaseSchema` bag statements compile against the built `@object-ui/types` and the installed spec with `satisfies ObjectGridProps` (control: a misspelt `objectNam` is TS2561); the 6 changed `tsx` blocks compile in full against the built `react` / `data-objectstack` / `types` closure (control: an injected TS2322 fires). Scratch harness, removed. ## Gates (exit codes captured before any pipe, at `9f45be6d` unless marked) - exit 0: `check:new-line-citations` ("VERDICT new-cross-file-line-citations: 0 new citation(s)"), `check:control-bytes` ("OK (scanned 9915 tracked text file(s); skipped 85 binary)"), `check:doc-types` ("Every documented component type is registered."), `docs:check-links`, `check:handler-key-reads` ("OK 140 arm(s), 212 registration(s) (138 keyed onto an arm), 56 reachable handler read(s), 56 judged"), `check:spec-symbols`, `check:doc-example-ids`, `check:doc-fences`, `check:pending-changeset-literals`, `changeset:check` ("No changeset declares a `major` bump."), `check:governed-queue-guard`, `node scripts/markdown-test-inputs.mjs --audit` ("109 candidate test files, all adjudicated; 81 declared entries, all present"), `node scripts/check-changeset-presence.mjs` ("21 source file(s) of 3 released package(s) changed, and this change declares 2 changeset(s)"), `check-governed-queue-guard.mjs --test` over the 34 paths ("NOT GOVERNED"). At `e4927b7d`: `check:element-data-source-declaration`, `check:component-surface-parity`, `check:prompt-keys`, `check:test-path-roots`, `check:installed-pin-claims`, `check:vi-mock-specifiers`, `check:changeset-claims` (report-only; the pending `object-grid` changesets are answered in this PR's changeset). - eslint narrowing: `eslint --no-inline-config --format json` over the 20 changed `.ts` / `.tsx` files: 0 errors, 59 warnings, all `no-explicit-any`, 0 on an added line. `eslint.config.js` sets no `projectService` / `parserOptions.project`, so no untouched file's verdict can move. The full `pnpm lint` is CI's. - **NOT MEASURED** (PREREQUISITE NOT MET: unbuilt packages): `check:doc-snippets` (exit 2), `check:doc-examples` (exit 2; no `@example` changed), `check:skill-examples` (exit 2; no skill changed), `check:sdui-registration-pins` (exit 2, no console build), `check:readme-exports` (exit 1 with "the population COLLAPSED", 22 packages unbuilt; among what it did judge, 0 wrong-path, 0 fabricated). CI builds first. ## Deviations - **`content/docs/guide/layout.md` is not moved.** The order says both "⛔ Not PR objectui#11069's files" and "move every non-governed one … so no interval exists where `objectui validate` refuses objectui's own documents". The claim's read ("None touches … the docs this batch moves") is false for this file: PR objectui#11069 edits its prose two lines below the JSON block. I kept off the file (batch 4 did the same with `validate.ts`), so its one flat `object-grid` node is refused by `objectui validate` until it moves. Measured for the seat's call: the one-line move merges cleanly with PR objectui#11069's version of the file (`git merge-file` exit 0, no markers); PR objectui#11069 already conflicts with `main` at `packages/cli/src/commands/check.ts`, and this branch adds no conflict. - A second changeset (`@object-ui/plugin-grid` patch) beside the ordered one: the two plugin-grid `src/` test files require one, and the README is that package's (batches 4 and 6 did the same). - The first commit's body carries a `Part of #11276` line; the card relationship is declared here, and the history is not rewritten. - A few small vitest runs went outside the lock while iterating (the new pin alone, the cli arm-selection file alone, and one four-file re-check); every union, sweep, build and type-check above went through it. ## Acceptance notes - **The bag follows the spec row, which is not the flat mirror** (pinned). `filter` / `defaultFilters` take the `ViewFilterRule` array only, so the tuple form, the record form and a record-form `defaultFilters` are refused in the bag. The row types `columns` entries, `selection`, `exportOptions`, `operations`, `navigation`, `grouping` and a few display keys as unknown, so those shapes are not judged in the bag. - **`exportOptions`:** a bare format array, refused by name on the flat mirror (objectui#7762), parses in the bag (the row's `z.unknown()`), and `ObjectGrid` still reads only `exportOptions.formats`, so it is dropped for the csv/json default. Not re-added on the consumer side (the row is the declaration); reported as a finding on the spec row. - **`emptyState`:** `ObjectGrid` reads it (objectui#11068) but the row does not declare it, so it is refused in the bag and, on the node, by the strict face: not authorable in a document today. The docs now say so; reported as a finding on the spec row. (`keyboardNavigation` is refused the same way, and nothing reads it.) - **The row declares keys the mirror does not** (`rowHeight`, `grouping`, `aggregations`, `conditionalFormatting`, `rowColor`, `bulkActionDefs`, `navigation`, `singleClickEdit`, `resizableColumns`, `reorderableColumns`, `operations`): they parse in the bag, judged by the row. The mirror's drift ledger in `zod-mirror-parity.test.ts` (objectui#6152's) is untouched. - **`grouping` in the bag is unjudged** (the row's `z.unknown()`), so objectui#7347's padded-field refusal does not reach it; the census records `object-grid` as not covered, with that reason pinned. - **Record source:** the arm keeps the mirror's rule (`properties.objectName` or a binding). The spec row is looser (the recorded divergence, as on `object-map` / `object-gantt`). - The `objectos-integration.mdx` fragments also dropped keys no grid reads (`rowData`, `callbacks`, `rowSelection`, `exportConfig`, the adapter written on the node): the hooks block hands its rows over as inline `ViewData`, the callback block became a compiled `tsx` block passing `onRowClick` as a component prop, the Retool block maps to `bulkActions` / `exportOptions`, and the unit-test block passes the adapter as the renderer's `dataSource` prop. ## Overlap Merged `main` at `d59f11c0` (two commits, `app-shell` and `layout` only) before opening; no open PR names `objectql.zod.ts`. Session: `https://claude.ai/code/session_01JG2jy8a9su7ia4Hx7zxv42` (dispatched by seat `domain:ui#2`; this run is its subagent on branch `claude/issue-11276-object-grid-properties-bag`). --- _Generated by [Claude Code](https://claude.ai/code/session_01JG2jy8a9su7ia4Hx7zxv42)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent e100589 commit 6aa029b

35 files changed

Lines changed: 1482 additions & 405 deletions
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
'@object-ui/types': minor
3+
---
4+
5+
feat(types): an authored `object-grid` takes its props in the spec's `properties` bag; the flat spelling is refused by name (objectui#11276)
6+
7+
**BREAKING (authoring):** an `object-grid` node that writes its props on the node itself is now refused by `safeValidateSchema`, `validateSchema` and the strict authoring face, and so by `objectui validate`. Move each prop into the node's `properties` bag:
8+
9+
```json
10+
{ "type": "object-grid", "properties": { "objectName": "task", "columns": ["title", "status"], "sort": [{ "field": "title", "order": "asc" }] } }
11+
```
12+
13+
Nothing changes at render time: `SchemaRenderer` hoists every `properties` key onto the node before `ObjectGrid` runs, so the bag node draws what the flat one drew, and a stored flat node, or a node built in code (`ObjectView`, `ListView`, the designers, a host mounting `<ObjectGrid schema={…}>`), keeps working with its flat keys.
14+
15+
**Clause-②: yes** — the accept set narrows (a flat `object-grid` node that parsed is refused) and widens (a spec-shaped bag node that was refused parses). Released as `minor` under the objectui narrowing rule, with this banner.
16+
17+
**Why.** `@objectstack/spec`'s `ComponentPropsMap['object-grid']` row is the published declaration of an authored `object-grid` node's props, and the spec's own strict `PageComponentSchema` refuses a prop written on the node as mis-layered (ADR-0089 D3a). The arm here was the flat mirror of the TypeScript `ObjectGridSchema`, so the two validators disagreed both ways: the objectstack showcase's work queues, written in the bag, were refused (the flat mirror found no `objectName` on the node), and the flat node `os validate` refuses was accepted.
18+
19+
**What changed, in observable terms.**
20+
21+
- `@object-ui/types/zod` exports `ObjectGridBlockSchema`, built the way `ObjectGanttBlockSchema` is: `BaseSchema`, the `object-grid` literal, the node-level `responsiveStyles`, the node's `dataSource` binding (the spec's `ElementDataSourceSchema`), and `properties`, which is the spec row by reference, so the row's members, value types and strictness judge the bag.
22+
- Each member of the row written flat on the node is refused on both faces, with a message that names its bag member (`Did you mean \`objectName\` → \`properties.objectName\`?`). The refusal set is read off the row. `label` stays on the node too, because the spec's page component declares a node-level `label`; a flat `defaultSort` keeps the row's own retirement message. `operators`, `rowSpecActions`, `bulkSpecActions`, `name`, `placeholder` and `showFilters` keep their retirement messages, `onNavigate` stays a refused runtime slot, and `body` / `children` stay refused (objectui#9256).
23+
- The record-source rule stays, read in the bag: the node needs `properties.objectName`, or a `dataSource` binding naming the object. The spec has no such rule.
24+
- `ObjectGridBlockSchema` reaches `AnyComponentSchema` through `ObjectQLPublicBlockComponentSchema`. `ObjectGridSchema` leaves `ObjectQLComponentSchema`.
25+
- Inside the bag the spec row decides, and it differs from the flat mirror. `filter` and `defaultFilters` take the `ViewFilterRule` array only (`[{ field, operator, value }]`), so the tuple form, the record form and a record-form `defaultFilters` are refused there. The row types `columns` entries, `selection`, `exportOptions`, `operations`, `navigation`, `grouping` and a few display keys as unknown, so their shapes are not judged inside the bag: notably a bare-array `exportOptions`, which the flat mirror refuses by name (objectui#7762), is not refused there. The row declares keys the flat mirror does not (`rowHeight`, `grouping`, `aggregations`, `conditionalFormatting`, `rowColor`, `bulkActionDefs`, `navigation`, `singleClickEdit`, `resizableColumns`, `reorderableColumns`, `operations`), so they parse in the bag. It does not declare `emptyState` or `keyboardNavigation`, so the bag refuses them, and on the node the strict face refuses them as unknown keys: `emptyState` is not authorable in a document until the spec's row declares it.
26+
27+
**The same release's changesets** that describe what the validators say about an `object-grid` written flat (`.changeset/7762-object-grid-export-options-bare-array-refusal.md`, `.changeset/9739-object-grid-operators-tombstone.md`, `.changeset/11068-grid-declared-keys.md`, `.changeset/11068-object-grid-show-filters.md`, `.changeset/11117-datasource-objectname-waiver.md`, `.changeset/10872-flat-arm-responsive-styles.md` and others) describe the flat mirror, which still behaves as they say. On an authored node the props now live in the bag, where the spec row judges them as listed above; the retirements, the record-source rule and `responsiveStyles` hold there as they say.
28+
29+
**What did not move.** The TypeScript `ObjectGridSchema` and its zod mirror `ObjectGridSchema` stay published and unchanged in shape. They are the node as `ObjectGrid` reads it after the hoist, and as code composes it, and the `object-view` `table` slot is still built from the mirror.
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@object-ui/plugin-grid': patch
3+
---
4+
5+
docs(plugin-grid): authored `object-grid` examples write their props in the `properties` bag (objectui#11276)
6+
7+
The README's authored `object-grid` examples now write `{ "type": "object-grid", "properties": { … } }`, the spelling `@objectstack/spec`'s `ComponentPropsMap['object-grid']` row declares and `objectui validate` now requires, each bag checked with `satisfies ObjectGridProps` (the spec's row type). `emptyState` is described as what it is today: a key `ObjectGrid` reads that the spec's row does not declare, so not authorable in a document. The examples that mount `ObjectGrid` directly keep the flat `schema` prop: a component mounted without `SchemaRenderer` receives the node as it reads it, and nothing hoists a bag there. Under `src/`, a new render pin holds that the bag and a stored flat node draw the same grid, and the CRUD-guide render pin reads the guide's bag. No runtime change.

‎README.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -212,17 +212,19 @@ published is not an error: the expression is returned as its own source text.
212212
```json
213213
{
214214
"type": "object-grid",
215-
"objectName": "user",
216-
"title": "Users",
217-
"columns": [
218-
{ "field": "name", "label": "Name", "sortable": true },
219-
{ "field": "email", "label": "Email" },
220-
{ "field": "role", "label": "Role" },
221-
{ "field": "status", "label": "Status" },
222-
{ "field": "created_at", "label": "Joined" }
223-
],
224-
"showSearch": true,
225-
"operations": { "create": true, "read": true, "update": true, "delete": true, "export": true }
215+
"properties": {
216+
"objectName": "user",
217+
"title": "Users",
218+
"columns": [
219+
{ "field": "name", "label": "Name", "sortable": true },
220+
{ "field": "email", "label": "Email" },
221+
{ "field": "role", "label": "Role" },
222+
{ "field": "status", "label": "Status" },
223+
{ "field": "created_at", "label": "Joined" }
224+
],
225+
"showSearch": true,
226+
"operations": { "create": true, "read": true, "update": true, "delete": true, "export": true }
227+
}
226228
}
227229
```
228230

‎content/docs/api/schema-reference.md‎

Lines changed: 40 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -730,37 +730,36 @@ These schemas integrate with [ObjectStack](https://objectstack.ai) for automatic
730730

731731
A data grid that auto-fetches from an ObjectQL object definition. Includes search, filters, pagination, grouping, and inline editing.
732732

733+
An authored `object-grid` node takes its props in its `properties` bag, whose members are `@objectstack/spec`'s `ComponentPropsMap['object-grid']` row. `objectui validate` judges the bag against that row and refuses a prop written flat on the node by name, naming its bag member, as the spec's own page component does (objectui#11276). `SchemaRenderer` hoists the bag onto the node before `ObjectGrid` runs, so `ObjectGridSchema` is the node as the renderer reads it, and the table below lists its members. Base props such as `description` and `className` stay on the node, beside the bag.
734+
733735
```json
734736
{
735737
"type": "object-grid",
736-
"objectName": "Contact",
737-
"title": "All Contacts",
738738
"description": "Manage your contacts",
739-
"searchableFields": ["name", "email", "company"],
740-
"resizable": true,
741-
"columns": [
742-
{ "field": "name" },
743-
{ "field": "email" },
744-
{ "field": "company" },
745-
{ "field": "phone" },
746-
{ "field": "status", "label": "Status", "sortable": true }
747-
],
748-
"sort": [{ "field": "name", "order": "asc" }],
749-
"operations": {
750-
"create": true,
751-
"update": true,
752-
"delete": true,
753-
"export": true
754-
},
755-
"rowActions": ["edit", "delete"],
756-
"pagination": {
757-
"pageSize": 25,
758-
"pageSizeOptions": [10, 25, 50, 100]
759-
},
760-
"emptyState": {
761-
"title": "No contacts yet",
762-
"message": "Contacts you add appear here.",
763-
"icon": "users"
739+
"properties": {
740+
"objectName": "Contact",
741+
"title": "All Contacts",
742+
"searchableFields": ["name", "email", "company"],
743+
"resizable": true,
744+
"columns": [
745+
{ "field": "name" },
746+
{ "field": "email" },
747+
{ "field": "company" },
748+
{ "field": "phone" },
749+
{ "field": "status", "label": "Status", "sortable": true }
750+
],
751+
"sort": [{ "field": "name", "order": "asc" }],
752+
"operations": {
753+
"create": true,
754+
"update": true,
755+
"delete": true,
756+
"export": true
757+
},
758+
"rowActions": ["edit", "delete"],
759+
"pagination": {
760+
"pageSize": 25,
761+
"pageSizeOptions": [10, 25, 50, 100]
762+
}
764763
}
765764
}
766765
```
@@ -770,7 +769,9 @@ also author `showFilters` (now retired on this node, below), `striped` and
770769
`operations.read`, which nothing reads, and `selection: { enabled, mode }` and
771770
`pagination.enabled`, which the validator refuses: selection is spelled `selection: { type: 'multiple' }` (`'none'`,
772771
`'single'` or `'multiple'`), and `pagination` declares no on switch — its
773-
presence enables paging.
772+
presence enables paging. It also authored `emptyState`, which the grid reads but
773+
the spec's row does not declare, so it is not authorable in a document today (see
774+
its row below).
774775

775776
| Property | Type | Description |
776777
|----------|------|-------------|
@@ -789,7 +790,7 @@ presence enables paging.
789790
| `grouping` | `GroupingConfig` | Row grouping configuration. **Server-side**: the set of groups, every group count and every per-group aggregation come from the group header query (`dataSource.queryGroupHeaders`), and each group's rows are paged by the server. Rows handed in whole are grouped in the browser (exact); over a data source with no header query, a grid that fetches its own rows refuses grouping with an error naming `queryGroupHeaders`. |
790791
| `frozenColumns` | `number` | Number of columns frozen on scroll. |
791792
| `navigation` | `ViewNavigationConfig` | SPA navigation configuration. |
792-
| `emptyState` | `{ title?, message?, icon? }` | Drawn in place of an empty table: a Lucide `icon`, a `title` (default: the table's "No results found") and a `message` (default: none). Not drawn when a term in the grid's own server-side search box emptied it — the table and its search box stay (objectui#11068). |
793+
| `emptyState` | `{ title?, message?, icon? }` | Drawn in place of an empty table: a Lucide `icon`, a `title` (default: the table's "No results found") and a `message` (default: none). Not drawn when a term in the grid's own server-side search box emptied it — the table and its search box stay (objectui#11068). **Not authorable in a document today:** the spec's `object-grid` row does not declare it, so `objectui validate` refuses it in the `properties` bag, and the strict face refuses it on the node; a host mounting `<ObjectGrid schema={…}>` or composing the node in code can set it. |
793794

794795
> **`name`, `placeholder`, `rowSpecActions` and `bulkSpecActions` are retired on
795796
> this node (objectui#11068).** Nothing ever read them: `rowSpecActions` /
@@ -1282,8 +1283,10 @@ A toggle control that switches between different view types (list, grid, kanban,
12821283
"icon": "List",
12831284
"schema": {
12841285
"type": "object-grid",
1285-
"objectName": "Contact",
1286-
"columns": ["name", "email", "phone"]
1286+
"properties": {
1287+
"objectName": "Contact",
1288+
"columns": ["name", "email", "phone"]
1289+
}
12871290
}
12881291
},
12891292
{
@@ -1366,10 +1369,12 @@ Schemas are designed to compose. Nest any `SchemaNode` inside another to build c
13661369
},
13671370
{
13681371
"type": "object-grid",
1369-
"objectName": "Lead",
1370-
"title": "All Leads",
1371-
"showSearch": true,
1372-
"columns": ["name", "company", "status", "value"]
1372+
"properties": {
1373+
"objectName": "Lead",
1374+
"title": "All Leads",
1375+
"showSearch": true,
1376+
"columns": ["name", "company", "status", "value"]
1377+
}
13731378
}
13741379
]
13751380
}

‎content/docs/fields/grid.mdx‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -236,20 +236,23 @@ For advanced grid features, use the grid plugin (`@object-ui/plugin-grid`):
236236
{ type: 'grid', name: 'items', columns: [...] }
237237
238238
// Advanced grid with full features (requires plugin)
239-
// Keys sit on the node — a `props` envelope is never read by the renderer
239+
// The block's props go in its `properties` bag (the spec's
240+
// `ComponentPropsMap['object-grid']` row) — a `props` envelope is never read
240241
{
241242
type: 'object-grid', // the registered type name — there is no `plugin:grid`
242-
bind: 'items', // resolves the array from the surrounding data scope
243-
columns: [ // spec `ListColumn[]` — each entry is keyed by `field`
244-
{ field: 'product', label: 'Product' },
245-
{ field: 'quantity', label: 'Quantity', sortable: false }
246-
],
247-
editable: true, // Plugin feature: inline cell editing
248-
pagination: { pageSize: 20 } // Plugin feature: pagination
243+
bind: 'items', // node-level: resolves the array from the surrounding data scope
244+
properties: {
245+
columns: [ // spec `ListColumn[]` — each entry is keyed by `field`
246+
{ field: 'product', label: 'Product' },
247+
{ field: 'quantity', label: 'Quantity', sortable: false }
248+
],
249+
editable: true, // Plugin feature: inline cell editing
250+
pagination: { pageSize: 20 } // Plugin feature: pagination
251+
}
249252
}
250253
```
251254

252-
**Note**: `editable` and `pagination` are read off the node by `@object-ui/plugin-grid`, not by the basic grid field. Sorting and search are **not** node keys: column sorting is on by default and is turned off per column (`{ field, sortable: false }`), and there is no node-level `filterable` — a grid that fetches its own rows declares its query with `objectName` plus `filter` / `sort`.
255+
**Note**: `editable` and `pagination` are read by `@object-ui/plugin-grid` (after `SchemaRenderer` hoists the bag onto the node), not by the basic grid field. Sorting and search are **not** node keys: column sorting is on by default and is turned off per column (`{ field, sortable: false }`), and there is no node-level `filterable` — a grid that fetches its own rows declares its query with `objectName` plus `filter` / `sort`.
253256

254257
## Use Cases
255258

‎content/docs/guide/building-crud-app.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -227,7 +227,7 @@ function App() {
227227
<SchemaRenderer
228228
schema={{
229229
type: 'object-grid',
230-
objectName: 'task',
230+
properties: { objectName: 'task' },
231231
}}
232232
/>
233233
</div>
@@ -253,7 +253,9 @@ a grid that draws its header and nothing else:
253253
`dataSource` written on the block itself reaches that one block and never
254254
becomes context for anything under it.
255255
- **The object is named by `objectName`.** That is the key each of these blocks
256-
declares as required; a differently-spelled key (`object`) is not read, so the
256+
declares as required — inside the `properties` bag on `object-grid` and
257+
`object-form`, as the spec's page component declares their props, and on the
258+
node on `detail-view`; a differently-spelled key (`object`) is not read, so the
257259
block has no object to query.
258260

259261
Neither mistake used to say anything — the block simply rendered empty. Both now
@@ -278,7 +280,7 @@ carries a data source of its own:
278280
<!-- doc-snippet: fragment — JSX to place inside the Step 5 App component; showForm, editId and their setters are the state declared in the block above -->
279281
```tsx
280282
<SchemaRenderer
281-
schema={{ type: 'object-grid', objectName: 'task' }}
283+
schema={{ type: 'object-grid', properties: { objectName: 'task' } }}
282284
onRowClick={(row: any) => { setEditId(row.id); setShowForm(true); }}
283285
/>
284286

@@ -354,8 +356,8 @@ so this block does not offer that fallback.
354356
in the toolbar — on by default — and typing there drives
355357
`DataSource.find()`'s `$search` parameter directly; there is no separate
356358
query-param key to author. Add `searchableFields: ['title', 'description']`
357-
to the schema to narrow which fields the server matches; leave it out and the
358-
server decides.
359+
to the grid's `properties` bag to narrow which fields the server matches; leave
360+
it out and the server decides.
359361

360362
## Step 8: Add a Detail View
361363

‎content/docs/guide/layout.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ A `page` node has no action row of its own. Buttons are NODES, and they go in `c
173173
},
174174
{
175175
"type": "object-grid",
176-
"objectName": "products"
176+
"properties": { "objectName": "products" }
177177
}
178178
]
179179
}

0 commit comments

Comments
 (0)