[material-ui][docs] Revise the Accordion page

docs/data/material/components/accordion/AccordionUsage.js

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import Accordion from '@mui/material/Accordion';
+import AccordionActions from '@mui/material/AccordionActions';
+import AccordionSummary from '@mui/material/AccordionSummary';
+import AccordionDetails from '@mui/material/AccordionDetails';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import Button from '@mui/material/Button';
+
+export default function AccordionUsage() {
+  return (
+    <div>
+      <Accordion>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel1-content"
+          id="panel1-header"
+        >
+          Accordion 1
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+      </Accordion>
+      <Accordion>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel2-content"
+          id="panel2-header"
+        >
+          Accordion 2
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+      </Accordion>
+      <Accordion expanded>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel3-content"
+          id="panel3-header"
+        >
+          Accordion Actions
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+        <AccordionActions>
+          <Button>Cancel</Button>
+          <Button>Agree</Button>
+        </AccordionActions>
+      </Accordion>
+    </div>
+  );
+}

docs/data/material/components/accordion/AccordionUsage.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import Accordion from '@mui/material/Accordion';
+import AccordionActions from '@mui/material/AccordionActions';
+import AccordionSummary from '@mui/material/AccordionSummary';
+import AccordionDetails from '@mui/material/AccordionDetails';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import Button from '@mui/material/Button';
+
+export default function AccordionUsage() {
+  return (
+    <div>
+      <Accordion>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel1-content"
+          id="panel1-header"
+        >
+          Accordion 1
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+      </Accordion>
+      <Accordion>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel2-content"
+          id="panel2-header"
+        >
+          Accordion 2
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+      </Accordion>
+      <Accordion expanded>
+        <AccordionSummary
+          expandIcon={<ExpandMoreIcon />}
+          aria-controls="panel3-content"
+          id="panel3-header"
+        >
+          Accordion Actions
+        </AccordionSummary>
+        <AccordionDetails>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+          malesuada lacus ex, sit amet blandit leo lobortis eget.
+        </AccordionDetails>
+        <AccordionActions>
+          <Button>Cancel</Button>
+          <Button>Agree</Button>
+        </AccordionActions>
+      </Accordion>
+    </div>
+  );
+}

docs/data/material/components/accordion/BasicAccordion.js → docs/data/material/components/accordion/DisabledAccordion.js

@@ -5,14 +5,14 @@ import AccordionDetails from '@mui/material/AccordionDetails';
 import Typography from '@mui/material/Typography';
 import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
 
