🚧 Derive component docs.json from TS

[adierkens]

This change builds upon some of the foundations from #6047 to enable us to progressively move towards more colocated documentation for our prop types inline with the TS source-code.

As a first-step, the list of properties to expose to documentation will still remain in the *.docs.json file, but each now have the option of using the "derive": true flag to gather any pertinent information from the TS types, including description (JSDoc), defaultValue, type, and required. Fields specified in the *.docs.json will override any from TS, allowing for customization as more is moved into each component.

This reduces the amount of overhead for maintaining the separate *.docs.json per Component and also has the added benefit of exposing better documentation for users within their IDEs (which already pull from JSDoc comments and tags like @default)

Before	After

Validation & AutoFixing

Included in the doc-gen package is the ability to validate that the exports for a component in TS match what is present in the docs.json file:

This will highlight differences in what we're exposing to our users from documentation & in their IDE.

Running with -v will present a detailed breakdown of what each source exports:

And running with the --fix flag will write all data from the docs.json back into the TS type in order to align them

---

Sample report generation

Component Documentation Status

Detailed Component Summary

Component Name	Passing Props (Count)	Passing Props	Broken Props (Count)	Broken Props
ActionBar	5	aria-label, aria-labelledby, size, flush, className	1	children
ActionBar.IconButton	5	aria-label, aria-labelledby, size, flush, className	1	children
ActionBar.Divider	5	aria-label, aria-labelledby, size, flush, className	1	children
ActionList	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.Item	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.Heading	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.LinkItem	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.LeadingVisual	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.TrailingVisual	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.TrailingAction	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.Description	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.GroupHeading	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.Group	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionList.Divider	4	selectionVariant, showDividers, role, sx	5	children, variant, as, disableFocusZone, className
ActionMenu	4	children, open, onOpenChange, anchorRef	0
ActionMenu.Button	4	children, open, onOpenChange, anchorRef	0
ActionMenu.Anchor	4	children, open, onOpenChange, anchorRef	0
ActionMenu.Overlay	4	children, open, onOpenChange, anchorRef	0
AnchoredOverlay	10	onOpen, onClose, anchorRef, anchorId, overlayProps, focusTrapSettings, focusZoneSettings, className, height, width	12	open, renderAnchor, side, align, alignmentOffset, anchorOffset, preventOverflow, pinPosition, variant, displayCloseButton, closeButtonProps, onPositionChange
Autocomplete	0		2	children, id
Autocomplete.Input	0		2	children, id
Autocomplete.Overlay	0		2	children, id
Autocomplete.Menu	0		2	children, id
Avatar	1	sx	5	alt, size, square, src, className
AvatarStack	1	sx	8	children, alignRight, disableExpand, size, className, variant, shape, style
Banner	7	description, hideTitle, icon, onDismiss, primaryAction, secondaryAction, variant	3	aria-label, className, title
Banner.Title	7	description, hideTitle, icon, onDismiss, primaryAction, secondaryAction, variant	3	aria-label, className, title
Banner.Description	7	description, hideTitle, icon, onDismiss, primaryAction, secondaryAction, variant	3	aria-label, className, title
Banner.PrimaryAction	7	description, hideTitle, icon, onDismiss, primaryAction, secondaryAction, variant	3	aria-label, className, title
Banner.SecondaryAction	7	description, hideTitle, icon, onDismiss, primaryAction, secondaryAction, variant	3	aria-label, className, title
Blankslate	3	border, narrow, spacious	2	className, size
Blankslate.Visual	3	border, narrow, spacious	2	className, size
Blankslate.Heading	3	border, narrow, spacious	2	className, size
Blankslate.Description	3	border, narrow, spacious	2	className, size
Blankslate.PrimaryAction	3	border, narrow, spacious	2	className, size
Blankslate.SecondaryAction	3	border, narrow, spacious	2	className, size
Box	1	sx	2	ref, as
BranchName	1	sx	2	ref, as
Breadcrumbs	2	className, sx	1	children
Breadcrumbs.Item	2	className, sx	1	children
Button	9	alignContent, block, leadingVisual, loading, loadingAnnouncement, sx, trailingVisual, trailingAction, disabled	12	as, href, children, count, inactive, leadingIcon, ref, size, trailingIcon, variant, labelWrap, icon
IconButton	3	variant, size, sx	17	children, as, href, inactive, icon, aria-label, keyshortcuts, keybindingHint, tooltipDirection, description, aria-labelledby, unsafeDisableTooltip, disabled, block, loading, loadingAnnouncement, labelWrap
ButtonGroup	1	sx	4	ref, as, role, className
Checkbox	4	disabled, validationStatus, value, sx	7	checked, defaultChecked, indeterminate, onChange, ref, as, required
CheckboxGroup	3	aria-labelledby, onChange, sx	5	children, disabled, id, required, className
CheckboxGroup.Label	3	aria-labelledby, onChange, sx	5	children, disabled, id, required, className
CheckboxGroup.Caption	3	aria-labelledby, onChange, sx	5	children, disabled, id, required, className
CheckboxGroup.Validation	3	aria-labelledby, onChange, sx	5	children, disabled, id, required, className
CircleBadge	1	sx	5	variant, size, inline, ref, as
CircleBadge.Icon	1	sx	5	variant, size, inline, ref, as
CircleOcticon	1	sx	3	icon, size, as
ConfirmationDialog	4	onClose, title, className, height	6	cancelButtonContent, confirmButtonContent, confirmButtonType, width, cancelButtonLoading, confirmButtonLoading
CounterLabel	1	sx	2	scheme, className
DataTable	6	aria-describedby, aria-labelledby, cellPadding, initialSortColumn, initialSortDirection, onToggleSort	3	data, columns, getRowId
Details	1	sx	0
Details.Summary	1	sx	0
Dialog	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.Body	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.Buttons	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.CloseButton	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.Footer	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.Header	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog.Title	13	title, subtitle, renderHeader, renderBody, renderFooter, footerButtons, role, width, height, returnFocusRef, initialFocusRef, position, className	2	onClose, sx
Dialog	3	narrow, wide, sx	6	isOpen, onDismiss, returnFocusRef, initialFocusRef, aria-labelledby, aria-label
Dialog.Header	3	narrow, wide, sx	6	isOpen, onDismiss, returnFocusRef, initialFocusRef, aria-labelledby, aria-label
FeatureFlags	0		1	flags
Flash	1	sx	4	full, variant, ref, as
FormControl	1	sx	7	children, disabled, id, required, layout, className, ref
FormControl.Label	1	sx	7	children, disabled, id, required, layout, className, ref
FormControl.Caption	1	sx	7	children, disabled, id, required, layout, className, ref
FormControl.Validation	1	sx	7	children, disabled, id, required, layout, className, ref
FormControl.LeadingVisual	1	sx	7	children, disabled, id, required, layout, className, ref
Header	1	sx	1	as
Header.Item	1	sx	1	as
Header.Link	1	sx	1	as
Heading	2	sx, variant	1	as
Hidden	0		4	when, children, className, style
InlineMessage	1	variant	2	size, sx
KeybindingHint	0		5	keys, format, variant, size, className
Label	0		2	variant, size
LabelGroup	2	overflowStyle, visibleChildCount	3	as, className, sx
Link	1	sx	7	href, muted, inline, underline, hoverColor, ref, as
NavList	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.Item	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.LeadingVisual	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.TrailingVisual	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.SubNav	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.Group	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.GroupHeading	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.Divider	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.TrailingAction	1	sx	5	aria-label, aria-labelledby, ref, as, children
NavList.GroupExpand	1	sx	5	aria-label, aria-labelledby, ref, as, children
Octicon	1	sx	5	aria-label, icon, color, size, verticalAlign
Overlay	3	overflow, data-test-id, sx	25	returnFocusRef, onClickOutside, onEscape, ignoreClickRefs, initialFocusRef, width, height, maxHeight, maxWidth, visibility, anchorSide, top, left, right, bottom, position, portalContainerName, preventOverflow, role, responsiveVariant, as, style, children, className, preventFocusOnOpen
PageHeader	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.ContextArea	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.ParentLink	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.ContextBar	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.ContextAreaActions	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.TitleArea	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.LeadingAction	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.LeadingVisual	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.Title	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.TrailingVisual	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.TrailingAction	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.Actions	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.Breadcrumbs	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.Description	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageHeader.Navigation	1	sx	6	aria-label, className, hidden, role, as, hasBorder
PageLayout	1	sx	7	containerWidth, padding, columnGap, rowGap, _slotsConfig, className, style
PageLayout.Header	1	sx	7	containerWidth, padding, columnGap, rowGap, _slotsConfig, className, style
PageLayout.Content	1	sx	7	containerWidth, padding, columnGap, rowGap, _slotsConfig, className, style
PageLayout.Pane	1	sx	7	containerWidth, padding, columnGap, rowGap, _slotsConfig, className, style
PageLayout.Footer	1	sx	7	containerWidth, padding, columnGap, rowGap, _slotsConfig, className, style
Pagehead	1	sx	1	as
Pagination	0		9	currentPage, pageCount, hrefBuilder, marginPageCount, onPageChange, showPages, surroundingPageCount, renderPage, sx
PointerBox	3	bg, border, borderColor	2	caret, sx
Popover	1	sx	5	as, caret, open, relative, className
Popover.Content	1	sx	5	as, caret, open, relative, className
Portal	0		2	onMount, containerName
ProgressBar	1	sx	5	animated, progress, barSize, inline, bg
ProgressBar.Item	1	sx	5	animated, progress, barSize, inline, bg
Radio	5	value, name, checked, disabled, sx	5	defaultChecked, onChange, ref, as, required
RadioGroup	4	aria-labelledby, name, onChange, sx	5	children, disabled, id, required, className
RadioGroup.Label	4	aria-labelledby, name, onChange, sx	5	children, disabled, id, required, className
RadioGroup.Caption	4	aria-labelledby, name, onChange, sx	5	children, disabled, id, required, className
RadioGroup.Validation	4	aria-labelledby, name, onChange, sx	5	children, disabled, id, required, className
RelativeTime	1	sx	22	datetime, date, format, tense, precision, threshold, prefix, second, minute, hour, weekday, day, month, year, timeZoneName, ref, noTitle, attributeChangedCallback, connectedCallback, onRelativeTimeUpdated, update, as
SegmentedControl	7	aria-label, aria-labelledby, aria-describedby, fullWidth, onChange, size, sx	3	variant, ref, className
SegmentedControl.Button	7	aria-label, aria-labelledby, aria-describedby, fullWidth, onChange, size, sx	3	variant, ref, className
SegmentedControl.IconButton	7	aria-label, aria-labelledby, aria-describedby, fullWidth, onChange, size, sx	3	variant, ref, className
Select	0		13	block, contrast, placeholder, size, validationStatus, as, hasTrailingAction, isInputFocused, monospace, width, minWidth, maxWidth, sx
SelectPanel	7	items, onOpenChange, aria-label, open, anchorId, anchorRef, disableFullscreenOnNarrow	41	title, subtitle, placeholder, placeholderText, inputLabel, filterValue, selected, onSelectedChange, onFilterChange, onCancel, overlayProps, textInputProps, variant, footer, message, notice, secondaryAction, showSelectedOptionsFirst, showSelectAll, loading, align, initialLoadingType, className, role, id, renderItem, renderGroup, showItemDividers, groupMetadata, loadingType, onListContainerRefChanged, onInputRefChanged, inputRef, messageText, announcementsEnabled, fullScreenOnNarrow, onSelectAllChange, sx, height, width, renderAnchor
SkeletonBox	2	width, className	2	height, sx
SkeletonAvatar	1	className	2	size, square
SkeletonText	2	maxWidth, className	2	size, lines
Spinner	3	size, className, sx	4	srText, aria-label, data-*, style
SplitPageLayout	1	className	0
SplitPageLayout.Header	1	className	0
SplitPageLayout.Content	1	className	0
SplitPageLayout.Pane	1	className	0
SplitPageLayout.Footer	1	className	0
Stack	7	gap, direction, align, wrap, justify, padding, className	1	as
Stack.Item	7	gap, direction, align, wrap, justify, padding, className	1	as
StateLabel	1	status	1	variant
SubNav	0		6	actions, align, full, label, aria-label, sx
SubNav.Link	0		6	actions, align, full, label, aria-label, sx
SubNav.Links	0		6	actions, align, full, label, aria-label, sx
TabNav	0		2	aria-label, sx
TabNav.Link	0		2	aria-label, sx
Text	4	sx, size, weight, whiteSpace	1	as
TextInput	6	loading, loaderPosition, leadingVisual, trailingVisual, trailingAction, sx	16	aria-label, autoComplete, block, contrast, size, loaderText, monospace, validationStatus, variant, width, maxWidth, minWidth, icon, ref, as, disabled
TextInput.Action	6	loading, loaderPosition, leadingVisual, trailingVisual, trailingAction, sx	16	aria-label, autoComplete, block, contrast, size, loaderText, monospace, validationStatus, variant, width, maxWidth, minWidth, icon, ref, as, disabled
TextInputWithTokens	4	tokens, onTokenRemove, maxHeight, visibleTokenCount	21	tokenComponent, preventTokenWrapping, size, hideTokenRemoveButtons, validationStatus, disabled, width, block, contrast, monospace, variant, minWidth, maxWidth, sx, icon, loading, loaderPosition, loaderText, leadingVisual, trailingVisual, trailingAction
Textarea	5	validationStatus, sx, className, minHeight, maxHeight	10	required, cols, rows, block, resize, contrast, ref, as, disabled, style
Timeline	1	sx	2	clipSidebar, className
Timeline.Item	1	sx	2	clipSidebar, className
Timeline.Badge	1	sx	2	clipSidebar, className
Timeline.Body	1	sx	2	clipSidebar, className
Timeline.Break	1	sx	2	clipSidebar, className
ToggleSwitch	8	aria-labelledby, defaultChecked, disabled, loading, checked, onChange, onClick, loadingLabelDelay	5	aria-describedby, size, statusLabelPosition, loadingLabel, buttonType
Token	8	leadingVisual, text, onRemove, hideRemoveButton, isSelected, id, size, sx	2	as, disabled
Tooltip	2	align, sx	5	direction, noDelay, aria-label, wrap, text
Tooltip	1	sx	4	direction, text, type, keybindingHint
TreeView	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.Item	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.LeadingVisual	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.TrailingVisual	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.DirectoryIcon	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.SubTree	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
TreeView.ErrorDialog	3	aria-label, aria-labelledby, children	4	className, flat, truncate, style
Truncate	1	sx	4	maxWidth, inline, expandable, as
UnderlineNav	2	children, sx	5	aria-label, loadingCounters, variant, as, className
UnderlineNav.Item	2	children, sx	5	aria-label, loadingCounters, variant, as, className
FilteredSearch	1	sx	1	children
UnderlineNav	0		5	actions, align, full, aria-label, label
UnderlineNav.Link	0		5	actions, align, full, aria-label, label
IssueLabel	0		6	as, className, fillColor, variant, onClick, href
SelectPanel	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.Button	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.Header	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.SearchInput	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.Footer	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.SecondaryAction	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.Loading	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
SelectPanel.Message	0		17	title, defaultOpen, description, variant, selectionVariant, onSubmit, onCancel, onClearSelection, anchorRef, open, children, width, height, maxHeight, id, anchoredPositionSettings, className
UnderlinePanels	5	aria-label, aria-labelledby, children, id, sx	2	loadingCounters, className
UnderlinePanels.Tab	5	aria-label, aria-labelledby, children, id, sx	2	loadingCounters, className
UnderlinePanels.Panel	5	aria-label, aria-labelledby, children, id, sx	2	loadingCounters, className

[changeset-bot]

⚠️ No Changeset found

Latest commit: 058b71d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github depends on. If you are GitHub staff, we recommend testing these changes with github/github using the integration workflow. Thanks!

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	89.94 KB (0%)
packages/react/dist/browser.umd.js	90.11 KB (0%)