Skip to content

Commit 78c7900

Browse files
committed
docs(spec): a field group's relatedList describe and docblock say it names body tables only
Written on top of the #27352 wording: the sentence saying relatedList: false on the FK still hides the table is replaced by the body-table rule, the refusal at defineStack and the metadata write door, and the remedy. A describe pin in related-list-body-table.test.ts; object.mdx regenerated. Claude-Session: https://claude.ai/code/session_01WGufzgpxjnsDPHLokR644U Co-authored-by: Claude <noreply@anthropic.com>
1 parent e216f4e commit 78c7900

3 files changed

Lines changed: 32 additions & 5 deletions

File tree

‎content/docs/references/data/object.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -315,7 +315,7 @@ const result = ApiMethod.parse(data);
315315
| **label** | `string` | ✅ | Group display label |
316316
| **icon** | `string` | optional | Icon name (Lucide/Material) for the group header |
317317
| **description** | `string` | optional | Optional description shown under the group header |
318-
| **relatedList** | `string` | optional | Places a related list's body table at this position in the record's details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. relatedList: false on the relationship still hides the table. |
318+
| **relatedList** | `string` | optional | Places a related list's body table at this position in the record's details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. It names a body table only (a FK declaring relatedList: 'primary', or a master_detail FK that sets inlineEdit and declares no relatedList): a group naming a side card or a list hidden by relatedList: false draws nothing, so it is refused where the child's fields are known (os validate / os build and the metadata write door), naming the FK and the remedy (set relatedList: 'primary' on it, or remove the group's relatedList). |
319319
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Section visibility predicate (CEL) — the whole group (header included) is shown only when TRUE, else hidden (fail-closed). e.g. P`record.type == 'invoice'` |
320320
| **collapse** | `Enum<'none' \| 'expanded' \| 'collapsed'>` | optional (default: `"none"`) | [ADR-0085] Section collapse behaviour: 'none' (always open, no toggle), 'expanded' (collapsible, starts open), 'collapsed' (collapsible, starts closed). |
321321
| **defaultExpanded** | `boolean` | optional | [DEPRECATED → collapse] true → 'expanded', false → 'collapsed'. |
@@ -701,7 +701,7 @@ External datasource binding (ADR-0015)
701701
| **label** | `string` | ✅ | Group display label |
702702
| **icon** | `string` | optional | Icon name (Lucide/Material) for the group header |
703703
| **description** | `string` | optional | Optional description shown under the group header |
704-
| **relatedList** | `string` | optional | Places a related list's body table at this position in the record's details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. relatedList: false on the relationship still hides the table. |
704+
| **relatedList** | `string` | optional | Places a related list's body table at this position in the record's details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. It names a body table only (a FK declaring relatedList: 'primary', or a master_detail FK that sets inlineEdit and declares no relatedList): a group naming a side card or a list hidden by relatedList: false draws nothing, so it is refused where the child's fields are known (os validate / os build and the metadata write door), naming the FK and the remedy (set relatedList: 'primary' on it, or remove the group's relatedList). |
705705
| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Section visibility predicate (CEL) — the whole group (header included) is shown only when TRUE, else hidden (fail-closed). e.g. P`record.type == 'invoice'` |
706706
| **collapse** | `Enum<'none' \| 'expanded' \| 'collapsed'>` | optional (default: `"none"`) | [ADR-0085] Section collapse behaviour: 'none' (always open, no toggle), 'expanded' (collapsible, starts open), 'collapsed' (collapsible, starts closed). |
707707
| **defaultExpanded** | `boolean` | optional | [DEPRECATED → collapse] true → 'expanded', false → 'collapsed'. |

