[docs] Detailed type definitions #818
Conversation
vladmoroz
requested review from
michaldudak,
atomiks and
colmtuite
as code owners
| @@ -0,0 +1,14 @@ | |||
| { | |||
| "name": "AccordionHeader", | |||
| "description": "", | |||
There was a problem hiding this comment.
Empty descriptions throw warnings during the API generation
Netlify deploy preview |
| @@ -24,6 +24,7 @@ const customStyleHookMapping: CustomStyleHookMapping<DialogBackdrop.OwnerState> | |||
| }; | |||
|
|
|||
| /** | |||
| * An overlay displayed beneath the popup. Renders a `<div>` element. | |||
There was a problem hiding this comment.
Do we like this and the other descriptions I added in the PR @colmtuite @samuelsycamore?
I plan to add/rework the descriptions for all the components in this style. (Most are missing).
There was a problem hiding this comment.
I left a note on one but in general I'm happy with the descriptions and their style. 🤝
| { | ||
| "props": { | ||
| "anchor": { | ||
| "type": "React.Ref | Element | VirtualElement | (() => Element | VirtualElement | null) | null" | ||
| }, | ||
| "className": { | ||
| "type": "string | (state) => string" | ||
| }, | ||
| "collisionBoundary": { | ||
| "type": "'clippingAncestors' | Element | Element[] | Rect" | ||
| }, | ||
| "collisionPadding": { | ||
| "type": "number | Rect" | ||
| }, | ||
| "container": { | ||
| "type": "React.Ref | HTMLElement | null" | ||
| }, | ||
| "initialFocus": { | ||
| "type": "React.Ref | (interactionType => HTMLElement | null)" | ||
| }, | ||
| "inputRef": { | ||
| "type": "React.Ref" | ||
| }, | ||
| "onClick": { | ||
| "type": "(event) => void" | ||
| }, | ||
| "render": { | ||
| "type": "React.ReactElement | (props, state) => React.ReactElement" | ||
| } | ||
| }, | ||
| "types": { | ||
| "bool": "boolean", | ||
| "func": "function", | ||
| "node": "React.ReactNode", | ||
| "ref": "React.Ref", | ||
| "Array<number>": "number[]", | ||
| "Array<string>": "string[]", | ||
| "'bottom' | 'left' | 'right' | 'top'": "'top' | 'bottom' | 'left' | 'right'", | ||
| "'center' | 'end' | 'start'": "'start' | 'center' | 'end'", | ||
| "'both' | 'none' | 'x' | 'y'": "'none' | 'x' | 'y' | 'both'" | ||
| } | ||
| } |
There was a problem hiding this comment.
Point of interest: these are type definition overrides across all components. E.g. all render prop definitions get this one; all bool types are transformed to boolean, etc.
| { | ||
| "name": "DialogPopup", | ||
| "attributes": { | ||
| "[data-open]": { | ||
| "description": "Present when the dialog is open." | ||
| }, | ||
| "[data-closed]": { | ||
| "description": "Present when the dialog is closed." | ||
| }, | ||
| "[data-entering]": { | ||
| "description": "Present when the dialog is animating in." | ||
| }, | ||
| "[data-exiting]": { | ||
| "description": "Present when the dialog is animating out." | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Point of interest: this is how data attributes are documented
| { | ||
| "name": "NumberFieldRoot", | ||
| "props": { | ||
| "format": { | ||
| "type": "Intl.NumberFormatOptions" | ||
| }, | ||
| "onValueChange": { | ||
| "type": "(value, event) => void" | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Point of interest: this is how generated type definitions are overridden when they are no good
| @@ -28,6 +28,7 @@ const customStyleHookMapping: CustomStyleHookMapping<DialogPopup.OwnerState> = { | |||
| }; | |||
|
|
|||
| /** | |||
| * A component that groups the dialog contents. Renders a `<div>` element. | |||
There was a problem hiding this comment.
I find this a little confusing when comparing with the description in DialogRoot.tsx below—I think I know the difference given that I have insider context, but for a newer user it might be hard to figure out. Is there a way to rewrite one or the other for clarity?
There was a problem hiding this comment.
Ah right, I didn't notice that both are saying that they group things.
Does this feel good for the Popup part?
| * A component that groups the dialog contents. Renders a `<div>` element. | |
| * A container for the dialog contents. Renders a `<div>` element. |
Link
https://deploy-preview-818--base-ui.netlify.app/new/components/dialog
What's up
How it works
@mui-internal/api-docs-builderdocs/reference/overridesdocs/reference/overrides/common.jsondocs/reference/generateddocs/datafolder is still in place and is used by the existing setup, but will be removed once we are finished.Things that we will need to add to overrides pretty much all the time:
Screenshot
If you are looking at the screenshot and wondering about nicer formatting for multiline union types, that's coming in a future PR.