Display deprecation messages in components API pages

mui · May 23, 2024 · 98f6fdb · 98f6fdb
1 parent c409a0c
commit 98f6fdb
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 3 deletions.
diff --git a/docs/pages/material-ui/api/hidden.json b/docs/pages/material-ui/api/hidden.json
@@ -40,5 +40,6 @@
   "filename": "/packages/mui-material/src/Hidden/Hidden.js",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/material-ui/react-hidden/\">Hidden</a></li></ul>",
-  "cssComponent": false
+  "cssComponent": false,
+  "deprecated": true
 }
diff --git a/docs/src/modules/components/ApiPage.js b/docs/src/modules/components/ApiPage.js
@@ -7,6 +7,7 @@ import Divider from '@mui/material/Divider';
 import AdGuest from 'docs/src/modules/components/AdGuest';
 import Alert from '@mui/material/Alert';
 import VerifiedRoundedIcon from '@mui/icons-material/VerifiedRounded';
+import DangerousIcon from '@mui/icons-material/Dangerous';
 import { alpha } from '@mui/material/styles';
 import { useTranslate, useUserLanguage } from '@mui/docs/i18n';
 import HighlightedCode from 'docs/src/modules/components/HighlightedCode';
@@ -82,6 +83,7 @@ export default function ApiPage(props) {
   const {
     cssComponent,
     demos,
+    deprecated,
     filename,
     forwardsRefTo,
     inheritance,
@@ -114,6 +116,7 @@ export default function ApiPage(props) {
     componentDescription,
     componentDescriptionToc = [],
     classDescriptions,
+    deprecationInfo,
     propDescriptions,
     slotDescriptions,
   } = descriptions[userLanguage];
@@ -190,6 +193,42 @@ export default function ApiPage(props) {
     >
       <MarkdownElement>
         <h1>{pageContent.name} API</h1>
+        {deprecated ? (
+          <Alert
+            severity="error"
+            variant="outlined"
+            icon={<DangerousIcon sx={{ fontSize: 20 }} />}
+            sx={(theme) => ({
+              mt: 1.5,
+              mb: 1.5,
+              fontSize: theme.typography.pxToRem(16),
+              backgroundColor: (theme.vars || theme).palette.error[50],
+              borderColor: (theme.vars || theme).palette.error[100],
+              '& .MuiAlert-message': {
+                '& * a': {
+                  color: (theme.vars || theme).palette.error[800],
+                  textDecorationColor: alpha(theme.palette.error[600], 0.3),
+                },
+              },
+              ...theme.applyDarkStyles({
+                backgroundColor: alpha(theme.palette.error[700], 0.12),
+                borderColor: alpha(theme.palette.error[400], 0.1),
+                '& .MuiAlert-message': {
+                  '& * a': {
+                    color: (theme.vars || theme).palette.error[100],
+                    textDecorationColor: alpha(theme.palette.error[100], 0.3),
+                  },
+                },
+              }),
+            })}
+          >
+            <span
+              dangerouslySetInnerHTML={{
+                __html: deprecationInfo || t('api-docs.defaultDeprecationMessage'),
+              }}
+            />
+          </Alert>
+        ) : null}
         <Typography variant="h5" component="p" className="description" gutterBottom>
           {description}
           {disableAd ? null : (

diff --git a/docs/translations/api-docs/hidden/hidden.json b/docs/translations/api-docs/hidden/hidden.json
@@ -1,5 +1,6 @@
 {
   "componentDescription": "Responsively hides children based on the selected implementation.",
+  "deprecationInfo": "The Hidden component was deprecated in Material UI v5. To learn more, see <a href=\"/material-ui/migration/v5-component-changes/#hidden\">the Hidden section</a> of the migration docs.",
   "propDescriptions": {
     "children": { "description": "The content of the component." },
     "implementation": {

diff --git a/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts b/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts
@@ -81,6 +81,7 @@ export interface ReactApi extends ReactDocgenApi {
   imports: string[];
   translations: {
     componentDescription: string;
+    deprecationInfo: string | undefined;
     propDescriptions: {
       [key: string]: {
         description: string;
@@ -104,6 +105,7 @@ export interface ReactApi extends ReactDocgenApi {
    * The folder used to store the API translation.
    */
   apiDocsTranslationFolder?: string;
+  deprecated: true | undefined;
 }
 
 const cssComponents = ['Box', 'Grid', 'Typography', 'Stack'];
@@ -409,6 +411,7 @@ const generateApiPage = async (
       .map((item) => `<li><a href="${item.demoPathname}">${item.demoPageTitle}</a></li>`)
       .join('\n')}</ul>`,
     cssComponent: cssComponents.indexOf(reactApi.name) >= 0,
+    deprecated: reactApi.deprecated,
   };
 
   const { classesSort = sortAlphabetical('key'), slotsSort = null } = {
@@ -463,9 +466,14 @@ const generateApiPage = async (
   }
 };
 
-const attachTranslations = (reactApi: ReactApi, settings?: CreateDescribeablePropSettings) => {
+const attachTranslations = (
+  reactApi: ReactApi,
+  deprecationInfo: string | undefined,
+  settings?: CreateDescribeablePropSettings,
+) => {
   const translations: ReactApi['translations'] = {
     componentDescription: reactApi.description,
+    deprecationInfo: deprecationInfo ? renderMarkdown(deprecationInfo) : undefined,
     propDescriptions: {},
     classDescriptions: {},
   };
@@ -804,8 +812,13 @@ export default async function generateComponentApi(
     reactApi.classes = classes;
   }
 
+  const deprecation = componentJsdoc.tags.find((tag) => tag.title === 'deprecated');
+  const deprecationInfo = deprecation?.description || undefined;
+
+  reactApi.deprecated = !!deprecation || undefined;
+
   attachPropsTable(reactApi, projectSettings.propsSettings);
-  attachTranslations(reactApi, projectSettings.propsSettings);
+  attachTranslations(reactApi, deprecationInfo, projectSettings.propsSettings);
 
   // eslint-disable-next-line no-console
   console.log('Built API docs for', reactApi.apiPathname);

diff --git a/packages/mui-docs/src/translations/translations.json b/packages/mui-docs/src/translations/translations.json
@@ -15,6 +15,7 @@
     "defaultComponent": "Default component",
     "defaultValue": "Default value",
     "defaultHTMLTag": "Default HTML tag",
+    "defaultDeprecationMessage": "This API is deprecated.",
     "demos": "Demos",
     "deprecated": "Deprecated",
     "description": "Description",