From ff072b15efcf834719fc23319cc72fddc31983f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 03:49:30 +0000 Subject: [PATCH 1/2] docs(objectui): stop teaching phantom section-level performance keys in the Layout DSL The 'Performance Considerations' section documented section-level virtualScroll / itemHeight / lazy / source and a layout.renderStrategy block. None of these exist on any schema: ui/FormSection declares exactly ten authorable keys, and itemHeight / renderStrategy / lazy appear zero times across the whole generated authorable surface. FormSectionSchema is .strict(), so an author following the page got a parse rejection. Replaced with a Performance section that states the absence and points at the one real, consumed switch (ListViewSchema.virtualScroll), matching the convention widget-contract.mdx already uses for this defect class. Refs #8251 --- content/docs/protocol/objectui/layout-dsl.mdx | 60 +++++++------------ 1 file changed, 20 insertions(+), 40 deletions(-) diff --git a/content/docs/protocol/objectui/layout-dsl.mdx b/content/docs/protocol/objectui/layout-dsl.mdx index 486ae12c92..decc57ee30 100644 --- a/content/docs/protocol/objectui/layout-dsl.mdx +++ b/content/docs/protocol/objectui/layout-dsl.mdx @@ -940,46 +940,26 @@ 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. + +Virtualization for large datasets is configured on the **view**, not on a section +or a layout: set the boolean `virtualScroll` on a list-shaped view +(`ListViewSchema`). That is the only virtual-scrolling switch objectui reads — +see [Widget Contract → Performance](/docs/protocol/objectui/widget-contract#performance). + + + 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**. For the keys a section really accepts, see the + [View Reference](/docs/references/ui/view). + ## What's Next? From c55cd817159dea25c4ed9b705d2360e4c348c872 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 04:04:19 +0000 Subject: [PATCH 2/2] docs(objectui): align the Layout DSL performance note with the #7176 view-level retirement PR #8252 landed while this branch was open, retiring the pass-through-only list-view virtualScroll under ADR-0049. The replacement section pointed at that key as the real switch; it is no longer authorable (zero entries across the whole authorable surface). Re-pointed at the view's pagination block, matching the wording widget-contract.mdx now carries. Refs #8251 --- content/docs/protocol/objectui/layout-dsl.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/content/docs/protocol/objectui/layout-dsl.mdx b/content/docs/protocol/objectui/layout-dsl.mdx index decc57ee30..8858ebf1bf 100644 --- a/content/docs/protocol/objectui/layout-dsl.mdx +++ b/content/docs/protocol/objectui/layout-dsl.mdx @@ -948,16 +948,19 @@ The Layout DSL has **no** performance surface. A section declares no (`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. -Virtualization for large datasets is configured on the **view**, not on a section -or a layout: set the boolean `virtualScroll` on a list-shaped view -(`ListViewSchema`). That is the only virtual-scrolling switch objectui reads — -see [Widget Contract → Performance](/docs/protocol/objectui/widget-contract#performance). +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). 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**. For the keys a section really accepts, see the + implemented** — real virtualization is an implementation card first. For the + keys a section really accepts, see the [View Reference](/docs/references/ui/view).