diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index af3855f0ea..24bdc1438d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -5,9 +5,13 @@ name: build on: push: - branches: [ master ] + branches: + - master + - development pull_request: - branches: [ master ] + branches: + - master + - development jobs: build: diff --git a/examples/create-react-app-typescript/src/components/App.tsx b/examples/create-react-app-typescript/src/components/App.tsx index c3db5c0774..27a02332b8 100644 --- a/examples/create-react-app-typescript/src/components/App.tsx +++ b/examples/create-react-app-typescript/src/components/App.tsx @@ -14,6 +14,7 @@ import HelpDrawerExample from './Examples/HelpDrawerExample'; import MaskedFieldExample from './Examples/MaskedFieldExample'; import ModalDialogExample from './Examples/ModalDialogExample'; import MonthPickerExample from './Examples/MonthPickerExample'; +import PaginationExample from './Examples/PaginationExample'; import SpinnerExample from './Examples/SpinnerExample'; import TableExample from './Examples/TableExample'; import TabsExample from './Examples/TabsExample'; @@ -110,6 +111,7 @@ function App() { + diff --git a/examples/create-react-app-typescript/src/components/Examples/PaginationExample.tsx b/examples/create-react-app-typescript/src/components/Examples/PaginationExample.tsx new file mode 100644 index 0000000000..da868d70c4 --- /dev/null +++ b/examples/create-react-app-typescript/src/components/Examples/PaginationExample.tsx @@ -0,0 +1,13 @@ +import { Pagination } from '@cmsgov/design-system'; +import React from 'react'; + +function PaginationExample(): React.ReactElement { + return ( +
+

Pagination Example

+ +
+ ); +} + +export default PaginationExample; diff --git a/examples/create-react-app/src/components/App.js b/examples/create-react-app/src/components/App.js index 9ee2297e6b..9184580962 100644 --- a/examples/create-react-app/src/components/App.js +++ b/examples/create-react-app/src/components/App.js @@ -14,6 +14,7 @@ import HelpDrawerExample from './Examples/HelpDrawerExample'; import MaskedFieldExample from './Examples/MaskedFieldExample'; import ModalDialogExample from './Examples/ModalDialogExample'; import MonthPickerExample from './Examples/MonthPickerExample'; +import PaginationExample from './Examples/PaginationExample'; import SpinnerExample from './Examples/SpinnerExample'; import TableExample from './Examples/TableExample'; import TabsExample from './Examples/TabsExample'; @@ -110,6 +111,7 @@ function App() { + diff --git a/examples/create-react-app/src/components/Examples/PaginationExample.js b/examples/create-react-app/src/components/Examples/PaginationExample.js new file mode 100644 index 0000000000..66fea20027 --- /dev/null +++ b/examples/create-react-app/src/components/Examples/PaginationExample.js @@ -0,0 +1,13 @@ +import { Pagination } from '@cmsgov/design-system'; +import React from 'react'; + +function PaginationExample() { + return ( +
+

Pagination Example

+ +
+ ); +} + +export default PaginationExample; diff --git a/packages/design-system-docs/src/pages/components/Pagination/Pagination.example.jsx b/packages/design-system-docs/src/pages/components/Pagination/Pagination.example.jsx new file mode 100644 index 0000000000..3ab3b20ea7 --- /dev/null +++ b/packages/design-system-docs/src/pages/components/Pagination/Pagination.example.jsx @@ -0,0 +1,86 @@ +import { Pagination } from '@design-system'; +import React from 'react'; +import ReactDOM from 'react-dom'; +import State from '../State/State'; + +ReactDOM.render( +
+
Default pagination
+ + {([page, setPage]) => { + const totalPages = 15; + const onPageChange = (evt, page) => { + evt.preventDefault(); + setPage(page); + }; + return ( + <> + + Current page: {page} / {totalPages} + + `#/results/${page}`} + /> + + ); + }} + + +
Pagination with hidden navigation
+ + {([page, setPage]) => { + const totalPages = 15; + const onPageChange = (evt, page) => { + evt.preventDefault(); + setPage(page); + }; + return ( + <> + + Current page: {page} / {totalPages} + + `#${page}`} + isNavigationHidden + /> + + ); + }} + + +
Compact pagination
+ + {([page, setPage]) => { + const totalPages = 15; + const onPageChange = (evt, page) => { + evt.preventDefault(); + setPage(page); + }; + return ( + <> + + Current page: {page} / {totalPages} + + `#/results?page=${page}`} + compact + /> + + ); + }} + +
, + document.getElementById('js-example') +); diff --git a/packages/design-system-docs/src/pages/components/Pagination/_Pagination.docs.scss b/packages/design-system-docs/src/pages/components/Pagination/_Pagination.docs.scss new file mode 100644 index 0000000000..6dfa233f69 --- /dev/null +++ b/packages/design-system-docs/src/pages/components/Pagination/_Pagination.docs.scss @@ -0,0 +1,83 @@ +/* +Pagination + +@uswds https://designsystem.digital.gov/components/pagination/ + +Pagination is navigation for paginated content. + +## About the pagination component + +Paginated content is any content split into multiple pages determined by a specific amount of content per page, not split by any meaningful attribute, like feature or subject or step. Search results and article collections are often paginated. Readers use the pagination component to move from page to page in paginated content, or directly to the first or last page of the paginated set. + +Markup: pagination.example.html + +@status Draft + +Style guide: components.pagination +*/ + +/* +`` + +Pagination requires two properties: `totalPages`, which is the total number of pages, and `onPageChange`, which is a function used to handle state changes when the user clicks a page. + +Pagination also comes in two styles: default, which is compact on mobile viewports and expands to reveal individual pages on larger viewports, and `compact`, which maintains the compact layout regardless of viewport size. + +@react-example Pagination.example.jsx + +@react-props Pagination.tsx + +Style guide: components.pagination.react +*/ + +/* +--- + +### When to use + +- Typically used for paginated search results. +- Can be used for multi-page collections of related items, including articles related to a category or tag, content archives, and history or activity. Splitting a large collection of related items into individual pages can improve browsability and scannability. + +### When to consider alternatives + +- If you need to indicate progress in a series of steps that must be completed in succession, like an onboarding or checkout flow, this isn't the component for you. +- If the length of the entire collection is less than 3-4 screen lengths long, consider showing all the items at once instead of paginating. + +### Usage + +- Users want to know the length of a paginated section, so show the size of the paginated set. +- Highlight the current page the user is on in relation to the entire collection of pages. +- Don't split the navigation items over multiple lines as this can make individual pages more difficult to understand and select. +- Don't include out-of-sequence items directly adjacent to one another. Wherever there are missing pages, an ellipses should be used. +- Avoid adding complexity by focusing on the essentials and avoid adding more items to Pagination just to fill the space. +- Use touch targets that are big enough to select with any finger and have enough separation to avoid mistakes. +- Do not use buttons for URL-based pagination. Because the URL is updated, the browser history stack updates and a link is the correct tag to use. +- Consider page load, performance, and the user's scrolling preferences when determining how many items are displayed on each page. + +### Style customization + +The following Sass variables can be overridden to theme alerts: + +- `$pagination-nav-link-color` - Used to set color of next/previous and page number links. +- `$pagination-nav-link-color-hover` - Used to set color of next/previous and page number links on hover. +- `$pagination-nav-link-color-active` - Used to set color of next/previous and page number links when active. +- `$pagination-nav-link-color-focus` - Used to set color of next/previous and page number links on focus. + +- `$pagination-current-page-color` - Used to set the current page element text color. +- `$pagination-overflow-color` - Used to set the overflow element text color. +- `$pagination-page-count-color` - Used to set the page count element text color. + +### Accessibility + +- Use a wrapping `