Add Pagination Component

Author: Hector Arce De Las Heras

src/components/pagination/__tests__/pagination.test.tsx

@@ -0,0 +1,81 @@
+import { fireEvent, screen } from '@testing-library/react';
+import * as React from 'react';
+
+import { axe } from 'jest-axe';
+
+import { renderProvider } from '@/tests/renderProvider/renderProvider.utility';
+
+import { Pagination } from '../pagination';
+
+const mockProps = {
+  dataTestId: 'Pagination',
+  variant: 'DEFAULT',
+  maxStepsNumber: 10,
+  paginationLeftButtonControl: {
+    icon: 'CHEVRON_LEFT',
+    ariaLabel: 'left button',
+    onClick: jest.fn(),
+  },
+  paginationRightButtonControl: {
+    icon: 'CHEVRON_RIGHT',
+    ariaLabel: 'right button',
+    onClick: jest.fn(),
+  },
+};
+
+const onStepClick = jest.fn();
+
+describe('Pagination Component', () => {
+  it('Should have a valid HTML structure', async () => {
+    const { container } = renderProvider(<Pagination {...mockProps} currentStep={0} />);
+
+    const results = await axe(container);
+
+    expect(container).toHTMLValidate();
+    expect(results).toHaveNoViolations();
+  });
+  it('Should call paginationControl onClick when pressed', () => {
+    renderProvider(<Pagination {...mockProps} currentStep={5} onStepClick={onStepClick} />);
+
+    const leftButton = screen.getByLabelText('left button');
+    const rightButton = screen.getByLabelText('right button');
+    const anyCounter = screen.getByTestId(`${mockProps.dataTestId}StepsContent`).children[0];
+
+    fireEvent.click(leftButton);
+    expect(mockProps.paginationLeftButtonControl.onClick).toHaveBeenCalled();
+
+    fireEvent.click(rightButton);
+    expect(mockProps.paginationRightButtonControl.onClick).toHaveBeenCalled();
+
+    fireEvent.click(anyCounter);
+    expect(onStepClick).toHaveBeenCalled();
+  });
+
+  it('Should have the left button disabled when the current position is the first', () => {
+    renderProvider(<Pagination currentStep={0} {...mockProps} />);
+
+    const leftButton = screen.getByLabelText('left button');
+    expect(leftButton).toBeDisabled();
+  });
+
+  it('Should have the right button disabled when the current position is the last', () => {
+    renderProvider(<Pagination currentStep={9} {...mockProps} />);
+
+    const rightButton = screen.getByLabelText('right button');
+    expect(rightButton).toBeDisabled();
+  });
+
+  it('Should accept a custom counter number', () => {
+    const maxCountersNumber = 6;
+    renderProvider(
+      <Pagination {...mockProps} currentStep={10} maxCountersNumber={maxCountersNumber} />
+    );
+
+    const childsNumber = screen.getByTestId(
+      `${mockProps.dataTestId}StepsContent`
+    ).childElementCount;
+    const ellipsis = screen.getAllByText('...').length;
+
+    expect(childsNumber).toBe(maxCountersNumber + ellipsis);
+  });
+});

src/components/pagination/fragments/index.ts

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

src/components/pagination/fragments/paginationButtonControl.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+
+import { ElementOrIcon } from '@/components/elementOrIcon';
+
+import { IPaginationButtonControl } from '../types/pagination';
+import { PaginationArrowIconStyleType } from '../types/paginationTheme';
+
+interface IPaginationButtonControlProps {
+  styles?: PaginationArrowIconStyleType;
+  paginationButtonControl: IPaginationButtonControl;
+  disabled: boolean;
+}
+
+export const PaginationButtonControl = ({
+  styles,
+  paginationButtonControl,
+  disabled,
+}: IPaginationButtonControlProps): JSX.Element => {
+  const iconStyles = disabled && styles?.disabled ? styles.disabled : styles;
+  const handleOnClick: React.MouseEventHandler<HTMLButtonElement> = event => {
+    !disabled && paginationButtonControl.onClick?.(event);
+  };
+  return (
+    <ElementOrIcon
+      altText={paginationButtonControl?.ariaLabel}
+      aria-controls={paginationButtonControl?.ariaControls}
+      aria-label={paginationButtonControl?.ariaLabel}
+      customIconStyles={iconStyles}
+      disabled={disabled}
+      icon={paginationButtonControl?.icon}
+      onClick={handleOnClick}
+    />
+  );
+};

