Skip to content

docs(objectui): stop teaching phantom section-level performance keys in the Layout DSL#8301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 3 commits into from
Aug 13, 2026
Merged

docs(objectui): stop teaching phantom section-level performance keys in the Layout DSL #8301

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff072b1
docs(objectui): stop teaching phantom section-level performance keys …
claude Aug 13, 2026
cd72ac4
Merge origin/main into claude/issue-8251-layout-dsl-phantom-keys
claude Aug 13, 2026
c55cd81
docs(objectui): align the Layout DSL performance note with the #7176 …
claude Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 23 additions & 40 deletions content/docs/protocol/objectui/layout-dsl.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -940,46 +940,29 @@ steps:
showAllFields: true
```

## Performance Considerations

### Lazy Loading

Load sections/tabs only when visible:

```yaml
sections:
- label: Details
lazy: false # Load immediately

- label: History (10,000 records)
lazy: true # Load when section expanded
source: /api/customers/123/history
```

### Virtual Scrolling

For long lists of fields:

```yaml
section:
label: Product Catalog (1,000 items)
virtualScroll: true
itemHeight: 60 # px
fields: [...] # Large array
```

### Progressive Rendering

Render above-the-fold content first:

```yaml
layout:
renderStrategy: progressive
priority:
- sections[0] # Render first section immediately
- sections[1] # Render second section after 100ms
- sections[2] # Render third section after 200ms
```
## Performance

The Layout DSL has **no** performance surface. A section declares no
`virtualScroll`, `itemHeight`, `lazy` or `source` key, and there is no
`layout.renderStrategy`. `FormSectionSchema`
(`packages/spec/src/ui/view.zod.ts`) is `.strict()`, so authoring any of them is
a **parse failure** — a loud rejection, not a silent no-op.

Nor is there an authorable virtual-scrolling switch anywhere else: since 17.0.0
(#7176) the view-level boolean `virtualScroll` is retired too, under ADR-0049
enforce-or-remove — every measured reader only copied the key forward and the
grid renderer never applied it. Large datasets page via the view's `pagination`
block. See
[Widget Contract → Performance](/docs/protocol/objectui/widget-contract#performance).

<Callout type="info">
Earlier revisions of this page documented section-level `virtualScroll` /
`itemHeight` / `lazy` / `source` and a `layout.renderStrategy: progressive`
block. None of them existed on any schema, so they are **removed rather than
implemented** — real virtualization is an implementation card first. For the
keys a section really accepts, see the
[View Reference](/docs/references/ui/view).
</Callout>

## What's Next?

Expand Down
Loading