Skip to content

Commit 49c8568

Browse files
docs(spec): the app page record binding's describe and TSDoc say what the console does (#30663)
domain:spec#3 · os-sales · session_01L6bhgTqqeHSwZYJmApbDCa <!-- claude-projects-attribution: {"github_login":"os-sales"} --> _Requested by **Sales** · [project thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuKB8Sg6c6sVpL96ruVvdxaf)_ Fixes #30614 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`page.zod.ts` 中 app 页面 `record` 绑定的 describe 与 `PageRecordBindingSchema` TSDoc,以及组件 `visibleWhen` 的 describe 与 TSDoc,改写为控制台的真实行为,并重新生成参考页。 - 为什么改:旧文案说"渲染器尚未实现、`record` 不绑定",而控制台早已读取它;照文案写元数据的作者和 AI 会放弃一个能用的绑定。 - 风险与回滚:仅文案,无键、形状、默认值或导出变化;回滚即 revert 本 PR。 - 先看:`packages/spec/src/ui/page.zod.ts`(四处文案:`PageRecordBindingSchema` TSDoc、`record` describe、组件 `visibleWhen` TSDoc 含其「Measured on the renderer」段、`visibleWhen` describe)、`content/docs/ui/pages.mdx`(手写指南 `record` 行)、`packages/spec/liveness/page.json`(两条说明)。 - 两分钟验证:`git grep -n "Planned in the renderer\|faulting predicate renders\|configEvaluationScope" -- packages/spec/src/ui/page.zod.ts content/docs ':!content/docs/releases'` 预期零命中(在 4afb995 实测退出码 1、无输出)。 - 需要你做的:无,席位落地。 ## What changes - `packages/spec/src/ui/page.zod.ts`, the `PageRecordBindingSchema` TSDoc: the "Planned in the renderer" paragraph is replaced by what the console does. The binding is read once per page open (the first row under `sort`, under the caller's identity); every component's `visibleWhen` sees that row as `record`; a record block that binds its own row still provides that row to its own subtree; and the three states a predicate sees (pending: the body is not drawn; no row, or a read the server refuses as forbidden (403): `record` is null; any other failure: the body is not drawn). A page drawn through `interfaceConfig.source` reads no binding (round 2). - The same file, the `record` key's `.describe()`: the same reading, in one string. The parse half is unchanged and still stated: `type: 'app'` only (`checkPageRecordBindingPlacement`), a strict one-row shape with no `limit`. - The same file, the component `visibleWhen` TSDoc and `.describe()` (round 2, review escalation): "a faulting `visibleWhen` renders the component ... a gate that never gates" (TSDoc), "a faulting predicate renders the component, so such a gate never gates" and, for `hasCapability` on a host with no capability list, "a faulting predicate renders the component" (describe) now say the console withholds the component. `data.total > 0` and `data.total == 0` both hide it. The advice that the page's row is `record` is kept. - The same file, the `visibleWhen` TSDoc's "Measured on the renderer" paragraph (round 3, delta review 6672431263). It named `configEvaluationScope`, which does not exist under `ui/`, and said `record` is added "only when the page has a row — on an app page, once the renderer mounts the page's `record` binding". It now names `buildNodeEvaluationScope` and says `record` is the page's row: the record a record page opens, or the row an app page's `record` binding reads, `null` when that read finds no row or is refused as forbidden. - `content/docs/references/ui/page.mdx`: regenerated by `gen:docs`, never hand-edited. - `content/docs/ui/pages.mdx` :63, the hand-written `record` row of the Pages guide: "Planned in the renderer: until the console mounts it, `record` stays unbound on an `app` page" is replaced by the describe's reading, in the same words, kept as one table cell (round 1). A grep of `content/docs` outside `releases/` for "stays unbound" and "Planned in the renderer" now finds no hit. - `packages/spec/liveness/page.json`, the `props.regions` note (round 3): the `[120] PageComponent.visibleWhen` read point named `SchemaRenderer.tsx#configEvaluationScope` with `record` "only when the page has a row". It now names `ui/packages/react/src/SchemaRenderer.tsx#buildNodeEvaluationScope` (noting the old name at objectui @1fb1ced36243) and states the same `record` reading as the TSDoc. - `packages/spec/liveness/page.json`, the `props.record` note: its last sentence said this describe and TSDoc were stale. This PR makes that false, so it now says they state the same reading. - `.changeset/30614-page-record-binding-describe.md`: `@objectstack/spec` patch, which also names the Pages guide row. Every sentence was checked against the readers on `origin/main` `b8929f486`: `ui/packages/app-shell/src/views/PageView.tsx` (`appPageRecordBinding`, `AppPageRecordGate`, `AppPageRecordRead` with `$top: 1` and `$orderby` from `sort`), `ui/packages/app-shell/src/providers/ExpressionProvider.tsx#PageRecordScope`, `ui/packages/react/src/SchemaRenderer.tsx#buildNodeEvaluationScope`, and the pin `ui/packages/app-shell/src/views/__tests__/PageView.appPageRecord-12931.test.tsx`. ## Tests No behaviour changes, so there is no new test and no ablation. The `@objectstack/spec` page suites pass, spec typecheck passes, and `check:generated` reports all 14 artifacts up to date. ## Acceptance notes - Two old sentences beyond "Planned in the renderer" were also false against the console, and were replaced as part of stating the three states. The TSDoc said zero rows or a refused row "leaves `record` unbound: a predicate reading it faults, and a faulting `visibleWhen` renders the component". The describe said "No row, no `record`: the predicate faults and the component renders". On `main`, `AppPageRecordRead` binds `record` as `null` for both cases (pinned by the 0-row and 403 cases of the pin test). Separately, `SchemaRenderer.tsx#visibilityFaultOutcome` now fails a declared `visibleWhen` closed on a fault, so "renders" is no longer the verdict. The new text does not describe the fault verdict of a field read on a null `record`, because no test pins it. - `packages/spec/liveness/page.json`, the `props.record` note: its last sentence ("The schema's own describe() and TSDoc still say 'Planned in the renderer' — stale prose left for a spec change") was made false by this PR. It now reads "The schema's own describe() and TSDoc state this same reading." It ships (`liveness` is in the package's `files`), the claim's file surface was amended to hold it (6670237155), and `check:liveness` is green. - `content/docs/ui/pages.mdx` :63 carried the same stale sentence and is fixed in round 1, under the amended claim (6670237155). The Pages guide row was already silent on the no-row verdict, so only the "Planned in the renderer" sentence was false there. It gains the three states the describe states, and no claim the describe does not make. - Round 2 (contract review 6671102362, PASS, should-fix S1-S3 and the escalation; claim amendment 6671162776): - S1: "a refused read" is narrowed to "a read the server refuses as forbidden (403)". Only 403 / `PERMISSION_DENIED` / `FORBIDDEN` classify `forbidden` (`ui/packages/react/src/utils/error-message.ts`). A 401, a 400 or rejected read, and api-disabled land in the failed-read state. - S2: the TSDoc drops "and the failed-read state stands in its place". An unresolved view, a refused filter or no adapter draws the gate's own panel (`ElementDataSourceGate.tsx`). The TSDoc now agrees with the describe: any other failure draws no page body. - S3: an `app` page that also sets `interfaceConfig.source` is drawn as `InterfaceListPage` outside `AppPageRecord` (`PageView.tsx`), so it reads no binding. One clause in both texts, and no refinement. - Escalation: since objectui#13299, `visibilityFaultOutcome` (`SchemaRenderer.tsx`) answers a declared `visibleWhen` that faults with `false`, pinned by `SchemaRenderer.nodeVisibilityFailClosed-13299.test.tsx` and `SchemaRenderer.visibleWhenRecordBinding.test.tsx` ("WITHHOLDS the block"). - Grep of `packages/spec/src/**` (non-test) and the hand-written `content/docs/**` for "faulting predicate renders", "faulting `visibleWhen` renders" and "never gates": only the `page.zod.ts` sites carried the false claim. The other hits (`automation/schemaless-node-config.zod.ts` decision `condition`, `ui/action.zod.ts` `pressed`, `data/object.zod.ts` `disabledWhen` fail-soft, `kernel/public-auth-features.ts`, two migration entries) carry no visibility fault-renders claim and are untouched. - Round 2b: `content/docs/ui/pages.mdx` :63 now matches the round-2 describe word for word on the two points, with "no row, or a read the server refuses as forbidden (403), binds `record` as null" and "A page drawn through `interfaceConfig.source` reads no binding". It is still one table cell and adds no other claim. - Not changed: the `ui/packages/app-shell/src/providers/ExpressionProvider.tsx` `PageRecordScope` docblock still states the fail-soft verdict (no `ui/` change). - `packages/spec/src/ui/page.zod.ts` keeps "re-read when the bound object is written": `AppPageRecordRead` keys its read on `useDataInvalidation(object)`, so it is still true beside "once per page open". ## Verification <details><summary>Local gates, round 3 (head 4afb995, after merging origin/main at 606df50)</summary> - `turbo run build --concurrency=2`: lock VERDICT command-exit 0, 119/119 tasks. - `gen:docs && check:generated && vitest run` over the page suites `&& typecheck` (spec): lock VERDICT command-exit 0. "All 14 generated artifacts are up to date" (no regenerated diff: the edited paragraph is TSDoc only). Test Files 10 passed (10), Tests 572 passed (572). `check:test-typecheck: OK`. - `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0. - `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97 commands, all exit 0 on the first pass (`check:liveness` among them). `--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN". - `check-changeset-no-major --base origin/main`: "This diff introduces no `major` bump". - The two-minute grep in 维护者速读: exit 1, no output. </details> <details><summary>Local gates, round 2b (head 0aeb81b, after merging origin/main at 8f4aaf7)</summary> - `turbo run build --concurrency=2`: lock VERDICT command-exit 0, 119/119 tasks. - `pnpm --filter @objectstack/spec check:generated`: exit 0, "All 14 generated artifacts are up to date". - `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97 commands, all exit 0 on the first pass (`check:doc-authoring`, `check:doc-anchors`, `check:doc-frontmatter`, `check:docs-single-h1` and `check:docs-redirects` among them). `--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN". - `check-changeset-no-major --base origin/main`: "This diff introduces no `major` bump". </details> <details><summary>Local gates, round 2 (head f7299af, after merging origin/main at 4533101)</summary> - `turbo run build --concurrency=2`: lock VERDICT command-exit 0, 119/119 tasks. - `gen:docs && check:generated && vitest run` over the page suites `&& typecheck` (spec): lock VERDICT command-exit 0. "All 14 generated artifacts are up to date". Test Files 10 passed (10), Tests 572 passed (572). `check:test-typecheck: OK`. - `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0. - `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97 commands, all exit 0 on the first pass. `--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN". - `check-changeset-no-major --base origin/main`: "This diff introduces no `major` bump". </details> <details><summary>Local gates, round 1 (head 03429fc, after merging origin/main)</summary> - `turbo run build --concurrency=2`: lock VERDICT command-exit 0, 119/119 tasks. - `pnpm --filter @objectstack/spec check:generated`: exit 0, "All 14 generated artifacts are up to date". - `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97 commands, all exit 0 on the first pass, `check:doc-authoring`, `check:doc-anchors`, `check:doc-frontmatter` and `check:docs-single-h1` among them. `--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN". - `check-changeset-no-major --base origin/main`: "This diff introduces no `major` bump". </details> <details><summary>Local gates, round 0 (head 2529918)</summary> All read at head `2529918f4`, exit codes captured before any pipe. - `pnpm --filter @objectstack/spec build`: lock VERDICT command-exit 0. - `pnpm --filter @objectstack/spec gen:docs && pnpm --filter @objectstack/spec check:generated`: exit 0. "All 14 generated artifacts are up to date". The first `check:generated` run named `content/docs/references/**` stale. That page is regenerated in the second commit. - `vitest run` over `src/ui/page*.test.ts` (9 files) and `src/ui/object-refinement-check-exports.test.ts`: Test Files 10 passed (10), Tests 572 passed (572). - `pnpm --filter @objectstack/spec typecheck`: exit 0. - `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0. - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack`: 97 commands, all exit 0. Six first exited 3 (PREREQUISITE NOT MET, unbuilt workspace packages). They were re-run after `turbo run build` and exited 0. - `--ran` reconciliation: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN". - `check-changeset-no-major --base origin/main`: "This diff introduces no `major` bump". - Local-only: `check:dev-prereqs` exit 0, `check:skill-frame-freshness` exit 0. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 40a9265 commit 49c8568

