finding(types,plugin-kanban): `ObjectKanbanSchema` requires `groupField` (zero read sites) and declares neither `groupBy` nor `limit` — no working `object-kanban` node is assignable to any declared type

[yinlianghui]

Found while bringing content/docs/plugins/plugin-kanban.mdx under check:doc-snippets (objectui#5174 batch 7, PR to follow). Filed unassigned and NOT fixed there — packages/* source is outside that PR's surface. Measured on origin/main d717e8bc3 against the built dist.

What

An object-kanban node cannot be annotated with any type this repo ships. There are two declarations in play and each rejects the shape the renderer actually consumes.

1. ObjectKanbanSchema names a lane field the renderer never reads

packages/types/src/objectql.ts declares:

export interface ObjectKanbanSchema extends BaseSchema {
  type: 'object-kanban';
  objectName: string;
  groupField: string;   // REQUIRED
  titleField?: string;
  cardFields?: string[];
  // … quickAdd, coverImageField, allowCollapse, conditionalFormatting
}

But packages/plugin-kanban/src/ObjectKanban.tsx — the component the object-kanban registration renders — reads schema.groupBy, at nine sites (lines 630, 631, 642, 654, 655, 660, 669, 670, 776, 894 …), and reads schema.limit for the row cap (line 293: $top: schema.limit ?? DEFAULT_KANBAN_LIMIT, and again in the effect deps at 320).

groupField has zero read sites anywhere in packages/plugin-kanban:

$ git grep -c "groupField" -- 'packages/plugin-kanban/**'
(no output — zero)

Neither groupBy nor limit is declared on ObjectKanbanSchema. They type-check today only because BaseSchema carries [key: string]: any, so both land on the index signature and are structurally invisible — the objectui#5155 / #6269 blind spot.

The package's own test suite writes the documented shape, not the declared one:

// packages/plugin-kanban/src/ObjectKanban.elementDataSource.test.tsx:192
{ type: 'object-kanban', objectName: 'account', groupBy: 'status', columns: LANES, limit: 20 }

2. ObjectKanbanComponentProps.schema is KanbanSchema, whose type is 'kanban'

// packages/plugin-kanban/src/ObjectKanban.tsx:141
export interface ObjectKanbanComponentProps {
  schema: KanbanSchema;
}

KanbanSchema.type is the literal 'kanban'. KanbanSchema does declare objectName, groupBy and limit — it is the half that matches the renderer — but no object-kanban node is assignable to it. ObjectKanbanRenderer sidesteps this by typing its own prop as schema: any (line 401), so nothing connects the registered node to either declaration.

Measured

Both annotations planted on the docs page's row-cap example, gate run, restored from HEAD under a trap (git diff HEAD empty after each):

annotated ObjectKanbanSchema
  TS2741: Property 'groupField' is missing in type
          '{ type: "object-kanban"; objectName: string; groupBy: string; limit: number; }'
          but required in type 'ObjectKanbanSchema'.

annotated KanbanSchema (what the component's prop actually declares)
  TS2322: Type '"object-kanban"' is not assignable to type '"kanban"'.

Note what the first diagnostic does not say: groupBy and limit produced no error at all. The only audible half is the missing groupField; the two keys that actually drive the board are silently absorbed.

Why this is filed rather than fixed

The renderer is the working half and the declaration is the stale half — the same shape as objectui#5903 (ObjectGantt read 11 keys ObjectGanttSchema did not declare) and objectui#7311 (ObjectCalendarComponentProps.schema cannot accept an object-calendar node). Which way to reconcile is a types decision with consumers beyond this docs page:

1. ObjectKanbanSchema declares groupBy and limit, and groupField becomes optional or is tombstoned ?: never the way TimelineSchema.timeScale was (objectui#6355). Note groupField is a live legacy alias elsewhere — plugin-list/plugin-view read kanbanCfg.groupByField || kanbanCfg.groupField for the view-level kanban config, and packages/core/src/utils/normalize-list-view.ts maps kanban.groupField to the spec's groupByField. So it is not dead in general; it is dead on this node.
2. ObjectKanbanComponentProps.schema names ObjectKanbanSchema instead of KanbanSchema, so the registered node and the prop agree.

Both need someone who owns the kanban authoring surface. Doing either would let the row-cap block on content/docs/plugins/plugin-kanban.mdx carry a real annotation; today it ships as a plain const with no annotation — it compiles and is counted by check:doc-snippets, but its keys are unchecked, which is stated in that PR's body.

Reachability

Nothing a user hits at runtime: the documented groupBy / limit shape is what the renderer reads and what its tests assert, so boards work. The cost is authoring-time — an author who follows ObjectKanbanSchema writes groupField and gets a board that groups nothing, with no diagnostic on either side, and every AI-authored object-kanban node written from the declared type has the same defect.

Related: objectui#7311, objectui#7313, objectui#5903, objectui#6973.

[os-zhuang]

分诊 — domain:spec / priority:p2 / pm:queue / finding / tooling

锚定 (anchoring)：这张卡里有两个不同的缺陷，落点不同：

	缺陷	落点	lane
①	ObjectKanbanSchema 要求死键 groupField、不声明 groupBy/limit	packages/types/src/objectql.ts	domain:spec
②	ObjectKanbanComponentProps.schema 指向 KanbanSchema	packages/plugin-kanban/src/ObjectKanban.tsx	domain:ui（与 #7311 同型同修法）

整卡锚 domain:spec，因为 ① 挡着 ② —— 在 ObjectKanbanSchema 声明 groupBy/limit 之前把 prop 指过去，十三处读取当场全断。⛔ 顺序是 ① → ②，不是并行。②做完可把 lane 改成 domain:ui，或者拆出去与 #7311 并轨（两者是同一家族的第四、第五个成员）。

在 origin/main a472b07 上复核 —— 核心读数全部成立

⚠️ 卡片测于 d717e8bc3，行号已漂移：

packages/plugin-kanban/src/ObjectKanban.tsx:142   export interface ObjectKanbanComponentProps {     (卡片写 :141)
packages/plugin-kanban/src/ObjectKanban.tsx:143     schema: KanbanSchema;
packages/plugin-kanban/src/ObjectKanban.tsx:264       $top: schema.limit ?? DEFAULT_KANBAN_LIMIT,     (卡片写 :293)
packages/plugin-kanban/src/ObjectKanban.tsx:291   }, [schema.objectName, …, schema.limit, …]);        (卡片写 :320)

卡片最要害的那个负结果，我用正控制重测了：

$ git grep -c "groupField" origin/main -- 'packages/plugin-kanban/*'
(0 命中)

正控制，同一次读：
$ git grep -c "schema.groupBy" origin/main -- packages/plugin-kanban/src/ObjectKanban.tsx
13

groupField 在整个 plugin-kanban 包里零读取，同时 schema.groupBy 在渲染器一个文件里就有 13 行。这是实测的缺席，不是搜错目录。

⭐ 卡片"groupField 在别处仍是活别名"的警告 —— 实测为真，且比它写的更广

这条最容易被接手者误伤，所以逐条列出来：

packages/core/src/utils/normalize-list-view.ts:284    *    ({@link PER_VIEW_CONFIG_ALIASES}): `kanban.groupField` → `groupByField`,
packages/plugin-list/src/ListView.tsx:2091            if (schema.kanban?.groupByField || schema.kanban?.groupField || schema.options?.kanban?.groupField) {
packages/plugin-list/src/ListView.tsx:2411              const laneField = groupByField || groupField || detectStatusField(objectDef) || undefined;
packages/plugin-view/src/ObjectView.tsx:1234                kanbanCfg.groupField ||

⚠️ ListView.tsx:2091 读了三个拼写（kanban.groupByField / kanban.groupField / options.kanban.groupField），比卡片说的两处还多一层。所以卡片那句判断是精确的、也是硬约束：groupField 不是普遍的死键，它只在 object-kanban 这个节点上是死的。 ⛔ 谁都不许把它当全局遗留键一并清掉。

定级理由

priority:p2（比同族的 #7311 / #7313 高一级），依据是卡片的 Reachability 段：

an author who follows ObjectKanbanSchema writes groupField and gets a board that groups nothing, with no diagnostic on either side, and every AI-authored object-kanban node written from the declared type has the same defect.

这不是"类型骗人但代码能跑"（那是 #7311/#7313 的形状，p3），而是照着声明写就一定错，且两侧都不报：

• 写 groupField → 渲染器零读取 → 看板不分组；
• 写正确的 groupBy/limit → 因为 BaseSchema 的 [key: string]: any（finding(types): BaseSchema's [key: string]: any leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key #5155 / finding(types): ObjectViewSchema's table and form slots declare ZERO properties — the same Omit-under-index-signature collapse as #6151, in property position #6269 的盲区）静默落到 index signature，一个诊断都没有。

卡片的实测把这条钉死了 —— annotate 之后唯一发声的是缺失的 groupField，真正驱动看板的两个键连一句话都没有。对一个以"让 AI 写的元数据难以出错"为方向的仓库，这是最坏的形状。

不上 p1：现有的、按文档写的看板正常工作（渲染器与其测试都用 groupBy），没有回归。

定型：Bug，不踩 manual floor

groupBy / limit 是渲染器已消费、文档已教授、包内测试已断言的键（卡片引的 ObjectKanban.elementDataSource.test.tsx:192 就是证据）；补声明 ⇒ 恢复 declared = enforced。groupField 转可选或 tombstone ⇒ 收窄。两者都不加宽授权面。带 changeset。

⛔ 给执行席的边界

1. groupField 处置：优先 tombstone，不是简单转可选。 卡片指出的样板是 TimelineSchema.timeScale 的 ?: never（Retire the timeScale alias on the timeline node, now that scale is canonical on all three surfaces #6355）。转成 groupField?: string 会让"照声明写 groupField"继续编译通过、继续静默不分组 —— 缺陷的最坏部分原封不动。?: never 才会让那些节点当场报错。⛔ 别图省事。
2. 只动 ObjectKanbanSchema，别碰 view-level 的 kanban 配置。 见上面四处活别名。
3. ② 做的时候照 ObjectGantt reads 11 top-level schema keys that ObjectGanttSchema does not declare — all via as any, so nothing connects read to declaration #5903 / ObjectMapSchema(types)声明的键几乎与 ObjectMap 实际读的键无交集:map 块整体未建模,组件 props 类型写的是 ObjectGridSchema,每处 map 读取都走 as any #5018 的落地形状（finding(plugin-calendar): ObjectCalendarComponentProps.schema is typed ObjectGridSchema | CalendarSchema, so no object-calendar node is assignable — the documented direct-React usage cannot compile #7311 的路由评注里列了那两个样板），并把随之暴露的 as any 一并清掉。
4. 落地后回 content/docs/plugins/plugin-kanban.mdx 给 row-cap 那个块补真注解 —— batch-7 PR 说明里写着它今天是"编译且被计数、但键未被检查"的裸 const，那是本卡的完成信号。
5. ⛔ 不要顺手去修 BaseSchema 的 [key: string]: any。那是 finding(types): BaseSchema's [key: string]: any leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key #5155 的范围，且是本仓最大的单点决策之一，夹带进来会让这张 p2 卡永远合不了。

⛔ 分诊席不认领、不派单、不写码、不裁定 ①/② 的具体拼写。

---

Generated by Claude Code