@patternfly/react-core 4.234.4 → 4.235.2

package/src/next/components/Wizard/WizardStep.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+
+import { WizardControlStep } from './types';
+import { WizardBody, WizardBodyProps } from './WizardBody';
+
+/**
+ * Used as a passthrough of step properties for Wizard and all supporting child components.
+ * Also acts as a wrapper for content, with an optional inclusion of WizardBody.
+ */
+
+export interface WizardStepProps extends Omit<WizardControlStep, 'parentId' | 'subStepIds' | 'visited'> {
+  /** Optional for when the step is used as a parent to sub-steps */
+  children?: React.ReactNode;
+  /** Props for WizardBody that wraps content by default. Can be set to null for exclusion of WizardBody. */
+  body?: WizardBodyProps | null;
+  /** Optional list of sub-steps */
+  steps?: React.ReactElement<WizardStepProps>[];
+}
+
+export const WizardStep = ({ body, children }: WizardStepProps) =>
+  body === undefined ? <WizardBody {...body}>{children}</WizardBody> : <>{children}</>;
+
+WizardStep.displayName = 'WizardStep';

package/src/next/components/Wizard/WizardToggle.tsx

@@ -0,0 +1,209 @@
+import React from 'react';
+
+import { css } from '@patternfly/react-styles';
+import styles from '@patternfly/react-styles/css/components/Wizard/wizard';
+import AngleRightIcon from '@patternfly/react-icons/dist/esm/icons/angle-right-icon';
+import CaretDownIcon from '@patternfly/react-icons/dist/esm/icons/caret-down-icon';
+
+import { KeyTypes } from '../../../helpers/constants';
+import { WizardNav, WizardNavItem } from '../Wizard';
+import {
+  WizardControlStep,
+  CustomWizardNavFunction,
+  DefaultWizardNavProps,
+  isWizardBasicStep,
+  isWizardParentStep,
+  isWizardSubStep,
+  isCustomWizardNav
+} from './types';
+
+/**
+ * Used to toggle between step content, including the body and footer. This is also where the nav and its expandability is controlled.
+ */
+
+export interface WizardToggleProps {
+  /** List of steps and/or sub-steps */
+  steps: WizardControlStep[];
+  /** The currently active WizardStep */
+  activeStep: WizardControlStep;
+  /** The WizardFooter */
+  footer: React.ReactElement;
+  /** Custom WizardNav or callback used to create a default WizardNav */
+  nav: DefaultWizardNavProps | CustomWizardNavFunction;
+  /** Navigate using the step index */
+  goToStepByIndex: (index: number) => void;
+  /** The button's aria-label */
+  'aria-label'?: string;
+  /** Flag to unmount inactive steps instead of hiding. Defaults to true */
+  unmountInactiveSteps?: boolean;
+}
+
+export const WizardToggle = ({
+  steps,
+  activeStep,
+  footer,
+  nav,
+  goToStepByIndex,
+  unmountInactiveSteps = true,
+  'aria-label': ariaLabel = 'Wizard toggle'
+}: WizardToggleProps) => {
+  const [isNavOpen, setIsNavOpen] = React.useState(false);
+  const isActiveSubStep = isWizardSubStep(activeStep);
+
+  const handleKeyClicks = React.useCallback(
+    (event: KeyboardEvent): void => {
+      if (isNavOpen && event.key === KeyTypes.Escape) {
+        setIsNavOpen(!isNavOpen);
+      }
+    },
+    [isNavOpen]
+  );
+
+  // Open/close collapsable nav on keydown event
+  React.useEffect(() => {
+    const target = typeof document !== 'undefined' ? document.body : null;
+    target?.addEventListener('keydown', handleKeyClicks, false);
+
+    return () => {
+      target?.removeEventListener('keydown', handleKeyClicks, false);
+    };
+  }, [handleKeyClicks]);
+
+  // Only render the active step when unmountInactiveSteps is true
+  const bodyContent = unmountInactiveSteps
+    ? activeStep?.component
+    : steps.map(step => {
+        if (activeStep?.name === step.name) {
+          return step.component;
+        }
+
+        return (
+          <div key={step.id} style={{ display: 'none' }}>
+            {step.component}
+          </div>
+        );
+      });
+
+  const wizardNav = isCustomWizardNav(nav)
+    ? nav(isNavOpen, steps, activeStep, goToStepByIndex)
+    : React.useMemo(() => {
+        const props = {
+          isOpen: isNavOpen,
+          'aria-label': nav?.ariaLabel || 'Wizard nav',
+          ...(nav?.ariaLabelledBy && { 'aria-labelledby': nav?.ariaLabelledBy })
+        };
+
+        return (
+          <WizardNav {...props}>
+            {steps.map((step, index) => {
+              const stepIndex = index + 1;
+              const stepNavItem = step.navItem && <React.Fragment key={step.id}>{step.navItem}</React.Fragment>;
+
+              if (isWizardParentStep(step)) {
+                let firstSubStepIndex;
+                let hasActiveChild = false;
+
+                const subNavItems = step.subStepIds?.map((subStepId, index) => {
+                  const subStep = steps.find(step => step.id === subStepId);
+                  const subStepIndex = steps.indexOf(subStep) + 1;
+
+                  if (index === 0) {
+                    firstSubStepIndex = subStepIndex;
+                  }
+
+                  if (activeStep?.id === subStep.id) {
+                    hasActiveChild = true;
+                  }
+
+                  return subStep.navItem ? (
+                    <React.Fragment key={subStep.id}>{subStep.navItem}</React.Fragment>
+                  ) : (
+                    <WizardNavItem
+                      key={subStep.id}
+                      id={subStep.id}
+                      content={subStep.name}
+                      isCurrent={activeStep?.id === subStep.id}
+                      isDisabled={subStep.isDisabled || (nav?.forceStepVisit && !subStep.visited)}
+                      step={subStepIndex}
+                      onNavItemClick={goToStepByIndex}
+                    />
+                  );
+                });
+
+                const hasEnabledChildren = React.Children.toArray(subNavItems).some(
+                  child => React.isValidElement(child) && !child.props.isDisabled
+                );
+
+                return (
+                  stepNavItem || (
+                    <WizardNavItem
+                      key={step.id}
+                      id={step.id}
+                      content={step.name}
+                      isExpandable={nav?.isExpandable}
+                      isCurrent={hasActiveChild}
+                      isDisabled={!hasEnabledChildren}
+                      step={firstSubStepIndex}
+                      onNavItemClick={goToStepByIndex}
+                    >
+                      <WizardNav {...props} returnList>
+                        {subNavItems}
+                      </WizardNav>
+                    </WizardNavItem>
+                  )
+                );
+              }
+
+              if (isWizardBasicStep(step)) {
+                return (
+                  stepNavItem || (
+                    <WizardNavItem
+                      key={step.id}
+                      id={step.id}
+                      content={step.name}
+                      isCurrent={activeStep?.id === step.id}
+                      isDisabled={step.isDisabled || (nav?.forceStepVisit && !step.visited)}
+                      step={stepIndex}
+                      onNavItemClick={goToStepByIndex}
+                    />
+                  )
+                );
+              }
+            })}
+          </WizardNav>
+        );
+      }, [activeStep?.id, goToStepByIndex, isNavOpen, nav, steps]);
+
+  return (
+    <>
+      <button
+        onClick={() => setIsNavOpen(prevIsOpen => !prevIsOpen)}
+        className={css(styles.wizardToggle, isNavOpen && 'pf-m-expanded')}
+        aria-label={ariaLabel}
+        aria-expanded={isNavOpen}
+      >
+        <span className={css(styles.wizardToggleList)}>
+          <span className={css(styles.wizardToggleListItem)}>
+            {activeStep?.name}
+            {isActiveSubStep && <AngleRightIcon className={css(styles.wizardToggleSeparator)} aria-hidden="true" />}
+          </span>
+          {isActiveSubStep && <span className={css(styles.wizardToggleListItem)}>{activeStep?.name}</span>}
+        </span>
+
+        <span className={css(styles.wizardToggleIcon)}>
+          <CaretDownIcon aria-hidden="true" />
+        </span>
+      </button>
+      <div className={css(styles.wizardOuterWrap)}>
+        <div className={css(styles.wizardInnerWrap)}>
+          {wizardNav}
+          {bodyContent}
+        </div>
+
+        {footer}
+      </div>
+    </>
+  );
+};
+
+WizardToggle.displayName = 'WizardToggle';

