diff --git a/packages/react-core/src/components/Alert/examples/Alert.md b/packages/react-core/src/components/Alert/examples/Alert.md index d186f28879c..c4e94a4d37c 100644 --- a/packages/react-core/src/components/Alert/examples/Alert.md +++ b/packages/react-core/src/components/Alert/examples/Alert.md @@ -13,9 +13,12 @@ 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 + +### Variants + +PatternFly supports several alerts variants for different scenarios and applications. 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. -### Types ```ts import React from 'react'; import { Alert } from '@patternfly/react-core'; @@ -29,7 +32,27 @@ import { Alert } from '@patternfly/react-core'; ``` -### Variations +If no `variant` property is specified, then the variant will be set to default. Otherwise, use the following variants: + +| 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 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 | + + +#### Variations + +PatternFly supports a number of properties and variations that can be used to add extra content to an alert. + +* Use the `actionLinks` property to add one or more `AlertActionLink` components that place links beneath the alert message. + +* Links may also be added within the alert message using an `href`. + +* Use the `actionClose` property to add an `AlertActionCloseButton` component, which manages and customizes alert dismissals. + ```ts import React from 'react'; import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core'; @@ -70,12 +93,142 @@ import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/reac ``` +#### 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 number to dismiss the alert after a specific 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([]); + const onClick = () => { + const timeout = 8000; + setAlerts(prevAlerts => { + return [...prevAlerts, + + View details + Ignore + + }> + This alert will dismiss after {`${timeout / 1000} seconds`} + + ] + }); + } + + return ( + + + + + {alerts} + + + ); +}; +``` + +#### Expandable alerts + +An alert can contain additional, hidden information that is made visible by clicking 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 using `timeout` within a toast [alert group](/components/alert#alert) because the alert could timeout before users have time to interact with and view the entire alert. See [alert accessibility considerations](https://www.patternfly.org/v4/components/alert/design-guidelines#accessibility-considerations) to understand the accessibility risks associated with using expandable alerts in toast alert groups. + +```ts +import React from 'react'; +import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core'; + + + alert('Clicked the close button')} />} + actionLinks={ + + alert('Clicked on View details')}>View details + alert('Clicked on Ignore')}>Ignore + + } + > +

Success alert description. This should tell the user more information about the alert.

+ + alert('Clicked the close button')} />} + actionLinks={ + + alert('Clicked on View details')}>View details + alert('Clicked on Ignore')}>Ignore + + } + > +

Success alert description. This should tell the user more information about the alert.

+ + +``` + + +#### Truncated alerts + +Use the `truncateTitle` property to shorten a long alert message. Setting `truncateTitle` equal to a number (passed in as `{n}`) will reduce the number of lines of text in the alert's message. Users may hover over a truncated alert to see the full message in a popup. + +```ts +import React from 'react'; +import { Alert } from '@patternfly/react-core'; + + + + + + +``` + +#### 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'; + + + } title="Default alert title" /> + } variant="info" title="Info alert title" /> + } variant="success" title="Success alert title" /> + } variant="warning" title="Warning alert title" /> + } variant="danger" title="Danger alert title" /> + +``` +### Inline alerts + +Use inline alerts to display an alert inline with content. + +#### Variants + +All alert variants may use the `isInline` property to place alerts in content-heavy areas, such as within forms, wizards, or drawers. + +```ts +import React from 'react'; +import { Alert } from '@patternfly/react-core'; @@ -84,12 +237,13 @@ import { Alert } from '@patternfly/react-core'; ``` +#### Inline variations + +The same variations that exist for general alerts can use the `isInline` property to adjust the styling so that they can be placed inline with content. -### Inline variations ```ts import React from 'react'; import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core'; - ``` -### Inline plain types +#### Plain 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'; - @@ -147,14 +303,13 @@ import { Alert } from '@patternfly/react-core'; ``` -### Inline plain variations +#### Plain variations -It is not recommended to use an inline plain alert with actionClose nor actionLinks. +It is not recommended to use an inline plain alert with `actionClose` nor `actionLinks`. ```ts import React from 'react'; import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core'; - ``` -### Expandable +### 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. +Accessible Rich Internet Applications (ARIA) is a set of roles and attributes specified by the [World Wide Web Consortium](https://www.w3.org/WAI/standards-guidelines/aria/). ARIA defines ways to make web content and web applications more accessible to people with disabilities. -```ts -import React from 'react'; -import { Alert, AlertActionCloseButton, AlertActionLink } from '@patternfly/react-core'; +ARIA live regions allow you to expose dynamic content changes in a way that can be announced by assistive technologies. - - alert('Clicked the close button')} />} - actionLinks={ - - alert('Clicked on View details')}>View details - alert('Clicked on Ignore')}>Ignore - - } - > -

