@patternfly/patternfly-doc-core 1.15.3 → 1.15.5

package/dist/docs/api/v6/components/alert/react

@@ -0,0 +1,452 @@
+import './alert.css';
+
+Micro animations have been added for `<Alert>` components within an `<AlertGroup>`. By default, you must opt into animations, since they can require updates to tests. To enable or disable animations as needed, use the `hasAnimations` property. With animations enabled, we recommend you ensure that dynamically-added alerts are prepended to a list of alerts, rather than appended to the end of it.
+
+Micro animations are turned on for all examples and demos where alerts are dynamically added.
+
+## Alert examples
+
+### Alert variants
+
+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 "custom".
+
+| Variant | Description                                                                                                                                              |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Custom  | Use for generic messages that should have a custom color set by the associated CSS variable. Should be used when the message has 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                                                                                           |
+
+```ts
+
+<Fragment>
+  <Alert title="Custom alert title" ouiaId="CustomAlert" />
+  <Alert variant="info" title="Info alert title" ouiaId="InfoAlert" />
+  <Alert variant="success" title="Success alert title" ouiaId="SuccessAlert" />
+  <Alert variant="warning" title="Warning alert title" ouiaId="WarningAlert" />
+  <Alert variant="danger" title="Danger alert title" ouiaId="DangerAlert" />
+</Fragment>;
+```
+
+### 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 variation below, use the `actionClose` property to add an `<AlertActionCloseButton>` component, which can be used to manage and customize alert dismissals.
+
+- As demonstrated in the 4th and 5th variations below, use the `component` property to set the element for an alert title.
+  - If there is not a description passed via `children` prop, then the `component` prop should be set to a non-heading element such as a `span` or `div`.
+  - If there is a description passed via `children` prop, then the `component` prop should be a heading element. 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
+
+<Fragment>
+  <Alert
+    variant="success"
+    title="Success alert title"
+    actionLinks={
+      <Fragment>
+        <AlertActionLink component="a" href="#">
+          View details
+        </AlertActionLink>
+        <AlertActionLink // eslint-disable-next-line no-console
+          onClick={() => console.log('Clicked on Ignore')}
+        >
+          Ignore
+        </AlertActionLink>
+      </Fragment>
+    }
+  >
+    <p>Success alert description. This should tell the user more information about the alert.</p>
+  </Alert>
+  <Alert variant="success" title="Success alert title">
+    <p>
+      Success alert description. This should tell the user more information about the alert.{' '}
+      <a href="#">This is a link.</a>
+    </p>
+  </Alert>
+  <Alert
+    variant="success"
+    title="Success alert title"
+    // eslint-disable-next-line no-console
+    actionClose={<AlertActionCloseButton onClose={() => console.log('Clicked the close button')} />}
+  >
+    <p>Short alert description.</p>
+  </Alert>
+  <Alert variant="success" title="div success alert title" component="div" />
+  <Alert variant="success" title="h6 Success alert title" component="h6">
+    <p>Short alert description.</p>
+  </Alert>
+</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
+
+const AlertTimeout: React.FunctionComponent = () => {
+  const [alerts, setAlerts] = useState<React.ReactNode[]>([]);
+  const [newAlertKey, setNewAlertKey] = useState<number>(0);
+
+  const onClick = () => {
+    const timeout = 8000;
+    setNewAlertKey((key) => key + 1);
+    setAlerts((prevAlerts) => {
+      return [
+        <Alert
+          title="Default timeout Alert"
+          timeout={timeout}
+          actionLinks={
+            <Fragment>
+              <AlertActionLink component="a" href="#">
+                View details
+              </AlertActionLink>
+              <AlertActionLink // eslint-disable-next-line no-console
+                onClick={() => console.log('Clicked on Ignore')}
+              >
+                Ignore
+              </AlertActionLink>
+            </Fragment>
+          }
+          key={newAlertKey}
+        >
+          This alert will dismiss after {`${timeout / 1000} seconds`}
+        </Alert>, ...prevAlerts
+      ];
+    });
+  };
+
+  return (
+    <Fragment>
+      <Button variant="secondary" onClick={onClick}>
+        Add alert
+      </Button>
+      <Button variant="secondary" onClick={() => setAlerts([])}>
+        Remove all alerts
+      </Button>
+      <AlertGroup hasAnimations isLiveRegion>{alerts}</AlertGroup>
+    </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#toast-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
+
+<Fragment>
+  <Alert
+    isExpandable
+    variant="success"
+    title="Success alert title"
+    // eslint-disable-next-line no-console
+    actionClose={<AlertActionCloseButton onClose={() => console.log('Clicked the close button')} />}
+  >
+    <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"
+    actionLinks={
+      <Fragment>
+        <AlertActionLink component="a" href="#">
+          View details
+        </AlertActionLink>
+        <AlertActionLink // eslint-disable-next-line no-console
+          onClick={() => console.log('Clicked on Ignore')}
+        >
+          Ignore
+        </AlertActionLink>
+      </Fragment>
+    }
+  >
+    <p>Success alert description. This should tell the user more information about the alert.</p>
+  </Alert>
+</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
+
+<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.
+  `}
+  />
+</Fragment>;
+```
+
+### Custom icons
+
+Use the `customIcon` property to replace a default alert icon with a custom icon.
+
+```ts
+
+<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" />
+</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
+<Fragment>
+  <Alert variant="custom" isInline title="Custom inline alert title" />
+  <Alert variant="info" isInline title="Info inline alert title" />
+  <Alert variant="success" isInline title="Success inline alert title" />
+  <Alert variant="warning" isInline title="Warning inline alert title" />
+  <Alert variant="danger" isInline title="Danger inline alert title" />
+</Fragment>;
+```
+
+### Inline alert variations
+
+All general alert variations can use the `isInline` property to apply inline styling.
+
+```ts
+<Fragment>
+  <Alert
+    isInline
+    variant="success"
+    title="Success alert title"
+    actionLinks={
+      <Fragment>
+        <AlertActionLink component="a" href="#">
+          View details
+        </AlertActionLink>
+        <AlertActionLink // eslint-disable-next-line no-console
+          onClick={() => console.log('Clicked on Ignore')}
+        >
+          Ignore
+        </AlertActionLink>
+      </Fragment>
+    }
+  >
+    <p>Success alert description. This should tell the user more information about the alert.</p>
+  </Alert>
+  <Alert isInline variant="success" title="Success alert title">
+    <p>
+      Success alert description. This should tell the user more information about the alert.{' '}
+      <a href="#">This is a link.</a>
+    </p>
+  </Alert>
+  <Alert
+    isInline
+    variant="success"
+    title="Success alert title"
+    // eslint-disable-next-line no-console
+    actionClose={<AlertActionCloseButton onClose={() => console.log('Clicked the close button')} />}
+  >
+    <p>Short alert description.</p>
+  </Alert>
+  <Alert isInline variant="success" title="div success alert title" component="div" />
+  <Alert isInline variant="success" title="h6 Success alert title" component="h6">
+    <p>Short alert description.</p>
+  </Alert>
+</Fragment>;
+```
+
+### 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
+<Fragment>
+  <Alert variant="custom" isInline isPlain title="Custom inline alert title" />
+  <Alert variant="info" isInline isPlain title="Info inline alert title" />
+  <Alert variant="success" isInline isPlain title="Success inline alert title" />
+  <Alert variant="warning" isInline isPlain title="Warning inline alert title" />
+  <Alert variant="danger" isInline isPlain title="Danger inline alert title" />
+</Fragment>;
+```
+
+### Plain inline alert variations
+
+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
+<Alert isInline isPlain variant="success" title="Success alert title">
+  <p>Success alert description. This should tell the user more information about the alert.</p>
+</Alert>;
+```
+
+### Static live region alerts
+
+Live region alerts allow you to expose dynamic content changes in a way that can be announced by assistive technologies.
+
+By default, `isLiveRegion`alerts are static.
+
+```ts
+
+<Fragment>
+  <Alert
+    isLiveRegion
+    variant="info"
+    title="Default live region configuration"
+    // eslint-disable-next-line no-console
+    actionClose={<AlertActionCloseButton onClose={() => console.log('Clicked the close button')} />}
+  >
+    This alert uses the recommended <code>isLiveRegion</code> prop to automatically set ARIA attributes and CSS classes.
+  </Alert>
+  <Alert
+    aria-live="assertive"
+    aria-relevant="additions text"
+    aria-atomic="true"
+    variant="info"
+    title="Customized live region"
+    // eslint-disable-next-line no-console
+    actionClose={<AlertActionCloseButton onClose={() => console.log('Clicked the close button')} />}
+  >
+    You can alternatively omit the <code>isLiveRegion</code> prop to specify ARIA attributes and CSS manually on the
+    containing element.
+  </Alert>
+</Fragment>;
+```
+
+### Dynamic live region alerts
+
+Alerts that are asynchronously appended into dynamic [alert groups](/components/alert/#alert-group-examples) 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.
+
+
+import AlertDynamicLiveRegion from "./AlertDynamicLiveRegion.tsx?raw"
+
+<LiveExample src={AlertDynamicLiveRegion} />
+
+### Asynchronous live region alerts
+
+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 [alert accessibility](/components/alert/accessibility/) for more information.
+
+
+import AlertAsyncLiveRegion from "./AlertAsyncLiveRegion.tsx?raw"
+
+<LiveExample src={AlertAsyncLiveRegion} />
+
+## Alert group examples
+
+An alert group stacks and positions 2 or more alerts in a live region, either in a layer over the main content of a page or inline with the page content. Alert groups should always rank alerts by age, stacking new alerts on top of old ones as they surface.
+
+### Alert group variants
+
+Alert groups can be one of the following variants:
+
+| Variant       | Description                                                                                                                                                                                                 |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Static inline | Static inline alert groups contain alerts that appear when the page loads, and are seen within the normal page content flow. These groups should not contain alerts that will dynamically appear or update. |
+| Toast         | Toast alert groups contain alerts that typically appear in response to an asynchronous event or user action. These groups are positioned on top of other content at the top right of the page.              |
+| Dynamic       | Dynamic alert groups contain alerts that typically appear in response to a user action, and are seen within the normal page content flow.                                                                   |
+
+Dynamic alerts that are generated after the page initially loads must be appended to either a toast or dynamic `AlertGroup`, both of which must use the `isLiveRegion` property. New alerts appended to a toast or dynamic group will be announced by assistive technologies the moment the change happens. For information about customizing this announcement, read the [aria-atomic and aria-relevant](/components/alert/accessibility#aria-atomic-and-aria-relevant) section of the alert accessibility documentation.
+
+### Static inline alert group
+
+All alert group variants may combine multiple [alert variants](/components/alert) For example, the following static inline alert group includes one "success" alert and one "info" alert.
+
+
+import AlertGroupStatic from "./AlertGroupStatic.tsx?raw"
+
+<LiveExample src={AlertGroupStatic} />
+
+### Toast alert group
+
+Toast alert groups are created by passing in the `isToast` and `isLiveRegion` properties.
+
+Click the buttons in the example below to add alerts to a toast group.
+
+
+import AlertGroupToast from "./AlertGroupToast.tsx?raw"
+
+<LiveExample src={AlertGroupToast} />
+
+### Toast alert group with overflow capture
+
+Users will see an overflow message once a predefined number of alerts are displayed. They will not see any alerts beyond the display limit, which must be explicitly set.
+
+In the following example, an overflow message will appear when more than 4 alerts would be shown. When a 5th alert would appear, an overflow message is shown instead.
+
+When an overflow message appears in an `AlertGroup` using the `isLiveRegion` property, the "view 1 more alert" text label will be announced, but the alert message will not.
+
+Users navigating via keyboard or another assistive technology will need a way to navigate to and reveal hidden alerts before they disappear. Alternatively, there should be a place where notifications or alerts are collected to be viewed or read later.
+
+
+import AlertGroupToastOverflowCapture from "./AlertGroupToastOverflowCapture.tsx?raw"
+
+<LiveExample src={AlertGroupToastOverflowCapture} />
+
+### Asynchronous alert groups
+
+The following example shows how alerts can be triggered by an asynchronous event in the application. You can customize how an alert will be announced to assistive technology by adjusting the value of the `aria-live` property. Click the "start async" alert button below and then click the buttons in the above toast examples to demonstrate how asynchronous events add alerts to a group. Click the "stop async alerts" button to halt this behavior.
+
+See the [alert accessibility tab](/components/alert/accessibility) for more information on customizing this behavior.
+
+
+import AlertGroupAsync from "./AlertGroupAsync.tsx?raw"
+
+<LiveExample src={AlertGroupAsync} />
+
+### Dynamic alert groups
+
+Click the buttons in the example below to add dynamic alerts to a group.
+
+
+import AlertGroupSingularDynamic from "./AlertGroupSingularDynamic.tsx?raw"
+
+<LiveExample src={AlertGroupSingularDynamic} />
+
+### Dynamic alert group with overflow message
+
+In the following example, there can be a maximum of 4 alerts shown at once.
+
+
+import AlertGroupSingularDynamicOverflow from "./AlertGroupSingularDynamicOverflow.tsx?raw"
+
+<LiveExample src={AlertGroupSingularDynamicOverflow} />
+
+### Multiple dynamic alert groups
+
+You may add multiple alerts to an alert group at once. Click the "add alert collection" button in the example below to add a batch of 3 toast alerts to a group.
+
+
+import AlertGroupMultipleDynamic from "./AlertGroupMultipleDynamic.tsx?raw"
+
+<LiveExample src={AlertGroupMultipleDynamic} />

package/dist/docs/api/v6/components/avatar/html

@@ -0,0 +1,66 @@
+## Examples
+
+### Basic
+
+
+import Example1 from './Example1.html?raw'
+
+<LiveExample html={Example1} />
+
+### Bordered
+
+
+import Example2 from './Example2.html?raw'
+
+<LiveExample html={Example2} />
+
+### Small
+
+
+import Example3 from './Example3.html?raw'
+
+<LiveExample html={Example3} />
+
+### Medium
+
+
+import Example4 from './Example4.html?raw'
+
+<LiveExample html={Example4} />
+
+### Large
+
+
+import Example5 from './Example5.html?raw'
+
+<LiveExample html={Example5} />
+
+### Extra large
+
+
+import Example6 from './Example6.html?raw'
+
+<LiveExample html={Example6} />
+
+## Documentation
+
+### Overview
+
+The avatar component provides a default SVG icon. If an image is used it should be 36px by 36px.
+
+### Accessibility
+
+| Attribute | Applied to | Outcome |
+| -- | -- | -- |
+| `alt` | `.pf-v6-c-avatar` | The alt attribute describes the appearance and function of the avatar image. **Required** |
+
+### Usage
+
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `.pf-v6-c-avatar` | `<img>` |  Initiates an avatar image. **Required** |
+| `.pf-m-bordered` | `.pf-v6-c-avatar` | Modifies an avatar to have a border. |
+| `.pf-m-sm{-on-[breakpoint]}` | `.pf-v6-c-avatar` | Modifies an avatar to be small on an optional [breakpoint](/tokens/all-patternfly-tokens). |
+| `.pf-m-md{-on-[breakpoint]}` | `.pf-v6-c-avatar` | Modifies an avatar to be medium on an optional [breakpoint](/tokens/all-patternfly-tokens). **Note:** This is the default size. |
+| `.pf-m-lg{-on-[breakpoint]}` | `.pf-v6-c-avatar` | Modifies an avatar to be large on an optional [breakpoint](/tokens/all-patternfly-tokens). |
+| `.pf-m-xl{-on-[breakpoint]}` | `.pf-v6-c-avatar` | Modifies an avatar to be extra large on an optional [breakpoint](/tokens/all-patternfly-tokens). |

package/dist/docs/api/v6/components/avatar/react

@@ -0,0 +1,22 @@
+## Examples
+
+### Basic
+
+
+import AvatarBasic from "./AvatarBasic.tsx?raw"
+
+<LiveExample src={AvatarBasic} />
+
+### Bordered 
+
+
+import AvatarBordered from "./AvatarBordered.tsx?raw"
+
+<LiveExample src={AvatarBordered} />
+
+### Size variations
+
+
+import AvatarSizeVariations from "./AvatarSizeVariations.tsx?raw"
+
+<LiveExample src={AvatarSizeVariations} />

package/dist/docs/api/v6/components/back-to-top/html

@@ -0,0 +1,19 @@
+import './BackToTop.css'
+
+## Examples
+
+### Basic
+
+
+import Example1 from './Example1.html?raw'
+
+<LiveExample html={Example1} />
+
+## Documentation
+
+### Usage
+
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `.pf-v6-c-back-to-top` | `<div>` | Initiates the back to top component. **Required** |
+| `.pf-m-hidden` | `.pf-v6-c-back-to-top` | Modifies the component to be hidden. |