[docs] Further template the CSS API descriptions

docs/scripts/buildApi.ts

@@ -30,8 +30,9 @@ import getStylesCreator from '@material-ui/styles/getStylesCreator';
 import { createMuiTheme } from '@material-ui/core/styles';
 import { getLineFeed, getUnstyledFilename } from './helpers';
 
-// Only run for ButtonBase
+// Only run for the named component
 const TEST = false;
+// const TEST = 'Accordion';
 
 const DEMO_IGNORE = LANGUAGES_IN_PROGRESS.map((language) => `-${language}.md`);
 
@@ -800,17 +801,27 @@ async function annotateClassesDefinition(context: {
  * Substitute CSS class description conditions with placeholder
  */
 function extractClassConditions(descriptions: any) {
-  const classConditions: { [key: string]: { description: string; conditions?: string } } = {};
-  const stylesRegex = /(if |unless )(`.*)./;
+  const classConditions: {
+    [key: string]: { description: string; conditions?: string; nodeName?: string };
+  } = {};
+  const stylesRegex = /(Styles|Pseudo-class) applied to (.*?)(( if | unless | when |, ){1}(.*))?\./;
 
   Object.entries(descriptions).forEach(([className, classDescription]: any) => {
     if (className) {
       const conditions = classDescription.match(stylesRegex);
+      const applied =
+        conditions && conditions[1] === 'Styles' ? '{{stylesApplied}}' : '{{pseudoClassApplied}}';
 
-      if (conditions) {
+      if (conditions && conditions[5]) {
         classConditions[className] = {
-          description: classDescription.replace(stylesRegex, '$1{{conditions}}.'),
-          conditions: conditions[2].replace(/`(.*?)`/g, '<code>$1</code>'),
+          description: classDescription.replace(stylesRegex, `${applied}$4{{conditions}}.`),
+          nodeName: conditions[2],
+          conditions: conditions[5].replace(/`(.*?)`/g, '<code>$1</code>'),
+        };
+      } else if (conditions && conditions[2]) {
+        classConditions[className] = {
+          description: classDescription.replace(stylesRegex, `${applied}$4`),
+          nodeName: conditions[2],
         };
       } else {
         classConditions[className] = { description: classDescription };
@@ -880,7 +891,7 @@ async function buildDocs(options: {
   const component = require(componentObject.filename);
   const name = path.parse(componentObject.filename).name;
 
-  if (TEST && name !== 'ButtonBase') {
+  if (TEST && name !== TEST) {
     return;
   }
 

docs/src/modules/components/ApiPage.js

@@ -99,10 +99,11 @@ function ClassesTable(props) {
               dangerouslySetInnerHTML={{
                 __html:
                   classDescriptions[className] &&
-                  classDescriptions[className].description.replace(
-                    /{{conditions}}/,
-                    classDescriptions[className].conditions,
-                  ),
+                  classDescriptions[className].description
+                    .replace(/{{stylesApplied}}/, t('api-docs.stylesApplied'))
+                    .replace(/{{pseudoClassApplied}}/, t('api-docs.pseudoClassApplied'))
+                    .replace(/{{conditions}}/, classDescriptions[className].conditions)
+                    .replace(/{{nodeName}}/, classDescriptions[className].nodeName),
               }}
             />
           </tr>

docs/translations/api-docs/accordion-actions/accordion-actions.json

@@ -6,9 +6,10 @@
     "disableSpacing": "If <code>true</code>, the actions do not have additional margin."
   },
   "classDescriptions": {
-    "root": { "description": "Styles applied to the root element." },
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" },
     "spacing": {
-      "description": "Styles applied to the root element unless {{conditions}}.",
+      "description": "{{stylesApplied}} unless {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>disableSpacing={true}</code>"
     }
   }

docs/translations/api-docs/accordion-details/accordion-details.json

@@ -4,5 +4,7 @@
     "children": "The content of the component.",
     "classes": "Override or extend the styles applied to the component. See <a href=\"#css\">CSS API</a> below for more details."
   },
-  "classDescriptions": { "root": { "description": "Styles applied to the root element." } }
+  "classDescriptions": {
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" }
+  }
 }

docs/translations/api-docs/accordion-summary/accordion-summary.json

@@ -7,19 +7,26 @@
     "focusVisibleClassName": "This prop can help identify which element has keyboard focus. The class name will be applied when the element gains the focus through keyboard interaction. It&#39;s a polyfill for the <a href=\"https://drafts.csswg.org/selectors-4/#the-focus-visible-pseudo\">CSS :focus-visible selector</a>. The rationale for using this feature <a href=\"https://github.com/WICG/focus-visible/blob/master/explainer.md\">is explained here</a>. A <a href=\"https://github.com/WICG/focus-visible\">polyfill can be used</a> to apply a <code>focus-visible</code> class to other components if needed."
   },
   "classDescriptions": {
-    "root": { "description": "Styles applied to the root element." },
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" },
     "expanded": {
-      "description": "Pseudo-class applied to the root element, children wrapper element and `IconButton` component if {{conditions}}.",
-      "conditions": "<code>expanded={true}</code>"
+      "description": "{{pseudoClassApplied}}, {{conditions}}.",
+      "nodeName": "the root element",
+      "conditions": "children wrapper element and <code>IconButton</code> component if <code>expanded={true}</code>"
     },
     "focusVisible": {
-      "description": "Pseudo-class applied to the ButtonBase root element if the button is keyboard focused."
+      "description": "{{pseudoClassApplied}} if {{conditions}}.",
+      "nodeName": "the ButtonBase root element",
+      "conditions": "the button is keyboard focused"
     },
     "disabled": {
-      "description": "Pseudo-class applied to the root element if {{conditions}}.",
+      "description": "{{pseudoClassApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>disabled={true}</code>"
     },
-    "content": { "description": "Styles applied to the children wrapper element." },
-    "expandIconWrapper": { "description": "Styles applied to the `expandIcon`'s wrapper element." }
+    "content": { "description": "{{stylesApplied}}", "nodeName": "the children wrapper element" },
+    "expandIconWrapper": {
+      "description": "{{stylesApplied}}",
+      "nodeName": "the `expandIcon`'s wrapper element"
+    }
   }
 }

docs/translations/api-docs/accordion/accordion.json

@@ -12,21 +12,26 @@
     "TransitionProps": "Props applied to the transition element. By default, the element is based on this <a href=\"http://reactcommunity.org/react-transition-group/transition\"><code>Transition</code></a> component."
   },
   "classDescriptions": {
-    "root": { "description": "Styles applied to the root element." },
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" },
     "rounded": {
-      "description": "Styles applied to the root element unless {{conditions}}.",
+      "description": "{{stylesApplied}} unless {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>square={true}</code>"
     },
     "expanded": {
-      "description": "Pseudo-class applied to the root element if {{conditions}}.",
+      "description": "{{pseudoClassApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>expanded={true}</code>"
     },
     "disabled": {
-      "description": "Pseudo-class applied to the root element if {{conditions}}.",
+      "description": "{{pseudoClassApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>disabled={true}</code>"
     },
     "region": {
-      "description": "Styles applied to the region element, the container of the children."
+      "description": "{{stylesApplied}}, {{conditions}}.",
+      "nodeName": "the region element",
+      "conditions": "the container of the children"
     }
   }
 }

docs/translations/api-docs/alert-title/alert-title.json

@@ -4,5 +4,7 @@
     "children": "The content of the component.",
     "classes": "Override or extend the styles applied to the component. See <a href=\"#css\">CSS API</a> below for more details."
   },
-  "classDescriptions": { "root": { "description": "Styles applied to the root element." } }
+  "classDescriptions": {
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" }
+  }
 }

docs/translations/api-docs/alert/alert.json

@@ -14,71 +14,87 @@
     "variant": "The variant to use."
   },
   "classDescriptions": {
-    "root": { "description": "Styles applied to the root element." },
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" },
     "filled": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"filled\"</code>"
     },
     "outlined": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"outlined\"</code>"
     },
     "standard": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"standard\"</code>"
     },
     "standardSuccess": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"standard\"</code> and <code>color=\"success\"</code>"
     },
     "standardInfo": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"standard\"</code> and <code>color=\"info\"</code>"
     },
     "standardWarning": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"standard\"</code> and <code>color=\"warning\"</code>"
     },
     "standardError": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"standard\"</code> and <code>color=\"error\"</code>"
     },
     "outlinedSuccess": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"outlined\"</code> and <code>color=\"success\"</code>"
     },
     "outlinedInfo": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"outlined\"</code> and <code>color=\"info\"</code>"
     },
     "outlinedWarning": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"outlined\"</code> and <code>color=\"warning\"</code>"
     },
     "outlinedError": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"outlined\"</code> and <code>color=\"error\"</code>"
     },
     "filledSuccess": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"filled\"</code> and <code>color=\"success\"</code>"
     },
     "filledInfo": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"filled\"</code> and <code>color=\"info\"</code>"
     },
     "filledWarning": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"filled\"</code> and <code>color=\"warning\"</code>"
     },
     "filledError": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>variant=\"filled\"</code> and <code>color=\"error\"</code>"
     },
-    "icon": { "description": "Styles applied to the icon wrapper element." },
-    "message": { "description": "Styles applied to the message wrapper element." },
+    "icon": { "description": "{{stylesApplied}}", "nodeName": "the icon wrapper element" },
+    "message": { "description": "{{stylesApplied}}", "nodeName": "the message wrapper element" },
     "action": {
-      "description": "Styles applied to the action wrapper element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the action wrapper element",
       "conditions": "<code>action</code> is provided"
     }
   }

docs/translations/api-docs/app-bar/app-bar.json

@@ -7,45 +7,55 @@
     "position": "The positioning type. The behavior of the different options is described <a href=\"https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning\">in the MDN web docs</a>. Note: <code>sticky</code> is not universally supported and will fall back to <code>static</code> when unavailable."
   },
   "classDescriptions": {
-    "root": { "description": "Styles applied to the root element." },
+    "root": { "description": "{{stylesApplied}}", "nodeName": "the root element" },
     "positionFixed": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>position=\"fixed\"</code>"
     },
     "positionAbsolute": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>position=\"absolute\"</code>"
     },
     "positionSticky": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>position=\"sticky\"</code>"
     },
     "positionStatic": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>position=\"static\"</code>"
     },
     "positionRelative": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>position=\"relative\"</code>"
     },
     "colorDefault": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>color=\"default\"</code>"
     },
     "colorPrimary": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>color=\"primary\"</code>"
     },
     "colorSecondary": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>color=\"secondary\"</code>"
     },
     "colorInherit": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>color=\"inherit\"</code>"
     },
     "colorTransparent": {
-      "description": "Styles applied to the root element if {{conditions}}.",
+      "description": "{{stylesApplied}} if {{conditions}}.",
+      "nodeName": "the root element",
       "conditions": "<code>color=\"transparent\"</code>"
     }
   }