Found while correcting the BaseSchema common-props table for #7079. Filed unassigned rather than fixed: it is a defect in the declaration, and #7079's scope was the docs table.
The claim
packages/types/src/base.ts:296-301:
/**
* Controls whether the component is hidden (but still rendered).
* When true, component is rendered but not visible (visibility: hidden).
* @default false
*/
hidden?: boolean;
and its sibling, base.ts:262-264:
/**
* Controls whether the component is visible.
* When false, component is not rendered (display: none).
*/
So the declaration draws a distinction: visible: false removes the node, hidden: true keeps it in the tree and hides it visually.
What the renderer does
packages/react/src/SchemaRenderer.tsx evaluates both keys in oneshouldHide chain (from around line 1176). visible, visibleWhen, visibleOn, visibility, hidden and hiddenOn are legs of the same early-return chain, and every leg feeds the same boolean:
- line 1245:
if (shouldHide) { newSchema._hidden = true; } - line 1386:
if (evaluatedSchema._hidden) return null;
_hidden has exactly one effect and one consumer — that early return. So hidden: true and visible: false converge on an identical outcome: the component returns null and is not rendered. Nothing in the renderer emits visibility: hidden, and there is no branch that could tell the two apart, because the distinguishing information is gone by the time _hidden is read.
The file's own doc comment agrees, at line 266: "true sets _hidden and this component returns null".
Why this is worth writing down
It nearly caused a bad docs edit. The hidden / hiddenOn row in the schema-reference table read "Inverse of visible", and while splitting that combined row I checked whether to correct the wording toward base.ts's JSDoc. Doing so would have made the page less accurate: "Inverse of visible" is a true description of the shipped behaviour, and base.ts's "rendered but not visible" is not. The row was left unchanged for that reason, and the reason belongs somewhere findable.
The general hazard is that the JSDoc is the authority a docs correction is measured against — that is exactly how #7079 was worked — so a wrong JSDoc propagates into the docs on the next pass, with every step of the process looking correct.
Not decided here
Whether the JSDoc should be corrected to describe the single hide path, or whether the two keys were meant to differ and the renderer lost the distinction. The second reading is not obviously wrong: two separately declared keys that behave identically is itself a question, and hidden's "still rendered" promise is the kind of thing an accessibility or animation use-case would want. Answering it means ruling on whether the distinction should exist, which is above a docs card.
Refs #7079 · #3955 · #3862.
Generated by Claude Code
Found while correcting the
BaseSchemacommon-props table for #7079. Filed unassigned rather than fixed: it is a defect in the declaration, and #7079's scope was the docs table.The claim
packages/types/src/base.ts:296-301:and its sibling,
base.ts:262-264:So the declaration draws a distinction:
visible: falseremoves the node,hidden: truekeeps it in the tree and hides it visually.What the renderer does
packages/react/src/SchemaRenderer.tsxevaluates both keys in oneshouldHidechain (from around line 1176).visible,visibleWhen,visibleOn,visibility,hiddenandhiddenOnare legs of the same early-return chain, and every leg feeds the same boolean:if (shouldHide) { newSchema._hidden = true; }if (evaluatedSchema._hidden) return null;_hiddenhas exactly one effect and one consumer — that early return. Sohidden: trueandvisible: falseconverge on an identical outcome: the component returnsnulland is not rendered. Nothing in the renderer emitsvisibility: hidden, and there is no branch that could tell the two apart, because the distinguishing information is gone by the time_hiddenis read.The file's own doc comment agrees, at line 266: "
truesets_hiddenand this component returnsnull".Why this is worth writing down
It nearly caused a bad docs edit. The
hidden/hiddenOnrow in the schema-reference table read "Inverse of visible", and while splitting that combined row I checked whether to correct the wording towardbase.ts's JSDoc. Doing so would have made the page less accurate: "Inverse ofvisible" is a true description of the shipped behaviour, andbase.ts's "rendered but not visible" is not. The row was left unchanged for that reason, and the reason belongs somewhere findable.The general hazard is that the JSDoc is the authority a docs correction is measured against — that is exactly how #7079 was worked — so a wrong JSDoc propagates into the docs on the next pass, with every step of the process looking correct.
Not decided here
Whether the JSDoc should be corrected to describe the single hide path, or whether the two keys were meant to differ and the renderer lost the distinction. The second reading is not obviously wrong: two separately declared keys that behave identically is itself a question, and
hidden's "still rendered" promise is the kind of thing an accessibility or animation use-case would want. Answering it means ruling on whether the distinction should exist, which is above a docs card.Refs #7079 · #3955 · #3862.
Generated by Claude Code