src/components/pagination/helpers/getMaxCountersNumber.ts

@@ -0,0 +1,53 @@
+const buildBeforeCounters = (beforeNum, currentPosition) =>
+  [...Array(beforeNum)].map((_, index) => currentPosition - (beforeNum - index));
+
+const buildAfterCounters = (afterNum, currentPosition) =>
+  [...Array(afterNum)].map((_, index) => currentPosition + 1 + index);
+
+// eslint-disable-next-line complexity
+export const buildstepsNumber = (
+  currentStep: number,
+  maxSteps: number,
+  themeMaxNumber: number | undefined = 0,
+  propsMaxNumber: number | undefined
+): Array<string | number> => {
+  let maxCounters =
+    propsMaxNumber && propsMaxNumber > themeMaxNumber ? propsMaxNumber : themeMaxNumber;
+
+  let startWith: Array<string | number> = [];
+  let endWith: Array<string | number> = [];
+  let beforeCounters: Array<number> = [];
+  let afterCounters: Array<number> = [];
+
+  let currentPosition = currentStep + 1;
+
+  if (currentPosition >= maxCounters) {
+    maxCounters--;
+    startWith = [1, '...'];
+  }
+
+  if (Math.abs(maxSteps - currentPosition) >= maxCounters) {
+    maxCounters--;
+    endWith = ['...', maxSteps];
+  }
+
+  const isLeftEdge = currentPosition <= maxCounters;
+  const isRightEdge = Math.abs(maxSteps - currentPosition) < maxCounters;
+
+  if (isLeftEdge) {
+    currentPosition = 1;
+    afterCounters = buildAfterCounters(maxCounters - 1, currentPosition);
+  } else if (isRightEdge) {
+    currentPosition = maxSteps - maxCounters + 1;
+    afterCounters = buildAfterCounters(maxCounters - 1, currentPosition);
+  } else {
+    const counterDivided = (maxCounters - 1) / 2;
+    const beforeNum = Math.floor(counterDivided);
+    const afterNum = Math.ceil(counterDivided);
+
+    beforeCounters = buildBeforeCounters(beforeNum, currentPosition);
+    afterCounters = buildAfterCounters(afterNum, currentPosition);
+  }
+
+  return [...startWith, ...beforeCounters, currentPosition, ...afterCounters, ...endWith];
+};

src/components/pagination/helpers/index.ts

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

src/components/pagination/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+
+export { Pagination } from './pagination';

src/components/pagination/pagination.styled.ts

@@ -0,0 +1,27 @@
+import styled from 'styled-components';
+
+import { getStyles } from '@/utils';
+
+import { PaginationState, PaginationStyledProps } from './types';
+
+export const PaginationContainerStyled = styled.div<{
+  styles: PaginationStyledProps;
+}>`
+  ${({ styles }) => getStyles(styles.container)};
+`;
+
+export const PaginationPagesContainerStyled = styled.div<{
+  styles: PaginationStyledProps;
+}>`
+  ${({ styles }) => getStyles(styles.pagesContainer)};
+`;
+
+export const PaginationPageContainerStyled = styled.span<{
+  styles: PaginationStyledProps;
+  state: PaginationState;
+  $isClickable: boolean;
+}>`
+  ${({ styles, state }) => getStyles(styles[state]?.pageContainer)};
+  ${({ styles, state, $isClickable }) =>
+    $isClickable && getStyles(styles[state]?.pageContainer?.clickable)};
+`;

src/components/pagination/pagination.tsx

