@indico-data/design-system 2.58.1 → 2.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indico-data/design-system",
-  "version": "2.58.1",
+  "version": "2.59.0",
   "description": "",
   "author": "",
   "main": "lib/index.js",
@@ -45,7 +45,6 @@
     "date-fns": "^3.6.0",
     "focus-trap-react": "^10.2.3",
     "html-webpack-plugin": "^5.6.0",
-    "nanoid": "^5.1.5",
     "prop-types": "^15.8.1",
     "react-aria-components": "^1.2.1",
     "react-data-table-component": "^7.6.2",

package/src/components/index.ts

@@ -27,3 +27,4 @@ export { BarSpinner } from './loading-indicators/BarSpinner/BarSpinner';
 export { CirclePulse } from './loading-indicators/CirclePulse/CirclePulse';
 export { Truncate } from './truncate';
 export { toast, ToastContainer } from 'react-toastify';
+export { Stepper } from './stepper';

package/src/components/stepper/Stepper.mdx

@@ -0,0 +1,140 @@
+import { Canvas, Meta, Controls } from '@storybook/blocks';
+import * as Stepper from './Stepper.stories';
+
+<Meta title="Components/Stepper" name="Stepper" />
+
+# Stepper
+The Stepper component is used to guide users through a series of steps. It is managed via a steps array of objects and individual steps inside the component.
+
+<Canvas of={Stepper.CommonExampleStory} />
+
+<Controls of={Stepper.CommonExampleStory} />
+
+## Usage
+In order to use the stepper, you have various options. You could have a stepper with all steps required, meaning that you must complete the current step before you can proceed to the next step. You also have the option to mix and match other steps between required and optional. You can also make all steps optional as well. The other examples demonstrate those settings. For the sake of time, we currently only have all required as a documented example below.
+
+### All Steps Required
+#### Data
+Copy the data below to recreate the example displayed on this page.
+```ts
+const exampleSteps = [
+    {
+      id: 'step1',
+      label: 'Application Information',
+      isCompleted: false,
+      isOptional: false,
+      isSidebarEnabled: true,
+      isNextDisabled: false,
+    },
+    {
+      id: 'step2',
+      label: 'Agent Information',
+      isCompleted: false,
+      isOptional: false,
+      isSidebarEnabled: false,
+      isNextDisabled: true,
+    },
+    {
+      id: 'step3',
+      label: 'User Information',
+      isCompleted: false,
+      isOptional: false,
+      isSidebarEnabled: false,
+      isNextDisabled: true,
+    },
+  ];
+```
+
+#### Functions And Components
+Copy the functions and components below to recreate the example displayed on this page.
+```tsx
+
+  // This sets up the data for the stepper on a parent component. We want to follow this process to maintain state outside of the stepper component.
+  const [currentStep, setCurrentStep] = useState(0); // This handles the current step that is being viewed.
+  const [steps, setSteps] = useState(exampleSteps); // This is the list of all the steps, matching up in index order with the children of the stepper.
+
+  // This handles what happens when the back button is clicked on the stepper. The current step is decremented by 1.
+  const handleBackClick = () => {
+    setCurrentStep(currentStep - 1);
+  };
+
+  // Handles next button click - only proceeds if current step is completed. We set the sidebar for the next step to enabled and we enable the next step. Then, we increment the current step by 1.
+  const handleNextClick = () => {
+    const currentStepData = steps[currentStep];
+    if (currentStepData && currentStepData.isCompleted) {
+      setSteps(
+        steps.map((step, index) =>
+          index === currentStep + 1
+            ? { ...step, isSidebarEnabled: true, isNextDisabled: false }
+            : step,
+        ),
+      );
+      setCurrentStep(currentStep + 1);
+    }
+  };
+
+  // This handles what happens when a step is clicked on the sidebar. We only allow clicking on enabled steps in the sidebar. Then, we set the current step to the step that was clicked.
+  const handleSidebarNavigationItemClick = (step: number) => {
+    if (steps[step].isSidebarEnabled) {
+      setCurrentStep(step);
+    }
+  };
+
+  // This handles what happens when a step is completed. We set the current step as completed and we enable the next step in the sidebar.
+  const handleOnStepCompletion = (step: number) => {
+    setSteps(
+      steps.map((currentStep, index) => {
+        if (index === step) {
+          // Mark current step as completed
+          return { ...currentStep, isCompleted: true, isNextDisabled: false };
+        } else if (index === step + 1) {
+          // Enable the next step in the sidebar
+          return { ...currentStep, isSidebarEnabled: true };
+        } else {
+          return currentStep;
+        }
+      }),
+    );
+  };
+
+  // This handles what happens when the finish button is clicked. We check if all steps are completed. If they are, we show a success message. If they are not, we show an error message.
+  const handleCompleteStepperClick = () => {
+    // if all steps are completed, then show a success message
+    if (steps.every((step) => step.isCompleted)) {
+      alert('Successfully completed all required steps!');
+    } else {
+      alert('You must complete all steps before finishing.');
+    }
+  };
+
+  return (
+    <Stepper
+      steps={steps}
+      currentStep={currentStep}
+      legendHeader={
+        <div>
+          <h1>Publish Agent To Gallery</h1>
+          <p className="subtitle-2 color-tertiary-200 mt-2 mb-6">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore.
+          </p>
+        </div>
+      }
+      legendFooter={
+        <p className="subtitle-2 color-tertiary-200 mt-6">Example of a legend footer</p>
+      }
+      onBackClick={handleBackClick}
+      onNextClick={handleNextClick}
+      onFinishClick={handleCompleteStepperClick}
+      onStepClick={handleSidebarNavigationItemClick}
+    >
+      <StepOne onCompletion={() => handleOnStepCompletion(0)} /> // index 0 of the steps array
+      <StepTwo onCompletion={() => handleOnStepCompletion(1)} /> // index 1 of the steps array
+      <StepThree onCompletion={() => handleOnStepCompletion(2)} /> // index 2 of the steps array
+    </Stepper>
+  );
+};
+```
+
+## TODO
+-- Document the other examples

