@patternfly/react-core 4.267.13 → 4.268.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patternfly/react-core",
-  "version": "4.267.13",
+  "version": "4.268.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",
@@ -71,5 +71,5 @@
     "react": "^16.8 || ^17 || ^18",
     "react-dom": "^16.8 || ^17 || ^18"
   },
-  "gitHead": "122f28feeb8a8130c8beb9e2504ba34e48b911b1"
+  "gitHead": "4464f97977ce3984b4e589711f26993f1f64a23f"
 }

package/src/components/Dropdown/DropdownToggleCheckbox.tsx

@@ -3,6 +3,7 @@ import styles from '@patternfly/react-styles/css/components/Dropdown/dropdown';
 import { css } from '@patternfly/react-styles';
 import { PickOptional } from '../../helpers/typeUtils';
 import { getOUIAProps, OUIAProps, getDefaultOUIAId } from '../../helpers';
+import { Spinner } from '../Spinner';
 
 export interface DropdownToggleCheckboxProps
   extends Omit<React.HTMLProps<HTMLInputElement>, 'type' | 'onChange' | 'disabled' | 'checked'>,
@@ -15,6 +16,8 @@ export interface DropdownToggleCheckboxProps
   isDisabled?: boolean;
   /** Flag to show if the checkbox is checked */
   isChecked?: boolean | null;
+  /** @beta Flag to show if the checkbox is in progress */
+  isInProgress?: boolean | null;
   /** Alternate Flag to show if the checkbox is checked */
   checked?: boolean | null;
   /** A callback for when the checkbox selection changes */
@@ -25,6 +28,10 @@ export interface DropdownToggleCheckboxProps
   id: string;
   /** Aria-label of the checkbox */
   'aria-label': string;
+  /** @beta Text describing current loading status or progress */
+  defaultProgressAriaValueText?: string;
+  /** @beta Aria-label for the default progress icon to describe what is loading */
+  defaultProgressAriaLabel?: string;
   /** Value to overwrite the randomly generated data-ouia-component-id.*/
   ouiaId?: number | string;
   /** Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false. */
@@ -68,6 +75,9 @@ export class DropdownToggleCheckbox extends React.Component<DropdownToggleCheckb
       isValid,
       isDisabled,
       isChecked,
+      isInProgress = false,
+      defaultProgressAriaLabel,
+      defaultProgressAriaValueText = 'Loading...',
       children,
       ouiaId,
       ouiaSafe,
@@ -77,13 +87,27 @@ export class DropdownToggleCheckbox extends React.Component<DropdownToggleCheckb
       /* eslint-enable @typescript-eslint/no-unused-vars */
       ...props
     } = this.props;
+
+    const spinner = (
+      <Spinner
+        diameter="1em"
+        isSVG
+        aria-valuetext={defaultProgressAriaValueText}
+        aria-live="polite"
+        aria-label={defaultProgressAriaLabel}
+      />
+    );
+
     const text = children && (
       <span className={css(styles.dropdownToggleText, className)} aria-hidden="true" id={`${props.id}-text`}>
         {children}
       </span>
     );
     return (
-      <label className={css(styles.dropdownToggleCheck, className)} htmlFor={props.id}>
+      <label
+        className={css(styles.dropdownToggleCheck, isInProgress && styles.modifiers.inProgress, className)}
+        htmlFor={props.id}
+      >
         <input
           {...props}
           {...(this.calculateChecked() !== undefined && { onChange: this.handleChange })}
@@ -98,6 +122,7 @@ export class DropdownToggleCheckbox extends React.Component<DropdownToggleCheckb
             ouiaSafe
           )}
         />
+        {isInProgress && <span className={css(styles.dropdownToggleProgress, className)}>{spinner}</span>}
         {text}
       </label>
     );

package/src/components/Dropdown/examples/Dropdown.md

@@ -116,7 +116,7 @@ You may use a `<BadgeToggle>` to display the number of dropdown menu items.
 ```ts file="./DropdownBadge.tsx"
 ```
 
