[Alert] Introduce new component (#18702)

docs/pages/api/alert-title.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './alert-title.md';
+
+export default function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}

docs/pages/api/alert-title.md

@@ -0,0 +1,48 @@
+---
+filename: /packages/material-ui-lab/src/AlertTitle/AlertTitle.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# AlertTitle API
+
+<p class="description">The API documentation of the AlertTitle React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import AlertTitle from '@material-ui/lab/AlertTitle';
+// or
+import { AlertTitle } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | The content of the component. |
+| <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element (native element).
+
+## CSS
+
+- Style sheet name: `MuiAlertTitle`.
+- Style sheet details:
+
+- `root`
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/AlertTitle/AlertTitle.js) for more detail.
+

docs/pages/api/alert.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './alert.md';
+
+export default function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}

docs/pages/api/alert.md

@@ -0,0 +1,83 @@
+---
+filename: /packages/material-ui-lab/src/Alert/Alert.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# Alert API
+
+<p class="description">The API documentation of the Alert React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import Alert from '@material-ui/lab/Alert';
+// or
+import { Alert } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">action</span> | <span class="prop-type">node</span> |  | The action to display. It renders after the message, at the end of the alert. |
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | The content of the component. |
+| <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
+| <span class="prop-name">closeText</span> | <span class="prop-type">string</span> | <span class="prop-default">'Close'</span> | Override the default label for the *close popup* icon button.<br>For localization purposes, you can use the provided [translations](/guides/localization/). |
+| <span class="prop-name">color</span> | <span class="prop-type">'error'<br>&#124;&nbsp;'info'<br>&#124;&nbsp;'success'<br>&#124;&nbsp;'warning'</span> |  | The main color for the alert. Unless provided, the value is taken from the `severity` prop. |
+| <span class="prop-name">icon</span> | <span class="prop-type">node</span> |  | Override the icon displayed before the children. Unless provided, the icon is mapped to the value of the `severity` prop. |
+| <span class="prop-name">iconMapping</span> | <span class="prop-type">{ error?: node, info?: node, success?: node, warning?: node }</span> | <span class="prop-default">{  success: &lt;SuccessOutlinedIcon fontSize="inherit" />,  warning: &lt;ReportProblemOutlinedIcon fontSize="inherit" />,  error: &lt;ErrorOutlineIcon fontSize="inherit" />,  info: &lt;InfoOutlinedIcon fontSize="inherit" />,}</span> | The component maps the `severity` prop to a range of different icons, for instance success to `<SuccessOutlined>`. If you wish to change this mapping, you can provide your own. Alternatively, you can use the `icon` prop to override the icon displayed. |
+| <span class="prop-name">onClose</span> | <span class="prop-type">func</span> |  | Callback fired when the component requests to be closed. When provided and no `action` prop is set, a close icon button is displayed that triggers the callback when clicked.<br><br>**Signature:**<br>`function(event: object) => void`<br>*event:* The event source of the callback. |
+| <span class="prop-name">role</span> | <span class="prop-type">string</span> | <span class="prop-default">'alert'</span> | The ARIA role attribute of the element. |
+| <span class="prop-name">severity</span> | <span class="prop-type">'error'<br>&#124;&nbsp;'info'<br>&#124;&nbsp;'success'<br>&#124;&nbsp;'warning'</span> | <span class="prop-default">'success'</span> | The severity of the alert. This defines the color and icon used. |
+| <span class="prop-name">variant</span> | <span class="prop-type">'filled'<br>&#124;&nbsp;'outlined'<br>&#124;&nbsp;'standard'</span> | <span class="prop-default">'standard'</span> | The variant to use. |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element ([Paper](/api/paper/)).
+
+## CSS
+
+- Style sheet name: `MuiAlert`.
+- Style sheet details:
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.MuiAlert-root</span> | Styles applied to the root element.
+| <span class="prop-name">standardSuccess</span> | <span class="prop-name">.MuiAlert-standardSuccess</span> | Styles applied to the root element if `variant="standard"` and `color="success"`.
+| <span class="prop-name">standardInfo</span> | <span class="prop-name">.MuiAlert-standardInfo</span> | Styles applied to the root element if `variant="standard"` and `color="info"`.
+| <span class="prop-name">standardWarning</span> | <span class="prop-name">.MuiAlert-standardWarning</span> | Styles applied to the root element if `variant="standard"` and `color="warning"`.
+| <span class="prop-name">standardError</span> | <span class="prop-name">.MuiAlert-standardError</span> | Styles applied to the root element if `variant="standard"` and `color="error"`.
+| <span class="prop-name">outlinedSuccess</span> | <span class="prop-name">.MuiAlert-outlinedSuccess</span> | Styles applied to the root element if `variant="outlined"` and `color="success"`.
+| <span class="prop-name">outlinedInfo</span> | <span class="prop-name">.MuiAlert-outlinedInfo</span> | Styles applied to the root element if `variant="outlined"` and `color="info"`.
+| <span class="prop-name">outlinedWarning</span> | <span class="prop-name">.MuiAlert-outlinedWarning</span> | Styles applied to the root element if `variant="outlined"` and `color="warning"`.
+| <span class="prop-name">outlinedError</span> | <span class="prop-name">.MuiAlert-outlinedError</span> | Styles applied to the root element if `variant="outlined"` and `color="error"`.
+| <span class="prop-name">filledSuccess</span> | <span class="prop-name">.MuiAlert-filledSuccess</span> | Styles applied to the root element if `variant="filled"` and `color="success"`.
+| <span class="prop-name">filledInfo</span> | <span class="prop-name">.MuiAlert-filledInfo</span> | Styles applied to the root element if `variant="filled"` and `color="info"`.
+| <span class="prop-name">filledWarning</span> | <span class="prop-name">.MuiAlert-filledWarning</span> | Styles applied to the root element if `variant="filled"` and `color="warning"`.
+| <span class="prop-name">filledError</span> | <span class="prop-name">.MuiAlert-filledError</span> | Styles applied to the root element if `variant="filled"` and `color="error"`.
+| <span class="prop-name">icon</span> | <span class="prop-name">.MuiAlert-icon</span> | Styles applied to the icon wrapper element.
+| <span class="prop-name">message</span> | <span class="prop-name">.MuiAlert-message</span> | Styles applied to the message wrapper element.
+| <span class="prop-name">action</span> | <span class="prop-name">.MuiAlert-action</span> | Styles applied to the action wrapper element if `action` is provided.
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/Alert/Alert.js) for more detail.
+
+## Inheritance
+
+The props of the [Paper](/api/paper/) component are also available.
+You can take advantage of this behavior to [target nested components](/guides/api/#spread).
+
+## Demos
+
+- [Alert](/components/alert/)
+

docs/pages/api/snackbar-content.md

@@ -24,10 +24,10 @@ You can learn more about the difference by [reading this guide](/guides/minimizi
 
 | Name | Type | Default | Description |
 |:-----|:-----|:--------|:------------|
-| <span class="prop-name">action</span> | <span class="prop-type">node</span> |  | The action to display. |
+| <span class="prop-name">action</span> | <span class="prop-type">node</span> |  | The action to display. It renders after the message, at the end of the snackbar. |
 | <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
 | <span class="prop-name">message</span> | <span class="prop-type">node</span> |  | The message to display. |
-| <span class="prop-name">role</span> | <span class="prop-type">'alert'<br>&#124;&nbsp;'alertdialog'</span> | <span class="prop-default">'alert'</span> | The role of the SnackbarContent. If the Snackbar requires focus to be closed, the `alertdialog` role should be used instead. |
+| <span class="prop-name">role</span> | <span class="prop-type">string</span> | <span class="prop-default">'alert'</span> | The ARIA role attribute of the element. |
 
 The `ref` is forwarded to the root element.
 

docs/pages/api/snackbar.md

@@ -24,7 +24,7 @@ You can learn more about the difference by [reading this guide](/guides/minimizi
 
 | Name | Type | Default | Description |
 |:-----|:-----|:--------|:------------|
-| <span class="prop-name">action</span> | <span class="prop-type">node</span> |  | The action to display. |
+| <span class="prop-name">action</span> | <span class="prop-type">node</span> |  | The action to display. It renders after the message, at the end of the snackbar. |
 | <span class="prop-name">anchorOrigin</span> | <span class="prop-type">{ horizontal: 'left'<br>&#124;&nbsp;'center'<br>&#124;&nbsp;'right', vertical: 'top'<br>&#124;&nbsp;'bottom' }</span> | <span class="prop-default">{ vertical: 'bottom', horizontal: 'center' }</span> | The anchor of the `Snackbar`. |
 | <span class="prop-name">autoHideDuration</span> | <span class="prop-type">number</span> |  | The number of milliseconds to wait before automatically calling the `onClose` function. `onClose` should then set the state of the `open` prop to hide the Snackbar. This behavior is disabled by default with the `null` value. |
 | <span class="prop-name">children</span> | <span class="prop-type">element</span> |  | Replace the `SnackbarContent` component. |

docs/pages/api/typography.md

@@ -34,7 +34,7 @@ You can learn more about the difference by [reading this guide](/guides/minimizi
 | <span class="prop-name">noWrap</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the text will not wrap, but instead will truncate with a text overflow ellipsis.<br>Note that text overflow can only happen with block or inline-block level elements (the element needs to have a width in order to overflow). |
 | <span class="prop-name">paragraph</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the text will have a bottom margin. |
 | <span class="prop-name">variant</span> | <span class="prop-type">'h1'<br>&#124;&nbsp;'h2'<br>&#124;&nbsp;'h3'<br>&#124;&nbsp;'h4'<br>&#124;&nbsp;'h5'<br>&#124;&nbsp;'h6'<br>&#124;&nbsp;'subtitle1'<br>&#124;&nbsp;'subtitle2'<br>&#124;&nbsp;'body1'<br>&#124;&nbsp;'body2'<br>&#124;&nbsp;'caption'<br>&#124;&nbsp;'button'<br>&#124;&nbsp;'overline'<br>&#124;&nbsp;'srOnly'<br>&#124;&nbsp;'inherit'</span> | <span class="prop-default">'body1'</span> | Applies the theme typography styles. |
-| <span class="prop-name">variantMapping</span> | <span class="prop-type">object</span> | <span class="prop-default">{  h1: 'h1',  h2: 'h2',  h3: 'h3',  h4: 'h4',  h5: 'h5',  h6: 'h6',  subtitle1: 'h6',  subtitle2: 'h6',  body1: 'p',  body2: 'p',}</span> | We are empirically mapping the variant prop to a range of different DOM element types. For instance, subtitle1 to `<h6>`. If you wish to change that mapping, you can provide your own. Alternatively, you can use the `component` prop. |
+| <span class="prop-name">variantMapping</span> | <span class="prop-type">object</span> | <span class="prop-default">{  h1: 'h1',  h2: 'h2',  h3: 'h3',  h4: 'h4',  h5: 'h5',  h6: 'h6',  subtitle1: 'h6',  subtitle2: 'h6',  body1: 'p',  body2: 'p',}</span> | The component maps the variant prop to a range of different DOM element types. For instance, subtitle1 to `<h6>`. If you wish to change that mapping, you can provide your own. Alternatively, you can use the `component` prop. |
 
 The `ref` is forwarded to the root element.
 

docs/pages/components/alert.js

@@ -0,0 +1,14 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+
+const req = require.context('docs/src/pages/components/alert', false, /\.(md|js|tsx)$/);
+const reqSource = require.context(
+  '!raw-loader!../../src/pages/components/alert',
+  false,
+  /\.(js|tsx)$/,
+);
+const reqPrefix = 'pages/components/alert';
+
+export default function Page() {
+  return <MarkdownDocs req={req} reqSource={reqSource} reqPrefix={reqPrefix} />;
+}

docs/src/pages.js

@@ -114,6 +114,7 @@ const pages = [
         subheader: '/components/lab',
         children: [
           { pathname: '/components/about-the-lab' },
+          { pathname: '/components/alert' },
           { pathname: '/components/autocomplete' },
           { pathname: '/components/rating' },
           { pathname: '/components/skeleton' },

docs/src/pages/components/alert/ActionAlerts.js

@@ -0,0 +1,32 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { Alert } from '@material-ui/lab';
+import Button from '@material-ui/core/Button';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    width: '100%',
+    '& > * + *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function ActionAlerts() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Alert onClose={() => {}}>This is a success alert — check it out!</Alert>
+      <Alert
+        action={
+          <Button color="inherit" size="small">
+            UNDO
+          </Button>
+        }
+      >
+        This is a success alert — check it out!
+      </Alert>
+    </div>
+  );
+}

docs/src/pages/components/alert/ActionAlerts.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import { Alert } from '@material-ui/lab';
+import Button from '@material-ui/core/Button';
+
+const useStyles = makeStyles((theme: Theme) =>
+  createStyles({
+    root: {
+      width: '100%',
+      '& > * + *': {
+        marginTop: theme.spacing(2),
+      },
+    },
+  }),
+);
+
+export default function ActionAlerts() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Alert onClose={() => {}}>This is a success alert — check it out!</Alert>
+      <Alert
+        action={
+          <Button color="inherit" size="small">
+            UNDO
+          </Button>
+        }
+      >
+        This is a success alert — check it out!
+      </Alert>
+    </div>
+  );
+}

docs/src/pages/components/alert/ColorAlerts.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { Alert } from '@material-ui/lab';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    width: '100%',
+    '& > * + *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function ColorAlerts() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Alert severity="success" color="info">
+        This is a success alert — check it out!
+      </Alert>
+    </div>
+  );
+}

docs/src/pages/components/alert/ColorAlerts.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import { Alert } from '@material-ui/lab';
+
+const useStyles = makeStyles((theme: Theme) =>
+  createStyles({
+    root: {
+      width: '100%',
+      '& > * + *': {
+        marginTop: theme.spacing(2),
+      },
+    },
+  }),
+);
+
+export default function ColorAlerts() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Alert severity="success" color="info">
+        This is a success alert — check it out!
+      </Alert>
+    </div>
+  );
+}

docs/src/pages/components/alert/DescriptionAlerts.js

@@ -0,0 +1,37 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { Alert, AlertTitle } from '@material-ui/lab';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    width: '100%',
+    '& > * + *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function DescriptionAlerts() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Alert severity="error">
+        <AlertTitle>Error</AlertTitle>
+        This is an error alert — check it out!
+      </Alert>
+      <Alert severity="warning">
+        <AlertTitle>Warning</AlertTitle>
+        This is a warning alert — check it out!
+      </Alert>
+      <Alert severity="info">
+        <AlertTitle>Info</AlertTitle>
+        This is an info alert — check it out!
+      </Alert>
+      <Alert severity="success">
+        <AlertTitle>Success</AlertTitle>
+        This is a success alert — check it out!
+      </Alert>
+    </div>
+  );
+}