diff --git a/docs/scripts/buildApi.ts b/docs/scripts/buildApi.ts index b05c07e1ccfac8..fdee2930122845 100644 --- a/docs/scripts/buildApi.ts +++ b/docs/scripts/buildApi.ts @@ -27,7 +27,7 @@ const DEMO_IGNORE = LANGUAGES_IN_PROGRESS.map((language) => `-${language}.md`); const propDescriptions: { [key: string]: { [key: string]: string | undefined } } = {}; const classDescriptions: { [key: string]: { [key: string]: string } } = {}; -const componentDescriptions: { [key: string]: string } = {}; +const componentDescriptions: { [key: string]: { [key: string]: string } } = {}; const generateClassName = createGenerateClassName(); @@ -472,6 +472,7 @@ async function buildDocs(options: { throw err; } + // Add prop descriptions for JSON Object.entries(reactAPI.props).forEach(([propName, propData]) => { let description = propData.description; @@ -493,9 +494,12 @@ async function buildDocs(options: { delete reactAPI.props[propName].description; }); + componentDescriptions[reactAPI.name] = { name: reactAPI.name }; + if (reactAPI.description.length) { - componentDescriptions[reactAPI.name] = reactAPI.description; + componentDescriptions[reactAPI.name].description = reactAPI.description; } + classDescriptions[reactAPI.name] = reactAPI.styles.descriptions; // https://medium.com/@captaindaylight/get-a-subset-of-an-object-9896148b9c72 diff --git a/docs/src/modules/components/ApiDocs.js b/docs/src/modules/components/ApiDocs.js index fa746ee2b360f5..05ad36e4a3d92f 100644 --- a/docs/src/modules/components/ApiDocs.js +++ b/docs/src/modules/components/ApiDocs.js @@ -72,8 +72,11 @@ function ApiDocs(props) { styles: componentStyles, } = pageContent; - const description = t('apiDescription').replace(/{{name}}/, name); - + const apiDescription = t('apiDescription').replace(/{{name}}/, name); + const description = + componentDescription[userLanguage] && componentDescription[userLanguage].description; + const componentName = + (componentDescription[userLanguage] && componentDescription[userLanguage].name) || name; const source = filename .replace( /\/packages\/material-ui(-(.+?))?\/src/, @@ -127,7 +130,7 @@ function ApiDocs(props) { } function dangerousMarkdown(md) { - return ; + return md && ; } function heading(hash, level = 2) { @@ -147,7 +150,7 @@ function ApiDocs(props) { return ( - + {disableAd ? null : ( @@ -164,9 +167,9 @@ function ApiDocs(props) {
-

{name} API

+

{componentName} API

- {description} + {apiDescription} {heading('import')} {dangerousMarkdown(t('apiImportDifference'))} - {componentDescription[userLanguage] && - dangerousMarkdown(componentDescription[userLanguage])} + {description && dangerousMarkdown(description)} {componentStyles.name && ( {heading('component-name')} diff --git a/docs/translations/component-descriptions-zh.json b/docs/translations/component-descriptions-zh.json index 185c6b00c2256d..5e7303a359ff4e 100644 --- a/docs/translations/component-descriptions-zh.json +++ b/docs/translations/component-descriptions-zh.json @@ -1,37 +1,247 @@ { - "ButtonBase": "`ButtonBase` contains as few styles as possible.\nIt aims to be a simple building block for creating a button.\nIt contains a load of style reset and some focus/ripple logic.", - "Chip": "Chips represent complex entities in small blocks, such as a contact.", - "CircularProgress": "## ARIA\n\nIf the progress bar is describing the loading progress of a particular region of a page,\nyou should use `aria-describedby` to point to the progress bar, and set the `aria-busy`\nattribute to `true` on that region until it has finished loading.", - "ClickAwayListener": "Listen for click events that occur somewhere in the document, outside of the element itself.\nFor instance, if you need to hide a menu when people click anywhere else on your page.", - "Collapse": "The Collapse transition is used by the\n[Vertical Stepper](/components/steppers/#vertical-stepper) StepContent component.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.", - "CssBaseline": "Kickstart an elegant, consistent, and simple baseline to build upon.", - "Dialog": "Dialogs are overlaid modal paper based components with a backdrop.", - "Drawer": "The props of the [Modal](/api/modal/) component are available\nwhen `variant=\"temporary\"` is set.", - "Fade": "The Fade transition is used by the [Modal](/components/modal/) component.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.", - "FormControl": "Provides context such as filled/focused/error/required for form inputs.\nRelying on the context provides high flexibility and ensures that the state always stays\nconsistent across the children of the `FormControl`.\nThis context is used by the following components:\n\n - FormLabel\n - FormHelperText\n - Input\n - InputLabel\n\nYou can find one composition example below and more going to [the demos](/components/text-fields/#components).\n\n```jsx\n\n Email address\n \n We'll never share your email.\n\n```\n\n⚠️ Only one `InputBase` can be used within a FormControl because it create visual inconsistencies.\nFor instance, only one input can be focused at the same time, the state shouldn't be shared.", - "FormControlLabel": "Drop in replacement of the `Radio`, `Switch` and `Checkbox` component.\nUse this component if you want to display an extra label.", - "FormGroup": "`FormGroup` wraps controls such as `Checkbox` and `Switch`.\nIt provides compact row layout.\nFor the `Radio`, you should be using the `RadioGroup` component instead of this one.", - "Grow": "The Grow transition is used by the [Tooltip](/components/tooltips/) and\n[Popover](/components/popover/) components.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.", - "Hidden": "Responsively hides children based on the selected implementation.", - "IconButton": "Refer to the [Icons](/components/icons/) section of the documentation\nregarding the available icon options.", - "InputBase": "`InputBase` contains as few styles as possible.\nIt aims to be a simple building block for creating an input.\nIt contains a load of style reset and some state logic.", - "LinearProgress": "## ARIA\n\nIf the progress bar is describing the loading progress of a particular region of a page,\nyou should use `aria-describedby` to point to the progress bar, and set the `aria-busy`\nattribute to `true` on that region until it has finished loading.", - "ListItem": "Uses an additional container component if `ListItemSecondaryAction` is the last child.", - "ListItemAvatar": "A simple wrapper to apply `List` styles to an `Avatar`.", - "ListItemIcon": "A simple wrapper to apply `List` styles to an `Icon` or `SvgIcon`.", - "ListItemSecondaryAction": "Must be used as the last child of ListItem to function properly.", - "MenuList": "A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton.\nIt's exposed to help customization of the [`Menu`](/api/menu/) component. If you\nuse it separately you need to move focus into the component manually. Once\nthe focus is placed inside the component it is fully keyboard accessible.", - "Modal": "Modal is a lower-level construct that is leveraged by the following components:\n\n- [Dialog](/api/dialog/)\n- [Drawer](/api/drawer/)\n- [Menu](/api/menu/)\n- [Popover](/api/popover/)\n\nIf you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component\nrather than directly using Modal.\n\nThis component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals).", - "NativeSelect": "An alternative to `\n We'll never share your email.\n\n```\n\n⚠️ Only one `InputBase` can be used within a FormControl because it create visual inconsistencies.\nFor instance, only one input can be focused at the same time, the state shouldn't be shared." + }, + "FormControlLabel": { + "name": "FormControlLabel", + "description": "Drop in replacement of the `Radio`, `Switch` and `Checkbox` component.\nUse this component if you want to display an extra label." + }, + "FormGroup": { + "name": "FormGroup", + "description": "`FormGroup` wraps controls such as `Checkbox` and `Switch`.\nIt provides compact row layout.\nFor the `Radio`, you should be using the `RadioGroup` component instead of this one." + }, + "FormHelperText": { "name": "FormHelperText" }, + "FormLabel": { "name": "FormLabel" }, + "Grid": { "name": "Grid" }, + "Grow": { + "name": "Grow", + "description": "The Grow transition is used by the [Tooltip](/components/tooltips/) and\n[Popover](/components/popover/) components.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally." + }, + "Hidden": { + "name": "Hidden", + "description": "Responsively hides children based on the selected implementation." + }, + "Icon": { "name": "Icon" }, + "IconButton": { + "name": "IconButton", + "description": "Refer to the [Icons](/components/icons/) section of the documentation\nregarding the available icon options." + }, + "ImageList": { "name": "ImageList" }, + "ImageListItem": { "name": "ImageListItem" }, + "ImageListItemBar": { "name": "ImageListItemBar" }, + "Input": { "name": "Input" }, + "InputAdornment": { "name": "InputAdornment" }, + "InputBase": { + "name": "InputBase", + "description": "`InputBase` contains as few styles as possible.\nIt aims to be a simple building block for creating an input.\nIt contains a load of style reset and some state logic." + }, + "InputLabel": { "name": "InputLabel" }, + "LinearProgress": { + "name": "LinearProgress", + "description": "## ARIA\n\nIf the progress bar is describing the loading progress of a particular region of a page,\nyou should use `aria-describedby` to point to the progress bar, and set the `aria-busy`\nattribute to `true` on that region until it has finished loading." + }, + "Link": { "name": "Link" }, + "List": { "name": "List" }, + "ListItem": { + "name": "ListItem", + "description": "Uses an additional container component if `ListItemSecondaryAction` is the last child." + }, + "ListItemAvatar": { + "name": "ListItemAvatar", + "description": "A simple wrapper to apply `List` styles to an `Avatar`." + }, + "ListItemIcon": { + "name": "ListItemIcon", + "description": "A simple wrapper to apply `List` styles to an `Icon` or `SvgIcon`." + }, + "ListItemSecondaryAction": { + "name": "ListItemSecondaryAction", + "description": "Must be used as the last child of ListItem to function properly." + }, + "ListItemText": { "name": "ListItemText" }, + "ListSubheader": { "name": "ListSubheader" }, + "LoadingButton": { "name": "LoadingButton" }, + "Menu": { "name": "Menu" }, + "MenuItem": { "name": "MenuItem" }, + "MenuList": { + "name": "MenuList", + "description": "A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton.\nIt's exposed to help customization of the [`Menu`](/api/menu/) component. If you\nuse it separately you need to move focus into the component manually. Once\nthe focus is placed inside the component it is fully keyboard accessible." + }, + "MobileStepper": { "name": "MobileStepper" }, + "Modal": { + "name": "Modal", + "description": "Modal is a lower-level construct that is leveraged by the following components:\n\n- [Dialog](/api/dialog/)\n- [Drawer](/api/drawer/)\n- [Menu](/api/menu/)\n- [Popover](/api/popover/)\n\nIf you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component\nrather than directly using Modal.\n\nThis component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals)." + }, + "NativeSelect": { + "name": "NativeSelect", + "description": "An alternative to `\n We'll never share your email.\n\n```\n\n⚠️ Only one `InputBase` can be used within a FormControl because it create visual inconsistencies.\nFor instance, only one input can be focused at the same time, the state shouldn't be shared.", - "FormControlLabel": "Drop in replacement of the `Radio`, `Switch` and `Checkbox` component.\nUse this component if you want to display an extra label.", - "FormGroup": "`FormGroup` wraps controls such as `Checkbox` and `Switch`.\nIt provides compact row layout.\nFor the `Radio`, you should be using the `RadioGroup` component instead of this one.", - "Grow": "The Grow transition is used by the [Tooltip](/components/tooltips/) and\n[Popover](/components/popover/) components.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.", - "Hidden": "Responsively hides children based on the selected implementation.", - "IconButton": "Refer to the [Icons](/components/icons/) section of the documentation\nregarding the available icon options.", - "InputBase": "`InputBase` contains as few styles as possible.\nIt aims to be a simple building block for creating an input.\nIt contains a load of style reset and some state logic.", - "LinearProgress": "## ARIA\n\nIf the progress bar is describing the loading progress of a particular region of a page,\nyou should use `aria-describedby` to point to the progress bar, and set the `aria-busy`\nattribute to `true` on that region until it has finished loading.", - "ListItem": "Uses an additional container component if `ListItemSecondaryAction` is the last child.", - "ListItemAvatar": "A simple wrapper to apply `List` styles to an `Avatar`.", - "ListItemIcon": "A simple wrapper to apply `List` styles to an `Icon` or `SvgIcon`.", - "ListItemSecondaryAction": "Must be used as the last child of ListItem to function properly.", - "MenuList": "A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton.\nIt's exposed to help customization of the [`Menu`](/api/menu/) component. If you\nuse it separately you need to move focus into the component manually. Once\nthe focus is placed inside the component it is fully keyboard accessible.", - "Modal": "Modal is a lower-level construct that is leveraged by the following components:\n\n- [Dialog](/api/dialog/)\n- [Drawer](/api/drawer/)\n- [Menu](/api/menu/)\n- [Popover](/api/popover/)\n\nIf you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component\nrather than directly using Modal.\n\nThis component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals).", - "NativeSelect": "An alternative to `\n We'll never share your email.\n\n```\n\n⚠️ Only one `InputBase` can be used within a FormControl because it create visual inconsistencies.\nFor instance, only one input can be focused at the same time, the state shouldn't be shared." + }, + "FormControlLabel": { + "name": "FormControlLabel", + "description": "Drop in replacement of the `Radio`, `Switch` and `Checkbox` component.\nUse this component if you want to display an extra label." + }, + "FormGroup": { + "name": "FormGroup", + "description": "`FormGroup` wraps controls such as `Checkbox` and `Switch`.\nIt provides compact row layout.\nFor the `Radio`, you should be using the `RadioGroup` component instead of this one." + }, + "FormHelperText": { "name": "FormHelperText" }, + "FormLabel": { "name": "FormLabel" }, + "Grid": { "name": "Grid" }, + "Grow": { + "name": "Grow", + "description": "The Grow transition is used by the [Tooltip](/components/tooltips/) and\n[Popover](/components/popover/) components.\nIt uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally." + }, + "Hidden": { + "name": "Hidden", + "description": "Responsively hides children based on the selected implementation." + }, + "Icon": { "name": "Icon" }, + "IconButton": { + "name": "IconButton", + "description": "Refer to the [Icons](/components/icons/) section of the documentation\nregarding the available icon options." + }, + "ImageList": { "name": "ImageList" }, + "ImageListItem": { "name": "ImageListItem" }, + "ImageListItemBar": { "name": "ImageListItemBar" }, + "Input": { "name": "Input" }, + "InputAdornment": { "name": "InputAdornment" }, + "InputBase": { + "name": "InputBase", + "description": "`InputBase` contains as few styles as possible.\nIt aims to be a simple building block for creating an input.\nIt contains a load of style reset and some state logic." + }, + "InputLabel": { "name": "InputLabel" }, + "LinearProgress": { + "name": "LinearProgress", + "description": "## ARIA\n\nIf the progress bar is describing the loading progress of a particular region of a page,\nyou should use `aria-describedby` to point to the progress bar, and set the `aria-busy`\nattribute to `true` on that region until it has finished loading." + }, + "Link": { "name": "Link" }, + "List": { "name": "List" }, + "ListItem": { + "name": "ListItem", + "description": "Uses an additional container component if `ListItemSecondaryAction` is the last child." + }, + "ListItemAvatar": { + "name": "ListItemAvatar", + "description": "A simple wrapper to apply `List` styles to an `Avatar`." + }, + "ListItemIcon": { + "name": "ListItemIcon", + "description": "A simple wrapper to apply `List` styles to an `Icon` or `SvgIcon`." + }, + "ListItemSecondaryAction": { + "name": "ListItemSecondaryAction", + "description": "Must be used as the last child of ListItem to function properly." + }, + "ListItemText": { "name": "ListItemText" }, + "ListSubheader": { "name": "ListSubheader" }, + "LoadingButton": { "name": "LoadingButton" }, + "Menu": { "name": "Menu" }, + "MenuItem": { "name": "MenuItem" }, + "MenuList": { + "name": "MenuList", + "description": "A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton.\nIt's exposed to help customization of the [`Menu`](/api/menu/) component. If you\nuse it separately you need to move focus into the component manually. Once\nthe focus is placed inside the component it is fully keyboard accessible." + }, + "MobileStepper": { "name": "MobileStepper" }, + "Modal": { + "name": "Modal", + "description": "Modal is a lower-level construct that is leveraged by the following components:\n\n- [Dialog](/api/dialog/)\n- [Drawer](/api/drawer/)\n- [Menu](/api/menu/)\n- [Popover](/api/popover/)\n\nIf you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component\nrather than directly using Modal.\n\nThis component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals)." + }, + "NativeSelect": { + "name": "NativeSelect", + "description": "An alternative to `