[docs] Iterating on recent Joy UI Component page updates

docs/data/joy/components/alert/AlertColors.js

@@ -1,11 +1,12 @@
+import * as React from 'react';
 import Alert from '@mui/joy/Alert';
+import Stack from '@mui/joy/Stack';
 import Box from '@mui/joy/Box';
 import Radio from '@mui/joy/Radio';
 import RadioGroup from '@mui/joy/RadioGroup';
 import Sheet from '@mui/joy/Sheet';
 
 import Typography from '@mui/joy/Typography';
-import * as React from 'react';
 
 export default function AlertColors() {
   const [variant, setVariant] = React.useState('solid');
@@ -14,16 +15,11 @@ export default function AlertColors() {
       sx={{
         display: 'flex',
         alignItems: 'center',
-        gap: 3,
+        justifyContent: 'center',
+        width: '100%',
       }}
     >
-      <Box
-        sx={{
-          display: 'grid',
-          gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))',
-          gap: 1,
-        }}
-      >
+      <Stack spacing={1} sx={{ width: '100%', maxWidth: 400 }}>
         <Alert variant={variant} color="primary">
           Primary
         </Alert>
@@ -42,15 +38,8 @@ export default function AlertColors() {
         <Alert variant={variant} color="warning">
           Warning
         </Alert>
-      </Box>
-      <Sheet
-        sx={{
-          background: 'transparent',
-          pl: 4,
-          borderLeft: '1px solid',
-          borderColor: 'divider',
-        }}
-      >
+      </Stack>
+      <Sheet sx={{ pl: 4, ml: 3, borderLeft: '1px solid', borderColor: 'divider' }}>
         <Typography
           level="body2"
           fontWeight="xl"

docs/data/joy/components/alert/AlertColors.tsx

@@ -1,11 +1,12 @@
+import * as React from 'react';
 import Alert from '@mui/joy/Alert';
+import Stack from '@mui/joy/Stack';
 import Box from '@mui/joy/Box';
 import Radio from '@mui/joy/Radio';
 import RadioGroup from '@mui/joy/RadioGroup';
 import Sheet from '@mui/joy/Sheet';
 import { VariantProp } from '@mui/joy/styles';
 import Typography from '@mui/joy/Typography';
-import * as React from 'react';
 
 export default function AlertColors() {
   const [variant, setVariant] = React.useState<VariantProp>('solid');
@@ -14,16 +15,11 @@ export default function AlertColors() {
       sx={{
         display: 'flex',
         alignItems: 'center',
-        gap: 3,
+        justifyContent: 'center',
+        width: '100%',
       }}
     >
-      <Box
-        sx={{
-          display: 'grid',
-          gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))',
-          gap: 1,
-        }}
-      >
+      <Stack spacing={1} sx={{ width: '100%', maxWidth: 400 }}>
         <Alert variant={variant} color="primary">
           Primary
         </Alert>
@@ -42,15 +38,8 @@ export default function AlertColors() {
         <Alert variant={variant} color="warning">
           Warning
         </Alert>
-      </Box>
-      <Sheet
-        sx={{
-          background: 'transparent',
-          pl: 4,
-          borderLeft: '1px solid',
-          borderColor: 'divider',
-        }}
-      >
+      </Stack>
+      <Sheet sx={{ pl: 4, ml: 3, borderLeft: '1px solid', borderColor: 'divider' }}>
         <Typography
           level="body2"
           fontWeight="xl"

docs/data/joy/components/alert/alert.md

@@ -22,55 +22,34 @@ Use the Joy UI [Modal](https://mui.com/joy-ui/react-modal/) if you need the beha
 
 {{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
 
-## Usage
-
-After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
+## Basics
 
 ```jsx
 import Alert from '@mui/joy/Alert';
-
-export default function MyApp() {
-  return <Alert />;
-}
 ```
 
-## Basics
-
 The Alert component wraps around its content, and stretches to fill its enclosing container, as shown below:
 
 {{"demo": "AlertBasic.js"}}
 
-## Anatomy
-
-The Alert component is composed of a single root `<div>` element with its `role` set to `alert`:
-
-```html
-<div role="alert" class="JoyAlert-root">
-  This is how an Alert renders in the DOM.
-</div>
-```
-
-### Overriding the root slot
+## Customization
 
-Use the `component` prop to override the root slot with a custom element.
-For example, the following code snippet replaces the default `<div>` with a `<span>`:
+### Variants
 
-```jsx
-<Alert component="span">Alert content</Alert>
+The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`.
 
-// renders as:
-<span role="alert" class="JoyAlert-root">
-  Alert content
-</span>
-```
+{{"demo": "AlertVariants.js"}}
 
-## Customization
+:::success
+To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
+Note that you lose the global variants when you add custom variants.
+:::
 
-### Variants
+### Sizes
 
-The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`.
+The Alert component comes in three sizes: `sm`, `md` (default), and `lg`:
 
-{{"demo": "AlertVariants.js"}}
+{{"demo": "AlertSizes.js"}}
 
 ### Colors
 
@@ -79,12 +58,6 @@ The demo below shows how the values for the `color` prop are affected by the glo
 
 {{"demo": "AlertColors.js"}}
 
-### Sizes
-
-The Alert component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`:
-
-{{"demo": "AlertSizes.js"}}
-
 ### Decorators
 
 Use the `startDecorator` and `endDecorator` props to append actions and icons to either side of the Alert:
@@ -111,3 +84,13 @@ Here are some factors to consider to ensure that your Alert is accessible:
 - Alerts that occur too frequently can [inhibit the usability](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html) of your app.
 - Dynamically rendered alerts are announced by screen readers; alerts that are already present on the page when it loads are _not_ announced.
 - Color does not add meaning to the UI for users who require assistive technology. You must ensure that any information conveyed through color is also denoted in other ways, such as within the text of the alert itself, or with additional hidden text that's read by screen readers.
+
+## Anatomy
+
+The Alert component is composed of a single root `<div>` element with its `role` set to `alert`:
+
+```html
+<div role="alert" class="JoyAlert-root">
+  <!-- Alert contents -->
+</div>
+```

docs/data/joy/components/aspect-ratio/aspect-ratio.md

@@ -18,76 +18,31 @@ As of Q4 2022, compatibility is at 90%.
 Source: [Can I use…](https://caniuse.com/?search=aspect-ratio)
 :::
 
-## Usage
-
-After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
+## Basics
 
 ```jsx
 import AspectRatio from '@mui/joy/AspectRatio';
-
-export default function MyApp() {
-  return <AspectRatio />;
-}
 ```
 
-## Basics
-
 The Aspect Ratio component wraps around the content that it resizes.
 The element to be resized must be the first direct child.
 The default ratio is `16/9`.
 
 {{"demo": "BasicRatio.js"}}
 
-## Anatomy
-
-The Aspect Ratio component is composed of a root `<div>` with a content `<div>` nested inside; the child component is given a `data-first-child` attribute for styling purposes:
-
-```html
-<div class="JoyAspectRatio-root">
-  <div class="JoyAspectRatio-content">
-    <some-element data-first-child>
-      This is how an Aspect Ratio component renders in the DOM.
-    </some-element>
-  </div>
-</div>
-```
-
-### Overriding the root slot
-
-Use the `component` prop to override the root slot with a custom element.
-For example, the following code snippet replaces the default `<div>` with a `<section>`:
-
-```jsx
-<AspectRatio component="section" />
-```
-
-### Overriding interior slots
-
-Use the `components` prop to override any interior slots in addition to the root:
-
-<AspectRatio components={{ Content: 'article' }} />
-
-:::warning
-If the root element is customized with both the `component` and `components` props, then `component` will take precedence.
-:::
-
-Use the `componentsProps` prop to pass custom props to internal slots.
-The following code snippet applies a CSS class called `my-content` to the content slot:
-
-<AspectRatio componentsProps={{ content: { className: 'my-content' } }} />
-
-:::warning
-Note that `componentsProps` slot names are written in lowercase (root) while `components` slot names are capitalized (Root).
-:::
-
 ## Customization
 
 ### Variants
 
-The Aspect Ratio component supports the four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`.
+The Aspect Ratio component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`.
 
 {{"demo": "VariantsRatio.js"}}
 
+:::success
+To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
+Note that you lose the global variants when you add custom variants.
+:::
+
 ### Ratio
 
 Use the `ratio` prop to change the aspect ratio, following the pattern `height/width`.
@@ -120,13 +75,13 @@ This is useful when the Aspect Ratio component wraps dynamic-width content, as s
 
 {{"demo": "MinMaxRatio.js"}}
 
-### Usage inside a flex row
+## Usage inside a flex row
 
 When the Aspect Ratio component is a child of a flexbox `row` container, use `flex-basis` to set the ideal width of the content:
 
 {{"demo": "FlexRowRatio.js"}}
 
-### Usage with Next.js Image component
+## Usage with Next.js Image
 
 The Aspect Ratio component can be used with a [Next.js Image](https://nextjs.org/docs/basic-features/image-optimization) component as a child.
 The Image should always include the `layout="fill"` property—otherwise it requires `height` and `width` values, which would defeat the purpose of the Aspect Ratio component.
@@ -161,3 +116,17 @@ In designs like this, make sure to assign a `minWidth` value to prevent the Aspe
 This is a simple illustration of how to use Aspect Ratio with list components:
 
 {{"demo": "ListStackRatio.js"}}
+
+## Anatomy
+
+The Aspect Ratio component is composed of a root `<div>` with a content `<div>` nested inside; the child component is given a `data-first-child` attribute for styling purposes:
+
+```html
+<div class="JoyAspectRatio-root">
+  <div class="JoyAspectRatio-content">
+    <some-element data-first-child>
+      <!-- Aspect Ratio contents -->
+    </some-element>
+  </div>
+</div>
+```

docs/data/joy/components/avatar/AvatarVariants.js

@@ -5,8 +5,8 @@ import Box from '@mui/joy/Box';
 export default function AvatarVariants() {
   return (
     <Box sx={{ display: 'flex', gap: 2, alignItems: 'center' }}>
-      <Avatar variant="soft" />
       <Avatar variant="solid" />
+      <Avatar variant="soft" />
       <Avatar variant="outlined" />
       <Avatar variant="plain" />
     </Box>

docs/data/joy/components/avatar/AvatarVariants.tsx

@@ -5,8 +5,8 @@ import Box from '@mui/joy/Box';
 export default function AvatarVariants() {
   return (
     <Box sx={{ display: 'flex', gap: 2, alignItems: 'center' }}>
-      <Avatar variant="soft" />
       <Avatar variant="solid" />
+      <Avatar variant="soft" />
       <Avatar variant="outlined" />
       <Avatar variant="plain" />
     </Box>

docs/data/joy/components/avatar/AvatarVariants.tsx.preview

@@ -1,4 +1,4 @@
-<Avatar variant="soft" />
 <Avatar variant="solid" />
+<Avatar variant="soft" />
 <Avatar variant="outlined" />
 <Avatar variant="plain" />

docs/data/joy/components/avatar/BasicAvatar.js

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import Avatar from '@mui/joy/Avatar';
+
+export default function BasicAvatar() {
+  return <Avatar />;
+}

docs/data/joy/components/avatar/BasicAvatar.tsx.preview

@@ -0,0 +1 @@
+<Avatar />

docs/data/joy/components/avatar/BasicAvatars.js

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import Avatar from '@mui/joy/Avatar';
+import Box from '@mui/joy/Box';
+
+export default function BasicAvatars() {
+  return (
+    <Box sx={{ display: 'flex', gap: 2 }}>
+      <Avatar />
+      <Avatar>JG</Avatar>
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+    </Box>
+  );
+}

docs/data/joy/components/avatar/BasicAvatars.tsx

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import Avatar from '@mui/joy/Avatar';
+import Box from '@mui/joy/Box';
+
+export default function BasicAvatars() {
+  return (
+    <Box sx={{ display: 'flex', gap: 2 }}>
+      <Avatar />
+      <Avatar>JG</Avatar>
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+    </Box>
+  );
+}

docs/data/joy/components/avatar/BasicAvatars.tsx.preview

@@ -0,0 +1,3 @@
+<Avatar />
+<Avatar>JG</Avatar>
+<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />