[docs-infra] Allow to link slots to their dedicated section

docs/pages/base-ui/api/button.json

@@ -26,7 +26,8 @@
       "name": "root",
       "description": "The component that renders the root.",
       "default": "props.href || props.to ? 'a' : 'button'",
-      "class": "base-Button-root"
+      "class": "base-Button-root",
+      "tutorial": "https://mui.com/sdlkfj/sdlkfjls"
     }
   ],
   "classes": [

docs/src/modules/components/ApiPage/list/SlotsList.tsx

@@ -9,6 +9,7 @@ import { useTranslate } from '@mui/docs/i18n';
 import ExpandableApiItem, {
   ApiItemContaier,
 } from 'docs/src/modules/components/ApiPage/list/ExpandableApiItem';
+import { Link } from '@mui/docs/Link';
 
 const StyledApiItem = styled(ExpandableApiItem)(
   ({ theme }) => ({
@@ -25,6 +26,11 @@ const StyledApiItem = styled(ExpandableApiItem)(
       fontFamily: theme.typography.fontFamilyCode,
       fontWeight: theme.typography.fontWeightRegular,
     },
+    '& .tutorial-slot-value': {
+      ...theme.typography.caption,
+      fontFamily: theme.typography.fontFamilyCode,
+      fontWeight: theme.typography.fontWeightRegular,
+    },
     '& .global-class-value': {
       ...theme.typography.caption,
       fontFamily: theme.typography.fontFamilyCode,
@@ -53,6 +59,7 @@ export type SlotsFormatedParams = {
   className: string;
   componentName: string;
   description?: string;
+  tutorial?: string;
   name: string;
   defaultValue?: string;
 };
@@ -69,7 +76,7 @@ export default function SlotsList(props: SlotsListProps) {
   return (
     <ApiItemContaier className="MuiApi-slot-list">
       {slots.map((params) => {
-        const { description, className, name, defaultValue, componentName } = params;
+        const { description, className, name, defaultValue, componentName, tutorial } = params;
 
         const isExtendable = description || defaultValue || className;
 
@@ -105,6 +112,11 @@ export default function SlotsList(props: SlotsListProps) {
                 <code className="default-slot-value">{defaultValue}</code>
               </p>
             )}
+            {tutorial && (
+              <p className="slot-default-element">
+                {t('api-docs.tutorial-link.see')}<Link href={tutorial}>{t('api-docs.tutorial-link.docs-section')}</Link>
+              </p>
+            )}
           </StyledApiItem>
         );
       })}

docs/src/modules/components/ApiPage/sections/SlotsSection.tsx

@@ -11,7 +11,7 @@ import SlotsList from 'docs/src/modules/components/ApiPage/list/SlotsList';
 import SlotsTable from 'docs/src/modules/components/ApiPage/table/SlotsTable';
 
 export type SlotsSectionProps = {
-  componentSlots: { class: string; name: string; default: string }[];
+  componentSlots: { class: string; name: string; default: string; tutorial?: string }[];
   slotDescriptions: { [key: string]: string };
   componentName: string;
   title?: string;
@@ -42,15 +42,18 @@ export default function SlotsSection(props: SlotsSectionProps) {
     return null;
   }
 
-  const formatedSlots = componentSlots?.map(({ class: className, name, default: defaultValue }) => {
-    return {
-      description: slotDescriptions[name],
-      className,
-      name,
-      defaultValue,
-      componentName,
-    };
-  });
+  const formatedSlots = componentSlots?.map(
+    ({ class: className, name, default: defaultValue, tutorial }) => {
+      return {
+        description: slotDescriptions[name],
+        tutorial,
+        className,
+        name,
+        defaultValue,
+        componentName,
+      };
+    },
+  );
 
   return (
     <React.Fragment>

docs/src/modules/components/ApiPage/table/SlotsTable.tsx

@@ -6,6 +6,7 @@ import {
   brandingDarkTheme as darkTheme,
   brandingLightTheme as lightTheme,
 } from '@mui/docs/branding';
+import { Link } from '@mui/docs/Link';
 import { SlotsFormatedParams, getHash } from 'docs/src/modules/components/ApiPage/list/SlotsList';
 import StyledTableContainer from 'docs/src/modules/components/ApiPage/table/StyledTableContainer';
 
@@ -89,7 +90,7 @@ export default function SlotsTable(props: SlotsTableProps) {
         </thead>
         <tbody>
           {slots.map((params) => {
-            const { description, className, name, defaultValue, componentName } = params;
+            const { description, className, name, defaultValue, componentName, tutorial } = params;
 
             return (
               <tr key={className} id={getHash({ componentName, className })}>
@@ -106,6 +107,15 @@ export default function SlotsTable(props: SlotsTableProps) {
                       __html: description || '',
                     }}
                   />
+                  {tutorial && (
+                    <React.Fragment>
+                      <br />
+                      <span>
+                        {t('api-docs.tutorial-link.see')}
+                        <Link href={tutorial}>{t('api-docs.tutorial-link.docs-section')}</Link>
+                      </span>
+                    </React.Fragment>
+                  )}
                 </td>
               </tr>
             );

packages/api-docs-builder/utils/parseSlotsAndClasses.ts

@@ -18,6 +18,7 @@ export interface Slot {
   name: string;
   description: string;
   default?: string;
+  tutorial?: string;
 }
 
 /**
@@ -223,6 +224,7 @@ function extractSlots(
       description: getSymbolDescription(propertySymbol, project),
       default: tags.default?.text?.[0].text,
       class: slotClassDefinition?.className ?? null,
+      tutorial: tags.tutorial?.text?.[0].text,
     };
   });
 

packages/mui-base/src/Button/Button.types.ts

@@ -41,6 +41,7 @@ export interface ButtonSlots {
   /**
    * The component that renders the root.
    * @default props.href || props.to ? 'a' : 'button'
+   * @tutorial https://mui.com/sdlkfj/sdlkfjls
    */
   root?: React.ElementType;
 }

packages/mui-docs/src/translations/translations.json

@@ -61,6 +61,10 @@
       "joy-size": "To learn how to add custom sizes to the component, check out <a href='/joy-ui/customization/themed-components/#extend-sizes'>Themed components—Extend sizes</a>.",
       "joy-color": "To learn how to add your own colors, check out <a href='/joy-ui/customization/themed-components/#extend-colors'>Themed components—Extend colors</a>.",
       "joy-variant": "To learn how to add your own variants, check out <a href='/joy-ui/customization/themed-components/#extend-variants'>Themed components—Extend variants</a>."
+    },
+    "tutorial-link": {
+      "see": "See ",
+      "docs-section": "dedicated demos"
     }
   },
   "landingPageDescr": "A responsive landing page layout with common sections found in marketing pages.",