@@ -0,0 +1,72 @@
+import * as React from 'react';
+
+import { useMediaDevice, useStyles } from '@/hooks';
+import { ErrorBoundary, FallbackComponent } from '@/provider/errorBoundary';
+
+// helpers
+import { buildstepsNumber } from './helpers';
+import { PaginationStandAlone } from './paginationStandAlone';
+import { PaginationStyledProps } from './types';
+// interfaces
+import { IPagination, IPaginationStandAlone } from './types/pagination';
+
+const PAGINATION_STYLES = 'PAGINATION_STYLES';
+
+const PaginationComponent = React.forwardRef(
+  <V extends string | unknown>(
+    { variant, currentStep, maxStepsNumber, maxCountersNumber, ctv, ...props }: IPagination<V>,
+    ref: React.ForwardedRef<HTMLDivElement> | undefined | null
+  ): JSX.Element => {
+    const styles = useStyles<PaginationStyledProps, V>(PAGINATION_STYLES, variant, ctv);
+    const device = useMediaDevice();
+
+    const limitCurrentStep = Math.max(0, Math.min(currentStep, maxStepsNumber - 1));
+
+    const stepsNumber = buildstepsNumber(
+      limitCurrentStep,
+      maxStepsNumber,
+      styles.paginationCountersNumber?.[device]?.counters,
+      maxCountersNumber
+    );
+    const stepActive = stepsNumber.indexOf(limitCurrentStep + 1);
+
+    const leftDisabled = limitCurrentStep === 0;
+    const rightDisabled = limitCurrentStep === maxStepsNumber - 1;
+
+    return (
+      <PaginationStandAlone
+        ref={ref}
+        leftDisabled={leftDisabled}
+        rightDisabled={rightDisabled}
+        stepActive={stepActive}
+        stepsNumber={stepsNumber}
+        styles={styles}
+        {...props}
+      />
+    );
+  }
+);
+PaginationComponent.displayName = 'PaginationComponent';
+
+const PaginationBoundary = <V extends string | unknown>(
+  props: IPagination<V>,
+  ref: React.ForwardedRef<HTMLDivElement> | undefined | null
+): JSX.Element => (
+  <ErrorBoundary
+    fallBackComponent={
+      <FallbackComponent>
+        <PaginationStandAlone {...(props as unknown as IPaginationStandAlone)} ref={ref} />
+      </FallbackComponent>
+    }
+  >
+    <PaginationComponent {...props} ref={ref} />
+  </ErrorBoundary>
+);
+
+const Pagination = React.forwardRef(PaginationBoundary) as <V extends string | unknown>(
+  props: React.PropsWithChildren<IPagination<V>> & {
+    ref?: React.ForwardedRef<HTMLDivElement> | undefined | null;
+  }
+) => ReturnType<typeof PaginationBoundary>;
+
+export { Pagination };

src/components/pagination/paginationStandAlone.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+
+import { ButtonType } from '@/components/button';
+import { Text, TextComponentType } from '@/components/text';
+import { ROLES } from '@/types';
+
+import { PaginationButtonControl } from './fragments';
+import {
+  PaginationContainerStyled,
+  PaginationPageContainerStyled,
+  PaginationPagesContainerStyled,
+} from './pagination.styled';
+import { PaginationState } from './types';
+// interfaces
+import { IPaginationButtonControl, IPaginationStandAlone } from './types/pagination';
+
+const PaginationStandAloneComponent = (
+  {
+    styles,
+    stepActive,
+    stepsNumber,
+    onStepClick,
+    paginationLeftButtonControl,
+    paginationRightButtonControl,
+    leftDisabled,
+    rightDisabled,
+    dataTestId,
+  }: IPaginationStandAlone,
+  ref: React.ForwardedRef<HTMLDivElement> | undefined | null
+): JSX.Element => {
+  return (
+    <PaginationContainerStyled ref={ref} data-testid={`${dataTestId}Container`} styles={styles}>
+      <PaginationButtonControl
+        disabled={leftDisabled}
+        paginationButtonControl={paginationLeftButtonControl as IPaginationButtonControl}
+        styles={styles.paginationLeftArrowIcon}
+      />
+      <PaginationPagesContainerStyled data-testid={`${dataTestId}StepsContent`} styles={styles}>
+        {stepsNumber.map((value, index) => {
+          const state = stepActive === index ? PaginationState.SELECTED : PaginationState.DEFAULT;
+          const isClickable = typeof value === 'number';
+          return (
+            <PaginationPageContainerStyled
+              key={`PaginationContent-${index}`}
+              $isClickable={isClickable}
+              as={isClickable ? ROLES.BUTTON : undefined}
+              state={state}
+              styles={styles}
+              type={isClickable ? ButtonType.BUTTON : undefined}
+              onClick={isClickable ? onStepClick?.(value - 1) : undefined}
+            >
+              <Text component={TextComponentType.SPAN} customTypography={styles[state]?.page}>
+                {value}
+              </Text>
+            </PaginationPageContainerStyled>
+          );
+        })}
+      </PaginationPagesContainerStyled>
+      <PaginationButtonControl
+        disabled={rightDisabled}
+        paginationButtonControl={paginationRightButtonControl as IPaginationButtonControl}
+        styles={styles.paginationRightArrowIcon}
+      />
+    </PaginationContainerStyled>
+  );
+};
+
+export const PaginationStandAlone = React.forwardRef(PaginationStandAloneComponent);