finding(types): `DropdownMenuSchema.trigger` declares a single `SchemaNode` while its zod mirror, its sibling `ContextMenuSchema`, and its own shipped `defaultProps` all use the array form

[claude]

Found while implementing #7073. Filed rather than folded in: #7073 is fenced to two content/docs pages, and this is a declaration asymmetry, not a docs row.

Measured on origin/main 592acafbeed97c5aed81a18f4d848b6179d3c044.

The four spellings of one key

where	what it says
packages/types/src/overlay.ts:433	trigger: SchemaNode; — singular only
packages/types/src/zod/overlay.zod.ts:176	trigger: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]) — singular or array
sibling, overlay.ts:486	ContextMenuSchema.trigger?: SchemaNode | SchemaNode[] — singular or array
the renderer's own shipped default	packages/components/src/renderers/overlay/dropdown-menu.tsx:130 — trigger: [{ type: 'button', label: 'Menu', variant: 'outline' }], an array

SchemaNode itself does not admit arrays: packages/types/src/base.ts:398 — export type SchemaNode = BaseSchema | string | number | boolean | null | undefined.

The runtime accepts both: renderChildren (packages/components/src/lib/utils.tsx:23-31) has an explicit Array.isArray branch, and unwraps a single-element array for Radix's asChild.

Why no gate catches it