-### Split button
+### Split button (checkbox)
 
 To combine an action button or other control with a dropdown menu, use a split button. A `<DropdownToggle>` can be rendered as a split button by using the `splitButtonItems` property. Elements to be displayed before the toggle button must be included in `splitButtonItems`.
 
@@ -125,13 +125,20 @@ The following example shows a split button with a `<DropdownToggleCheckbox>`, wh
 ```ts file="./DropdownSplitButton.tsx"
 ```
 
-### Split button text label
+### Split button (checkbox with toggle text)
 
 Text labels may optionally be used alongside actions within split buttons.
 
 ```ts file="./DropdownSplitButtonText.tsx"
 ```
 
+### Split button (progress checkbox)
+
+The `isInProgress` property can be used to indicate a progress state by rendering a spinner in place of a checkbox.
+
+```ts isBeta file="./DropdownSplitButtonProgressCheckbox.tsx"
+```
+
 ### Split button toggle variants
 
 Use the `toggleVariant` and `splitButtonVariant` properties to adjust the styling of split button toggles. 

package/src/components/Dropdown/examples/DropdownSplitButton.tsx

@@ -54,7 +54,7 @@ export const DropdownSplitButton: React.FunctionComponent = () => {
       toggle={
         <DropdownToggle
           splitButtonItems={[
-            <DropdownToggleCheckbox id="split-button-checkbox" key="split-checkbox" aria-label="Select all" />
+            <DropdownToggleCheckbox id="split-button-toggle-checkbox" key="split-checkbox" aria-label="Select all" />
           ]}
           onToggle={onToggle}
           id="toggle-split-button"

package/src/components/Dropdown/examples/DropdownSplitButtonProgressCheckbox.tsx

@@ -0,0 +1,140 @@
+import React from 'react';
+import {
+  Dropdown,
+  DropdownToggle,
+  DropdownToggleCheckbox,
+  DropdownItem,
+  DropdownSeparator
+} from '@patternfly/react-core';
+
+export const DropdownSplitButtonProgressCheckbox: React.FunctionComponent = () => {
+  const [isOpen1, setIsOpen1] = React.useState(false);
+  const [isOpen2, setIsOpen2] = React.useState(false);
+
+  const [isChecked1, setIsChecked1] = React.useState(false);
+  const [isChecked2, setIsChecked2] = React.useState(false);
+
+  const [isTimedOut1, setIsTimedOut1] = React.useState(true);
+  const [isTimedOut2, setIsTimedOut2] = React.useState(true);
+
+  const onToggle1 = (isOpen: boolean) => {
+    setIsOpen1(isOpen);
+  };
+
+  const onToggle2 = (isOpen: boolean) => {
+    setIsOpen2(isOpen);
+  };
+
+  const showProgressIcon1 = () => {
+    setIsTimedOut1(false);
+    setTimeout(() => setIsTimedOut1(true), 3000);
+  };
+
+  const showProgressIcon2 = () => {
+    setIsTimedOut2(false);
+    setTimeout(() => setIsTimedOut2(true), 3000);
+  };
+
+  const onFocus1 = () => {
+    const element = document.getElementById('toggle-split-button-progress');
+    element.focus();
+  };
+
+  const onFocus2 = () => {
+    const element = document.getElementById('toggle-split-button-progress-text');
+    element.focus();
+  };
+
+  const onChange1 = (checked: boolean) => {
+    setIsChecked1(checked);
+    showProgressIcon1();
+  };
+
+  const onChange2 = (checked: boolean) => {
+    setIsChecked2(checked);
+    showProgressIcon2();
+  };
+
+  const onSelect1 = () => {
+    setIsOpen1(false);
+    onFocus1();
+  };
+
+  const onSelect2 = () => {
+    setIsOpen2(false);
+    onFocus2();
+  };
+
+  const dropdownItems = [
+    <DropdownItem key="link">Link</DropdownItem>,
+    <DropdownItem key="action" component="button">
+      Action
+    </DropdownItem>,
+    <DropdownItem key="disabled link" isDisabled href="www.google.com">
+      Disabled link
+    </DropdownItem>,
+    <DropdownItem
+      key="disabled action"
+      isAriaDisabled
+      component="button"
+      tooltip="Tooltip for disabled item"
+      tooltipProps={{ position: 'top' }}
+    >
+      Disabled action
+    </DropdownItem>,
+    <DropdownSeparator key="separator" />,
+    <DropdownItem key="separated link">Separated link</DropdownItem>,
+    <DropdownItem key="separated action" component="button">
+      Separated action
+    </DropdownItem>
+  ];
+
+  return (
+    <>
+      <Dropdown
+        onSelect={onSelect1}
+        toggle={
+          <DropdownToggle
+            splitButtonItems={[
+              <DropdownToggleCheckbox
+                onChange={onChange1}
+                isChecked={isChecked1}
+                isInProgress={!isTimedOut1}
+                id="split-button-progress-toggle-checkbox"
+                key="split-progress-checkbox"
+                aria-label="Select all"
+              />
+            ]}
+            onToggle={onToggle1}
+            id="toggle-split-button-progress"
+          />
+        }
+        isOpen={isOpen1}
+        dropdownItems={dropdownItems}
+      />{' '}
+      <Dropdown
+        onSelect={onSelect2}
+        toggle={
+          <DropdownToggle
+            splitButtonItems={[
+              <DropdownToggleCheckbox
+                onChange={onChange2}
+                isChecked={isChecked2}
+                isInProgress={!isTimedOut2}
+                id="split-button-progress-text-checkbox"
+                key="split-progress-checkbox"
+                aria-label="Select all"
+              >
+                10 selected
+              </DropdownToggleCheckbox>
+            ]}
+            onToggle={onToggle2}
+            id="toggle-split-button-progress-text"
+          />
+        }
+        isOpen={isOpen2}
+        dropdownItems={dropdownItems}
+      />
+    </>
+  );
+};

package/src/components/Page/examples/Page.md

@@ -23,49 +23,99 @@ import './page.css';
 
 ## Examples
 
-### Vertical nav
+### Basic page components
+
+A page will typically contain the following components: 
+
+- A `<Page>` with a `header` that often contains a [masthead](/components/masthead)
+  - Mastheads contain the `<PageToggleButton>`, a `<MastheadMain>` that contains a `<MastheadBrand>`, and the page's header toolbar within `<MastheadContent>`. 
+- A `<PageSidebar>` for vertical navigation 
+- 1 or more `<PageSection>` components
+
+### Vertical navigation
+
+To add a vertical sidebar to a `<Page>`, pass a `<PageSidebar>` component into the `sidebar` property. To render navigation in the sidebar, use the `nav` property of the `<PageSidebar>`. 
+
+The `isNavOpen` property helps facilitate the opening and closing of the sidebar and should be 'true' when the navigation sidebar is visible. 
 
 ```ts file="./PageVerticalNav.tsx"
 ```
 
-### Horizontal nav
+### Legacy page header
+
+This example shows the legacy implementation of a page's vertical navigation. Our updated recommendation advises you to use a masthead and toolbar to make headers, rather than `<PageHeader>` and `<PageHeaderTools>` as shown in the following example.
+
+```ts file="./PageVerticalNavUsingPageHeaderComponent.tsx"
+```
+
+### Horizontal navigation
+
+To add horizontal navigation to the top of a `<Page>`, add the navigation inside of a `<ToolbarItem>` in the `<Toolbar>` that is passed to the `<MastheadContent>` of the `<Masthead>`.
 
 ```ts file="./PageHorizontalNav.tsx"
 ```
 
-### Tertiary nav
+### Legacy tertiary navigation
+
+[Horizontal sub-navigation](/components/navigation#horizontal-subnav) is now recommended instead of tertiary-level navigation. 
+
+Tertiary navigation allows you to add an additional navigation menu alongside vertical or horizontal navigation. To create tertiary navigation, use the `tertiaryNav` property. The following example passes `tertiaryNav="Navigation"` into a `<Page>` component.
 
 ```ts file="./PageTertiaryNav.tsx"
 ```
 
-### With or without fill
+### Uncontrolled navigation
+
+When the `isManagedSidebar` property is true, it manages the sidebar open/close state, removing the need to pass both `isNavOpen` into the `<PageSidebar>` and `onNavToggle` into the `<PageHeader>`.
+
+```ts file="./PageUncontrolledNav.tsx"
+```
+
+### Filled page sections
+
+By default, the last page section is "filled", meaning it fills the available vertical space of a page.
+
+To change the default behavior, use the `isFilled` property. To make other page sections "filled", set `isFilled` equal to "true". To disable the last page section from being "filled", set `isFilled` equal to "false".
 
 ```ts file="./PageWithOrWithoutFill.tsx"
 ```
 
 ### Main section padding
 
-```ts file="./PageMainSectionPadding.tsx"
-```
+To adjust the padding of a `<PageSection>`, you can pass in different values to the `padding` property. These values should be aligned to a specific breakpoint: 'default', 'sm', 'md', 'lg', 'xl', and '2xl'. Each breakpoint passed into the property should be given a value of either ‘padding’ or ‘noPadding’. 
 
-### Uncontrolled nav
+As the page's viewport width increases, breakpoints inherit the padding behavior of the previous breakpoint. For example, padding that is set on 'lg' also applies to 'xl' and '2xl'. 
 
-```ts file="./PageUncontrolledNav.tsx"
+To remove padding entirely, pass 'noPadding' to the `default` breakpoint. For example, the second section in this example passes in `padding={{ default: 'noPadding' }}`. Since no specific breakpoints are mentioned, every breakpoint will have 'noPadding'.
+
+To add padding at specific breakpoints, pass in "padding" at those breakpoints. For example, the third section in this example passes in `padding={{ default: 'noPadding', md: 'padding' }}`. At 'md', 'lg',  'xl', and '2xl' breakpoints, the default value will be overwritten, and padding will be added.
+
+To remove padding at specific breakpoints, pass in 'noPadding' at those breakpoints. For example, the fourth section in this example passes in `padding={{ md: 'noPadding' }}`, which means that 'md', 'lg'  'xl', and '2xl' breakpoints will have `noPadding`.
+
+```ts file="./PageMainSectionPadding.tsx"
 ```
 
 ### Group section
 
-```ts file="./PageGroupSection.tsx"
-```
+To group page content sections, add 1 or more `<PageGroup>` components to a `<Page>`. 
 
-### Vertical nav using PageHeader component
+The following example adds a group containing `<PageNavigation>`, `<PageBreadcrumb>`, and `<PageSection>` components.
 
-This example is provided because PageHeader and PageHeaderTools are still in use; however, going forward Masthead and Toolbar should be used to make headers rather than PageHeader and PageHeaderTools.
+To add additional components and information to a group, you may use the following properties: 
 
-```ts file="./PageVerticalNavUsingPageHeaderComponent.tsx"
+- To indicate that a breadcrumb should be in a group, use `isBreadcrumbGrouped`. 
+- To indicate that tertiary navigation should be in a group, use `isTertiaryNavGrouped`.
+- To specify additional group content, use `additionalGroupedContent`. 
+
+
+```ts file="./PageGroupSection.tsx"
 ```
 
 ### Centered section
 
+By default, a page section spans the width of the page. To reduce the width of a section, use the `isWidthLimited` property. To center align width-limited page sections, use the `isCenterAligned` property.  When the main content area of a page is wider than the value of a centered, width-limited page section's `--pf-c-page--section--m-limit-width--MaxWidth` custom property, the section will automatically be centered.
+
+The content in this example is placed in a card to better illustrate how the section behaves when it is centered, but a card is not required to center a page section.
+
 ```ts file="./PageCenteredSection.tsx"
 ```