[docs] Move the demo higher in the API TOC (#35202)

Signed-off-by: Olivier Tassinari <olivier.tassinari@gmail.com>
Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>

docs/src/modules/components/ApiPage.js

@@ -167,11 +167,11 @@ ClassesTable.propTypes = {
 
 function getTranslatedHeader(t, header) {
   const translations = {
+    demos: t('api-docs.demos'),
     import: t('api-docs.import'),
     'component-name': t('api-docs.componentName'),
     props: t('api-docs.props'),
     inheritance: t('api-docs.inheritance'),
-    demos: t('api-docs.demos'),
     css: 'CSS',
   };
 
@@ -254,12 +254,12 @@ export default function ApiPage(props) {
   }
 
   const toc = [
+    createTocEntry('demos'),
     createTocEntry('import'),
     ...componentDescriptionToc,
     componentStyles.name && createTocEntry('component-name'),
     createTocEntry('props'),
     componentStyles.classes.length > 0 && createTocEntry('css'),
-    createTocEntry('demos'),
   ].filter(Boolean);
 
   // The `ref` is forwarded to the root element.
@@ -305,6 +305,16 @@ export default function ApiPage(props) {
           {description}
           {disableAd ? null : <Ad />}
         </Typography>
+        <Heading hash="demos" />
+        <div className="MuiCallout-root MuiCallout-info">
+          <p
+            dangerouslySetInnerHTML={{
+              __html:
+                'For examples and details on the usage of this React component, visit the component demo pages:',
+            }}
+          />
+          <span dangerouslySetInnerHTML={{ __html: demos }} />
+        </div>
         <Heading hash="import" />
         <HighlightedCode
           code={`
@@ -379,8 +389,6 @@ import { ${componentName} } from '${source}';`}
             />
           </React.Fragment>
         ) : null}
-        <Heading hash="demos" />
-        <span dangerouslySetInnerHTML={{ __html: demos }} />
       </MarkdownElement>
       <svg style={{ display: 'none' }} xmlns="http://www.w3.org/2000/svg">
         <symbol id="anchor-link-icon" viewBox="0 0 16 16">

docs/translations/translations.json

@@ -17,7 +17,7 @@
     "nativeElement": "native",
     "overrideStyles": "You can override the style of the component using one of these customization options:\n",
     "overrideStylesStyledComponent": "<ul>\n<li>With a <a href=\"/material-ui/guides/interoperability/#global-css\">global class name</a>.</li>\n<li>With a rule name as part of the component's <a href=\"/material-ui/customization/theme-components/#global-style-overrides\"><code>styleOverrides</code> property</a> in a custom theme.</li>\n</ul>",
-    "pageDescription": "API documentation for the React {{name}} component. Learn about the available props and the CSS API.",
+    "pageDescription": "API reference docs for the React {{name}} component. Learn about the props, CSS, and other APIs of this exported module.",
     "props": "Props",
     "refNotHeld": "The component cannot hold a ref.",
     "refRootElement": "The <code>ref</code> is forwarded to the root element.",