@patternfly/react-core 4.241.3 → 4.242.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patternfly/react-core",
-  "version": "4.241.3",
+  "version": "4.242.0",
   "description": "This library provides a set of common React components for use with the PatternFly reference implementation.",
   "main": "dist/js/index.js",
   "module": "dist/esm/index.js",
@@ -70,5 +70,5 @@
     "react": "^16.8 || ^17 || ^18",
     "react-dom": "^16.8 || ^17 || ^18"
   },
-  "gitHead": "0a76fbdba0aabc4636f2e27a87c7bcc8b6e0939c"
+  "gitHead": "aacd4fd4e0c5b623fe98ddb5962efbb98c348465"
 }

package/src/components/Alert/examples/Alert.md

@@ -13,9 +13,20 @@ import DatabaseIcon from '@patternfly/react-icons/dist/esm/icons/database-icon';
 import ServerIcon from '@patternfly/react-icons/dist/esm/icons/server-icon';
 import LaptopIcon from '@patternfly/react-icons/dist/esm/icons/laptop-icon';
 
-## Examples
+## Examples 
+
+### Variant examples
+
+PatternFly supports several alert variants for different scenarios. Each variant has an associated status icon, background, and alert title coded to communicate the severity of an alert. Use the `variant` property to apply the following styling options. If no `variant` is specified, then the variant will be set to "default".
+
+| Variant | Description |
+|---|---|
+| Default | Use for generic messages with no associated severity |
+| Info | Use for general informational messages |
+| Success | Use to indicate that a task or process has been completed successfully |
+| Warning | Use to indicate that a non-critical error has occurred|
+| Danger | Use to indicate that a critical or blocking error has occurred |
 
-### Types
 ```ts
 import React from 'react';
 import { Alert } from '@patternfly/react-core';
@@ -29,7 +40,18 @@ import { Alert } from '@patternfly/react-core';
 </React.Fragment>
 ```
 
-### Variations
+### Alert variations
+
+PatternFly supports several properties and variations that can be used to add extra content to an alert. 
+
+* As demonstrated in the 1st variation below, use the `actionLinks` property to add one or more `<AlertActionLink>` components that place links beneath the alert message. You must pass in `href` and `component="a"` properties to have an `<AlertActionLink>` act as a proper link, rather than as a button.
+
+* As demonstrated in the 2nd variation below, use a native HTML `<a>` element to add links within an alert message.
+
+* As demonstrated in the 3rd and 4th variations below, use the `actionClose` property to add an `<AlertActionCloseButton>` component, which can be used to manage and customize alert dismissals. `actionClose` can be used with or without the presence of `actionLinks`.
+
+* As demonstrated in the 5th and 6th variations below, use the `titleHeadingLevel` property to set the heading level of an alert title. Headings should be ordered by their level and heading levels should not be skipped. For example, a heading of an `h2` level should not be followed directly by an `h4`.
+
 ```ts
 import React from 'react';
 import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core';
@@ -70,12 +92,139 @@ import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/reac
   <Alert variant="success" title="h6 Success alert title" titleHeadingLevel="h6" />
   </React.Fragment>
 ```
