@patternfly/react-core 4.234.4 → 4.235.0

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';

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

@@ -0,0 +1,101 @@
+import React from 'react';
+import { WizardNavProps, WizardNavItemProps } from '../Wizard';
+
+/** Type used to define 'basic' steps, or in other words, steps that are neither parents or children of parents. */
+export interface WizardBasicStep {
+  /** Name of the step's nav item */
+  name: React.ReactNode;
+  /** Unique identifier */
+  id: string | number;
+  /** Flag to disable the step's nav item */
+  isDisabled?: boolean;
+  /** Flag to represent whether the step has been visited (navigated to) */
+  visited?: boolean;
+  /** Content shown when the step's nav item is selected. When treated as a parent step, only sub-step content will be shown. */
+  component?: React.ReactElement;
+  /** (Unused if nav is controlled) Custom WizardNavItem */
+  navItem?: React.ReactElement<WizardNavItemProps>;
+  /** (Unused if footer is controlled) Can change the Next button text. If nextButtonText is also set for the Wizard, this step specific one overrides it. */
+  nextButtonText?: React.ReactNode;
+  /** (Unused if footer is controlled) The condition needed to disable the Next button */
+  disableNext?: boolean;
+  /** (Unused if footer is controlled) True to hide the Cancel button */
+  hideCancelButton?: boolean;
+  /** (Unused if footer is controlled) True to hide the Back button */
+  hideBackButton?: boolean;
+}
+
+/** Type used to define parent steps. */
+export interface WizardParentStep extends WizardBasicStep {
+  /** Nested step IDs */
+  subStepIds: string[];
+}
+
+/** Type used to define sub-steps. */
+export interface WizardSubStep extends WizardBasicStep {
+  /** Unique identifier of the parent step */
+  parentId: string | number;
+}
+
+/** Used to customize aspects of the Wizard's default navigation. */
+export interface DefaultWizardNavProps {
+  /** Flag indicating nav items with sub steps are expandable */
+  isExpandable?: boolean;
+  /** Aria-label for the Nav */
+  ariaLabel?: string;
+  /** Sets aria-labelledby on nav element */
+  ariaLabelledBy?: string;
+  /** Disable step nav items until they are visited */
+  forceStepVisit?: boolean;
+}
+
+/** Used to customize aspects of the Wizard's default footer. */
+export interface DefaultWizardFooterProps {
+  /** The Next button text */
+  nextButtonText?: React.ReactNode;
+  /** The Back button text */
+  backButtonText?: React.ReactNode;
+  /** The Cancel button text */
+  cancelButtonText?: React.ReactNode;
+}
+
+/** Encompasses all step type variants that are internally controlled by the Wizard. */
+export type WizardControlStep = WizardBasicStep | WizardParentStep | WizardSubStep;
+
+/** Callback for the Wizard's 'onNext', 'onBack', and 'onNavByIndex' properties. */
+export type WizardNavStepFunction = (currentStep: WizardNavStepData, previousStep: WizardNavStepData) => void;
+
+/** Data returned for either parameter of WizardNavStepFunction. */
+export type WizardNavStepData = Pick<WizardControlStep, 'id' | 'name'>;
+
+/** 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>;
+
+export function isCustomWizardNav(
+  nav: DefaultWizardNavProps | CustomWizardNavFunction
+): nav is CustomWizardNavFunction {
+  return typeof nav === 'function';
+}
+
+export function isCustomWizardFooter(
+  footer: DefaultWizardFooterProps | React.ReactElement
+): footer is React.ReactElement {
+  return React.isValidElement(footer);
+}
+
+export function isWizardBasicStep(step: WizardControlStep): step is WizardBasicStep {
+  return (step as WizardParentStep)?.subStepIds === undefined && !isWizardSubStep(step);
+}
+
+export function isWizardSubStep(step: WizardControlStep): step is WizardSubStep {
+  return (step as WizardSubStep)?.parentId !== undefined;
+}
+
+export function isWizardParentStep(step: WizardControlStep): step is WizardParentStep {
+  return (step as WizardParentStep)?.subStepIds !== undefined;
+}

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

@@ -0,0 +1,47 @@
+import React from 'react';
+
+import { WizardControlStep, WizardNavStepData } from './types';
+import { WizardStep, WizardStepProps } from './WizardStep';
+
+function hasWizardStepProps(props: WizardStepProps | any): props is WizardStepProps {
+  return props.name !== undefined && props.id !== undefined && props.children !== undefined;
+}
+
+/**
+ * Accumulate list of step & sub-step props pulled from child components
+ * @param children
+ * @returns WizardControlStep[]
+ */
+export const buildSteps = (children: React.ReactElement<WizardStepProps> | React.ReactElement<WizardStepProps>[]) =>
+  React.Children.toArray(children).reduce((acc: WizardControlStep[], child) => {
+    if (React.isValidElement(child)) {
+      if (child.type === WizardStep || hasWizardStepProps(child.props)) {
+        // Omit "children" and use the whole "child" (WizardStep) for the component prop. Sub-steps will do the same.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { steps: subSteps, id, children, ...stepProps } = child.props as WizardStepProps;
+
+        acc.push({
+          id,
+          component: child,
+          ...stepProps,
+          ...(subSteps && {
+            subStepIds: subSteps?.map(subStep => {
+              // eslint-disable-next-line @typescript-eslint/no-unused-vars
+              const { children, ...subStepProps } = subStep.props;
+              acc.push({ ...subStepProps, component: subStep, parentId: id });
+
+              return subStep.props.id;
+            })
+          })
+        });
+      } else {
+        throw new Error('Wizard only accepts children of type WizardStep');
+      }
+    }
+
+    return acc;
+  }, []);
+
+export const normalizeNavStep = ({ id, name }: WizardNavStepData) => ({ id, name });
+export const getActiveStep = (steps: WizardControlStep[], currentStepIndex: number) =>
+  steps.find((_, index) => index + 1 === currentStepIndex);

package/src/next/components/index.ts

@@ -1 +1 @@
-export * from './';
+export * from './Wizard';