[docs] Revise and expand Joy UI "Alert" page (#34838)

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

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+import Alert from '@mui/joy/Alert';
+
+export default function AlertBasic() {
+  return (
+    <Box sx={{ width: '100%' }}>
+      <Alert>This is a basic Alert.</Alert>
+    </Box>
+  );
+}

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

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+import Alert from '@mui/joy/Alert';
+
+export default function AlertBasic() {
+  return (
+    <Box sx={{ width: '100%' }}>
+      <Alert>This is a basic Alert.</Alert>
+    </Box>
+  );
+}

docs/data/joy/components/alert/AlertBasic.tsx.preview

@@ -0,0 +1 @@
+<Alert>This is a basic Alert.</Alert>

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

@@ -20,7 +20,7 @@ export default function AlertColors() {
       <Box
         sx={{
           display: 'grid',
-          gridTemplateColumns: 'repeat(3, minmax(150px, 1fr))',
+          gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))',
           gap: 1,
         }}
       >

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

@@ -20,7 +20,7 @@ export default function AlertColors() {
       <Box
         sx={{
           display: 'grid',
-          gridTemplateColumns: 'repeat(3, minmax(150px, 1fr))',
+          gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))',
           gap: 1,
         }}
       >

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

@@ -5,9 +5,9 @@ import Alert from '@mui/joy/Alert';
 export default function AlertSizes() {
   return (
     <Box sx={{ display: 'flex', gap: 2, width: '100%', flexDirection: 'column' }}>
-      <Alert size="sm">This is an alert in the small size.</Alert>
-      <Alert size="md">This is an alert in the medium size.</Alert>
-      <Alert size="lg">This is an alert in the large size.</Alert>
+      <Alert size="sm">This is a small Alert.</Alert>
+      <Alert size="md">This is a medium Alert.</Alert>
+      <Alert size="lg">This is a large Alert.</Alert>
     </Box>
   );
 }

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

@@ -5,9 +5,9 @@ import Alert from '@mui/joy/Alert';
 export default function AlertSizes() {
   return (
     <Box sx={{ display: 'flex', gap: 2, width: '100%', flexDirection: 'column' }}>
-      <Alert size="sm">This is an alert in the small size.</Alert>
-      <Alert size="md">This is an alert in the medium size.</Alert>
-      <Alert size="lg">This is an alert in the large size.</Alert>
+      <Alert size="sm">This is a small Alert.</Alert>
+      <Alert size="md">This is a medium Alert.</Alert>
+      <Alert size="lg">This is a large Alert.</Alert>
     </Box>
   );
 }

docs/data/joy/components/alert/AlertSizes.tsx.preview

@@ -1,3 +1,3 @@
-<Alert size="sm">This is an alert in the small size.</Alert>
-<Alert size="md">This is an alert in the medium size.</Alert>
-<Alert size="lg">This is an alert in the large size.</Alert>
+<Alert size="sm">This is a small Alert.</Alert>
+<Alert size="md">This is a medium Alert.</Alert>
+<Alert size="lg">This is a large Alert.</Alert>

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

@@ -26,7 +26,7 @@ export default function AlertUsage() {
         },
       ]}
       renderDemo={(props) => (
-        <Alert {...props}>This is a Joy UI alert — check it out!</Alert>
+        <Alert {...props}>This is a Joy UI Alert — check it out!</Alert>
       )}
     />
   );

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

@@ -5,10 +5,10 @@ import Alert from '@mui/joy/Alert';
 export default function AlertVariants() {
   return (
     <Box sx={{ display: 'flex', gap: 2, width: '100%', flexDirection: 'column' }}>
-      <Alert variant="solid">This is an alert using the solid variant.</Alert>
-      <Alert variant="soft">This is an alert using the soft variant.</Alert>
-      <Alert variant="outlined">This is an alert using the outlined variant.</Alert>
-      <Alert variant="plain">This is an alert using the plain variant.</Alert>
+      <Alert variant="solid">This is an Alert using the solid variant.</Alert>
+      <Alert variant="soft">This is an Alert using the soft variant.</Alert>
+      <Alert variant="outlined">This is an Alert using the outlined variant.</Alert>
+      <Alert variant="plain">This is an Alert using the plain variant.</Alert>
     </Box>
   );
 }

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

@@ -5,10 +5,10 @@ import Alert from '@mui/joy/Alert';
 export default function AlertVariants() {
   return (
     <Box sx={{ display: 'flex', gap: 2, width: '100%', flexDirection: 'column' }}>
-      <Alert variant="solid">This is an alert using the solid variant.</Alert>
-      <Alert variant="soft">This is an alert using the soft variant.</Alert>
-      <Alert variant="outlined">This is an alert using the outlined variant.</Alert>
-      <Alert variant="plain">This is an alert using the plain variant.</Alert>
+      <Alert variant="solid">This is an Alert using the solid variant.</Alert>
+      <Alert variant="soft">This is an Alert using the soft variant.</Alert>
+      <Alert variant="outlined">This is an Alert using the outlined variant.</Alert>
+      <Alert variant="plain">This is an Alert using the plain variant.</Alert>
     </Box>
   );
 }

docs/data/joy/components/alert/AlertVariants.tsx.preview

@@ -1,4 +1,4 @@
-<Alert variant="solid">This is an alert using the solid variant.</Alert>
-<Alert variant="soft">This is an alert using the soft variant.</Alert>
-<Alert variant="outlined">This is an alert using the outlined variant.</Alert>
-<Alert variant="plain">This is an alert using the plain variant.</Alert>
+<Alert variant="solid">This is an Alert using the solid variant.</Alert>
+<Alert variant="soft">This is an Alert using the soft variant.</Alert>
+<Alert variant="outlined">This is an Alert using the outlined variant.</Alert>
+<Alert variant="plain">This is an Alert using the plain variant.</Alert>

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

@@ -40,7 +40,7 @@ export default function AlertVariousStates() {
               {title}
             </Typography>
             <Typography fontSize="sm" sx={{ opacity: 0.8 }}>
-              This is a {title} message.
+              This is a time-sensitive {title} Alert.
             </Typography>
           </div>
         </Alert>

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

@@ -44,7 +44,7 @@ export default function AlertVariousStates() {
               {title}
             </Typography>
             <Typography fontSize="sm" sx={{ opacity: 0.8 }}>
-              This is a {title} message.
+              This is a time-sensitive {title} Alert.
             </Typography>
           </div>
         </Alert>

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

@@ -7,15 +7,22 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/alert/
 
 # Alert
 
-<p class="description">An alert displays a short, important message in a way that attracts the user's attention without interrupting the user's task.</p>
+<p class="description">Alerts display brief messages for the user without interrupting their use of the app.</p>
 
 ## Introduction
 
+The Alert component can be used to provide important and potentially time-sensitive information in a way that does not interfere with the user's tasks. (Source: [ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/alert/).)
+
+:::warning
+Alerts should not be confused with alert _dialogs_ ([ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)), which _are_ intended to interrupt the user to obtain a response.
+Use the Joy UI [Modal](https://mui.com/joy-ui/react-modal/) if you need the behavior of a dialog.
+:::
+
 {{"demo": "AlertUsage.js", "hideToolbar": true}}
 
 {{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
 
-## Component
+## Usage
 
 After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
 
@@ -27,28 +34,60 @@ export default function MyApp() {
 }
 ```
 
+## 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
+
+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>`:
+
+```jsx
+<Alert component="span">Alert content</Alert>
+
+// renders as:
+<span role="alert" class="JoyAlert-root">
+  Alert content
+</span>
+```
+
+## Customization
+
 ### Variants
 
-The alert component supports the four global variants: `solid` (default), `soft`, `outlined` and `plain`.
+The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`.
 
 {{"demo": "AlertVariants.js"}}
 
 ### Colors
 
 Every palette included in the theme is available via the `color` prop.
-Play around combining different colors with different variants.
+The demo below shows how the values for the `color` prop are affected by the global variants:
 
 {{"demo": "AlertColors.js"}}
 
 ### Sizes
 
-The alert components comes with three sizes out of the box: `sm`, `md` (the default), and `lg`.
+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/or `endDecorator` props to insert actionable buttons or icon buttons on the Alert.
+Use the `startDecorator` and `endDecorator` props to append actions and icons to either side of the Alert:
 
 {{"demo": "AlertWithDecorators.js"}}
 
@@ -64,12 +103,11 @@ Use the `startDecorator` and/or `endDecorator` props to insert actionable button
 
 ## Accessibility
 
-Here are a few tips to make sure you have an accessible alert component:
-
-- When the component is dynamically displayed, the content is automatically announced by most screen readers.
-  At this time, screen readers do not inform users of alerts that are present when the page loads.
-
-- Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies such as screen readers.
-  Ensure that information denoted by the color is either obvious from the content itself (for example the visible text), or is included through alternative means, such as additional hidden text.
+Here are some factors to consider to ensure that your Alert is accessible:
 
-- Actions must have a tab index of 0 so that they can be reached by keyboard-only users.
+- Because alerts are not intended to interfere with the use of the app, your Alert component should _never_ affect the keyboard focus.
+- If an alert contains an action, that action must have a `tabindex` of `0` so it can be reached by keyboard-only users.
+- Essential alerts should not disappear automatically—[timed interactions](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-no-exceptions.html) can make your app inaccessible to users who need extra time to understand or locate the alert.
+- 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.