5 files changed

Lines changed: 35 additions & 20 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
docs(spec): the app page `record` binding's describe and `PageRecordBindingSchema` TSDoc say what the console does
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The `record` key on `PageSchema` and the `PageRecordBindingSchema` TSDoc no longer say "Planned in the renderer". The console already reads the binding: once per page open, the first row under `sort`, under the caller's identity. Every component's `visibleWhen` sees that row as `record`, and a record block that binds its own row still provides that row to its own subtree. The text now names the three states a predicate sees: pending (the page body is not drawn), no row, or a read the server refuses as forbidden (403) (`record` is null), and any other failure (the page body is not drawn). A page drawn through `interfaceConfig.source` reads no binding. The old sentence that a missing row leaves `record` unbound and renders the component is gone, since the console binds `record` as null. The component `visibleWhen` describe and TSDoc no longer say a faulting predicate renders the component: the console withholds it, so a `data.*` read on an element no `api` data source binds, or `current_user.hasCapability(...)` on a host with no capability list, hides the component. No key, shape, default or export changes. The `props.record` liveness note drops its line that called this text stale, and the `record` row of the Pages guide (`content/docs/ui/pages.mdx`) now gives the same reading.

‎content/docs/references/ui/page.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ An any-of group: `{ or: [rule, ...] }` matches a record when ANY of its rules ma
223223
| **type** | `Enum<'record' \| 'home' \| 'app' \| 'utility' \| 'list'>` | optional (default: `"record"`) | Page type |
224224
| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array' \| 'record_id'>; defaultValue?: any; source?: string }[]` | optional | Local page state, exposed to expressions as `page.<name>` and writable by interactive elements via `source` (master/detail, filtered dashboards). |
225225
| **object** | `string` | optional | Bound object (for Record pages) |
226-
| **record** | `{ object: string; view?: string; filter?: (object \| object)[]; sort?: object[] }` | optional | The row an app page is about — a one-row query `{ object, view?, filter?, sort? }` whose FIRST row (by `sort`, read under the caller's identity) the page's components read as `record` in `visibleWhen`. A count or a plan is a field on that row: a `summary` roll-up (`record.environment_count > 1`) or the object's own field (`record.plan != 'free'`). No row, no `record`: the predicate faults and the component renders. Only on `type: 'app'` — refused on every other page type (a record page's row is the record it opens). Planned in the renderer: until the console mounts it, `record` stays unbound on an app page. |
226+
| **record** | `{ object: string; view?: string; filter?: (object \| object)[]; sort?: object[] }` | optional | The row an app page is about — a one-row query `{ object, view?, filter?, sort? }`. The console reads it once per page open: the FIRST row under `sort`, under the caller's identity. Every component's `visibleWhen` sees that row as `record`; a record block that binds its own row still provides that row to its own subtree. A page drawn through `interfaceConfig.source` reads no binding. A count or a plan is a field on that row: a `summary` roll-up (`record.environment_count > 1`) or the object's own field (`record.plan != 'free'`). Three states: while the read is pending, the page body is not drawn; no row, or a read the server refuses as forbidden (403), binds `record` as null; any other failure draws no page body. Only on `type: 'app'` — refused on every other page type (a record page's row is the record it opens). |
227227
| **template** | `Enum<'default' \| 'header-sidebar-main' \| 'three-column' \| 'dashboard'>` | optional (default: `"default"`) | Layout template — 'default', 'header-sidebar-main', 'three-column' or 'dashboard'. Each places its own regions (PAGE_TEMPLATE_SLOTS); a region the template does not place, or a second region filling the same slot, is refused at the region's name. |
228228
| **regions** | `{ name: string; width?: Enum<'small' \| 'medium' \| 'large' \| 'full'>; components: object[] }[]` | optional | Layout regions (header, main, sidebar, footer) with their components. Optional — list pages use interfaceConfig, slotted pages use slots, and an empty full page falls back to the synthesized default layout. |
229229
| **isDefault** | `boolean` | optional (default: `false`) | Whether this record page is the default record page of its `object` — the page the record view opens. At most one `isDefault: true` record page may exist for an object in a deployment: a second is refused (by defineStack / os validate, at package registration and at metadata save), naming both pages. Saving a page under the existing default's own name is that page, not a second default. Refused on any other page — a page that is not a record page bound to an object: nothing reads it there. An app opens on its first navigation item, and the root landing follows the app's own isDefault. |
@@ -348,7 +348,7 @@ An any-of group: `{ or: [rule, ...] }` matches a record when ANY of its rules ma
348348
| **style** | `Record<string, string>` | optional | Inline styles or utility classes |
349349
| **className** | `string` | optional | CSS class names |
350350
| **responsiveStyles** | `{ large?: Record<string, string \| number>; medium?: Record<string, string \| number>; small?: Record<string, string \| number>; xsmall?: Record<string, string \| number> }` | optional | Per-breakpoint scoped style maps (ADR-0065) |
351-
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Contract-bound roots: `record`, `current_user` (ADR-0068 aliases `user` / `ctx.user` — one object, three spellings), and page state as `page.<var>`. The shipping renderer additionally mounts `features` and `os.user` — renderer behaviour, NOT contract-guaranteed (ADR-0068 rules the user object only). It mounts NO `data` root on an element that no `api` data source binds: there a `data.*` read faults and a faulting predicate renders the component, so such a gate never gates; the page's row is `record` — the record a record page opens, or the row an app page's `record` binding reads (none without one; a block's own `dataSource` binds no `record` for its siblings). A count or a plan is a field on that row (a `summary` roll-up: `record.environment_count > 1`; `record.plan != 'free'`), never `features.*`, which are the deployment's public auth flags, the same for every organisation. `data` is mounted only on an element whose `dataSource` is an `api` data source (`provider: 'api'`): there, and on every element nested inside it, `data` is the value the binding selects, and the element's `visibleWhen` is decided once the read answers. To gate a component on a system capability, write `current_user.hasCapability('<name>')` with the name the gated action's `requiredPermissions` declares — it answers from the viewer's `systemPermissions`, the list the action gate reads, never a proxy such as `current_user.can('<object>', 'edit')`; a host that binds no capability list makes it fault, and a faulting predicate renders the component. ADR-0066 D4: `visibleWhen` hides, `requiredPermissions` refuses. ⚠️ A `page:tabs` item `visibleWhen` is a different evaluator: it binds `data` to the record ROW. e.g. "page.selectedProjectId != ''" |
351+
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Contract-bound roots: `record`, `current_user` (ADR-0068 aliases `user` / `ctx.user` — one object, three spellings), and page state as `page.<var>`. The shipping renderer additionally mounts `features` and `os.user` — renderer behaviour, NOT contract-guaranteed (ADR-0068 rules the user object only). It mounts NO `data` root on an element that no `api` data source binds: there a `data.*` read faults and a faulting predicate withholds the component, so `data.total > 0` and `data.total == 0` both hide it; the page's row is `record` — the record a record page opens, or the row an app page's `record` binding reads (none without one; a block's own `dataSource` binds no `record` for its siblings). A count or a plan is a field on that row (a `summary` roll-up: `record.environment_count > 1`; `record.plan != 'free'`), never `features.*`, which are the deployment's public auth flags, the same for every organisation. `data` is mounted only on an element whose `dataSource` is an `api` data source (`provider: 'api'`): there, and on every element nested inside it, `data` is the value the binding selects, and the element's `visibleWhen` is decided once the read answers. To gate a component on a system capability, write `current_user.hasCapability('<name>')` with the name the gated action's `requiredPermissions` declares — it answers from the viewer's `systemPermissions`, the list the action gate reads, never a proxy such as `current_user.can('<object>', 'edit')`; a host that binds no capability list makes it fault, and a faulting predicate withholds the component. ADR-0066 D4: `visibleWhen` hides, `requiredPermissions` refuses. ⚠️ A `page:tabs` item `visibleWhen` is a different evaluator: it binds `data` to the record ROW. e.g. "page.selectedProjectId != ''" |
352352
| **visibility** | `never` | optional | [REMOVED] `page.components[].visibility` was removed in @objectstack/spec 18 (ADR-0089 D2) — it was the page component's deprecated spelling of the conditional-visibility predicate, which the parse folded into `visibleWhen` until this release. Use `visibleWhen`. Rename the key; the value (a CEL predicate) is unchanged. Where a component writes both, `visibleWhen` is the one that was in effect: delete `visibility`. |
353353
| **dataSource** | `{ object: string; view?: string; filter?: (object \| object)[]; sort?: object[]; … } \| { provider: 'api'; read: object; path?: string }` | optional | Per-element data binding: an object binding `{ object, view?, filter?, sort?, limit? }` that overrides the page object, or an API binding `{ provider: 'api', read: { url }, path? }` that reads one same-origin endpoint |
354354
| **responsive** | `never` | optional | [REMOVED] `page.components[].responsive` was removed in @objectstack/spec 17 (ADR-0049 D2) — no renderer ever read it, so per-breakpoint layout overrides (columns/order/visibility) parsed, validated, and then did nothing. Delete the key. For breakpoint behaviour that IS applied, use the sibling `responsiveStyles` (ADR-0065) — per-breakpoint CSS maps compiled to id-scoped CSS at render, e.g. `responsiveStyles: { xsmall: { display: 'none' } }` to hide a component on the narrowest screens. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
@@ -528,7 +528,7 @@ Sort field and direction pair
528528
| **style** | `Record<string, string>` | optional | Inline styles or utility classes |
529529
| **className** | `string` | optional | CSS class names |
530530
| **responsiveStyles** | `{ large?: Record<string, string \| number>; medium?: Record<string, string \| number>; small?: Record<string, string \| number>; xsmall?: Record<string, string \| number> }` | optional | Per-breakpoint scoped style maps (ADR-0065) |
531-
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Contract-bound roots: `record`, `current_user` (ADR-0068 aliases `user` / `ctx.user` — one object, three spellings), and page state as `page.<var>`. The shipping renderer additionally mounts `features` and `os.user` — renderer behaviour, NOT contract-guaranteed (ADR-0068 rules the user object only). It mounts NO `data` root on an element that no `api` data source binds: there a `data.*` read faults and a faulting predicate renders the component, so such a gate never gates; the page's row is `record` — the record a record page opens, or the row an app page's `record` binding reads (none without one; a block's own `dataSource` binds no `record` for its siblings). A count or a plan is a field on that row (a `summary` roll-up: `record.environment_count > 1`; `record.plan != 'free'`), never `features.*`, which are the deployment's public auth flags, the same for every organisation. `data` is mounted only on an element whose `dataSource` is an `api` data source (`provider: 'api'`): there, and on every element nested inside it, `data` is the value the binding selects, and the element's `visibleWhen` is decided once the read answers. To gate a component on a system capability, write `current_user.hasCapability('<name>')` with the name the gated action's `requiredPermissions` declares — it answers from the viewer's `systemPermissions`, the list the action gate reads, never a proxy such as `current_user.can('<object>', 'edit')`; a host that binds no capability list makes it fault, and a faulting predicate renders the component. ADR-0066 D4: `visibleWhen` hides, `requiredPermissions` refuses. ⚠️ A `page:tabs` item `visibleWhen` is a different evaluator: it binds `data` to the record ROW. e.g. "page.selectedProjectId != ''" |
531+
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Contract-bound roots: `record`, `current_user` (ADR-0068 aliases `user` / `ctx.user` — one object, three spellings), and page state as `page.<var>`. The shipping renderer additionally mounts `features` and `os.user` — renderer behaviour, NOT contract-guaranteed (ADR-0068 rules the user object only). It mounts NO `data` root on an element that no `api` data source binds: there a `data.*` read faults and a faulting predicate withholds the component, so `data.total > 0` and `data.total == 0` both hide it; the page's row is `record` — the record a record page opens, or the row an app page's `record` binding reads (none without one; a block's own `dataSource` binds no `record` for its siblings). A count or a plan is a field on that row (a `summary` roll-up: `record.environment_count > 1`; `record.plan != 'free'`), never `features.*`, which are the deployment's public auth flags, the same for every organisation. `data` is mounted only on an element whose `dataSource` is an `api` data source (`provider: 'api'`): there, and on every element nested inside it, `data` is the value the binding selects, and the element's `visibleWhen` is decided once the read answers. To gate a component on a system capability, write `current_user.hasCapability('<name>')` with the name the gated action's `requiredPermissions` declares — it answers from the viewer's `systemPermissions`, the list the action gate reads, never a proxy such as `current_user.can('<object>', 'edit')`; a host that binds no capability list makes it fault, and a faulting predicate withholds the component. ADR-0066 D4: `visibleWhen` hides, `requiredPermissions` refuses. ⚠️ A `page:tabs` item `visibleWhen` is a different evaluator: it binds `data` to the record ROW. e.g. "page.selectedProjectId != ''" |
532532
| **visibility** | `never` | optional | [REMOVED] `page.components[].visibility` was removed in @objectstack/spec 18 (ADR-0089 D2) — it was the page component's deprecated spelling of the conditional-visibility predicate, which the parse folded into `visibleWhen` until this release. Use `visibleWhen`. Rename the key; the value (a CEL predicate) is unchanged. Where a component writes both, `visibleWhen` is the one that was in effect: delete `visibility`. |
533533
| **dataSource** | `{ object: string; view?: string; filter?: (object \| object)[]; sort?: object[]; … } \| { provider: 'api'; read: object; path?: string }` | optional | Per-element data binding: an object binding `{ object, view?, filter?, sort?, limit? }` that overrides the page object, or an API binding `{ provider: 'api', read: { url }, path? }` that reads one same-origin endpoint |
534534
| **responsive** | `never` | optional | [REMOVED] `page.components[].responsive` was removed in @objectstack/spec 17 (ADR-0049 D2) — no renderer ever read it, so per-breakpoint layout overrides (columns/order/visibility) parsed, validated, and then did nothing. Delete the key. For breakpoint behaviour that IS applied, use the sibling `responsiveStyles` (ADR-0065) — per-breakpoint CSS maps compiled to id-scoped CSS at render, e.g. `responsiveStyles: { xsmall: { display: 'none' } }` to hide a component on the narrowest screens. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |

‎content/docs/ui/pages.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ const homePage = {
6060
| `description` | `string` | optional | Page description |
6161
| `type` | `enum` | optional | Page type (see below; default `'record'`) |
6262
| `object` | `string` | optional | Associated object (for `record` type) |
63-
| `record` | `{ object, view?, filter?, sort? }` | optional | The row an `app` page is about: the FIRST row of this query, read under the caller's identity, which every component `visibleWhen` on the page reads as `record`. A count or a plan is a field on that row — a `summary` roll-up (`record.environment_count > 1`) or the object's own field (`record.plan != 'free'`). **Refused on any page that is not `type: 'app'`** (a record page's row is the record it opens). Planned in the renderer: until the console mounts it, `record` stays unbound on an `app` page |
63+
| `record` | `{ object, view?, filter?, sort? }` | optional | The row an `app` page is about. The console reads it once per page open: the FIRST row of this query under `sort`, under the caller's identity. Every component's `visibleWhen` sees that row as `record`; a record block that binds its own row still provides that row to its own subtree. A page drawn through `interfaceConfig.source` reads no binding. A count or a plan is a field on that row — a `summary` roll-up (`record.environment_count > 1`) or the object's own field (`record.plan != 'free'`). Three states: while the read is pending, the page body is not drawn; no row, or a read the server refuses as forbidden (403), binds `record` as null; any other failure draws no page body. **Refused on any page that is not `type: 'app'`** (a record page's row is the record it opens) |
6464
| `template` | `enum` | optional | Layout template: `'default'` (the default), `'header-sidebar-main'`, `'three-column'` or `'dashboard'` — see [Templates](#templates). Any other name is refused |
6565
| `kind` | `enum` | optional | Page override mode (default `'full'`). `full` \| `slotted` = structured authoring; `html` = author-written constrained JSX/HTML compiled (parsed, never executed) to the tree (ADR-0080; ADR-0081 named it `html`); `react` = real-React source executed at render by the runtime (ADR-0081) — it runs author JS, so it is gated by a host capability that defaults ON and is disabled server-side via `OS_PAGE_REACT=off`. See [Authoring modes](#authoring-modes) |
6666
| `regions` | `PageRegion[]` | optional | Layout regions with components (default `[]` — `list` pages render via `interfaceConfig`, and an empty `record`/`home`/`app` page falls back to the synthesized default layout) |

0 commit comments

Comments
 (0)