+### Alert timeout
+
+Use the `timeout` property to automatically dismiss an alert after a period of time. If set to `true`, the `timeout` will be 8000 milliseconds. Provide a specific value to dismiss the alert after a different number of milliseconds.
+
+```ts
+import React from 'react';
+import { Alert, AlertActionLink, AlertGroup, Button } from '@patternfly/react-core';
+
+const AlertTimeout: React.FunctionComponent = () => {
+  const [alerts, setAlerts] = React.useState<React.ReactNode[]>([]);
+  const onClick = () => {
+    const timeout = 8000;
+    setAlerts(prevAlerts => {
+      return [...prevAlerts,
+        <Alert title="Default timeout Alert" timeout={timeout} actionLinks={
+          <React.Fragment>
+            <AlertActionLink>View details</AlertActionLink>
+            <AlertActionLink>Ignore</AlertActionLink>
+          </React.Fragment>
+        }>
+          This alert will dismiss after {`${timeout / 1000} seconds`}
+        </Alert>
+      ]
+    });
+  }
+
+  return (
+    <React.Fragment>
+      <Button variant="secondary" onClick={onClick}>Add alert</Button>
+      <Button variant="secondary" onClick={() => setAlerts([])}>Remove all alerts</Button>
+      <AlertGroup isLiveRegion>
+        {alerts}
+      </AlertGroup>
+    </React.Fragment>
+  );
+};
+```
+
+### Expandable alerts
+
+An alert can contain additional, hidden information that is made visible when users click a caret icon. This information can be expanded and collapsed each time the icon is clicked.
+
+It is not recommended to use an expandable alert with a `timeout` in a toast [alert group](/components/alert-group) because the alert could timeout before users have time to interact with and view the entire alert. 
+
+See the [toast alert considerations](/components/alert/accessibility#toast-alerts) section of the alert accessibility documentation to understand the accessibility risks associated with using toast alerts.
+
+```ts
+import React from 'react';
+import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core';
+
+<React.Fragment>
+  <Alert
+    isExpandable
+    variant="success"
+    title="Success alert title"
+    actionClose={<AlertActionCloseButton onClose={() => alert('Clicked the close button')} />}
+    actionLinks={
+      <React.Fragment>
+        <AlertActionLink onClick={() => alert('Clicked on View details')}>View details</AlertActionLink>
+        <AlertActionLink onClick={() => alert('Clicked on Ignore')}>Ignore</AlertActionLink>
+      </React.Fragment>
+    }
+  >
+    <p>Success alert description. This should tell the user more information about the alert.</p>
+  </Alert>
+  <Alert
+    isExpandable
+    isInline
+    variant="success"
+    title="Success alert title"
+    actionClose={<AlertActionCloseButton onClose={() => alert('Clicked the close button')} />}
+    actionLinks={
+      <React.Fragment>
+        <AlertActionLink onClick={() => alert('Clicked on View details')}>View details</AlertActionLink>
+        <AlertActionLink onClick={() => alert('Clicked on Ignore')}>Ignore</AlertActionLink>
+      </React.Fragment>
+    } 
+  >
+    <p>Success alert description. This should tell the user more information about the alert.</p>
+  </Alert>
+</React.Fragment>
+```
+
+### Truncated alerts
+
+Use the `truncateTitle` property to shorten a long `title`. Set `truncateTitle` equal to a number (passed in as `{n}`) to reduce the number of lines of text in the alert's `title`. Users may hover over or tab to a truncated `title` to see the full message in a tooltip.
+
+```ts
+import React from 'react';
+import { Alert } from '@patternfly/react-core';
+
+<React.Fragment>
+  <Alert variant="info" truncateTitle={1} title={`
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
+  `} />
+  <Alert variant="warning" truncateTitle={2} title={`
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
+  `} />
+  <Alert variant="danger" truncateTitle={3} title={`
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
+  `} />
+</React.Fragment>
+```
+
+### Custom icons
+
+Use the `customIcon` property to replace a default alert icon with a custom icon.
 
-### Inline types
 ```ts
 import React from 'react';
 import { Alert } from '@patternfly/react-core';
+import UsersIcon from '@patternfly/react-icons/dist/esm/icons/users-icon';
+import BoxIcon from '@patternfly/react-icons/dist/esm/icons/box-icon';
+import DatabaseIcon from '@patternfly/react-icons/dist/esm/icons/database-icon';
+import ServerIcon from '@patternfly/react-icons/dist/esm/icons/server-icon';
+import LaptopIcon from '@patternfly/react-icons/dist/esm/icons/laptop-icon';
+
+<React.Fragment>
+  <Alert customIcon={<UsersIcon />} title="Default alert title" />
+  <Alert customIcon={<BoxIcon />} variant="info" title="Info alert title" />
+  <Alert customIcon={<DatabaseIcon />} variant="success" title="Success alert title" />
+  <Alert customIcon={<ServerIcon />} variant="warning" title="Warning alert title" />
+  <Alert customIcon={<LaptopIcon />} variant="danger" title="Danger alert title" />
+</React.Fragment>
+```
+
+### Inline alerts variants
 
+Use inline alerts to display an alert inline with content. All alert variants may use the `isInline` property to position alerts in content-heavy areas, such as within forms, wizards, or drawers.
+
+```ts
+import React from 'react';
+import { Alert } from '@patternfly/react-core';
 <React.Fragment>
   <Alert variant="default" isInline title="Default inline alert title" />
   <Alert variant="info" isInline title="Info inline alert title" />
@@ -84,12 +233,13 @@ import { Alert } from '@patternfly/react-core';
   <Alert variant="danger" isInline title="Danger inline alert title" />
 </React.Fragment>
 ```
+### Inline alert variations
+
+All general alert variations can use the `isInline` property to apply inline styling.
 
-### Inline variations
 ```ts
 import React from 'react';
 import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core';
-
 <React.Fragment>
   <Alert
     isInline
@@ -133,11 +283,13 @@ import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/reac
 </React.Fragment>
 ```
 
-### Inline plain types
+### Plain inline alert variants
+
+Use the `isPlain` property to make any inline alert plain. Plain styling removes the colored background but keeps colored text and icons.
+
 ```ts
 import React from 'react';
 import { Alert } from '@patternfly/react-core';
-
 <React.Fragment>
   <Alert variant="default" isInline isPlain title="Default inline alert title" />
   <Alert variant="info" isInline isPlain title="Info inline alert title" />
@@ -147,14 +299,13 @@ import { Alert } from '@patternfly/react-core';
 </React.Fragment>
 ```
 
-### Inline plain variations
+### Plain inline alert variations
 
-It is not recommended to use an inline plain alert with actionClose nor actionLinks.
+It is not recommended to use a plain inline alert with `actionClose` nor `actionLinks` because these alerts are non-dismissible and should persist until the error or action related to the alert is resolved.
 
 ```ts
 import React from 'react';
 import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core';
-
 <Alert
   isInline
   isPlain
@@ -165,48 +316,12 @@ import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/reac
 </Alert>
 ```
 
-### Expandable
+### Static live region alerts
 
-It is not recommended to use an expandable alert within a toast Alert group. In such a case, the Alert could timeout before users would have time to interact and view the entire Alert.
+Live region alerts allow you to expose dynamic content changes in a way that can be announced by assistive technologies.
 
-```ts
-import React from 'react';
-import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core';
+By default, `isLiveRegion`alerts are static.
 
-<React.Fragment>
-  <Alert
-    isExpandable
-    variant="success"
-    title="Success alert title"
-    actionClose={<AlertActionCloseButton onClose={() => alert('Clicked the close button')} />}
-    actionLinks={
-      <React.Fragment>
-        <AlertActionLink onClick={() => alert('Clicked on View details')}>View details</AlertActionLink>
-        <AlertActionLink onClick={() => alert('Clicked on Ignore')}>Ignore</AlertActionLink>
-      </React.Fragment>
-    }
-  >
-    <p>Success alert description. This should tell the user more information about the alert.</p>
-  </Alert>
-  <Alert
-    isExpandable
-    isInline
-    variant="success"
-    title="Success alert title"
-    actionClose={<AlertActionCloseButton onClose={() => alert('Clicked the close button')} />}
-    actionLinks={
-      <React.Fragment>
-        <AlertActionLink onClick={() => alert('Clicked on View details')}>View details</AlertActionLink>
-        <AlertActionLink onClick={() => alert('Clicked on Ignore')}>Ignore</AlertActionLink>
-      </React.Fragment>
-    } 
-  >
-    <p>Success alert description. This should tell the user more information about the alert.</p>
-  </Alert>
-</React.Fragment>
-```
-
-### Static live region alert
 ```ts
 import React from 'react';
 import { Alert, AlertActionCloseButton } from '@patternfly/react-core';
@@ -234,84 +349,15 @@ import { Alert, AlertActionCloseButton } from '@patternfly/react-core';
 </React.Fragment>
 ```
 
-### Dynamic live region alert
-Alerts asynchronously appended into dynamic AlertGroups with isLiveRegion will be announced to assistive technology at the moment the change happens, following the strategy used for aria-atomic, which defaults to false. This means only changes of type "addition" will be announced.
-```ts file="AlertDynamicLiveRegion.tsx"
-```
+### Dynamic live region alerts
 
-### Async live region alert
-This shows how an alert could be triggered by an asynchronous event in the application. Note that you can customize how the alert will be announced to assistive technology. See the alert accessibility tab for more information.
-```ts file="AlertAsyncLiveRegion.tsx"
-```
+Alerts that are asynchronously appended into dynamic [alert groups](/components/alert-group) via the `isLiveRegion` property will be announced to assistive technology the moment the change happens, following the strategy used for `aria-atomic`, which defaults to false. This means only changes of type "addition" will be announced.
 
-### Alert timeout
-```ts
-import React from 'react';
-import { Alert, AlertActionLink, AlertGroup, Button } from '@patternfly/react-core';
-
-const AlertTimeout: React.FunctionComponent = () => {
-  const [alerts, setAlerts] = React.useState<React.ReactNode[]>([]);
-  const onClick = () => {
-    const timeout = 8000;
-    setAlerts(prevAlerts => {
-      return [...prevAlerts,
-        <Alert title="Default timeout Alert" timeout={timeout} actionLinks={
-          <React.Fragment>
-            <AlertActionLink>View details</AlertActionLink>
-            <AlertActionLink>Ignore</AlertActionLink>
-          </React.Fragment>
-        }>
-          This alert will dismiss after {`${timeout / 1000} seconds`}
-        </Alert>
-      ]
-    });
-  }
-
-  return (
-    <React.Fragment>
-      <Button variant="secondary" onClick={onClick}>Add alert</Button>
-      <Button variant="secondary" onClick={() => setAlerts([])}>Remove all alerts</Button>
-      <AlertGroup isLiveRegion>
-        {alerts}
-      </AlertGroup>
-    </React.Fragment>
-  );
-};
-```
-
-### Truncate
-```ts
-import React from 'react';
-import { Alert } from '@patternfly/react-core';
-
-<React.Fragment>
-  <Alert variant="info" truncateTitle={1} title={`
-  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
-  `} />
-  <Alert variant="warning" truncateTitle={2} title={`
-  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
-  `} />
-  <Alert variant="danger" truncateTitle={3} title={`
-  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pellentesque neque cursus enim fringilla tincidunt. Proin lobortis aliquam dictum. Nam vel ullamcorper nulla, nec blandit dolor. Vivamus pellentesque neque justo, nec accumsan nulla rhoncus id. Suspendisse mollis, tortor quis faucibus volutpat, sem leo fringilla turpis, ac lacinia augue metus in nulla. Cras vestibulum lacinia orci. Pellentesque sodales consequat interdum. Sed porttitor tincidunt metus nec iaculis. Pellentesque non commodo justo. Morbi feugiat rhoncus neque, vitae facilisis diam aliquam nec. Sed dapibus vitae quam at tristique. Nunc vel commodo mi. Mauris et rhoncus leo.
-  `} />
-</React.Fragment>
+```ts file="AlertDynamicLiveRegion.tsx"
 ```
 
-### Custom icons
-```ts
-import React from 'react';
-import { Alert } from '@patternfly/react-core';
-import UsersIcon from '@patternfly/react-icons/dist/esm/icons/users-icon';
-import BoxIcon from '@patternfly/react-icons/dist/esm/icons/box-icon';
-import DatabaseIcon from '@patternfly/react-icons/dist/esm/icons/database-icon';
-import ServerIcon from '@patternfly/react-icons/dist/esm/icons/server-icon';
-import LaptopIcon from '@patternfly/react-icons/dist/esm/icons/laptop-icon';
+### Asynchronous live region alerts 
 
-<React.Fragment>
-  <Alert customIcon={<UsersIcon />} title="Default alert title" />
-  <Alert customIcon={<BoxIcon />} variant="info" title="Info alert title" />
-  <Alert customIcon={<DatabaseIcon />} variant="success" title="Success alert title" />
-  <Alert customIcon={<ServerIcon />} variant="warning" title="Warning alert title" />
-  <Alert customIcon={<LaptopIcon />} variant="danger" title="Danger alert title" />
-</React.Fragment>
-```
+This example shows how an alert could be triggered by an asynchronous event in the application. Note that you can customize how the alert will be announced to assistive technology. See the [https://www.patternfly.org/v4/components/alert/accessibility](alert accessibility) for more information.
+```ts file="AlertAsyncLiveRegion.tsx"
+```

package/src/components/ProgressStepper/ProgressStep.tsx

@@ -19,7 +19,7 @@ export interface ProgressStepProps
   /** Custom icon of a progress step. Will override default icons provided by the variant. */
   icon?: React.ReactNode;
   /** Description text of a progress step. */
-  description?: string;
+  description?: React.ReactNode;
   /** ID of the title of the progress step. */
   titleId?: string;
   /** Accessible label for the progress step. Should communicate all information being communicated by the progress

package/src/components/ProgressStepper/__tests__/ProgressStepper.test.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import { ProgressStepper } from '../ProgressStepper';
 import { ProgressStep } from '../ProgressStep';
 import InProgressIcon from '@patternfly/react-icons/dist/esm/icons/in-progress-icon';
@@ -110,3 +110,34 @@ describe('ProgressStep', () => {
     expect(asFragment()).toMatchSnapshot();
   });
 });
+
+test('renders description class and text', () => {
+  render(
+    <ProgressStep
+      description="Test description"
+    >
+      Title
+    </ProgressStep>
+  );
+
+  expect(screen.getByText('Test description')).toBeVisible();
+  expect(screen.getByText('Test description')).toHaveClass('pf-c-progress-stepper__step-description');
+});
+
+test('renders description line break', () => {
+  render(
+    <ProgressStep
+      description={
+        <>
+          Testing description
+          <br />
+          Line break
+        </>
+      }
+      >
+        Title
+      </ProgressStep>
+  );
+
+  expect(screen.getByText("Testing descriptionLine break")).toBeVisible();
+});