feat: Add horizontal layout and custom rendering to steps

Author: timogasda

pages/steps/permutations-utils.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import Box from '~components/box';
 import Button from '~components/button';
+import Icon from '~components/icon';
 import Link from '~components/link';
 import Popover from '~components/popover';
 import { StepsProps } from '~components/steps';
@@ -738,6 +739,7 @@ const changesetStepsInteractive: ReadonlyArray<StepsProps.Step> = [
 
 export const stepsPermutations = createPermutations<StepsProps>([
   {
+    orientation: ['vertical', 'horizontal'],
     steps: [
       initialSteps,
       loadingSteps,
@@ -761,4 +763,20 @@ export const stepsPermutations = createPermutations<StepsProps>([
     ],
     ariaLabel: ['test label'],
   },
+  {
+    steps: [allStatusesSteps, successfulSteps],
+    ariaLabel: ['test label'],
+    orientation: ['vertical', 'horizontal'],
+    renderStep: [
+      step => ({
+        header: <b>Custom header for {step.header}</b>,
+        details: step.details && <i>Custom details for {step.details}</i>,
+      }),
+      step => ({
+        header: step.header,
+        details: step.details && <i>Custom details for {step.details}</i>,
+        icon: <Icon ariaLabel="success" name="status-positive" variant="success" />,
+      }),
+    ],
+  },
 ]);

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -23069,6 +23069,49 @@ use the \`id\` attribute, consider setting it on a parent element instead.",
       "optional": true,
       "type": "string",
     },
+    {
+      "defaultValue": "'vertical'",
+      "description": "The visual orientation of the steps (vertical or horizontal).
+By default the orientation is vertical.",
+      "inlineType": {
+        "name": "StepsProps.Orientation",
+        "type": "union",
+        "values": [
+          "horizontal",
+          "vertical",
+        ],
+      },
+      "name": "orientation",
+      "optional": true,
+      "systemTags": [
+        "core",
+      ],
+      "type": "string",
+    },
+    {
+      "description": "Render a step. This overrides the default icon, header, and details provided by the component.
+The function is called for each step and should return an object with the following keys:
+* \`header\` (React.ReactNode) - Summary corresponding to the step.
+* \`details\` (React.ReactNode) - (Optional) Additional information corresponding to the step.
+* \`icon\` (React.ReactNode) - (Optional) Replaces the standard step icon from the status indicator.",
+      "inlineType": {
+        "name": "(step: StepsProps.Step) => { header: React.ReactNode; details?: React.ReactNode; icon?: React.ReactNode; }",
+        "parameters": [
+          {
+            "name": "step",
+            "type": "StepsProps.Step",
+          },
+        ],
+        "returnType": "{ header: React.ReactNode; details?: React.ReactNode; icon?: React.ReactNode; }",
+        "type": "function",
+      },
+      "name": "renderStep",
+      "optional": true,
+      "systemTags": [
+        "core",
+      ],
+      "type": "((step: StepsProps.Step) => { header: React.ReactNode; details?: React.ReactNode; icon?: React.ReactNode; })",
+    },
     {
       "description": "An array of individual steps
 

src/status-indicator/internal.tsx

@@ -82,7 +82,8 @@ export default function StatusIndicator({
           styles.container,
           styles[`display-${__display}`],
           wrapText === false && styles['overflow-ellipsis'],
-          __animate && styles['container-fade-in']
+          __animate && styles['container-fade-in'],
+          !children && styles['no-text']
         )}
       >
         <span

src/status-indicator/styles.scss

@@ -61,6 +61,10 @@ $_color-overrides: (
       padding-inline-end: awsui.$space-xxs;
     }
   }
+
+  &.no-text > .icon {
+    padding-inline-end: 0;
+  }
 }
 
 .overflow-ellipsis {

src/steps/__tests__/steps.test.tsx

@@ -68,6 +68,18 @@ const stepsWithIconAriaLabel: ReadonlyArray<StepsProps.Step> = [
   },
 ];
 
+const stepsForCustomRender: ReadonlyArray<StepsProps.Step> = [
+  {
+    header: 'Checked Cross Region Consent',
+    status: 'success',
+  },
+  {
+    header: 'Analyzing security rules',
+    status: 'loading',
+    details: 'Step details',
+  },
+];
+
 const renderSteps = (props: Partial<StepsProps>) => {
   const renderResult = render(<Steps {...defaultProps} {...props} />);
   return createWrapper(renderResult.container).findSteps()!;
@@ -142,4 +154,63 @@ describe('Steps', () => {
       });
     });
   });
+
+  describe('orientation', () => {
+    test('renders with default vertical orientation', () => {
+      const wrapper = renderSteps({ steps: successfullSteps });
+
+      expect(wrapper.getElement()).not.toHaveClass(stepsStyles.horizontal);
+    });
+
+    test('renders with horizontal orientation when explicitly set', () => {
+      const wrapper = renderSteps({
+        steps: successfullSteps,
+        orientation: 'horizontal',
+      });
+
+      expect(wrapper.getElement()).toHaveClass(stepsStyles.horizontal);
+    });
+
+    test('renders with vertical orientation', () => {
+      const wrapper = renderSteps({
+        steps: successfullSteps,
+        orientation: 'vertical',
+      });
+
+      expect(wrapper.getElement()).not.toHaveClass(stepsStyles.horizontal);
+    });
+  });
+
+  describe('renderStep', () => {
+    const customRenderStep = (step: StepsProps.Step) => ({
+      header: <span data-testid="custom-header">Custom: {step.header}</span>,
+      details: step.details ? <div data-testid="custom-details">Details: {step.details}</div> : undefined,
+      icon: <span data-testid="custom-icon">icon</span>,
+    });
+
+    test('renders custom content when using renderStep', () => {
+      const wrapper = renderSteps({ steps: stepsForCustomRender, renderStep: customRenderStep });
+
+      const customHeaders = wrapper.findAll('[data-testid="custom-header"]');
+      expect(customHeaders).toHaveLength(stepsForCustomRender.length);
+
+      expect(customHeaders[0].getElement()).toHaveTextContent('Checked Cross Region Consent');
+      expect(customHeaders[1].getElement()).toHaveTextContent('Analyzing security rules');
+    });
+
+    test('renders custom details when using renderStep', () => {
+      const wrapper = renderSteps({ steps: stepsForCustomRender, renderStep: customRenderStep });
+
+      const customDetails = wrapper.findAll('[data-testid="custom-details"]');
+      // Only last step has details
+      expect(customDetails).toHaveLength(1);
+      expect(customDetails[0].getElement()).toHaveTextContent('Step details');
+    });
+
+    test('does not render status indicators when using renderStep with icon', () => {
+      const wrapper = renderSteps({ steps: stepsForCustomRender, renderStep: customRenderStep });
+
+      expect(wrapper.findItems()[0].findHeader()?.findStatusIndicator()).toBeNull();
+    });
+  });
 });

src/steps/index.tsx

@@ -12,12 +12,14 @@ import InternalSteps from './internal';
 
 export { StepsProps };
 
-const Steps = ({ steps, ...props }: StepsProps) => {
+const Steps = ({ steps, orientation = 'vertical', ...props }: StepsProps) => {
   const baseProps = getBaseProps(props);
   const baseComponentProps = useBaseComponent('Steps');
   const externalProps = getExternalProps(props);
 
-  return <InternalSteps {...baseProps} {...baseComponentProps} {...externalProps} steps={steps} />;
+  return (
+    <InternalSteps {...baseProps} {...baseComponentProps} {...externalProps} steps={steps} orientation={orientation} />
+  );
 };
 
 applyDisplayName(Steps, 'Steps');

src/steps/interfaces.ts

@@ -14,6 +14,27 @@ export interface StepsProps extends BaseComponentProps {
    *  * `details` (ReactNode) - (Optional) Additional information corresponding to the step.
    */
   steps: ReadonlyArray<StepsProps.Step>;
+  /**
+   * The visual orientation of the steps (vertical or horizontal).
+   * By default the orientation is vertical.
+   *
+   * @awsuiSystem core
+   */
+  orientation?: StepsProps.Orientation;
+  /**
+   * Render a step. This overrides the default icon, header, and details provided by the component.
+   * The function is called for each step and should return an object with the following keys:
+   * * `header` (React.ReactNode) - Summary corresponding to the step.
+   * * `details` (React.ReactNode) - (Optional) Additional information corresponding to the step.
+   * * `icon` (React.ReactNode) - (Optional) Replaces the standard step icon from the status indicator.
+   *
+   * @awsuiSystem core
+   */
+  renderStep?: (step: StepsProps.Step) => {
+    header: React.ReactNode;
+    details?: React.ReactNode;
+    icon?: React.ReactNode;
+  };
   /**
    * Provides an `aria-label` to the progress steps container.
    * Don't use `ariaLabel` and `ariaLabelledby` at the same time.
@@ -40,4 +61,6 @@ export namespace StepsProps {
     header: React.ReactNode;
     details?: React.ReactNode;
   }
+
+  export type Orientation = 'vertical' | 'horizontal';
 }

src/steps/internal.tsx

@@ -3,6 +3,8 @@
 import React from 'react';
 import clsx from 'clsx';
 
+import { BoxProps } from '../box/interfaces';
+import InternalBox from '../box/internal';
 import { InternalBaseComponentProps } from '../internal/hooks/use-base-component';
 import { SomeRequired } from '../internal/types';
 import StatusIndicator from '../status-indicator/internal';
@@ -12,45 +14,107 @@ import styles from './styles.css.js';
 
 type InternalStepsProps = SomeRequired<StepsProps, 'steps'> & InternalBaseComponentProps;
 
-const InternalStep = ({ status, statusIconAriaLabel, header, details }: StepsProps.Step) => {
+const statusToColor: Record<StepsProps.Status, BoxProps.Color> = {
+  error: 'text-status-error',
+  warning: 'text-status-warning',
+  success: 'text-status-success',
+  info: 'text-status-info',
+  stopped: 'text-status-inactive',
+  pending: 'text-status-inactive',
+  'in-progress': 'text-status-inactive',
+  loading: 'text-status-inactive',
+};
+
+const CustomStep = ({
+  step,
+  orientation,
+  renderStep,
+}: {
+  step: StepsProps.Step;
+  orientation: StepsProps.Orientation;
+  renderStep: Required<StepsProps>['renderStep'];
+}) => {
+  const { status, statusIconAriaLabel } = step;
+  const { header, details, icon } = renderStep(step);
+  return (
+    <li className={styles.container}>
+      <div className={styles.header}>
+        {icon ? icon : <StatusIndicator type={status} iconAriaLabel={statusIconAriaLabel} />}
+        {orientation === 'vertical' ? header : <hr className={styles.connector} role="none" />}
+      </div>
+      {orientation === 'vertical' ? (
+        <hr className={styles.connector} role="none" />
+      ) : (
+        <div className={styles['horizontal-header']}>{header}</div>
+      )}
+      {details && <div className={styles.details}>{details}</div>}
+    </li>
+  );
+};
+
+const InternalStep = ({
+  status,
+  statusIconAriaLabel,
+  header,
+  details,
+  orientation,
+}: StepsProps.Step & { orientation: StepsProps.Orientation }) => {
   return (
     <li className={styles.container}>
       <div className={styles.header}>
         <StatusIndicator type={status} iconAriaLabel={statusIconAriaLabel}>
-          {header}
+          {orientation === 'vertical' && header}
         </StatusIndicator>
+        {orientation === 'horizontal' && <hr className={styles.connector} role="none" />}
       </div>
-      <hr className={styles.connector} role="none" />
+      {orientation === 'vertical' ? (
+        <hr className={styles.connector} role="none" />
+      ) : (
+        <div className={styles['horizontal-header']}>
+          <InternalBox color={statusToColor[status]}>{header}</InternalBox>
+        </div>
+      )}
       {details && <div className={styles.details}>{details}</div>}
     </li>
   );
 };
 
 const InternalSteps = ({
   steps,
+  orientation,
+  renderStep,
   ariaLabel,
   ariaLabelledby,
   ariaDescribedby,
   __internalRootRef,
   ...props
-}: InternalStepsProps) => {
+}: SomeRequired<InternalStepsProps, 'orientation'>) => {
   return (
-    <div {...props} className={clsx(styles.root, props.className)} ref={__internalRootRef}>
+    <div
+      {...props}
+      className={clsx(styles.root, props.className, orientation === 'horizontal' ? styles.horizontal : styles.vertical)}
+      ref={__internalRootRef}
+    >
       <ol
         className={styles.list}
         aria-label={ariaLabel}
         aria-labelledby={ariaLabelledby}
         aria-describedby={ariaDescribedby}
       >
-        {steps.map((step, index) => (
-          <InternalStep
-            key={index}
-            status={step.status}
-            statusIconAriaLabel={step.statusIconAriaLabel}
-            header={step.header}
-            details={step.details}
-          />
-        ))}
+        {steps.map((step, index) =>
+          renderStep ? (
+            <CustomStep key={index} orientation={orientation} step={step} renderStep={renderStep} />
+          ) : (
+            <InternalStep
+              key={index}
+              status={step.status}
+              statusIconAriaLabel={step.statusIconAriaLabel}
+              header={step.header}
+              details={step.details}
+              orientation={orientation}
+            />
+          )
+        )}
       </ol>
     </div>
   );