feat(component): create basic pagination component

packages/big-design/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,100 @@
+import { ArrowDropDownIcon, ChevronLeftIcon, ChevronRightIcon } from '@bigcommerce/big-design-icons';
+import React, { useEffect, useState } from 'react';
+
+import { MarginProps } from '../../mixins';
+import { Box } from '../Box';
+import { Dropdown } from '../Dropdown';
+import { Flex } from '../Flex';
+
+import { StyledButton, StyledIconButton } from './styled';
+
+export interface PaginationProps extends MarginProps {
+  currentRange: number;
+  currentPage: number;
+  totalItems: number;
+  rangeOptions: number[];
+  onPageChange(page: number): void;
+  onRangeChange(range: number): void;
+}
+
+export const Pagination: React.FC<PaginationProps> = props => {
+  const { currentRange, currentPage, totalItems, rangeOptions, onPageChange, onRangeChange } = props;
+
+  const [maxPages, setMaxPages] = useState(Math.ceil(totalItems / currentRange));
+  const [itemRange, setItemRange] = useState([0, 0]);
+
+  useEffect(() => {
+    const firstItemInRange = currentRange * (currentPage - 1) + 1;
+    let lastItemInRange = currentRange * currentPage;
+    if (lastItemInRange > totalItems) {
+      lastItemInRange = totalItems;
+    }
+
+    setItemRange([firstItemInRange, lastItemInRange]);
+  }, [currentPage, currentRange, totalItems]);
+
+  const handlePageIncrease = () => {
+    let nextPage = currentPage + 1;
+    if (nextPage > maxPages) {
+      nextPage = 1;
+    }
+    onPageChange(nextPage);
+  };
+
+  const handlePageDecrease = () => {
+    let nextPage = currentPage - 1;
+    if (nextPage < 1) {
+      nextPage = maxPages;
+    }
+    onPageChange(nextPage);
+  };
+
+  const handleRangeChange = (range: number) => {
+    setMaxPages(Math.ceil(totalItems / range));
+    onRangeChange(range);
+  };
+
+  const showRanges = () => {
+    if (itemRange[0] !== itemRange[1]) {
+      return `${itemRange[0]} - ${itemRange[1]} of ${totalItems}`;
+    } else {
+      return `${itemRange[0]} of ${totalItems}`;
+    }
+  };
+
+  return (
+    <Flex flexDirection="row" justifyContent="flex-start" role="navigation" aria-label="pagination">
+      <Dropdown
+        onItemClick={handleRangeChange}
+        trigger={
+          <StyledButton variant="subtle" iconRight={<ArrowDropDownIcon size="xxLarge" color="secondary70" />}>
+            {showRanges()}
+          </StyledButton>
+        }
+      >
+        {rangeOptions.map(range => {
+          return <Dropdown.Item value={range}>{range} per page</Dropdown.Item>;
+        })}
+      </Dropdown>
+      <Box>
+        <StyledIconButton
+          variant="subtle"
+          disabled={currentPage <= 1}
+          aria-label="previous page"
+          onClick={handlePageDecrease}
+        >
+          <ChevronLeftIcon />
+        </StyledIconButton>
+
+        <StyledIconButton
+          variant="subtle"
+          disabled={currentPage === maxPages}
+          aria-label="next page"
+          onClick={handlePageIncrease}
+        >
+          <ChevronRightIcon />
+        </StyledIconButton>
+      </Box>
+    </Flex>
+  );
+};

packages/big-design/src/components/Pagination/index.ts

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

packages/big-design/src/components/Pagination/styled.tsx

@@ -0,0 +1,12 @@
+import styled from 'styled-components';
+
+import { StyleableButton } from '../Button/private';
+
+export const StyledButton = styled(StyleableButton)`
+  color: ${({ theme }) => theme.colors.secondary70};
+`;
+
+// in case we need to add separate styles to the icon buttons or to the dropdown trigger
+export const StyledIconButton = styled(StyleableButton)`
+  color: ${({ theme }) => theme.colors.secondary70};
+`;

packages/big-design/src/components/index.ts

@@ -10,6 +10,7 @@ export * from './Grid';
 export * from './Input';
 export * from './Link';
 export * from './Modal';
+export * from './Pagination';
 export * from './Panel';
 export * from './ProgressBar';
 export * from './ProgressCircle';

