From f912ff829d1dece2b574603adb448e5291cf97da Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 4 Aug 2026 00:08:44 +0000 Subject: [PATCH] =?UTF-8?q?docs(protocol/objectui):=20widget-contract=20?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E6=95=99=E5=B7=B2=E5=88=A0=E9=99=A4=E7=9A=84?= =?UTF-8?q?=20PerformanceConfig=20(#4996)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 「Performance」小节把 #3896 删掉的 `PerformanceConfigSchema` 描述成「共享的、可用的」, 还给出它当年所在的确切路径;`WidgetManifest` 接口块也列着 `performance?: PerformanceConfig;`。 该页不是生成物,没有闸门会自动纠正它。 议题悬着的前提问题(那是 objectui 自己的字段还是被退役的 spec 键?)用代码即可判定: `WidgetManifestSchema` 就在本仓 `packages/spec/src/ui/widget.zod.ts:273`,其 `performance` 已是 `retiredKey(...)`(`z.never()`)—— 不只是没了,而是 parse 时会被拒。生成的 `references/ui/widget.mdx` 早已标注 `[REMOVED]`,只有这份手写页在反着说。 取改写而非整段删:虚拟滚动没退役,只是换了载体 —— 活的开关是 list 形态视图上的顶层 `virtualScroll`(`ListViewSchema`,view.zod.ts:909)。本节改成说真话,并用 warn callout 点明该键 17.0.0 起被拒、请删掉。顺带修掉同一次删除留下的第二个活指针:layout-dsl.mdx 把 responsive 参考页描述为含 performance 配置,而那页生成出来已零 performance 内容。 其余 `PerformanceConfig` 出现全部是历史记述(墓碑、CHANGELOG、changeset、release notes、 liveness 台账、ADR-0021、审计日志),按 #4832 的区分标准保留。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ --- .changeset/widget-contract-performanceconfig.md | 14 ++++++++++++++ content/docs/protocol/objectui/layout-dsl.mdx | 2 +- content/docs/protocol/objectui/widget-contract.mdx | 10 ++++++++-- 3 files changed, 23 insertions(+), 3 deletions(-) create mode 100644 .changeset/widget-contract-performanceconfig.md diff --git a/.changeset/widget-contract-performanceconfig.md b/.changeset/widget-contract-performanceconfig.md new file mode 100644 index 0000000000..7363eab1ef --- /dev/null +++ b/.changeset/widget-contract-performanceconfig.md @@ -0,0 +1,14 @@ +--- +--- + +docs(protocol/objectui): widget-contract 不再教已删除的 `PerformanceConfig` (#4996) + +`content/docs/protocol/objectui/widget-contract.mdx` 的「Performance」小节逐字写着「Performance tuning is supplied through the shared `PerformanceConfig` schema (`packages/spec/src/ui/responsive.zod.ts`)」,而 `PerformanceConfigSchema` / `PerformanceConfig` 早在 #3896 的 audit close-out 就被删掉了 —— 该文件里现在是一条墓碑注释,`responsive.test.ts` 里对应的用例也随之移除。同一页的 `WidgetManifest` 接口块还列着 `performance?: PerformanceConfig;`。这一页不是生成物(`packages/spec/scripts/` 下没有任何生成器写它),所以没有闸门会自动纠正,它才活到今天。 + +议题里悬着的那个前提问题 —— 「manifest 的 `performance` 是 objectui 自己的字段,还是被退役的那三个 spec 键?」 —— 用代码即可判定,不需要 objectui 分片确认:`WidgetManifestSchema` 就住在本仓 `packages/spec/src/ui/widget.zod.ts:273`,它的 `performance` 已经是 `retiredKey(...)`,也就是 `z.never()`。所以这个键不只是「没了」,而是**会在 parse 时被拒**:照文档写 `performance:` 的 manifest 今天直接校验失败。生成的 `content/docs/references/ui/widget.mdx` 早已如实标注 `[REMOVED]`,只有这份手写页还在反着说 —— 生成面与手写面对同一个键给出相反指令,正是 AI 作者最容易踩的形态。 + +处置取「改写」而非「整段删」:虚拟滚动这个真实用例并没有退役,只是换了载体 —— 活的开关是 list 形态视图上的顶层布尔 `virtualScroll`(`ListViewSchema`,`packages/spec/src/ui/view.zod.ts:909`)。整段删掉会让记得旧键的作者失去落点,于是本节改成说真话:manifest 上没有 performance 块,虚拟化配在**视图**上,并用一条 `warn` callout 点明该键在 17.0.0 被移除且现在会被拒、请删掉。接口块里的 `performance?: PerformanceConfig;` 一并删除。 + +顺带修掉同一次删除留下的第二个活指针:`layout-dsl.mdx` 的 Related Resources 把 `/docs/references/ui/responsive` 描述成「Responsive and performance configuration」,而那页生成出来已经零 performance 内容,改为「Breakpoint layout and scoped responsive styles」。 + +全仓复查后 `PerformanceConfig` 的其余出现全部是历史记述(墓碑注释、CHANGELOG、既往 changeset、release notes、liveness 台账、ADR-0021 当时的决策记录、审计日志),按 #4832 的活指针/历史记述区分标准一律保留。纯文档,releases nothing。 diff --git a/content/docs/protocol/objectui/layout-dsl.mdx b/content/docs/protocol/objectui/layout-dsl.mdx index e8f5e89ffe..486ae12c92 100644 --- a/content/docs/protocol/objectui/layout-dsl.mdx +++ b/content/docs/protocol/objectui/layout-dsl.mdx @@ -1002,4 +1002,4 @@ layout: - [Page Reference](/docs/references/ui/page) - Page, region, and component schemas - [View Reference](/docs/references/ui/view) - Form, list, kanban, and calendar views -- [Responsive Reference](/docs/references/ui/responsive) - Responsive and performance configuration +- [Responsive Reference](/docs/references/ui/responsive) - Breakpoint layout and scoped responsive styles diff --git a/content/docs/protocol/objectui/widget-contract.mdx b/content/docs/protocol/objectui/widget-contract.mdx index 73d03c1076..cb6a7c96c3 100644 --- a/content/docs/protocol/objectui/widget-contract.mdx +++ b/content/docs/protocol/objectui/widget-contract.mdx @@ -156,7 +156,6 @@ interface WidgetManifest { dependencies?: { name: string; version?: string; url?: string }[]; aria?: AriaProps; // ARIA accessibility attributes - performance?: PerformanceConfig; } ``` @@ -306,7 +305,14 @@ aria: ## Performance -Performance tuning is supplied through the shared `PerformanceConfig` schema (`packages/spec/src/ui/responsive.zod.ts`) on the manifest's `performance` field. Use it for options such as virtualization and lazy rendering for widgets that handle large datasets. +The widget manifest carries **no** performance block. Virtualization for large datasets is configured on the **view**, not on the widget: set the boolean `virtualScroll` on a list-shaped view (`ListViewSchema` in `packages/spec/src/ui/view.zod.ts`). That is the only virtual-scrolling switch objectui reads. + + + `widget.performance` was removed in `@objectstack/spec` 17.0.0 (#3896 audit + close-out) — it was authorable but no renderer or runtime ever read it. The key + is now refused at parse time, so a manifest that still carries it fails + validation: delete it and use the view's `virtualScroll` instead. + ## Theme