examples/schema-catalog: 13 个 grid 示例用了未声明的 `cols` 键,列数被静默丢弃 —— 要 3/4 列的示例在 docs 站实际渲染成 2 列

[yinlianghui]

发现于 #3965 的实施(PR #3998),不在该 PR 处理 —— 那一单只碰含 div 的文件与 div.tsx,这一条是另一个键、另一批文件。

现象

GridSchema 声明的键是 columns(packages/types/src/layout.ts:209),grid 渲染器也只读 schema.columns(packages/components/src/renderers/layout/grid.tsx:57-73),注册的 inputs 里同样只有 columns / smColumns / mdColumns / lgColumns / xlColumns / gap / className。

catalog 里有 13 个文件在 grid 节点上写的是 "cols" —— 一个引擎完全不认识的键。全仓 grep 过,core / react / types 里没有任何把 cols 归一到 columns 的处理。

实测(在 packages/components 里跑真渲染,对比两种写法):

cols:4     ->  grid grid-cols-2 gap-4
columns:4  ->  grid grid-cols-1 sm:grid-cols-2 md:grid-cols-4 gap-4

cols 被整个丢掉,落到 grid.tsx:54 的 let baseCols = 2 默认值上;因为 typeof schema.columns === 'number' 不成立,连 mobile-first 的响应式降级也不会触发,于是在所有断点上都是死板的 2 列。

也就是说:要 3 列或 4 列的示例,在 docs 站上渲染出来是 2 列,而且这不是 dev-only —— production 构建里一样错。

命中清单(13 个,全部在 grid 节点上)

要 4 列(实际 2 列):

• report/report-header-with-kpis.json:56
• theme/semantic-color-palette.json:3
• components-layout-page/full-dashboard.json:8

要 3 列(实际 2 列):

• components-data-display-statistic/metrics-grid.json:3
• components-layout-page/page-with-header.json:8
• forms/payment-form.json:67

要 2 列(碰巧和默认值一致,肉眼看不出来,但键依然是错的):

• components-data-display-statistic/sales-dashboard.json:12
• auth/signup.json:22
• components-complex-resizable/complex-layout.json:29
• components-basic-div/grid-layout.json:3
• theme/theme-aware-ui-elements.json:64
• plugin-view/form-view-mode.json:18
• forms/contact-form.json:29

为什么这条比「渲染不对」更值得修

• components-basic-div/grid-layout.json 是 content/docs/components/basic/div.mdx:35 的迁移范本 —— 「div 布局请改用 grid」这一条的示范代码本身写错了键。照着它抄的作者(和 AI)会继续写 cols,拿到静默的默认值。
• 「碰巧和默认值一致」的那 7 个是最坏的一类:渲染看起来对,所以没人会去查,错的键就一直传播。这正是 AGENTS.md 第二轴说的「AI 生成的 metadata 错误藏在宽容里」—— 只不过这里连宽容都没有,是纯静默丢弃。

修法(契约优先,别加别名)

改生产者:13 个 JSON 里 cols → columns。

⛔ 不要在 grid.tsx 里加 schema.columns ?? schema.cols 之类的兼容读取 —— AGENTS.md #0.1:宽容的 consumer 会把错写法固化成第二套事实契约。cols 从来没有被 spec / 类型 / 注册表声明过,它就是错的。

注意:改完之后要求 3/4 列的那 6 个示例渲染会变(从死板 2 列变成正确的响应式降级 grid-cols-1 sm:grid-cols-2 md:grid-cols-N),这是修好,不是回归 —— 抽样断言要按新的正确值钉。

顺带:sdui-parser 的 validate.ts 会对 html tier 里的 cols 报 unknown-prop,但 JSON 作者面没有这道门禁 —— 「catalog JSON 是否也该过一遍 manifest 的 prop 校验」是另一个更大的话题,不在本条里。

参考位置

• packages/types/src/layout.ts:202-219(GridSchema,声明 columns)
• packages/components/src/renderers/layout/grid.tsx:50-103(只读 columns,baseCols 默认 2)
• content/docs/components/basic/div.mdx:35(引用了写错键的迁移范本)

关联:#3965 / PR #3998(发现于此)

[yinlianghui]

PM 分诊(session_01GTRjn8xBqp75dk7kFupVRt):晋级 pm:queue,高优先 —— 13 个 catalog grid 示例用未声明的 cols 键,6 例在生产文档站可见地渲染错列数(runtime probe 实证),且 div→grid 迁移范本自身教错键、另 7 例侥幸匹配默认值是更危险的静默类。修法在生产者(13 JSON cols→columns),⛔ 正文已明令禁止渲染器加 ?? schema.cols 别名(AGENTS.md #0.1)。与 #3965 词表决策无关可立即派;与在飞 #3968(schema-catalog 的 test/tsconfig 面)文件不相交,与 #3965 决策后的 sweep 不冲突(先修键再换类型,顺序无关)。

(附:分诊时曾把本单标签误写到 objectstack#4001,已回滚并在该单留更正评论。)

---

Generated by Claude Code

[yinlianghui]

【PM 认领】objectui 分片(session_01GTRjn8xBqp75dk7kFupVRt),批次 7。派 os-dev 实施,分支 claude/issue-4001-grid-cols-columns(objectui 仓)。

按正文既定修法:改生产者(13 个 JSON cols → columns),⛔ 不加渲染器别名兼容;3/4 列示例渲染变化按新正确值钉。与 #4003(106 div 节点转换)同 catalog 面,#4003 等本单落 main 后再派。

---

Generated by Claude Code