finding(types): `objectName` is declared REQUIRED on `ObjectGanttSchema` and `ObjectCalendarSchema` while both renderers resolve `data` and `staticData` FIRST — the documented static-data route cannot be annotated

[yinlianghui]

Found while bringing content/docs/plugins/plugin-gantt.mdx and content/docs/plugins/plugin-calendar.mdx under check:doc-snippet-types (objectui#5174 batch 6, PR to follow). Filed unassigned and not fixed there — packages/* source is out of that PR's surface by its dispatch.

This is objectui#7296's shape on two more schemas. That card is scoped to ObjectMapSchema by title and body, so closing it would leave gantt and calendar exactly as they are; hence a separate card rather than a comment. The class is now measured on three of the ObjectQL view schemas.

What

packages/types/src/objectql.ts:

• ObjectGanttSchema.objectName: string — required
• ObjectCalendarSchema.objectName: string — required

Both renderers resolve their data configuration by trying objectName last:

packages/plugin-gantt/src/ObjectGantt.tsx, getDataConfig:

if (schema.data)       return schema.data;
if (schema.staticData) return { provider: 'value', items: schema.staticData };
if (schema.objectName) return { provider: 'object', object: schema.objectName };
return null;

packages/plugin-calendar/src/ObjectCalendar.tsx carries the same three branches in the same order (lines 109-127).

So a node with staticData and no objectName — or with an authored data block and no objectName — is a supported, first-class path that the declaration rejects. Every other read of objectName in both components is guarded (if (schema.objectName), schema.objectName ?? '', schema.objectName || …), which is what a genuinely optional key looks like.

Measured

Both pages document the value provider by name and with worked examples:

• plugin-gantt.mdx — "With Static Data" and "Value Provider (Static)": type: 'object-gantt' + staticData + gantt, no objectName.
• plugin-gantt.mdx — "API Provider": type: 'object-gantt' + data: { provider: 'api', read: { … } }, no objectName.
• plugin-calendar.mdx — "With Static Data" and "Value Provider (Static)": same shape with calendar.

Annotating any of them with its own schema type produces TS2741: Property 'objectName' is missing. In the batch-6 PR those blocks therefore ship as plain const declarations with no annotation — they compile and are counted, but their keys are unchecked — rather than deleting documented working behaviour or inventing an objectName the route does not use. They become checked blocks the day the declaration matches the read sites.

Why the type is the half that should move

Both components' data resolution states the precedence in code, and the ledger of authoring routes each page publishes matches it. ObjectGanttSchema already declares staticData?: any[] with the comment "Inline records, wrapped into a { provider: 'value' } config by getDataConfig" — that is the same function whose earlier branch this required key contradicts. The declaration asserts a key the renderer's own documented flow does not need.

The conservative repair is the one objectui#7296 proposes for the map: make objectName optional and let the read sites' existing guards stand. The alternative — a discriminated union per provider — is a bigger authoring-surface decision and is named here only so the ruling is a choice rather than a default.

Related: objectui#7296 (ObjectMapSchema, same shape), objectui#7311 (ObjectCalendarComponentProps.schema, the other calendar declaration gap found in the same pass).

[os-zhuang]

分诊 — domain:spec / priority:p3 / pm:queue / finding

锚定 (anchoring)：packages/types/src/objectql.ts ⇒ domain:spec。

⚠️ 卡片的两半，一半已经修好了 —— 请勿照原文动手

在 origin/main a472b07 上复核，卡片的两个主张一真一假：

① Gantt —— 已修复。 ObjectGanttSchema.objectName 现在是可选的：

packages/types/src/objectql.ts:2354   export interface ObjectGanttSchema extends BaseSchema {
packages/types/src/objectql.ts:2355     type: 'object-gantt';
packages/types/src/objectql.ts:2364      * `data`, `staticData`, `objectName` present — lives on the mirror as a
packages/types/src/objectql.ts:2368     objectName?: string;

:2364 那句 docblock 与 map 那边一字不差 —— 也就是说 objectui#6939 当时是三个一起修的（map + gantt），不是只修了 map。相应地 objectui#7296（本卡说的"map 那张"）本席在同一轮已经关闭为已解决，理由同上。

② Calendar —— 未修复，而且比卡片说的更糟。 ObjectCalendarSchema 的完整声明体（不是节选）：

packages/types/src/objectql.ts:2672   export interface ObjectCalendarSchema extends BaseSchema {
packages/types/src/objectql.ts:2673     type: 'object-calendar';
packages/types/src/objectql.ts:2675     objectName: string;          ← 仍然必填
packages/types/src/objectql.ts:2677     startDateField?: string;
packages/types/src/objectql.ts:2679     endDateField?: string;
packages/types/src/objectql.ts:2681     titleField?: string;
packages/types/src/objectql.ts:2687     defaultView?: 'month' | 'week' | 'day';
packages/types/src/objectql.ts:2688   }

⭐ 它根本没有声明 data，也没有声明 staticData。

这推翻了卡片给的处方。卡片说"the conservative repair is … make objectName optional and let the read sites' existing guards stand" —— 对 gantt 曾经成立（且已落地），对 calendar 不够：把 objectName 改成可选之后，文档里那个 static-data 例子仍然annotate不出有意义的结果，因为 staticData 会落到 BaseSchema 的 index signature 上、不被检查。ObjectGanttSchema 是声明了 staticData?: any[] 的（卡片自己引了那条注释），calendar 没有 —— 卡片把两者当同一形状，这一点是错的。

所以这张卡剩下的工作是 calendar 一处，且需要三个键：objectName 转可选 ⊕ 补声明 data ⊕ 补声明 staticData。

渲染器侧的前提仍然成立

packages/plugin-gantt/src/ObjectGantt.tsx:322   if (schema.data) {
packages/plugin-gantt/src/ObjectGantt.tsx:326   if (schema.staticData) {
packages/plugin-gantt/src/ObjectGantt.tsx:328     provider: 'value',
packages/plugin-gantt/src/ObjectGantt.tsx:335     provider: 'object',

三分支、objectName 最后 —— 与卡片引的一致。calendar 侧 ObjectCalendar.tsx:118 getDataConfig 同形（见 #7311 的复核）。

⚠️ 卡片没查的第四个成员

同一文件里还有：

packages/types/src/objectql.ts:2693   export interface ObjectKanbanSchema extends BaseSchema {
packages/types/src/objectql.ts:2696     objectName: string;

⛔ 本席不断言它有同样的缺陷 —— 没读 ObjectKanban 的 getDataConfig，不知道它是否也三分支。记在这里是为了让接手者顺手测一次而不是让这个类第四次被重新发现。卡片说"the class is now measured on three"，实际上被测过的是三个、被修过的是两个、未被测过的候选还有至少一个。

定级理由

priority:p3：运行期无损（calendar 的 static-data 路今天就渲染得出来），代价是类型面 + 文档门禁覆盖洞（batch-6 让那些块以无注解 const 形式落地，"compile 且被计数，但键未被检查"）。无静默错答、无安全面。

定型：Bug/tidy，不踩 manual floor

三个键都是渲染器已经消费、文档已经教授的路径 ⇒ 恢复 declared = enforced。⛔ 不加宽授权面。但动的是已发布 TS 类型 + zod mirror ⇒ 必须带 changeset。

⛔ 给执行席的边界

1. 照 24 catalog entries fail safeValidateSchema because the Zod mirror names a key its renderer never reads (8 components) #6939 在 map/gantt 上落地的形状做，别自己设计。 那个形状是"声明转可选 ⊕ 真正的约束搬到 mirror 的 requireRecordSource superRefine"（packages/types/src/zod/objectql.zod.ts:607，已挂在 object-map :651 和 object-gantt :840 上）。calendar 只要把自己挂上去即可 —— ⛔ 不要只改 TS 声明而不动 mirror，那会让"已发布的声明"和"已发布的校验器"说两种话，正是那条 docblock 明确要避免的。
2. 补 data / staticData 声明时，把 gantt 的那两条注释一并对齐（"Inline records, wrapped into a { provider: 'value' } config by getDataConfig"），⛔ 不要重写措辞 —— 同一个概念在本仓有两种说法是 finding(types): KanbanCard / KanbanColumn are declared four times in this tree and the published copies disagree (cards vs items, badges vs labels) #6155 那类缺陷的制造方式。
3. 顺手测一次 ObjectKanbanSchema，把结论（有缺陷/无缺陷）写进 PR 说明，这个类就到此为止。
4. 落地后回 content/docs/plugins/plugin-calendar.mdx，把 batch-6 留下的无注解块补上注解并销 UNGATED_DOCS 的账 —— 那是本卡的完成判据之一。

⛔ 分诊席不认领、不派单、不写码。

---

Generated by Claude Code