package/src/next/components/Wizard/__tests__/Wizard.test.tsx

@@ -0,0 +1,298 @@
+import React from 'react';
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { DefaultWizardNavProps, WizardControlStep, DefaultWizardFooterProps } from '../types';
+import { WizardNav, WizardNavItem, Wizard, WizardStep } from '../';
+
+describe('Wizard', () => {
+  it('renders step when child is of type WizardStep', () => {
+    render(
+      <Wizard>
+        <WizardStep id="test-step" name="Test step">
+          Step content
+        </WizardStep>
+      </Wizard>
+    );
+
+    expect(screen.getByRole('button', { name: 'Test step' })).toBeVisible();
+    expect(screen.getByText('Step content')).toBeVisible();
+  });
+
+  it('renders step when child has required props; name, id, children', () => {
+    const CustomStep = props => <div {...props} />;
+
+    render(
+      <Wizard>
+        <CustomStep id="test-step" name="Test step">
+          Custom step content
+        </CustomStep>
+      </Wizard>
+    );
+
+    expect(screen.getByRole('button', { name: 'Test step' })).toBeVisible();
+    expect(screen.getByText('Custom step content')).toBeVisible();
+  });
+
+  it('renders a header when specified', () => {
+    render(
+      <Wizard header="Some header">
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByText('Some header')).toBeVisible();
+  });
+
+  it('renders default footer without specifying the footer prop', () => {
+    render(
+      <Wizard>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByRole('button', { name: 'Next' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Back' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeVisible();
+  });
+
+  it('renders default footer with custom props', () => {
+    const footer: DefaultWizardFooterProps = {
+      nextButtonText: <>Proceed with caution</>,
+      backButtonText: 'Turn back!',
+      cancelButtonText: 'Leave now!'
+    };
+
+    render(
+      <Wizard footer={footer}>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByRole('button', { name: 'Proceed with caution' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Turn back!' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Leave now!' })).toBeVisible();
+  });
+
+  it('renders custom footer', () => {
+    render(
+      <Wizard footer={<>Some footer</>}>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByText('Some footer')).toBeVisible();
+  });
+
+  it('renders default nav without specifying the nav prop', () => {
+    render(
+      <Wizard>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByRole('navigation')).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Test step' })).toBeVisible();
+  });
+
+  it('renders default nav with custom props', () => {
+    const nav: DefaultWizardNavProps = {
+      isExpandable: true,
+      ariaLabel: 'Some nav label',
+      ariaLabelledBy: 'wizard-id',
+      forceStepVisit: true
+    };
+
+    render(
+      <Wizard id="wizard-id" nav={nav}>
+        <WizardStep id="step-1" name="Test step 1" steps={[<WizardStep id="nested-step" name="Nested step" />]} />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    const navElement = screen.getByLabelText('Some nav label');
+
+    expect(navElement).toBeVisible();
+    expect(navElement).toHaveAttribute('aria-labelledby', 'wizard-id');
+    expect(screen.getByRole('button', { name: 'Test step 1' }).parentElement).toHaveClass('pf-m-expandable');
+    expect(screen.getByRole('button', { name: 'Test step 2' })).toHaveAttribute('disabled');
+  });
+
+  it('renders custom nav', () => {
+    const nav = (
+      isOpen: boolean,
+      steps: WizardControlStep[],
+      activeStep: WizardControlStep,
+      goToStepByIndex: (index: number) => void
+    ) => (
+      <WizardNav isOpen={isOpen}>
+        {steps.map((step, index) => (
+          <WizardNavItem
+            key={step.id}
+            id={step.id}
+            content={step.name}
+            isCurrent={activeStep.id === step.id}
+            isDisabled={step.isDisabled}
+            step={index + 1}
+            onNavItemClick={goToStepByIndex}
+          />
+        ))}
+      </WizardNav>
+    );
+
+    render(
+      <Wizard nav={nav}>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByRole('navigation')).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Test step' })).toBeVisible();
+  });
+
+  it('starts at the first step as the active one by default', () => {
+    render(
+      <Wizard>
+        <WizardStep id="step-1" name="Test step 1">
+          Step 1 content
+        </WizardStep>
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    expect(screen.getByText('Step 1 content')).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Test step 1' })).toHaveClass('pf-m-current');
+  });
+
+  it(`can start at a step that isn't the first by specifying 'startIndex'`, () => {
+    render(
+      <Wizard startIndex={2}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2">
+          Step 2 content
+        </WizardStep>
+      </Wizard>
+    );
+
+    expect(screen.getByText('Step 2 content')).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Test step 2' })).toHaveClass('pf-m-current');
+  });
+
+  it(`can use custom classNames and spread other props into the wizard's div`, () => {
+    render(
+      <Wizard className="some-class" data-testid="wizard-id">
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    expect(screen.getByTestId('wizard-id')).toHaveClass('some-class');
+  });
+
+  it(`can customize the wizard's height and width`, () => {
+    render(
+      <Wizard height={500} width={500} data-testid="wizard-id">
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    const wizard = screen.getByTestId('wizard-id');
+
+    expect(wizard).toHaveStyle('height: 500px');
+    expect(wizard).toHaveStyle('width: 500px');
+  });
+
+  it('calls onNavByIndex on nav item click', () => {
+    const onNavByIndex = jest.fn();
+
+    render(
+      <Wizard onNavByIndex={onNavByIndex}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Test step 2' }));
+    expect(onNavByIndex).toHaveBeenCalled();
+  });
+
+  it('calls onNext and not onSave on next button click when not on the last step', () => {
+    const onNext = jest.fn();
+    const onSave = jest.fn();
+
+    render(
+      <Wizard onNext={onNext} onSave={onSave}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Next' }));
+
+    expect(onNext).toHaveBeenCalled();
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  it('calls onBack on back button click', () => {
+    const onBack = jest.fn();
+
+    render(
+      <Wizard onBack={onBack}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Test step 2' }));
+    userEvent.click(screen.getByRole('button', { name: 'Back' }));
+
+    expect(onBack).toHaveBeenCalled();
+  });
+
+  it('calls onSave and not onClose on next button click when on the last step', () => {
+    const onSave = jest.fn();
+    const onClose = jest.fn();
+
+    render(
+      <Wizard onSave={onSave} onClose={onClose}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Test step 2' }));
+    userEvent.click(screen.getByRole('button', { name: 'Next' }));
+
+    expect(onSave).toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('calls onClose when onSave is not specified on next button click when on the last step', () => {
+    const onClose = jest.fn();
+
+    render(
+      <Wizard onClose={onClose}>
+        <WizardStep id="step-1" name="Test step 1" />
+        <WizardStep id="step-2" name="Test step 2" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Test step 2' }));
+    userEvent.click(screen.getByRole('button', { name: 'Next' }));
+
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('calls onClose on cancel link click', () => {
+    const onClose = jest.fn();
+
+    render(
+      <Wizard onClose={onClose}>
+        <WizardStep id="test-step" name="Test step" />
+      </Wizard>
+    );
+
+    userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+    expect(onClose).toHaveBeenCalled();
+  });
+});

package/src/next/components/Wizard/examples/Wizard.md

@@ -0,0 +1,125 @@
+---
+id: Wizard
+section: components
+cssPrefix: pf-c-wizard
+propComponents:
+  [
+    'Wizard',
+    'WizardFooter',
+    'WizardToggle',
+    'WizardStep',
+    'WizardBody',
+    'WizardHeader',
+    'WizardNav',
+    'WizardNavItem',
+    'WizardContextProps',
+    'WizardBasicStep',
+    'WizardParentStep',
+    'WizardSubStep',
+    'DefaultWizardNavProps',
+    'DefaultWizardFooterProps',
+  ]
+beta: true
+---
+
+import {
+FormGroup,
+TextInput,
+Drawer,
+DrawerContent,
+Button,
+Flex,
+DrawerPanelContent,
+DrawerColorVariant,
+DrawerHead,
+DrawerActions,
+DrawerCloseButton
+} from '@patternfly/react-core';
+import {
+Wizard,
+WizardFooter,
+WizardToggle,
+WizardStep,
+WizardBody,
+useWizardFooter,
+useWizardContext,
+WizardNavItem,
+WizardNav,
+WizardHeader
+} from '@patternfly/react-core/next';
+import { css } from '@patternfly/react-styles';
+import styles from '@patternfly/react-styles/css/components/Wizard/wizard';
+
+PatternFly has two implementations of a `Wizard`. This newer `Wizard` takes a more explicit and declarative approach compared to the older implementation, which can be found under the [React](/components/wizard/react) tab.
+
+## Examples
+
+### Basic
+
+```ts file="./WizardBasic.tsx"
+```
+
+### Custom navigation
+
+The `Wizard`'s `nav` property can be used to build your own navigation.
+
+```
+/** Callback for the Wizard's 'nav' property. Returns element which replaces the Wizard's default navigation. */
+export type CustomWizardNavFunction = (
+  isOpen: boolean,
+  steps: WizardControlStep[],
+  activeStep: WizardControlStep,
+  goToStepByIndex: (index: number) => void
+) => React.ReactElement<WizardNavProps>;
+
+/** Encompasses all step type variants that are internally controlled by the Wizard */
+type WizardControlStep = WizardBasicStep | WizardParentStep | WizardSubStep;
+```
+
+```ts file="./WizardCustomNav.tsx"
+```
+
+### Kitchen sink
+
+Includes a header, custom footer, sub-steps, step content with a drawer, custom nav item, and nav prevention until step visitation.
+
+Custom operations when navigating between steps can be achieved by utilizing `onNext`, `onBack` or `onNavByIndex` properties whose callback functions return the 'id' and 'name' of the currently focused step (currentStep), and the previously focused step (previousStep).
+
+```
+/** Callback for the Wizard's 'onNext', 'onBack', and 'onNavByIndex' properties */
+type WizardNavStepFunction = (currentStep: WizardNavStepData, previousStep: WizardNavStepData) => void;
+
+/** Data returned for either parameter of WizardNavStepFunction */
+type WizardNavStepData = Pick<WizardControlStep, 'id' | 'name'>;
+```
+
+```ts file="./WizardKitchenSink.tsx"
+```
+
+## Hooks
+
+### useWizardFooter
+
+Used to set a unique footer for the wizard on any given step. See step 3 of [Kitchen sink](#kitchen-sink) for a live example.
+
+```noLive
+import { useWizardFooter } from '@patternfly/react-core/next';
+
+const StepContent = () => {
+  useWizardFooter(<>Some footer</>);
+  return <>Step content</>;
+}
+```
+
+### useWizardContext
+
+Used to access any property of [WizardContext](#wizardcontextprops):
+
+```noLive
+import { useWizardContext } from '@patternfly/react-core/next';
+
+const StepContent = () => {
+  const { activeStep } = useWizardContext();
+  return <>This is the active step: {activeStep}</>;
+}
+```

package/src/next/components/Wizard/examples/WizardBasic.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { Wizard, WizardStep } from '@patternfly/react-core/next';
+
+export const WizardBasic: React.FunctionComponent = () => (
+  <Wizard height={400}>
+    <WizardStep name="First step" id="basic-first-step">
+      <p>Step 1 content</p>
+    </WizardStep>
+    <WizardStep name="Second step" id="basic-second-step">
+      <p>Step 2 content</p>
+    </WizardStep>
+    <WizardStep name="Third step" id="basic-third-step">
+      <p>Step 3 content</p>
+    </WizardStep>
+    <WizardStep name="Fourth step" id="basic-fourth-step">
+      <p>Step 4 content</p>{' '}
+    </WizardStep>
+    <WizardStep name="Review" id="basic-review-step" nextButtonText="Finish">
+      <p>Review step content</p>
+    </WizardStep>
+  </Wizard>
+);