Filed out-of-scope from the #7251 skills-optimization flight, noticed while writing a layout-primitive table from the renderers rather than from the types. Unassigned. A concrete instance of #4631 (a component type's declared surfaces disagreeing with what the renderer reads), narrowed to defaults.
Measured at 4704aa4.
Row 1 — container.maxWidth
packages/types/src/layout.ts, ContainerSchema:
/**
* Max width constraint
* @default 'lg'
*/
maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | ... | false;
packages/components/src/renderers/layout/container.tsx:
const maxWidth = schema.maxWidth ?? 'xl';
So a container with no maxWidth renders max-w-xl (36rem), while the type says it renders max-w-lg (32rem). An author reading the declaration to decide whether to set the key gets the wrong answer, in the direction that makes them skip setting it.
Row 2 — flex.align
packages/types/src/layout.ts, FlexLayoutProps (shared by FlexSchema and StackSchema):
/**
* Align items
* @default 'center'
*/
align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch';
The two renderers that read it:
flex.tsx:18 const align = schema.align || 'start';
stack.tsx:24 const align = schema.align || 'stretch'; // Stack items usually stretch
Neither is 'center'. And because one JSDoc block serves both types by design (FlexLayoutProps exists so the members are declared once — see its docblock and #6151), a single @default cannot be right for both: flex and stack deliberately diverge here, which is most of what distinguishes them.
Why it is worth a card rather than a silent fix
The @default tag is not decoration on this surface. sdui-parser serializes registry metadata into sdui.manifest.json and sdui-intrinsics.d.ts, and #4889 is the precedent for what happens when the declaration and the read disagree on this exact file: maxWidth: false was a declared value the renderer folded into max-w-xl, so an author asking for no constraint got the opposite of what they asked for. This is the same file, the same key, one layer up — the declaration is now right about the domain and wrong about the default.
Both rows are one-line documentation fixes if the renderers are taken as authoritative, which they should be: they are what runs. Row 2 additionally needs the shared @default to say that the two types differ, or the tag to move onto each type.
Not a duplicate of #4889 (closed — that was the ||-vs-?? read of false) or #7088 (BaseSchema.hidden's JSDoc promising visibility: hidden), but the same family as both.
Filed out-of-scope from the #7251 skills-optimization flight, noticed while writing a layout-primitive table from the renderers rather than from the types. Unassigned. A concrete instance of #4631 (a component type's declared surfaces disagreeing with what the renderer reads), narrowed to defaults.
Measured at
4704aa4.Row 1 —
container.maxWidthpackages/types/src/layout.ts,ContainerSchema:packages/components/src/renderers/layout/container.tsx:So a
containerwith nomaxWidthrendersmax-w-xl(36rem), while the type says it rendersmax-w-lg(32rem). An author reading the declaration to decide whether to set the key gets the wrong answer, in the direction that makes them skip setting it.Row 2 —
flex.alignpackages/types/src/layout.ts,FlexLayoutProps(shared byFlexSchemaandStackSchema):The two renderers that read it:
Neither is
'center'. And because one JSDoc block serves both types by design (FlexLayoutPropsexists so the members are declared once — see its docblock and #6151), a single@defaultcannot be right for both:flexandstackdeliberately diverge here, which is most of what distinguishes them.Why it is worth a card rather than a silent fix
The
@defaulttag is not decoration on this surface.sdui-parserserializes registry metadata intosdui.manifest.jsonandsdui-intrinsics.d.ts, and #4889 is the precedent for what happens when the declaration and the read disagree on this exact file:maxWidth: falsewas a declared value the renderer folded intomax-w-xl, so an author asking for no constraint got the opposite of what they asked for. This is the same file, the same key, one layer up — the declaration is now right about the domain and wrong about the default.Both rows are one-line documentation fixes if the renderers are taken as authoritative, which they should be: they are what runs. Row 2 additionally needs the shared
@defaultto say that the two types differ, or the tag to move onto each type.Not a duplicate of #4889 (closed — that was the
||-vs-??read offalse) or #7088 (BaseSchema.hidden's JSDoc promisingvisibility: hidden), but the same family as both.