package/src/components/stepper/Stepper.stories.tsx

@@ -0,0 +1,196 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { Stepper } from './Stepper';
+import { indiconDefinitions } from '@/components/icons/indicons';
+import { registerFontAwesomeIcons } from '@/setup/setupIcons';
+registerFontAwesomeIcons(...Object.values(fas), ...indiconDefinitions);
+
+// Import all example components
+import { MixedExample } from './examples/MixedExample';
+import { RequiredStepsExample } from './examples/RequiredStepsExample';
+import { OptionalStepsExample } from './examples/OptionalStepsExample';
+import { CommonExample } from './examples/commonExample/CommonExample';
+import { fas } from '@fortawesome/free-solid-svg-icons';
+
+const meta: Meta = {
+  title: 'Components/Stepper',
+  component: Stepper,
+  argTypes: {
+    legendHeader: {
+      control: false,
+      description: 'The header content for the legend.',
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'ReactNode',
+        },
+      },
+    },
+    legendFooter: {
+      control: false,
+      description: 'The footer content for the legend.',
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'ReactNode',
+        },
+      },
+    },
+    steps: {
+      control: false,
+      description: 'An array of step objects that define the stepper navigation.',
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'Step[]',
+        },
+      },
+    },
+    label: {
+      description: 'Display text for the step in the sidebar/legend',
+      table: {
+        category: 'Step Properties',
+        type: {
+          summary: 'string',
+        },
+      },
+      control: false,
+    },
+    isCompleted: {
+      description:
+        'Indicates whether this step has been completed. Used to track progress and determine whether to enable subsequent steps.',
+      table: {
+        category: 'Step Properties',
+        type: {
+          summary: 'boolean',
+        },
+        defaultValue: { summary: 'false' },
+      },
+      control: false,
+    },
+    isNextDisabled: {
+      description:
+        'When true, the Next button will be disabled for this step. Set to true for steps that require completion before proceeding.',
+      table: {
+        category: 'Step Properties',
+        type: {
+          summary: 'boolean',
+        },
+        defaultValue: { summary: 'false' },
+      },
+      control: false,
+    },
+    isOptional: {
+      description:
+        'When true, the step can be skipped (the Next button remains enabled). Used for optional information or steps that are not required to complete the flow.',
+      table: {
+        category: 'Step Properties',
+        type: {
+          summary: 'boolean',
+        },
+        defaultValue: { summary: 'false' },
+      },
+      control: false,
+    },
+    isSidebarEnabled: {
+      description:
+        'When true, the step is clickable in the sidebar. Used for restricting navigation until previous steps are completed.',
+      table: {
+        category: 'Step Properties',
+        type: {
+          summary: 'boolean',
+        },
+        defaultValue: { summary: 'true' },
+      },
+      control: false,
+    },
+    currentStep: {
+      control: false,
+      description:
+        'The current step of the stepper. This value should be an index of the steps array.',
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'number',
+        },
+      },
+      defaultValue: 0,
+    },
+    onBackClick: {
+      control: false,
+      description: 'The function to call when the back button is clicked.',
+      table: {
+        category: 'Callbacks',
+        type: {
+          summary: '() => void',
+        },
+      },
+    },
+    onFinishClick: {
+      control: false,
+      description: 'The function to call when the finish button is clicked.',
+      table: {
+        category: 'Callbacks',
+        type: {
+          summary: '() => void',
+        },
+      },
+    },
+    onStepClick: {
+      control: false,
+      description: 'The function to call when a step is clicked ont he legend.',
+      table: {
+        category: 'Callbacks',
+        type: {
+          summary: '(step: number) => void',
+        },
+      },
+    },
+    onNextClick: {
+      control: false,
+      description: 'The function to call when the next button is clicked.',
+      table: {
+        category: 'Callbacks',
+        type: {
+          summary: '() => void',
+        },
+      },
+    },
+    children: {
+      control: false,
+      description: 'Any item passed to this component as a child will be rendered as a step.',
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'ReactNode',
+        },
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Stepper>;
+
+export const CommonExampleStory: Story = {
+  name: 'Common Example',
+  render: () => <CommonExample />,
+};
+
+export const MixedExampleStory: Story = {
+  args: {},
+  name: 'Mixed Example',
+  render: () => <MixedExample />,
+};
+
+export const RequiredStepsStory: Story = {
+  args: {},
+  name: 'Required Steps',
+  render: () => <RequiredStepsExample />,
+};
+
+export const OptionalStepsStory: Story = {
+  args: {},
+  name: 'Optional Steps',
+  render: () => <OptionalStepsExample />,
+};