‎packages/spec/src/data/object.zod.ts‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1250,12 +1250,20 @@ export const ObjectFieldGroupSchema = lazySchema(() => strictObject({
12501250
* everywhere; a child that exists nowhere is refused at `defineStack` (save a
12511251
* platform-prefixed name, left to the runtime) and by a metadata write that
12521252
* names no package, and a write into a package stores it, placing nothing.
1253-
* Body tables no group places keep the record page's default position. `relatedList: false` on the FK
1254-
* still hides the table.
1253+
* It names a BODY TABLE only (`isBodyTableRelationship`, #27478): an inbound
1254+
* FK declaring `relatedList: 'primary'`, or a `master_detail` FK that sets
1255+
* `inlineEdit` and declares no `relatedList`. Body-ness is the FK's to
1256+
* decide; the group only positions it. A group naming a side card, or a list
1257+
* its FK hides with `relatedList: false`, draws nothing at the group, so it
1258+
* is refused wherever the child's fields are known: at `defineStack` and at
1259+
* the runtime metadata write door (`related-list-group-not-body`), naming
1260+
* each FK and the remedy (mark it `relatedList: 'primary'`, name only the
1261+
* body table as `object.field`, or remove the group's `relatedList`).
1262+
* Body tables no group places keep the record page's default position.
12551263
*/
12561264
relatedList: z.string().regex(RELATED_LIST_ENTRY_PATTERN, {
12571265
message: 'A field group\'s relatedList is a child object name (e.g. "task") or object.field (e.g. "event.related_to"), in snake_case',
1258-
}).optional().describe('Places a related list\'s body table at this position in the record\'s details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. relatedList: false on the relationship still hides the table.').meta({ title: 'Related List' }),
1266+
}).optional().describe('Places a related list\'s body table at this position in the record\'s details column instead of a section of fields: names one inbound relationship, as a relatedLists entry does (child object, or object.field when that child has more than one relationship to this object). A group with relatedList holds no fields: a field that names it as its group is refused. The name is judged as a relatedLists entry is: refused when its child is in the stack with no inbound lookup / master_detail field, or exists nowhere (by os validate / os build, which leave a sys_ / cloud_ / ai_ name to the runtime, and by a metadata write that names no package); a write into a package stores it, and the record page places nothing for it. It names a body table only (a FK declaring relatedList: \'primary\', or a master_detail FK that sets inlineEdit and declares no relatedList): a group naming a side card or a list hidden by relatedList: false draws nothing, so it is refused where the child\'s fields are known (os validate / os build and the metadata write door), naming the FK and the remedy (set relatedList: \'primary\' on it, or remove the group\'s relatedList).').meta({ title: 'Related List' }),
12591267

12601268
/**
12611269
* [ADR-0085 §5] Section visibility predicate — CEL, the ADR-0089 canonical

‎packages/spec/src/data/related-list-body-table.test.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
* a side card"); the page used to draw it as a body table.
1313
*/
1414
import { describe, it, expect } from 'vitest';
15+
import { z } from 'zod';
16+
import { ObjectFieldGroupSchema } from './object.zod';
1517
import {
1618
fieldGroupBodyTableRefusal,
1719
isBodyTableRelationship,
@@ -79,3 +81,20 @@ describe('fieldGroupBodyTableRefusal — the sentence both surfaces write', () =
7981
expect(msg).toContain("Set relatedList: 'primary' on those FKs, name only the body table as object.field ('event.related_to'), or remove");
8082
});
8183
});
84+
85+
describe('fieldGroups[i].relatedList describes the body-table rule it enforces', () => {
86+
const root = z.toJSONSchema(ObjectFieldGroupSchema as z.ZodType, { unrepresentable: 'any', io: 'input' }) as {
87+
properties?: Record<string, { description?: string }>;
88+
};
89+
const text = root.properties?.relatedList?.description ?? '';
90+
91+
it('says it names a body table only, and that any other list is refused with the remedy', () => {
92+
expect(text).toContain("It names a body table only (a FK declaring relatedList: 'primary', or a master_detail FK that sets inlineEdit and declares no relatedList)");
93+
expect(text).toContain('a group naming a side card or a list hidden by relatedList: false draws nothing, so it is refused');
94+
expect(text).toContain("set relatedList: 'primary' on it, or remove the group's relatedList");
95+
});
96+
97+
it('no longer says relatedList: false still hides a placed table', () => {
98+
expect(text).not.toContain('still hides the table');
99+
});
100+
});

0 commit comments

Comments
 (0)