packages/docs/PropTables/PaginationPropTable.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+
+import { PropTable } from '../components';
+
+export const PaginationPropTable: React.FC = () => {
+  return (
+    <PropTable>
+      <PropTable.Prop name="currentRange" types="number" defaults="" required>
+        Indicates how many items are displayed per page
+      </PropTable.Prop>
+      <PropTable.Prop name="currentPage" types="number" defaults="" required>
+        Indicates the page currently/initially displayed
+      </PropTable.Prop>
+      <PropTable.Prop name="totalItems" types="number" defaults="" required>
+        Indicates how many items in total will be displayed
+      </PropTable.Prop>
+      <PropTable.Prop name="rangeOptions" types="number[]" defaults="" required>
+        Indicates options for per-page ranges
+      </PropTable.Prop>
+      <PropTable.Prop name="onPageChange" types="(page: number) => void" required>
+        Function that will be called when a navigation arrow is clicked
+      </PropTable.Prop>
+      <PropTable.Prop name="onRangeChange" types="(range: number) => void" required>
+        Function that will be called when a new per-page range is selected
+      </PropTable.Prop>
+    </PropTable>
+  );
+};

packages/docs/PropTables/index.ts

@@ -11,6 +11,7 @@ export * from './InputPropTable';
 export * from './MarginPropTable';
 export * from './ModalPropTable';
 export * from './PaddingPropTable';
+export * from './PaginationPropTable';
 export * from './PanelPropTable';
 export * from './ProgressBarPropTable';
 export * from './ProgressCirclePropTable';

packages/docs/components/SideNav/SideNav.tsx

@@ -46,6 +46,9 @@ export const SideNav: React.FC = () => {
           <SideNavLink href="/Modal/ModalPage" as="/modal">
             Modal
           </SideNavLink>
+          <SideNavLink href="/Pagination/PaginationPage" as="/Pagination">
+            Pagination
+          </SideNavLink>
           <SideNavLink href="/Panel/PanelPage" as="/panel">
             Panel
           </SideNavLink>

packages/docs/next.config.js

@@ -32,6 +32,7 @@ module.exports = {
     '/margin': { page: '/Margin/MarginPage' },
     '/modal': { page: '/Modal/ModalPage' },
     '/padding': { page: '/Padding/PaddingPage' },
+    '/pagination': { page: '/Pagination/PaginationPage' },
     '/panel': { page: '/Panel/PanelPage' },
     '/progress-bar': { page: '/Progress/ProgressBarPage' },
     '/progress-circle': { page: '/Progress/ProgressCirclePage' },

packages/docs/pages/Pagination/PaginationPage.tsx

@@ -0,0 +1,75 @@
+import { H0, H1, H2, Link, Pagination, Text } from '@bigcommerce/big-design';
+import React from 'react';
+
+import { CodePreview, Collapsible } from '../../components';
+import { MarginPropTable, PaginationPropTable } from '../../PropTables';
+
+export default () => (
+  <>
+    <H0>Pagination</H0>
+
+    <Text>
+      Pagination allows for navigation through pages of content.{' '}
+      <Link href="https://design.bigcommerce.com/components/pagination" target="_blank">
+        Pagination Design Guidelines
+      </Link>
+      .
+    </Text>
+
+    <CodePreview>
+      {/* jsx-to-string:start */}
+      {function Example() {
+        const items = ['Item1', 'Item2', 'Item3', 'Item4', 'Item5'];
+        const ranges = [2, 3, 4];
+
+        const [range, setRange] = React.useState(ranges[0]);
+        const [page, setPage] = React.useState(1);
+        const [currentItems, setCurrentItems] = React.useState(['']);
+
+        {
+          /* This is similar to componentDidMount and componentDidUpdate */
+        }
+        React.useEffect(() => {
+          let lastItem = page * range;
+          const firstItem = lastItem - range;
+          if (lastItem > items.length) {
+            lastItem = items.length;
+          }
+
+          setCurrentItems(items.slice(firstItem, lastItem));
+        }, [page, items, range]);
+
+        return (
+          <>
+            <Pagination
+              currentPage={page}
+              currentRange={range}
+              rangeOptions={ranges}
+              totalItems={items.length}
+              onPageChange={newPage => setPage(newPage)}
+              onRangeChange={newRange => setRange(newRange)}
+            />
+            <ul>
+              {currentItems.map(item => (
+                <li>{item}</li>
+              ))}
+            </ul>
+          </>
+        );
+      }}
+      {/* jsx-to-string:end */}
+    </CodePreview>
+
+    <H1>API</H1>
+
+    <H2>Pagination</H2>
+
+    <PaginationPropTable />
+
+    <H2>Inherited Props</H2>
+
+    <Collapsible title="Inherited Props">
+      <MarginPropTable />
+    </Collapsible>
+  </>
+);