package/src/components/stepper/Stepper.tsx

@@ -0,0 +1,85 @@
+import { useState, Children } from 'react';
+import { Legend } from './components/Legend';
+import { BackNavigation } from './components/BackNavigation';
+import { NextNavigation } from './components/NextNavigation';
+import { StepperProps } from './types';
+
+export const Stepper = ({
+  currentStep: externalCurrentStep,
+  legendHeader,
+  legendFooter,
+  steps,
+  onBackClick,
+  onNextClick,
+  onFinishClick,
+  children,
+  onStepClick,
+}: StepperProps) => {
+  const [internalCurrentStep, setInternalCurrentStep] = useState(0);
+
+  const currentStep = externalCurrentStep !== undefined ? externalCurrentStep : internalCurrentStep;
+
+  // Convert children to array to access by index
+  const childrenArray = Children.toArray(children);
+  const totalSteps = childrenArray.length;
+
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === totalSteps - 1;
+
+  const handleBackClick = () => {
+    if (onBackClick) {
+      onBackClick();
+    } else if (!isFirstStep) {
+      setInternalCurrentStep(currentStep - 1);
+    }
+  };
+
+  const handleNextClick = () => {
+    if (onNextClick) {
+      onNextClick();
+    } else if (!isLastStep) {
+      setInternalCurrentStep(currentStep + 1);
+    }
+  };
+
+  const handleFinishClick = () => {
+    if (onFinishClick) {
+      onFinishClick();
+    }
+  };
+
+  const handleStepClick = (step: number) => {
+    onStepClick?.(step);
+  };
+
+  // If step is optional, and its not the last step, then enable the next button
+  const disableNextButton = (step: number) => {
+    return steps[step].isOptional || !steps[step].isCompleted;
+  };
+
+  return (
+    <div className="stepper">
+      <div className="legend">
+        <div className="legend-header">{legendHeader}</div>
+        <div className="legend-body">
+          <Legend currentStep={currentStep} steps={steps} onStepClick={handleStepClick} />
+        </div>
+        <div className="legend-footer">{legendFooter}</div>
+      </div>
+      <div className="stepper-body">
+        <div className="stepper-content">
+          <div className="stepper-steps">{childrenArray[currentStep]}</div>
+        </div>
+        <div className="stepper-actions">
+          <BackNavigation isDisabled={isFirstStep} onBackClick={handleBackClick} />
+          <NextNavigation
+            isLastStep={isLastStep}
+            onNextClick={handleNextClick}
+            onFinishClick={handleFinishClick}
+            isDisabled={disableNextButton(currentStep)}
+          />
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/components/stepper/__tests__/Stepper.tests.tsx

@@ -0,0 +1,213 @@
+import { render, screen } from '@testing-library/react';
+import { Stepper } from '../Stepper';
+import { StepOne } from '../examples/commonExample/steps/StepOne';
+import { StepTwo } from '../examples/commonExample/steps/StepTwo';
+import { StepThree } from '../examples/commonExample/steps/StepThree';
+import userEvent from '@testing-library/user-event';
+import React from 'react';
+
+// NOTES ================================================
+// The core functionality of the stepper is mainly various callbacks. As a result, we are indirectly testing them through the testing conditions created in this file. For example, to check if a step is complete, we have a callback function that fires when that step is complete. You will need to test your own logic in your implementation as the conditions tested here are for the purposes of the stepper itself, not the handlers we created.
+
+const exampleSteps = [
+  {
+    id: 'step1',
+    label: 'Application Name',
+    isCompleted: false,
+    isOptional: false,
+    isSidebarEnabled: true,
+    isNextDisabled: false,
+  },
+  {
+    id: 'step2',
+    label: 'Agent Information',
+    isCompleted: false,
+    isOptional: false,
+    isSidebarEnabled: false,
+    isNextDisabled: true,
+  },
+  {
+    id: 'step3',
+    label: 'User Information',
+    isCompleted: false,
+    isOptional: false,
+    isSidebarEnabled: false,
+    isNextDisabled: true,
+  },
+];
+
+// Test wrapper component to handle state
+const TestStepperWrapper = ({ initialStep = 0 }) => {
+  const [currentStep, setCurrentStep] = React.useState(initialStep);
+  const [steps, setSteps] = React.useState(exampleSteps);
+
+  const handleBackClick = () => {
+    setCurrentStep(Math.max(0, currentStep - 1));
+  };
+
+  const handleNextClick = () => {
+    const currentStepData = steps[currentStep];
+    if (currentStepData && currentStepData.isCompleted) {
+      setSteps(
+        steps.map((step, index) =>
+          index === currentStep + 1
+            ? { ...step, isSidebarEnabled: true, isNextDisabled: false }
+            : step,
+        ),
+      );
+      setCurrentStep(Math.min(steps.length - 1, currentStep + 1));
+    }
+  };
+
+  const handleSidebarNavigationItemClick = (step: number) => {
+    if (steps[step].isSidebarEnabled) {
+      setCurrentStep(step);
+    }
+  };
+
+  const handleOnStepCompletion = (step: number) => {
+    setSteps(
+      steps.map((currentStep, index) => {
+        if (index === step) {
+          return { ...currentStep, isCompleted: true, isNextDisabled: false };
+        } else if (index === step + 1) {
+          return { ...currentStep, isSidebarEnabled: true };
+        } else {
+          return currentStep;
+        }
+      }),
+    );
+  };
+
+  const handleCompleteStepperClick = () => {
+    // Mock alert for testing
+    if (steps.every((step) => step.isCompleted)) {
+      // all completed
+    } else {
+      // not all completed
+    }
+  };
+
+  return (
+    <Stepper
+      steps={steps}
+      currentStep={currentStep}
+      onBackClick={handleBackClick}
+      onNextClick={handleNextClick}
+      onFinishClick={handleCompleteStepperClick}
+      onStepClick={handleSidebarNavigationItemClick}
+    >
+      <StepOne onCompletion={() => handleOnStepCompletion(0)} />
+      <StepTwo onCompletion={() => handleOnStepCompletion(1)} />
+      <StepThree onCompletion={() => handleOnStepCompletion(2)} />
+    </Stepper>
+  );
+};
+
+describe('Stepper', () => {
+  it('It loads the stepper first step as the current step', () => {
+    render(<TestStepperWrapper initialStep={0} />);
+    const stepOneTitle = screen.getByTestId('step-1-title');
+    expect(stepOneTitle).toBeInTheDocument();
+  });
+
+  it('It loads the stepper second step as the current step', () => {
+    render(<TestStepperWrapper initialStep={1} />);
+    const stepTwoTitle = screen.getByTestId('step-2-title');
+    expect(stepTwoTitle).toBeInTheDocument();
+  });
+
+  it('It loads the stepper third step as the current step', () => {
+    render(<TestStepperWrapper initialStep={2} />);
+    const stepThreeTitle = screen.getByTestId('step-3-title');
+    expect(stepThreeTitle).toBeInTheDocument();
+  });
+
+  describe('Testing individual steps', () => {
+    it('Step one calls onCompletion when fields are filled', async () => {
+      const mockOnCompletion = jest.fn();
+      render(<StepOne onCompletion={mockOnCompletion} />);
+
+      // Fill required fields
+      const inputs = screen.getAllByRole('textbox');
+      await userEvent.type(inputs[0], 'Test App Name');
+      await userEvent.type(inputs[1], '1.0.0');
+
+      // Verify completion was called
+      expect(mockOnCompletion).toHaveBeenCalled();
+    });
+  });
+
+  describe('Stepper Navigation', () => {
+    it('prevents navigation to a step that is not completed', async () => {
+      render(<TestStepperWrapper initialStep={1} />);
+      const nextButton = screen.getByTestId('stepper-next-button');
+      await userEvent.click(nextButton);
+      expect(nextButton).toBeDisabled();
+    });
+    it('prevents back navigation on the first step', async () => {
+      render(<TestStepperWrapper initialStep={0} />);
+      const backButton = screen.getByTestId('stepper-back-button');
+      await userEvent.click(backButton);
+      expect(backButton).toBeDisabled();
+    });
+    it('prevents legend navigation when the selected step is not optional', async () => {
+      render(<TestStepperWrapper initialStep={1} />);
+      const legendNavigation = screen.getByTestId('stepper-legend-step-1');
+      await userEvent.click(legendNavigation);
+      expect(legendNavigation).toBeDisabled();
+    });
+    it('disables the finish button when not all steps are completed', async () => {
+      render(<TestStepperWrapper initialStep={2} />);
+      const finishButton = screen.getByTestId('stepper-finish-button');
+      await userEvent.click(finishButton);
+      expect(finishButton).toBeDisabled();
+    });
+    it('enables the finish button when all steps are completed', async () => {
+      render(<TestStepperWrapper initialStep={2} />);
+      const finishButton = screen.getByTestId('stepper-finish-button');
+      const inputs = screen.getAllByRole('textbox');
+      await userEvent.type(inputs[0], 'Test App Name');
+      await userEvent.type(inputs[1], '1.0.0');
+      await userEvent.click(finishButton);
+      expect(finishButton).toBeEnabled();
+    });
+    it('shows the finish button when on the last step', async () => {
+      render(<TestStepperWrapper initialStep={2} />);
+      const finishButton = screen.getByTestId('stepper-finish-button');
+      expect(finishButton).toBeInTheDocument();
+    });
+
+    it('It navigates to the next step when Next is clicked', async () => {
+      // Mock the necessary handler for testing
+      const handleNextClick = jest.fn();
+
+      render(
+        <Stepper
+          steps={exampleSteps.map((step) => ({
+            ...step,
+            isCompleted: true,
+            isNextDisabled: false,
+          }))}
+          currentStep={0}
+          onBackClick={() => {}}
+          onNextClick={handleNextClick}
+          onFinishClick={() => {}}
+          onStepClick={() => {}}
+        >
+          <StepOne onCompletion={() => {}} />
+          <StepTwo onCompletion={() => {}} />
+          <StepThree onCompletion={() => {}} />
+        </Stepper>,
+      );
+
+      expect(screen.getByTestId('step-1-title')).toBeInTheDocument();
+
+      const nextButton = screen.getByTestId('stepper-next-button');
+      await userEvent.click(nextButton);
+
+      // Verify next handler was called
+      expect(handleNextClick).toHaveBeenCalled();
+    });
+  });
+});

package/src/components/stepper/components/BackNavigation.tsx

@@ -0,0 +1,22 @@
+import { Button } from '../../button';
+type Props = {
+  isDisabled: boolean;
+  onBackClick: () => void;
+};
+
+export const BackNavigation = ({ isDisabled, onBackClick }: Props) => {
+  return (
+    <div className="stepper-navigation-back">
+      <Button
+        data-testid="stepper-back-button"
+        ariaLabel="Previous Step"
+        iconLeft="fa-arrow-left"
+        onClick={onBackClick}
+        variant="outline"
+        isDisabled={isDisabled}
+      >
+        Previous Step
+      </Button>
+    </div>
+  );
+};