[List] Add button runtime deprecation warning

docs/pages/api-docs/list-item.json

@@ -4,8 +4,16 @@
       "type": { "name": "enum", "description": "'center'<br>&#124;&nbsp;'flex-start'" },
       "default": "'center'"
     },
-    "autoFocus": { "type": { "name": "bool" } },
-    "button": { "type": { "name": "bool" } },
+    "autoFocus": {
+      "type": { "name": "bool" },
+      "deprecated": true,
+      "deprecationInfo": "checkout <a href=\"/api/list-item-button/\">ListItemButton</a> instead"
+    },
+    "button": {
+      "type": { "name": "bool" },
+      "deprecated": true,
+      "deprecationInfo": "checkout <a href=\"/api/list-item-button/\">ListItemButton</a> instead"
+    },
     "children": { "type": { "name": "custom", "description": "node" } },
     "classes": { "type": { "name": "object" } },
     "component": { "type": { "name": "elementType" } },
@@ -16,16 +24,25 @@
     "componentsProps": { "type": { "name": "object" }, "default": "{}" },
     "ContainerComponent": {
       "type": { "name": "custom", "description": "element type" },
-      "default": "'li'"
+      "default": "'li'",
+      "deprecated": true
     },
-    "ContainerProps": { "type": { "name": "object" }, "default": "{}" },
+    "ContainerProps": { "type": { "name": "object" }, "default": "{}", "deprecated": true },
     "dense": { "type": { "name": "bool" } },
-    "disabled": { "type": { "name": "bool" } },
+    "disabled": {
+      "type": { "name": "bool" },
+      "deprecated": true,
+      "deprecationInfo": "checkout <a href=\"/api/list-item-button/\">ListItemButton</a> instead"
+    },
     "disableGutters": { "type": { "name": "bool" } },
     "disablePadding": { "type": { "name": "bool" } },
     "divider": { "type": { "name": "bool" } },
     "secondaryAction": { "type": { "name": "node" } },
-    "selected": { "type": { "name": "bool" } },
+    "selected": {
+      "type": { "name": "bool" },
+      "deprecated": true,
+      "deprecationInfo": "checkout <a href=\"/api/list-item-button/\">ListItemButton</a> instead"
+    },
     "sx": { "type": { "name": "object" } }
   },
   "name": "ListItem",

docs/scripts/buildApi.ts