-export default function BasicAccordion() {
+export default function DisabledAccordion() {
   return (
     <div>
       <Accordion>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel1a-content"
-          id="panel1a-header"
+          aria-controls="panel1-content"
+          id="panel1-header"
         >
           <Typography>Accordion 1</Typography>
         </AccordionSummary>
@@ -26,8 +26,8 @@ export default function BasicAccordion() {
       <Accordion>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel2a-content"
-          id="panel2a-header"
+          aria-controls="panel2-content"
+          id="panel2-header"
         >
           <Typography>Accordion 2</Typography>
         </AccordionSummary>
@@ -41,8 +41,8 @@ export default function BasicAccordion() {
       <Accordion disabled>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel3a-content"
-          id="panel3a-header"
+          aria-controls="panel3-content"
+          id="panel3-header"
         >
           <Typography>Disabled Accordion</Typography>
         </AccordionSummary>

docs/data/material/components/accordion/BasicAccordion.tsx → docs/data/material/components/accordion/DisabledAccordion.tsx

@@ -5,14 +5,14 @@ import AccordionDetails from '@mui/material/AccordionDetails';
 import Typography from '@mui/material/Typography';
 import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
 
-export default function BasicAccordion() {
+export default function DisabledAccordion() {
   return (
     <div>
       <Accordion>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel1a-content"
-          id="panel1a-header"
+          aria-controls="panel1-content"
+          id="panel1-header"
         >
           <Typography>Accordion 1</Typography>
         </AccordionSummary>
@@ -26,8 +26,8 @@ export default function BasicAccordion() {
       <Accordion>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel2a-content"
-          id="panel2a-header"
+          aria-controls="panel2-content"
+          id="panel2-header"
         >
           <Typography>Accordion 2</Typography>
         </AccordionSummary>
@@ -41,8 +41,8 @@ export default function BasicAccordion() {
       <Accordion disabled>
         <AccordionSummary
           expandIcon={<ExpandMoreIcon />}
-          aria-controls="panel3a-content"
-          id="panel3a-header"
+          aria-controls="panel3-content"
+          id="panel3-header"
         >
           <Typography>Disabled Accordion</Typography>
         </AccordionSummary>

docs/data/material/components/accordion/accordion.md

@@ -11,22 +11,37 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
 
 <p class="description">The accordion component allows the user to show and hide sections of related content on a page.</p>
 
-An accordion is a lightweight container that may either be used standalone, or be connected to a larger surface, such as a card.
-
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
+## Introduction
+
+The Material UI Accordion component includes several complementary utility components to handle various use cases:
+
+- Accordion: the wrapper for grouping related components.
+- Accordion Summary: the wrapper for the Accordion header, which expands or collapses the content when clicked.
+- Accordion Details: the wrapper for the Accordion content.
+- Accordion Actions: an optional wrapper that groups a set of buttons.
+
+{{"demo": "AccordionUsage.js", "bg": true}}
+
 :::info
 This component is no longer documented in the [Material Design guidelines](https://m2.material.io/), but Material UI will continue to support it.
 :::
 
-## Basic accordion
+## Basics
 
-{{"demo": "BasicAccordion.js", "bg": true}}
+```jsx
+import Accordion from '@mui/material/Accordion';
+import AccordionDetails from '@mui/material/AccordionDetails';
+import AccordionSummary from '@mui/material/AccordionSummary';
+```
 
-## Controlled accordion
+### Controlled Accordion
 
 The Accordion component can be controlled or uncontrolled.
 
+{{"demo": "ControlledAccordions.js", "bg": true}}
+
 :::info
 
 - A component is **controlled** when it's managed by its parent using props.
@@ -35,34 +50,61 @@ The Accordion component can be controlled or uncontrolled.
 Learn more about controlled and uncontrolled components in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
 :::
 
-{{"demo": "ControlledAccordions.js", "bg": true}}
+### Disabled item
+
+Use the disabled prop on the Accordion component to disable interaction and focus.
+
+{{"demo": "DisabledAccordion.js", "bg": true}}
 
 ## Customization
 
-Here is an example of customizing the component.
-You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/).
+### Only one expanded at a time
+
+Use the `expanded` prop with React's `useState` hook to allow only one Accordion item to be expanded at a time.
+The demo below also shows a bit of visual customziation.
 
 {{"demo": "CustomizedAccordions.js"}}
 
 ## Performance
 
-The content of Accordions is mounted by default even if the accordion is not expanded.
+The Accordion content is mounted by default even if it's not expanded.
 This default behavior has server-side rendering and SEO in mind.
-If you render expensive component trees inside your accordion details or simply render many
-accordions it might be a good idea to change this default behavior by enabling the
-`unmountOnExit` in `TransitionProps`:
+
+If you render the Accordion Details with a big component tree nested inside, or if you have many Accordions, you may want to change this behavior by setting `unmountOnExit` to `true` inside the `TransitionProps` prop to improve performance:
 
 ```jsx
 <Accordion TransitionProps={{ unmountOnExit: true }} />
 ```
 
-As with any performance optimization this is not a silver bullet.
-Be sure to identify bottlenecks first and then try out these optimization strategies.
-
 ## Accessibility
 
-(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+The [WAI-ARIA guidelines for accordions](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) recommend setting an `id` and `aria-controls`, which in this case would apply to the Accordion Summary component.
+The Accordion component then derives the necessary `aria-labelledby` and `id` from its content.
 
-For optimal accessibility we recommend setting `id` and `aria-controls` on the
-`AccordionSummary`. The `Accordion` will derive the necessary `aria-labelledby`
-and `id` for the content region of the accordion.
+```jsx
+<Accordion>
+  <AccordionSummary id="panel-header" aria-controls="panel-content">
+    Header
+  </AccordionSummary>
+  <AccordionDetails>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  </AccordionDetails>
+</Accordion>
+```
+
+## Anatomy
+
+The Accordion component is composed of a root `<div>` that houses interior elements like the Accordion Summary and other optional components (such as buttons or decorators).
+
+```jsx
+<div class="MuiAccordion-root">
+  <div class="MuiButtonBase-root MuiAccordionSummary-root" role="button" aria-expanded="">
+      <!-- Accordion header button goes here -->
+  </div>
+  <div class="MuiAccordion-region" role="region">
+    <div class="MuiAccordionDetails-root">
+      <!-- Accordion content goes here -->
+    </div>
+  </div>
+</div>
+```