Found while working #6170 (PR #6352); deliberately left out of that card's scope. Observational — filed for triage, not as a defect claim.
The fact
PR #6352 declared items on TimelineSchema for the first time, as any[]. That is faithful to what the renderer does (items.map((item: any) => …) at every site, and items as Array<any> at two), but it means the element is still undeclared.
The renderer reads two different element shapes, discriminated by variant:
| variant | element shape read |
|---|
vertical / horizontal | time, title, description, variant, icon, color, content, className, meta, group |
gantt | label, items: [{ title, startDate, endDate, variant }] |
content/docs/plugins/plugin-timeline.mdx documents both as named shapes ("Timeline Item (Vertical/Horizontal)", "Gantt Item"), so the vocabulary is already written down — just nowhere a compiler or validator can read it.
Two of those keys are not in the docs at all: meta (inline chips beside the title) and group (sticky bucket headers). Both are produced by ObjectTimeline and consumed by TimelineRenderer, so they are a real internal contract with no declaration on either side.
Why it was left out
Declaring the element precisely is a genuine narrowing of a published type, not an additive declaration: items accepts anything today. It needs its own measurement — which keys are authored in the wild, whether meta/group are authorable or renderer-internal, and whether the two shapes should be one union or a discriminated pair keyed off variant. #6170's ruling did not cover it and PR #6352 declined to guess.
Blocked-by: #6170 — the alignment has to land first, since this refines a key that card introduced.
Reproduce
sed -n '250,300p' packages/plugin-timeline/src/renderer.tsx # feed item reads
sed -n '447,470p' packages/plugin-timeline/src/renderer.tsx # gantt row reads
sed -n '80,110p' content/docs/plugins/plugin-timeline.mdx # the two documented shapes
Refs: #6170, PR #6352.
Found while working #6170 (PR #6352); deliberately left out of that card's scope. Observational — filed for triage, not as a defect claim.
The fact
PR #6352 declared
itemsonTimelineSchemafor the first time, asany[]. That is faithful to what the renderer does (items.map((item: any) => …)at every site, anditems as Array<any>at two), but it means the element is still undeclared.The renderer reads two different element shapes, discriminated by
variant:vertical/horizontaltime,title,description,variant,icon,color,content,className,meta,groupganttlabel,items: [{ title, startDate, endDate, variant }]content/docs/plugins/plugin-timeline.mdxdocuments both as named shapes ("Timeline Item (Vertical/Horizontal)", "Gantt Item"), so the vocabulary is already written down — just nowhere a compiler or validator can read it.Two of those keys are not in the docs at all:
meta(inline chips beside the title) andgroup(sticky bucket headers). Both are produced byObjectTimelineand consumed byTimelineRenderer, so they are a real internal contract with no declaration on either side.Why it was left out
Declaring the element precisely is a genuine narrowing of a published type, not an additive declaration:
itemsaccepts anything today. It needs its own measurement — which keys are authored in the wild, whethermeta/groupare authorable or renderer-internal, and whether the two shapes should be one union or a discriminated pair keyed offvariant. #6170's ruling did not cover it and PR #6352 declined to guess.Blocked-by: #6170— the alignment has to land first, since this refines a key that card introduced.Reproduce
Refs: #6170, PR #6352.