uswds · thisisdano · Jun 16, 2021 · Apr 29, 2021 · Apr 29, 2021 · Apr 29, 2021
diff --git a/_components/pagination/guidance/accessibility.md b/_components/pagination/guidance/accessibility.md
@@ -0,0 +1,11 @@
+- **Use the `<nav>` element.** Use a wrapping `<nav>` element to identify Pagination as a navigation section to screen readers and other assistive technologies.
+
+- **Use a unique, descriptive ARIA label for the <nav> element.** Provide a descriptive ARIA label for any Pagination component's `<nav>` element that describes its purpose. For example, if the pagination component is used to navigate through a set of search results, an appropriate label could be `aria-label="search results page"`.  If you use more than one Pagination component on a page, each will need a unique ARIA label.
+
+- **Use an unordered list for the navigation items.** This allows screen readers to voice the number of elements in the Pagination component
+
+- **Voice the current page.** Use `aria-current="page"` on the current page's link item to properly voice the current page for screen readers.
+- **Voice the word "page" before the page numbers in links.** Use `aria-label="page [#]"` on each page link to be explicit that the numbers are links to page numbers.
+- **Voice "last page" on the last page's link in a bounded set.** Use `aria-label="last page, page [#]"` to voice that the last element in the navigation is the last page in the paginated section. Don't include this on the last navigation element in an unbounded set, since there is no last page in an unbounded set.
+- **Use a link for the current page for robustness.** While it may sound counterintuitive to link to the current page in your Pagination component, it makes sense to include this as a link so screen readers voice the current page whether the user navigates by element or by tabbing.
+- **Avoid large horizontal gaps between elements.** Users with limited vision or mobility may stop scanning and miss an element if there's too much horizontal space between it and the previous element in the reading order.
diff --git a/_components/pagination/guidance/implementation.md b/_components/pagination/guidance/implementation.md
@@ -0,0 +1,158 @@
+Unlike many USWDS components, Pagination includes behaviors we cannot build into the HTML, CSS, and JavaScript we ship with the design system. Developers will need to build these behaviors into their Pagination templates. We've outlined these behaviors below, and included them in the Nunjucks templates for Pagination in our source code.
+
+{:.usa-content-list}
+- **Set the current page item.** Use the `usa-current` class to highlight the currently active page.
+- **Pair with the Collection component.** To display related items like articles or events in a compact list, consider using Pagination with the [Collection component]({% link _components/collection/collection.md %}), which offers short descriptions and then directs users to the original source.
+- **Bounded and unbounded sets.** The USWDS Pagination component is designed to work with both paginated sets that have a discrete number of pages (most paginated content) and those that do not. **Bounded sets** have a discrete number of pages and each page is potentially equally relevant (such as a set of blog posts sorted chronologically). **Unbounded sets** (often returned as a search result) are large sets sorted by relevance, where deeper pages have less relevance. Unbounded sets show no last page.
+
+#### Behaviors
+<div class="measure-5">
+  <p>Pagination is navigation for paginated content. Taken as a whole, we call this paginated content a <strong>set</strong> Each item in the set is a <strong>page</strong> and the page the reader is on is the <strong>current page</strong>.</p>
+
+  <p>The Pagination component includes seven equal-sized, equally spaced <strong>slots</strong> arranged in a single horizontal line.  Each slot can accept a <strong>navigation item</strong> (typically a link to a specific page) or an <strong>overflow indicator</strong> (we use an ellipsis) to indicate that there are pages we're not showing. In the behaviors below, we'll number the slots 1–7, from left to right.</p>
+</div>
+
+<h5>General component properties</h5>
+
+<ul>
+  <li>The component features a maximum of seven slots.</li>
+  <li>Each slot can contain a navigation item or an overflow indicator.</li>
+  <li>The first slot is always the first page of the set.</li>
+  <li>If there are fewer than seven pages in the set, show only that number of slots.</li>
+  <li>The component should always show the first page and current page.</li>
+  <li>Show the next page, previous page, and last page if those pages exist.</li>
+  <li>Display the same number of slots for each page in the set.</li>
+</ul>
+
+<h5>Pagination behaviors</h5>
+
+<ul class="pagination-behaviors">
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      Remove extra slots if there are fewer than 7 pages.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-01-extra-slots.png"
+        alt="Example: A three-page set shows three items in three slots only. Slot one is current."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      Always highlight the current page.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-02-current-page.png"
+        alt="Example: A three-page set shows three items. Slot two is current and shows a distinct background color."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      Hide the <code>Previous</code> link on the first page of the set and hide the <code>Next</code> link on the last page of the set.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-03a-prev-next.png"
+        alt="Example: A three-page set shows three pages. Slot one is current. There is a 'next' link following the items. There is no previous link."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-03b-prev-next.png"
+        alt="Example: A three-page set shows three pages. Slot two is current. There is a 'previous' link preceding the items. There is a 'next' link following the items."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-03c-prev-next.png"
+        alt="Example: A three-page set shows three pages. Slot three is current. There is a 'previous' link preceding the items. There is no 'next' link."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      Always show both the previous page and the next page adjacent to the current page.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-4a.png"
+        alt="Example: A eight-page set shows pages 1 to 5 in slots 1 to 5. Slot 4 is current. Slot 6 shows an overflow indicator. Slot 7 shows page 8."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-4b.png"
+        alt="Incorrect example: A eight-page set shows page 1 in slot 1. Slot 2 is an overflow indicator. Slot 3 contains page 4 and is current. This is incorrect because we do not see page 3, the previous page in this instance."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      Show an overflow indicator when there are pages missing.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-5a.png"
+        alt="Example: A eight-page set. Page 1 is the current page. Instance shows pages 1 to 5 in slots 1 to 5. Slot 6 is overflow. Slot 7 page 8."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-5b.png"
+        alt="Example: A eight-page set. Page 5 is the current page. Instance shows page 1 in Slot 1. Slot 2 is overflow. Pages 4 to 8 appear in slots 3 to 7."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-5c.png"
+        alt="Example: A eight-page set. Page 6 is the current page. Instance shows page 1 in Slot 1. Slot 2 is overflow. Pages 4 to 8 appear in slots 3 to 7."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      <strong>Bounded</strong> sets can show overflow indicators in Slot 2 and Slot 6 only.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-6a.png"
+        alt="Example: A nine-page set. Page 5 is the current page. Instance shows page 1 in Slot 1. Slot 2 is overflow. Slots 3 to 5 contain Pages 4, 5, and 6. Slot 6 is overflow. Slot 7 is page 9."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-6b.png"
+        alt="Incorrect example: A nine-page set. Page 7 is the current page. Instance shows page 1 in Slot 1. Slots 2 and 3 are overflow. Slots 4 to 7 contain Pages 6 to 9. Slot 7 is page 8. Incorrect because Slot 3 is overflow."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      <strong>Unbounded</strong> sets always show an overflow indicator in Slot 7.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-7.png"
+        alt="Example: A unbounded set. Page 1 is the current page. Slots 1 to 6 contain pages 1 to 6. Slot 7 is overflow."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+  <li class="pagination-behaviors--item">
+    <p class="pagination-behaviors--guidance">
+      <strong>Unbounded sets</strong> use Slot 4 as the current page for pages 4 and higher.
+    </p>
+    <div class="pagination-behaviors--examples">
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-8a.png"
+        alt="Example: A unbounded set. Page 4 is the current page. Slots 1 to 6 contain pages 1 to 6. Slot 7 is overflow."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-8b.png"
+        alt="Example: A unbounded set. Page 5 is the current page. Slot 1 is page 1. Slot 2 is overflow. Slots 3 to 6 contain pages 4 to 7. Slot 4 is current. Slot 7 is overflow."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-8c.png"
+        alt="Example: A unbounded set. Page 7 is the current page. Slot 1 is page 1. Slot 2 is overflow. Slots 3 to 6 contain pages 6 to 9. Slot 4 is current. Slot 7 is overflow."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-8d.png"
+        alt="Incorrect example: A unbounded set. Page 7 is the current page. Slot 1 is page 1. Slot 2 is overflow. Slots 3 to 6 contain pages 5 to 8. Slot 5 is current. Slot 7 is overflow. Incorrect because Slot 5 is current."
+        class="pagination-behaviors--example" />
+      <img
+        src="{{ site.baseurl }}/assets/img/components/pagination/pagination-behaviors-8e.png"
+        alt="Incorrect example: A unbounded set. Page 7 is the current page. Slot 1 is page 1. Slot 2 is overflow. Slots 3 to 6 contain pages 4 to 7. Slot 6 is current. Slot 7 is overflow. Incorrect because Slot 6 is current."
+        class="pagination-behaviors--example" />
+    </div>
+  </li>
+</ul>
diff --git a/_components/pagination/guidance/usability.md b/_components/pagination/guidance/usability.md
@@ -0,0 +1,12 @@
+- **Show the size of the paginated set.** Users want to know the length of a paginated section. This is most commonly accomplished by always showing the last page as the last item in the pagination navigation. Users should also know if the set is unbounded and has no discrete length. For example, some large search results will not have a "last" page. The USWDS Pagination component will always show the last page of the set as a navigable link, or show an ellipsis at the end of the links if the set is unbounded.
+
+- **Highlight the current page.** Pagination shows the current page the user is on in relation to the entire collection of pages.
+
+- **Always include the first, previous, and next pages.** Users should always be able to navigate to each of these pages from any page in the set.
+
+- **Show navigation items in a single line.** Pagination can be hard to understand — and individual items can be more difficult to select — when the items break over one line. Don't split the navigation items over multiple lines. Avoid using Pagination in any context where it would be more than one line long.
+
+- **Indicate any missing pages.** Don't include out-of-sequence items directly adjacent to one another. Whenever there are pages missing — either between two elements, or at the end of an unbounded sequence — indicate the missing pages with an indicator like a non-selectable ellipsis.
+- **Use as few navigation items as possible.** Showing more pages than necessary tends to add complexity and use more space without proportional increases to the component's functionality.  Focus on the essential actions and avoid adding more items to Pagination just to fill space.
+- **Use generous touch targets.** Use touch targets that are big enough to select with any finger and have enough separation to avoid mistakes.
+- **Optimize the number of entries per page.** Consider page load, performance, and the user's scrolling preferences when determining how many items are displayed on each page. Some paginated content benefits from user control over the number of elements to show on each page.
diff --git a/_components/pagination/guidance/when-to-consider-something-else.md b/_components/pagination/guidance/when-to-consider-something-else.md
@@ -0,0 +1,5 @@
+- **Meaningful page groupings.** IIf you have long content split meaningfully, or grouped by subject or theme, use conventional navigation like [Side navigation]({% link _components/sidenav/sidenav.md %}).
+
+- **Steps in a sequence.** If you need to indicate progress in a series of steps that must be completed in succession, like an onboarding flow, consider using the [step indicator component]({% link _components/step-indicator/step-indicator.md %}).
+
+- **Short collections.** 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.
diff --git a/_components/pagination/guidance/when-to-use.md b/_components/pagination/guidance/when-to-use.md
@@ -0,0 +1,3 @@
+- **Search results.** Pagination is most commonly used with paginated search results. Our Pagination component is designed to work both with results that have a discrete number of results pages (bounded) and those with an uncalculated number of results pages (unbounded). See [Using the Pagination component](#using-the-pagination-component), below, for more on bounded and unbounded sets.
+
+- **Multi-page collections of related items.** Splitting a large collection of related items into individual pages can improve browsability and scannability. Common examples of multi-page collections include articles related to a category or tag, content archives, and history or activity.
diff --git a/_components/pagination/pagination.md b/_components/pagination/pagination.md
@@ -0,0 +1,22 @@
+---
+category: Components
+component:
+  name: pagination
+  status: ready
+  package: usa-pagination
+  dependencies:
+lead: Pagination is navigation for paginated content.
+permalink: /components/pagination/
+subnav:
+- text: Preview
+  href: '#pagination-preview'
+- text: Code
+  href: '#pagination-code'
+- text: Guidance
+  href: '#pagination-guidance'
+- text: Package
+  href: '#pagination-package'
+title: Pagination
+type: component
+---
+Paginated content is any content split into multiple pages determined only 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.
diff --git a/_config.yml b/_config.yml
@@ -2,7 +2,7 @@
 title: U.S. Web Design System (USWDS)
 description: USWDS makes it easier to build accessible, mobile-friendly government websites.
 google_analytics_ua: UA-48605964-43
-uswds_version: 2.11.2
+uswds_version: 2.12.0
 federalist_base: "https://federalist-3b6ba08e-0df4-44c9-ac73-6fc193b0e19c.app.cloud.gov/preview/uswds/uswds"
 federalist_component_preview: "components/preview"
 federalist_release_prefix: "release-"
@@ -44,7 +44,7 @@ jekyll_get:
     json: "https://api.github.com/repos/uswds/uswds/contents/SECURITY.md"
     decode_content: true
   - data: hash
-    json: "https://api.github.com/repos/uswds/uswds/contents/security/uswds-2.11.2-zip-hash.txt?ref=main"
+    json: "https://api.github.com/repos/uswds/uswds/contents/security/uswds-2.12.0-zip-hash.txt?ref=main"
     decode_content: true
 
 repos:

diff --git a/_data/nav.yml b/_data/nav.yml
@@ -55,6 +55,7 @@ Components:
   - href: /components/link/
   - href: /components/list/
   - href: /components/modal/
+  - href: /components/pagination/
   - href: /components/process-list/
   - href: /components/prose/
   - href: /components/radio-buttons/

diff --git a/_data/settings/components/pagination.yml b/_data/settings/components/pagination.yml
@@ -0,0 +1,27 @@
+name: Pagination
+contents:
+  - name: Pagination background color
+    description: The background color of the entire pagination component, used for accessible color setting.
+    var: $theme-pagination-background-color
+    default: '"white"'
+    type: color
+  - name: Breakpoint
+    description: Breakpoint at which full pagination displays.
+    var: $theme-pagination-breakpoint
+    default: '"tablet"'
+    type: units
+  - name: Button border radius
+    description: Default pagination button border radius.
+    var: $theme-pagination-button-border-radius
+    default: '"md"'
+    type: units
+  - name: Button border width
+    description: Width of button border.
+    var: $theme-pagination-button-border-width
+    default: "1px"
+    type: units
+  - name: Font family
+    description: Default font family for pagination.
+    var: $theme-pagination-font-family
+    default: '"ui"'
+    type: family
diff --git a/_includes/code/components/pagination.html b/_includes/code/components/pagination.html
@@ -0,0 +1,20 @@
+<h3 class="site-preview-heading">Default</h3>
+{% capture pagination %}
+  {% fractal_component pagination %}
+{% endcapture %}{{ pagination | strip }}
+
+<h3 class="site-preview-heading">unbounded</h3>
+{% capture pagination--unbounded %}
+  {% fractal_component pagination--unbounded %}
+{% endcapture %}{{ pagination--unbounded | strip }}
+
+<h3 class="site-preview-heading">Default (Spanish)</h3>
+{% capture pagination--lang-es %}
+{% fractal_component pagination--lang-es %}
+{% endcapture %}{{ pagination--lang-es }}
+
+<h3 class="site-preview-heading">unbounded (Spanish)</h3>
+{% capture pagination--unbounded-lang-es %}
+  {% fractal_component pagination--unbounded-lang-es %}
+{% endcapture %}{{ pagination--unbounded-lang-es | strip }}
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		- Search results. Pagination is most commonly used with paginated search results. Our Pagination component is designed to work both with results that have a discrete number of results pages (bounded) and those with an uncalculated number of results pages (unbounded). See [Using the Pagination component](#using-the-pagination-component), below, for more on bounded and unbounded sets.

		- Multi-page collections of related items. Splitting a large collection of related items into individual pages can improve browsability and scannability. Common examples of multi-page collections include articles related to a category or tag, content archives, and history or activity.