From daefd8b4548c0bb506fac2b45d2765fdc627220f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 24 Aug 2026 11:38:28 +0000 Subject: [PATCH] docs(formulas): pin the raw predicate example to the object-field layer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `### Predicate` fence opened with a bare `{ name, type, visibleWhen }` object literal. Nothing in that shape says which layer it is written against, and `visibleWhen` is one key spelled on layers that do not share a scope, so neither a reader nor `check:doc-formula-expressions` could tell whether the predicate was meant to bind `record`, a flow screen's flattened field names, or a page component's user roots. Wrap it in `ObjectSchema.create({ fields: { … } })`. The `fields:` MAP is the schema-backed statement of the object-field layer (`ObjectSchema.fields` is `z.record(name, FieldSchema)`, while every UI/flow layer spells `fields:` as an array), so the example now says structurally what it previously only implied by position on the page. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_015ahemw8RcTgqtxrj15PEZx --- content/docs/data-modeling/formulas.mdx | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/content/docs/data-modeling/formulas.mdx b/content/docs/data-modeling/formulas.mdx index 43c0cc7126..7811580455 100644 --- a/content/docs/data-modeling/formulas.mdx +++ b/content/docs/data-modeling/formulas.mdx @@ -272,12 +272,26 @@ Building the string by hand with `+` would also work, but CEL throws on ### Predicate (visibility, read-only, conditional required) +A conditional-rule predicate binds whatever its **layer** binds, and `visibleWhen` +is one key spelled on layers that do not share a scope — object field, per-option, +form-view field, page component, flow screen. So write the enclosing structure: +the `fields:` **map** below is what says *object field*, the layer on which a +predicate binds `record` (plus `previous`, and `parent` on a master-detail line +item) and nothing else. A bare `{ name, type, visibleWhen }` fragment names no +layer, so neither a reader nor `os build` can tell which scope it is written +against. + ```ts -{ - name: 'rating', - type: 'select', - visibleWhen: P`record.status == 'qualified'`, -} +ObjectSchema.create({ + name: 'opportunity', + fields: { + // Raw (non-factory) spelling — the map key is the field name. + rating: { + type: 'select', + visibleWhen: P`record.status == 'qualified'`, + }, + }, +}) Field.text({ visibleWhen: P`record.type == 'business'`,