@patternfly/react-core 4.234.2 → 4.235.0

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>
+);

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

@@ -0,0 +1,46 @@
+import React from 'react';
+import {
+  Wizard,
+  WizardStep,
+  WizardControlStep,
+  CustomWizardNavFunction,
+  WizardNav,
+  WizardNavItem
+} from '@patternfly/react-core/next';
+
+export const WizardCustomNav: React.FunctionComponent = () => {
+  const nav: CustomWizardNavFunction = (
+    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>
+  );
+
+  return (
+    <Wizard height={400} nav={nav}>
+      <WizardStep name="First step" id="cnav-first-step">
+        <p>Did you say...custom nav?</p>
+      </WizardStep>
+      <WizardStep name="Second step" id="cnav-second-step">
+        <p>Step 2 content</p>
+      </WizardStep>
+      <WizardStep name="Review" id="cnav-review-step" nextButtonText="Wrap it up">
+        <p>Review step content</p>
+      </WizardStep>
+    </Wizard>
+  );
+};

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

@@ -0,0 +1,170 @@
+import React from 'react';
+
+import {
+  FormGroup,
+  TextInput,
+  Drawer,
+  DrawerContent,
+  Button,
+  Flex,
+  DrawerPanelContent,
+  DrawerColorVariant,
+  DrawerHead,
+  DrawerActions,
+  DrawerCloseButton
+} from '@patternfly/react-core';
+import {
+  Wizard,
+  WizardStep,
+  WizardBody,
+  WizardFooter,
+  WizardStepProps,
+  WizardControlStep,
+  useWizardFooter,
+  useWizardContext,
+  WizardNavStepFunction,
+  WizardNavStepData,
+  WizardNavItem,
+  WizardHeader
+} from '@patternfly/react-core/next';
+import { css } from '@patternfly/react-styles';
+import styles from '@patternfly/react-styles/css/components/Wizard/wizard';
+
+const CustomWizardFooter = () => {
+  const { activeStep, onNext, onBack, onClose } = useWizardContext();
+  return <WizardFooter activeStep={activeStep} onNext={onNext} onBack={onBack} onClose={onClose} />;
+};
+
+const CustomNavItem = () => {
+  const { steps, activeStep, goToStepByIndex } = useWizardContext();
+  const step = (steps.find(step => step.id === 'third-step') || {}) as WizardControlStep;
+
+  return (
+    <WizardNavItem
+      id={step.id}
+      content={<span style={{ color: 'var(--pf-global--default-color--200)' }}>Custom item</span>}
+      isCurrent={activeStep.id === step.id}
+      step={steps.indexOf(step) + 1}
+      isDisabled={step.isDisabled || !step.visited}
+      onNavItemClick={goToStepByIndex}
+    />
+  );
+};
+
+const StepContentWithDrawer = () => {
+  const [isDrawerExpanded, setIsDrawerExpanded] = React.useState(false);
+
+  return (
+    <Drawer isInline isExpanded={isDrawerExpanded}>
+      <DrawerContent
+        panelContent={
+          <DrawerPanelContent widths={{ default: 'width_33' }} colorVariant={DrawerColorVariant.light200}>
+            <DrawerHead>
+              <span tabIndex={isDrawerExpanded ? 0 : -1}>drawer content</span>
+              <DrawerActions>
+                <DrawerCloseButton onClick={() => setIsDrawerExpanded(false)} />
+              </DrawerActions>
+            </DrawerHead>
+          </DrawerPanelContent>
+        }
+      >
+        <WizardBody>
+          <Flex direction={{ default: 'column' }}>
+            {!isDrawerExpanded && (
+              <Button isInline variant="link" onClick={() => setIsDrawerExpanded(prevExpanded => !prevExpanded)}>
+                Open drawer
+              </Button>
+            )}
+
+            <FormGroup fieldId="some-text-input" label="Text input label">
+              <TextInput aria-label="Some Text Input Label" />
+            </FormGroup>
+          </Flex>
+        </WizardBody>
+      </DrawerContent>
+    </Drawer>
+  );
+};
+
+const StepWithCustomFooter = () => {
+  const { onNext: goToNextStep, onBack, onClose } = useWizardContext();
+  const [isLoading, setIsLoading] = React.useState(false);
+
+  async function onNext(goToStep: () => void) {
+    setIsLoading(true);
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    setIsLoading(false);
+
+    goToStep();
+  }
+
+  const footer = React.useMemo(
+    () => (
+      <div className={css(styles.wizardFooter)}>
+        <Button
+          variant="primary"
+          type="submit"
+          onClick={() => onNext(goToNextStep)}
+          isLoading={isLoading}
+          isDisabled={isLoading}
+        >
+          Async Next
+        </Button>
+        <Button variant="secondary" onClick={onBack}>
+          Back
+        </Button>
+        <Button variant="link" onClick={onClose}>
+          Cancel
+        </Button>
+      </div>
+    ),
+    [isLoading, onBack, onClose, goToNextStep]
+  );
+  useWizardFooter(footer);
+
+  return <>Step 3 content w/ custom async footer</>;
+};
+
+const CustomStepFour = (props: WizardStepProps) => <div {...props} id={props.id.toString()} />;
+
+export const WizardKitchenSink: React.FunctionComponent = () => {
+  const onNext: WizardNavStepFunction = (currentStep: WizardNavStepData, previousStep: WizardNavStepData) => {
+    // eslint-disable-next-line no-console
+    console.log('currentStep: ', currentStep, '\n previousStep: ', previousStep);
+  };
+
+  return (
+    <Wizard
+      height={400}
+      header={<WizardHeader title="You're a wizard, Harry" closeButtonAriaLabel="Close header" />}
+      footer={<CustomWizardFooter />}
+      nav={{ forceStepVisit: true, isExpandable: true }}
+      onNext={onNext}
+    >
+      <WizardStep id="sink-first-step" name="First step" body={null}>
+        <StepContentWithDrawer />
+      </WizardStep>
+      <WizardStep
+        id="sink-second-step"
+        name="Second step"
+        steps={[
+          <WizardStep id="sink-sub-step-one" key="substep-one" name="Substep 1">
+            Substep 1 content
+          </WizardStep>,
+          <WizardStep id="sink-sub-step-two" key="substep-two" name="Substep 2">
+            Substep 2 content
+          </WizardStep>
+        ]}
+      />
+      <WizardStep id="sink-third-step" name="Third step" navItem={<CustomNavItem />}>
+        <StepWithCustomFooter />
+      </WizardStep>
+      <CustomStepFour id="sink-fourth-step" name="Fourth step">
+        <WizardBody>Step 4 content</WizardBody>
+      </CustomStepFour>
+      <WizardStep id="sink-review-step" name="Review" nextButtonText="Submit">
+        Review step content
+      </WizardStep>
+    </Wizard>
+  );
+};