Success alert description. This should tell the user more information about the alert.

- - alert('Clicked the close button')} />} - actionLinks={ - - alert('Clicked on View details')}>View details - alert('Clicked on Ignore')}>Ignore - - } - > -

Success alert description. This should tell the user more information about the alert.

- - -``` +Use the `isLiveRegion` property to indicate that an alert is in a live region. + +#### Static alerts + +By default, live region alerts are static. -### Static live region alert ```ts import React from 'react'; import { Alert, AlertActionCloseButton } from '@patternfly/react-core'; @@ -234,84 +359,15 @@ import { Alert, AlertActionCloseButton } from '@patternfly/react-core'; ``` -### 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 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 `AlertGroups` 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([]); - const onClick = () => { - const timeout = 8000; - setAlerts(prevAlerts => { - return [...prevAlerts, - - View details - Ignore - - }> - This alert will dismiss after {`${timeout / 1000} seconds`} - - ] - }); - } - - return ( - - - - - {alerts} - - - ); -}; -``` - -### Truncate -```ts -import React from 'react'; -import { Alert } from '@patternfly/react-core'; - - - - - - +```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 alerts - - } title="Default alert title" /> - } variant="info" title="Info alert title" /> - } variant="success" title="Success alert title" /> - } variant="warning" title="Warning alert title" /> - } variant="danger" title="Danger alert title" /> - -``` +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" +``` \ No newline at end of file diff --git a/packages/react-core/src/components/Button/examples/Button.md b/packages/react-core/src/components/Button/examples/Button.md index ae96055698a..ba6e26097bf 100644 --- a/packages/react-core/src/components/Button/examples/Button.md +++ b/packages/react-core/src/components/Button/examples/Button.md @@ -14,70 +14,103 @@ import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-i import UploadIcon from '@patternfly/react-icons/dist/esm/icons/upload-icon'; import { Link } from '@reach/router'; -## Examples +## Variants -### Variations +PatternFly supports several button styling variants to be used in different scenarios as needed. The following button variants can be assigned using the `variant` prop. ```ts file="./ButtonVariations.tsx" ``` -### Disabled +| Variant | Description| +| --- | ---| +| Primary | Primary buttons are the most visually prominent variant. Use for the most important call to action.| +| Secondary | Secondary buttons are less visually prominant than primary buttons. Use for general actions on a page that require less emphasis than primary buttons. | +| Tertiary | Tertiary buttons are the least visually prominent variant. Use to retain a classic button format with less emphasis than primary or secondary buttons. | +| Danger | Danger buttons may be used for actions that are potentially destructive or difficult/impossible to undo. Danger is an independent variant, but all button variants may use the the `isDanger` prop to apply similar styling. | +| Warning | Warning buttons may be used for actions that change an important setting or behavior, but not in a destructive or irreversible way. | +| Link | Links are labeled, but have no background or border. Use for actions that require less emphasis, actions that navigate users to another page within the same window, and/or actions that navigate to external pages in a new window. Links may be placed inline with text using the `isInline` prop.| +| Plain | Plain buttons have no styling and are intended to be labeled with icons. | +| Control | Control buttons can be labeled with text or icons. Primarily intended to be paired with other controls in an [input group](https://www.patternfly.org/v4/components/input-group). | + +### Disabled buttons + +To indicate that an action is currently unavailable, all button variations can be disabled using the `isDisabled` prop. ```ts file="./ButtonDisabled.tsx" ``` -### Aria disabled +### Progress indicators -```ts file="./ButtonAriaDisabled.tsx" +Progress indicators can be added to buttons to identify that an action is in progress after a click. + +```ts file="./ButtonProgress.tsx" ``` -### Aria disabled button with tooltip +### Small buttons -```ts file="./ButtonAriaDisabledTooltip.tsx" +To fit into tight spaces, primary, secondary. tertiary, danger, and warning button variations can be made smaller using the `isSmall` prop. + +```ts file="./ButtonSmall.tsx" ``` -### Aria disabled link as button with tooltip +### Call to action (CTA) buttons -```ts file="./ButtonAriaDisabledLinkTooltip.tsx" +CTA buttons and links direct users to complete an action. Primary, secondary, tertiary, and link button variants can be styled as CTAs using the `isLarge` prop. + +```ts file="./ButtonCallToAction.tsx" +``` + +### Block level buttons + +Block level buttons span the full width of the parent element and can be enabled using the `isBlock` prop. + +```ts file="./ButtonBlock.tsx" ``` +## Links + ### Links as buttons +Buttons that link to another resource may take the form of primary, secondary, tertiary, or link variants. Use `component="a"` and an `href` prop to designate the button's target link. + ```ts file="./ButtonLinks.tsx" ``` ### Inline link as span +Inline links should use `component="span"` and the `isInline` prop to wrap inline with surrounding text. + ```ts file="./ButtonInlineSpanLink.tsx" ``` -### Block level - -```ts file="./ButtonBlock.tsx" -``` +### Router link -### Types +Router links can be used for in-app linking in React environments to prevent page reloading. -```ts file="./ButtonTypes.tsx" +```ts file="./ButtonRouterLink.tsx" ``` -### Small +## Aria buttons -```ts file="./ButtonSmall.tsx" -``` +Accessible Rich Internet Applications (ARIA) is a set of roles and attributes specified by the [World Wide Web Consortium](https://www.w3.org/WAI/standards-guidelines/aria/). ARIA defines ways to make web content and web applications more accessible to people with disabilities. -### Call to action +### Aria disabled buttons -```ts file="./ButtonCallToAction.tsx" +Buttons that are aria disabled are similar to normal disabled buttons, except they can receive focus. Every button variant can be aria disabled using the `isAriaDisabled` prop. + +```ts file="./ButtonAriaDisabled.tsx" ``` -### Progress +### Aria disabled button with tooltip -```ts file="./ButtonProgress.tsx" +Unlike normal disabled buttons, aria disabled buttons can support tooltips. + +```ts file="./ButtonAriaDisabledTooltip.tsx" ``` -### Router link +### Aria disabled link as button with tooltip -```ts file="./ButtonRouterLink.tsx" -``` +Aria disabled buttons can operate as links, which also support tooltips. +```ts file="./ButtonAriaDisabledLinkTooltip.tsx" +``` \ No newline at end of file diff --git a/packages/react-core/src/demos/Button.md b/packages/react-core/src/demos/Button.md index 15e94cc2000..b6d7986f410 100644 --- a/packages/react-core/src/demos/Button.md +++ b/packages/react-core/src/demos/Button.md @@ -5,9 +5,9 @@ section: components import CheckCircleIcon from '@patternfly/react-icons/dist/esm/icons/check-circle-icon'; -## Demos +## Progress button -### Progress button +The following demo shows the intended flow for a button that visually indicates progress. This example demonstrates a login process, which updates the button label based on the `loginState`. ```ts import React from 'react';