docs: Added more fidelity on typedocs comments for Box and Button - #2780
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 4 Skipped Deployments
|
| as?: InteractiveAs<T> | ||
| /** Composite prop for setting padding and gap */ | ||
| /** | ||
| * Sets padding and gap to specify its size. |
There was a problem hiding this comment.
I’ve noticed we're describing composite props in several different ways — maybe best to make consistent?
| * Sets padding and gap to specify its size. | |
| * Composite prop that sets padding and gap |
| fullWidth?: Responsive<boolean> | ||
| /** Starting icon */ | ||
| /** | ||
| * Shows an icon in the start position (left side in left-to-right languages). |
There was a problem hiding this comment.
FWIW, these icons won't flip position for RTL languages — any chance this could be construed to suggest otherwise?
There was a problem hiding this comment.
I don't think we should use the term start if they don't flip direction.
| language?: string | ||
| /** CSS **font-size** property */ | ||
| /** | ||
| * Font size and line height from the code scale. |
There was a problem hiding this comment.
Reading this with 'line height' made me question if I needed to provide two values (font size and line height). Also not sure that consumers will know what the 'code scale' is — but I reckon they should be familiar with the idea that we have ramps for font size in general. Maybe just this?
| * Font size and line height from the code scale. | |
| * Font size |
| as?: T | ||
| /** CSS **font-size** property */ | ||
| /** | ||
| * Font size and line height, drawn from the same scale as Label. |
There was a problem hiding this comment.
| * Font size and line height, drawn from the same scale as Label. | |
| * Font size |
| /** Element to render */ | ||
| /** | ||
| * Semantic heading element to render. | ||
| * @remarks Always set this explicitly. |
There was a problem hiding this comment.
This remark makes me wonder why as is optional?
There was a problem hiding this comment.
I think we discussed making it required, but we haven't gotten to that yet.
| onClose: React.ReactEventHandler<HTMLDialogElement> | ||
| /** Whether the modal is open; defaults to false. */ | ||
| /** | ||
| * Controls the modal. |
There was a problem hiding this comment.
| * Controls the modal. | |
| * Controls the modal’s open state |
| as?: T | ||
| /** CSS **font-size** property */ | ||
| /** | ||
| * Font size and line height from the body text scale. |
There was a problem hiding this comment.
| * Font size and line height from the body text scale. | |
| * Font size |
| export interface TooltipGroupProps<T extends React.ElementType = 'div'> { | ||
| /** Element to render */ | ||
| /** | ||
| * HTML element to render as. |
There was a problem hiding this comment.
| * HTML element to render as. | |
| * HTML element to render |
| /** Focusable trigger element */ | ||
| /** | ||
| * The trigger element. | ||
| * @remarks Tooltip clones it to attach `aria-describedby` and the `interestfor` attribute that opens the label. |
There was a problem hiding this comment.
I'm wondering if the remark here is more implementation detail than the average consumer needs…?
| export interface VisuallyHiddenProps<T extends React.ElementType = 'span'> { | ||
| /** Element to render */ | ||
| /** | ||
| * HTML element to render. |
There was a problem hiding this comment.
Some of these say 'HTML element' and some say 'HTML element or component' — should they all be the latter, or do some not take components?
e19d087 to
bfbede9
Compare
2 participants
Adding more detailed typedoc comments for component props so they can be removed from documentation.
Note
Medium Risk
Mostly comment-only, but renaming
DialogPropstoModalPropsindialog.props.tswithout matching updates inDialog.tsxwould break types/exports if merged as-is.Overview
Expands JSDoc on
*.props.tsinterfaces across the UI package so generated docs can carry prop descriptions instead of duplicating them elsewhere. One-line summaries become multi-line blocks with clearer wording and@remarkswhere behavior, accessibility, or validation matter (e.g.Boxdisplayvs Flex/Grid, formerrorprops as visual-only, dialogopen/onClose, Popover/Tooltip triggers and portals).Dialog props also renames the exported interface from
DialogPropstoModalPropsindialog.props.tswhile prop docs forheader,onClose, andopenare rewritten.packages/ui/src/version.tsbumps to500alpha6.Reviewed by Cursor Bugbot for commit bfbede9. Bugbot is set up for automated code reviews on this repo. Configure here.