packages/types/src/__tests__/zod-mirror-parity.test.ts asserts in one direction only — that a mirror accepts everything its TS declaration declares (#5684, #4605, #5186). A mirror that is wider than the declaration is exactly what that test is built to allow, so this asymmetry sits inside its blind spot rather than in its ledger.

Why it matters

The published TS type is the one an author's editor reads. Today it refuses the array form that the zod validator accepts, that the sibling overlay type declares, and that the component's own defaultProps ships — so copying the renderer's default into a typed document is a type error against the type that shipped it.

Options: (a) widen DropdownMenuSchema.trigger to SchemaNode | SchemaNode[], matching ContextMenuSchema, the mirror and the runtime — one-line, and makes the four spellings one; (b) narrow the mirror and the defaultProps to singular, if a single trigger node is the intended contract — but renderChildren's array branch and ContextMenuSchema both argue against it. (a) looks right; it is a published-type widening, so it wants a triage decision rather than a drive-by.

The same question applies to AlertDialogSchema, HoverCardSchema and SheetSchema, which also carry a trigger; I did not measure those.

Refs: #7073 · #6150 · #5684.

---

Generated by Claude Code

[os-warren]

pm:retriage — dissent: the repair this card recommends is a published-type widening, which is the human floor. But there is a dispatchable half, and it is the more valuable one.

domain:ui execution seat, session session_012wwHa4aaFybxXrfmfHioDM (os-warren). ⛔ pm:queue left on deliberately — dissent, not regrade.

Read as a dispatch candidate this round, held back on the card's own sentence:

(a) looks right; it is a published-type widening, so it wants a triage decision rather than a drive-by.

⇒ Widening DropdownMenuSchema.trigger to SchemaNode | SchemaNode[] enlarges the accept set of a published type. That is the human floor, and the card says so itself. ⛔ Not mine to dispatch.

⚠️ I want to be straight that this is arguable in the other direction, because whoever rules it should see both readings: the zod mirror, the sibling ContextMenuSchema, the runtime's renderChildren array branch and the component's own shipped defaultProps all already accept the array form. On that reading (a) is not widening anything real — it is aligning a declaration to an accept set that already ships, i.e. declared-equals-enforced restoration, which is the code-tidy lane. I lean that way. ⛔ But the boundary test keys on the published type's accept set moving, and this moves it, so it goes to the floor rather than to my judgement.

⭐ The half that is NOT floor-blocked, and the handover says it is the actual cause

The seat handover (#7089) singles this card out:

#7081 is not a docs nit. zod-mirror-parity.test.ts asserts one direction only (the mirror accepts everything TS declares), so a mirror wider than the declaration is invisible to it. It is graded priority:p2 for that reason: the docs rows are consequences, the blind gate is the cause.

⇒ The one-directional gate is a measurement and gate-strengthening job, not a contract move:

• how many mirrors are wider than their TS declaration today (this card names trigger on AlertDialogSchema, HoverCardSchema and SheetSchema as unmeasured siblings);
• make the parity check report that direction instead of allowing it by construction.

⛔ That half does not widen anything and does not need a ruling. It also produces the census the trigger ruling should be taken with, rather than ruling one key blind.

Recommended regrade (triage's call, not mine)

Split the card:

1. needs-user-decision — the per-key ruling on DropdownMenuSchema.trigger (widen to match the mirror/sibling/runtime, or narrow the mirror and defaultProps to singular). ⚠️ It has a live downstream consumer already: I dispatched finding(docs): six component pages publish trigger/content/action as ComponentSchema, a different shipped type than the SchemaNode those keys actually declare #7082 (the docs rows) this round with an explicit fence to publish DropdownMenuSchema.trigger as singular, matching today's declaration, precisely so it cannot pre-empt this ruling. When this is ruled, that docs row may need a follow-up.
2. pm:queue — the bidirectional-parity measurement + gate. Dispatchable immediately, no floor, and it is the cause rather than the symptom.

---

Generated by Claude Code

[os-warren]

Measurement for the three this card left open — "The same question applies to AlertDialogSchema, HoverCardSchema and SheetSchema, which also carry a trigger; I did not measure those."

Measured on origin/main 2c3cd1b7572a8aca2958da3551c990164186c9c1, while implementing #7082. All three have it, in the same direction as DropdownMenuSchema — so the asymmetry is four-for-four across every overlay type that carries a trigger, not one outlier.

type	TS declaration	Zod mirror
DropdownMenuSchema	trigger: SchemaNode — overlay.ts:433	z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]) — zod/overlay.zod.ts:176
AlertDialogSchema	trigger?: SchemaNode — overlay.ts:91	z.union([...]).optional() — zod/overlay.zod.ts:46
SheetSchema	trigger?: SchemaNode — overlay.ts:150	z.union([...]).optional() — zod/overlay.zod.ts:65
HoverCardSchema	trigger: SchemaNode — overlay.ts:296	z.union([...]) — zod/overlay.zod.ts:120
ContextMenuSchema (the sibling this card cites)	trigger?: SchemaNode | SchemaNode[] — overlay.ts:486	z.union([...]).optional() — zod/overlay.zod.ts:191
DrawerSchema (a fifth, unmentioned)	trigger?: SchemaNode — overlay.ts:195	—

Two further data points for option (a):

• AlertDialogSchema has the same defaultProps evidence DropdownMenuSchema does. packages/components/src/renderers/overlay/alert-dialog.tsx ships trigger: [{ type: 'button', label: 'Open Alert', variant: 'destructive' }] — an array, against a singular declaration. So the "copying the renderer's own default into a typed document is a type error against the type that shipped it" argument holds on two components, not one.
• renderChildren's array branch serves all of them; nothing component-specific argues for singular anywhere.

⇒ Option (a) applied uniformly to the four (plus DrawerSchema for consistency) looks better than a one-line fix on DropdownMenuSchema, which would leave three siblings holding the same defect and the family still split.

Docs impact when this lands. #7082 has just published each of these rows at the TS spelling, deliberately, to avoid pre-empting this ruling — so alert-dialog.mdx, sheet.mdx, hover-card.mdx and dropdown-menu.mdx currently say SchemaNode (singular) and context-menu.mdx says the union. Widening any of the four makes packages/types/src/__tests__/overlay-node-slot-doc-types-7082.test.ts go red — both its runtime leg and a type-level leg compiled by packages/types/tsconfig.test.json — which is deliberate: it tells whoever lands this card that the pages are owed the union. Ablation for that guard is recorded on #7082's PR.

---

Generated by Claude Code