package/src/next/components/Wizard/hooks/index.ts

@@ -0,0 +1 @@
+export { useWizardFooter } from './useWizardFooter';

package/src/next/components/Wizard/hooks/useWizardFooter.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { useWizardContext } from '../WizardContext';
+
+/**
+ * Set a unique footer for the wizard. stepId is only required if inactive steps are hidden instead of unmounted.
+ * @param footer
+ * @param stepId
+ */
+export const useWizardFooter = (footer: React.ReactElement, stepId?: string | number) => {
+  const { activeStep, setFooter } = useWizardContext();
+
+  React.useEffect(() => {
+    if (!stepId || activeStep.id === stepId) {
+      setFooter(footer);
+
+      // Reset the footer on unmount.
+      return () => {
+        setFooter(null);
+      };
+    }
+  }, [activeStep, footer, setFooter, stepId]);
+};

package/src/next/components/Wizard/index.ts

@@ -0,0 +1,11 @@
+export * from './Wizard';
+export * from './WizardBody';
+export * from './WizardFooter';
+export * from './WizardToggle';
+export * from './WizardStep';
+export * from './WizardNav';
+export * from './WizardNavItem';
+export * from './WizardHeader';
+export * from './hooks';
+export * from './types';
+export { useWizardContext } from './WizardContext';