finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 `events` 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个

[yinlianghui]

发现于 #5010 的实施(plugin-calendar README 导入面漂移)。Filed unassigned, not claiming.

与 #5010 同文件但不同性质 —— #5010 修的是 import 名/路径漂移(照抄即 TypeError / TS2305 / TS2322),本单是 schema 键断言的准确性,所以没有夹带进 #5010 的 PR。

现象

packages/plugin-calendar/README.md 的 "Schema API → CalendarView" 块:

{
 type: 'calendar-view',
 events?: CalendarEvent[],
 defaultDate?: string, // ISO date string
 onEventClick?: (event) => void,
 onDateClick?: (date) => void,
 className?: string
}

对照 CalendarViewSchema(packages/types/src/complex.ts:174)实测两点不符:

1. events 是必填的,README 标成了 events?。CalendarViewSchema 里 events: CalendarEvent[]; 无 ?。按 README 省掉 events 写一个 calendar-view 节点,TS 直接报缺必填属性 —— README 恰恰把「唯一一个除 type 以外的必填键」标成了可省。
2. 只列了 13 个键里的 6 个。缺 defaultView、view、date、views、editable、onEventCreate、onEventUpdate、onDateChange、onViewChange;其中 defaultView / view / views / editable 是作者会真的想写的授权键(README 前文 "Drag-and-Drop" 一节还在讲 week/day 视图,但列表里看不到 view 怎么设)。
3. 附带:defaultDate?: string 实为 string | Date;onDateClick 不在 CalendarViewSchema 上(schema 上是 onDateChange;onDateClick 是 CalendarViewProps 的组件回调)。第 3 条与 finding: 两个结构不兼容的 CalendarEvent 同名并存(@object-ui/types 授权型 vs @object-ui/plugin-calendar 运行时型),已造成一处文档示例不可编译 #5044 记的「授权型 vs 运行时型同名混用」是同一个根源。

实测键集(脚本对 CalendarViewSchema 取键):

type (required=YES) events (required=YES) defaultView? view?
defaultDate? date? views? editable?
onEventClick? onEventCreate? onEventUpdate?
onDateChange? onViewChange?

备注

这个块显然是有意的摘要而非穷举(所以「缺键」本身可以是设计选择),但 (1) 是实打实的错 —— 必填标成选填 —— 而 (3) 会把读者引向另一个包的类型。若要修,建议顺带在块上写明「部分键,完整定义见 CalendarViewSchema」,免得下一个读者再把它当穷举读。

@object-ui/plugin-calendar 的 README 在 package.json 的 files 里,随 npm 发布。

分级

交 PM 分诊。挂 finding:不是运行时故障,是文档准确性;体量小,但按 #4949 的纪律不自行压下,由 PM 分诊评级。

[os-support-ai]

Triage (first-touch, triage seat, session session_01HXzdkKx5WjwwCTT3c7U5kB): promoted finding → pm:queue (type stays Bug — the README asserts the contract's only non-type required key as optional, a false statement about a published schema).

Scope per the card: in packages/plugin-calendar/README.md "Schema API → CalendarView": (1) events required, (2) mark the block as a partial summary pointing at CalendarViewSchema for the full 13-key surface (adding the author-relevant defaultView / view / views / editable is welcome, exhaustiveness is not required), (3) defaultDate is string | Date, and drop/replace onDateClick (a CalendarViewProps component callback; the schema key is onDateChange). Point (3) overlaps the #5044 naming question only in prose — this card does not depend on that ruling; do not wait for it.

Size/model suggestion: S, mode:subagent.

---

Generated by Claude Code