@@ -833,6 +833,8 @@ async function buildDocs(options: {
     default: string | undefined;
     required: boolean | undefined;
     type: { name: string | undefined; description: string | undefined };
+    deprecated: true | undefined;
+    deprecationInfo: string | undefined;
   }>(
     Object.entries(reactApi.props).map(([propName, propDescriptor]) => {
       let prop: DescribeablePropDescriptor | null;
@@ -874,6 +876,8 @@ async function buildDocs(options: {
         /\.isRequired/.test(prop.type.raw) ||
         (chainedPropType !== false && chainedPropType.required);
 
+      const deprecation = (propDescriptor.description || '').match(/@deprecated(\s+(?<info>.*))?/);
+
       return [
         propName,
         {
@@ -885,6 +889,9 @@ async function buildDocs(options: {
           default: defaultValue,
           // undefined values are not serialized => saving some bytes
           required: requiredProp || undefined,
+          deprecated: !!deprecation || undefined,
+          deprecationInfo:
+            renderMarkdownInline(deprecation?.groups?.info || '').trim() || undefined,
         },
       ];
     }),

docs/src/modules/components/ApiPage.js

@@ -3,12 +3,16 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import clsx from 'clsx';
 import { exactProp } from '@material-ui/utils';
+import { styled } from '@material-ui/core/styles';
+import Alert from '@material-ui/core/Alert';
 import Typography from '@material-ui/core/Typography';
 import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
 import HighlightedCode from 'docs/src/modules/components/HighlightedCode';
 import MarkdownElement from 'docs/src/modules/components/MarkdownElement';
 import AppLayoutDocs from 'docs/src/modules/components/AppLayoutDocs';
 
+const Asterisk = styled('abbr')(({ theme }) => ({ color: theme.palette.error.main }));
+
 function PropsTable(props) {
   const { componentProps, propDescriptions } = props;
   const t = useTranslate();
@@ -33,11 +37,11 @@ function PropsTable(props) {
                 <td align="left">
                   <span className={clsx('prop-name', propData.required ? 'required' : null)}>
                     {propName}
-                    {propData.required ? (
+                    {propData.required && (
                       <sup>
-                        <abbr title="required">*</abbr>
+                        <Asterisk title="required">*</Asterisk>
                       </sup>
-                    ) : null}
+                    )}
                   </span>
                 </td>
                 <td align="left">
@@ -49,12 +53,26 @@ function PropsTable(props) {
                 <td align="left">
                   {propDefault && <span className="prop-default">{propDefault}</span>}
                 </td>
-                <td
-                  align="left"
-                  dangerouslySetInnerHTML={{
-                    __html: propDescriptions[propName] || '',
-                  }}
-                />
+                <td align="left">
+                  {propData.deprecated && (
+                    <Alert severity="warning" sx={{ mb: 1, py: 0 }}>
+                      <strong>Deprecated</strong>
+                      {propData.deprecationInfo && ' - '}
+                      {propData.deprecationInfo && (
+                        <span
+                          dangerouslySetInnerHTML={{
+                            __html: propData.deprecationInfo,
+                          }}
+                        />
+                      )}
+                    </Alert>
+                  )}
+                  <div
+                    dangerouslySetInnerHTML={{
+                      __html: propDescriptions[propName] || '',
+                    }}
+                  />
+                </td>
               </tr>
             )
           );

packages/material-ui/src/ListItem/ListItem.d.ts

@@ -15,7 +15,7 @@ interface ListItemBaseProps {
    * If `true`, the list item is focused during the first mount.
    * Focus will also be triggered if the value changes from false to true.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   autoFocus?: boolean;
   /**
@@ -48,7 +48,7 @@ interface ListItemBaseProps {
   /**
    * If `true`, the component is disabled.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   disabled?: boolean;
   /**
@@ -73,7 +73,7 @@ interface ListItemBaseProps {
   /**
    * Use to apply selected styling.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   selected?: boolean;
   /**
@@ -128,7 +128,7 @@ declare const ListItem: ExtendButtonBase<
        * If `true`, the list item is a button (using `ButtonBase`). Props intended
        * for `ButtonBase` can then be applied to `ListItem`.
        * @default false
-       * @deprecated checkout `ListItemButton` instead
+       * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
        *
        */
       button: true;
@@ -143,7 +143,7 @@ declare const ListItem: ExtendButtonBase<
          * If `true`, the list item is a button (using `ButtonBase`). Props intended
          * for `ButtonBase` can then be applied to `ListItem`.
          * @default false
-         * @deprecated checkout `ListItemButton` instead
+         * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
          */
         button?: false;
       },

packages/material-ui/src/ListItem/ListItem.js

@@ -329,14 +329,14 @@ ListItem.propTypes /* remove-proptypes */ = {
    * If `true`, the list item is focused during the first mount.
    * Focus will also be triggered if the value changes from false to true.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   autoFocus: PropTypes.bool,
   /**
    * If `true`, the list item is a button (using `ButtonBase`). Props intended
    * for `ButtonBase` can then be applied to `ListItem`.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   button: PropTypes.bool,
   /**
@@ -414,7 +414,7 @@ ListItem.propTypes /* remove-proptypes */ = {
   /**
    * If `true`, the component is disabled.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   disabled: PropTypes.bool,
   /**
@@ -443,7 +443,7 @@ ListItem.propTypes /* remove-proptypes */ = {
   /**
    * Use to apply selected styling.
    * @default false
-   * @deprecated checkout `ListItemButton` instead
+   * @deprecated checkout [ListItemButton](/api/list-item-button/) instead
    */
   selected: PropTypes.bool,
   /**