Automate component documentation

[mperrotti]

I'm trying to automate more of our component documentation by using react-docgen-typscript. This could eliminate the need to maintain {ComponentName}.docs.json files.

See this discussion post for a more detailed overview of this work.

Try it out

npm run build:component-docs-json

Raw Docgen output: packages/react/script/prop-docs/docgen-output.json With data required by components.json schema: packages/react/script/prop-docs/components.json

Overview

The bulk of the changes in this PR are to make component documentation data parseable by react-docgen and react-typescript-docgen.

The main issue was caused by referencing accessing React's modules directly from the React import. I found 3 ways to work around this:

import React, {forwardRef, type FC, type PropsWithChildren} from 'react'

const PlainComponent: FC<PropsWithChildren<P>> = (props) => {}

const ComponentThatForwardsRef = forwardRef<HTMLElement, P>(
    (props, _ref) => {}
)

import * as React from 'react'

const PlainComponent: React.FC<React.PropsWithChildren<P>> = (props) => {}

const ComponentThatForwardsRef = React.forwardRef<HTMLElement, P>(
    (props, _ref) => {}
)

import React from 'react'

const PlainComponent = (props: P) => {}

const ComponentThatForwardsRef = React.forwardRef(
    (props: P, _ref) => {}
)

Still broken

There are a few files I haven't been able to parse yet.

Skipped entirely by react-docgen-typsecript

Comforting note: We might not even need docs for these because they're only used internally.

• packages/react/src/ActionList/ActionListContainerContext.tsx
• packages/react/src/Autocomplete/AutocompleteContext.tsx
• packages/react/src/Button/ButtonBase.tsx
• packages/react/src/UnderlineNav/UnderlineNavContext.tsx
• packages/react/src/deprecated/Button/ButtonStyles.tsx
• packages/react/src/drafts/MarkdownEditor/_SavedReplies.tsx

Props or args not documented

Comforting note: Some of these components don't have any props besides "children", and some of these files may not even need docs because they're not meant for external use.

• packages/react/src/ActionBar/ActionBar.tsx - ActionBar.Divider
• packages/react/src/Blankslate/Blankslate.tsx - Blankslate.Visual
• packages/react/src/Blankslate/Blankslate.tsx - Blankslate.Description
• packages/react/src/ConfirmationDialog/ConfirmationDialog.tsx - useConfirm
• packages/react/src/DataTable/Table.tsx - Table.Actions
• packages/react/src/DataTable/Table.tsx - Table.Divider
• packages/react/src/DataTable/Table.tsx - Table.Head
• packages/react/src/DataTable/Table.tsx - Table.Body
• packages/react/src/DataTable/Table.tsx - Table.Row
• packages/react/src/DataTable/Table.tsx - Table.CellPlaceholder
• packages/react/src/FormControl/_FormControlContext.tsx - useFormControlContext
• packages/react/src/FormControl/_FormControlContext.tsx - useFormControlForwardedProps
• packages/react/src/FormControl/_FormControlContext.tsx - FormControlContextProvider
• packages/react/src/Portal/Portal.tsx - registerPortalRoot
• packages/react/src/Select/Select.tsx - Select.OptGroup
• packages/react/src/ToggleSwitch/ToggleSwitchStoryWrapper.tsx - ToggleSwitchStoryWrapper
• packages/react/src/UnderlineNav/UnderlineNav.tsx - MoreMenuListItem
• packages/react/src/UnderlineNav/UnderlineNav.tsx - getValidChildren
• packages/react/src/hooks/useMedia.tsx - useMedia
• packages/react/src/utils/form-story-helpers.tsx - getTextInputArgTypes
• packages/react/src/utils/isNumeric.tsx - isNumeric
• packages/react/src/utils/ssr.tsx - SSRProvider
• packages/react/src/utils/ssr.tsx - useSSRSafeId
• packages/react/src/deprecated/ActionList/Divider.tsx - Divider
• packages/react/src/deprecated/ActionList/Divider.tsx - Divider.renderItem
• packages/react/src/deprecated/ActionList/Divider.tsx - StyledDivider
• packages/react/src/drafts/CSSComponent/index.tsx - Component
• packages/react/src/drafts/MarkdownEditor/Toolbar.tsx - MarkdownEditor.DefaultToolbarButtons
• packages/react/src/drafts/SelectPanel2/SelectPanel.tsx - SelectPanel.Footer
• packages/react/src/drafts/SelectPanel2/SelectPanel.tsx - SelectPanel.Loading
• packages/react/src/internal/components/LiveRegion.tsx - LiveRegion
• packages/react/src/internal/components/UnderlineTabbedInterface.tsx - StyledUnderlineItemList
• packages/react/src/internal/components/UnderlineTabbedInterface.tsx - LoadingCounter
• packages/react/src/drafts/MarkdownEditor/suggestions/_useEmojiSuggestions.tsx - useEmojiSuggestions
• packages/react/src/drafts/MarkdownEditor/suggestions/_useMentionSuggestions.tsx - useMentionSuggestions
• packages/react/src/drafts/MarkdownEditor/suggestions/_useReferenceSuggestions.tsx - useReferenceSuggestions
• packages/react/src/internal/components/CheckboxOrRadioGroup/CheckboxOrRadioGroupContext.tsx - Context

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 4a3295155421db9859cf7e73614142416a547554

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[bot]]

Hi! This pull request has been marked as stale because it has been open with no activity for 60 days. You can comment on the pull request or remove the stale label to keep it open. If you do nothing, this pull request will be closed in 7 days.

[github-actions[bot]]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	91.19 KB (-0.03% 🔽)
packages/react/dist/browser.umd.js	91.45 KB (-0.11% 🔽)