@workday/canvas-kit-docs 6.0.0-alpha.0-next.30 → 6.0.0-alpha.0-next.36

package/dist/mdx/react/pagination/pagination.mdx

@@ -1,84 +1,29 @@
 import {Pagination} from '@workday/canvas-kit-react/pagination';
-import StepControls from './examples/StepControls';
+
+import Basic from './examples/Basic';
 import CustomRange from './examples/CustomRange';
 import JumpControls from './examples/JumpControls';
 import GoToForm from './examples/GoToForm';
-import ShowAdditionalDetails from './examples/ShowAdditionalDetails';
 import HoistedModel from './examples/HoistedModel';
 import RTL from './examples/RTL';
+import {
+  PaginationHoistedComponent,
+  PageButtonComponent,
+  PageListComponent,
+  AdditionalDetailsComponent,
+  PaginationModelConfigComponent,
+  PaginationStateComponent,
+  PaginationEventsComponent,
+} from './PropTables.splitprops.tsx';
 
 
-# Canvas Kit Labs React Pagination
+# Canvas Kit Pagination
 
 `Pagination` is a
-[Compound Component](/getting-started/for-developers/resources/compound-components/) for handling
-navigation between pages in a range.
-
-## Table of Contents
-
-- [Canvas Kit React Pagination](#canvas-kit-react-pagination)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Usage](#usage)
-    - [Basic Usage](#basic-usage)
-      - [Pagination with Step Controls](#pagination-with-step-controls)
-      - [Pagination with Jump Controls](#pagination-with-jump-controls)
-      - [Pagination with a GoTo Form](#pagination-with-a-goto-form)
-    - [Advanced Usage](#advanced-usage)
-      - [Hoisted Model Pattern](#hoisted-model-pattern)
-  - [Components](#components)
-    - [Pagination](#pagination)
-      - [Usage](#usage-1)
-      - [Component Props](#component-props)
-    - [Pagination.Controls](#paginationcontrols)
-      - [Usage](#usage-2)
-      - [Component Props](#component-props-1)
-    - [Pagination.JumpToFirstButton](#paginationjumptofirstbutton)
-      - [Usage](#usage-3)
-      - [Component Props](#component-props-2)
-    - [Pagination.StepToPreviousButton](#paginationsteptopreviousbutton)
-      - [Usage](#usage-4)
-      - [Component Props](#component-props-3)
-    - [Pagination.StepToNextButton](#paginationsteptonextbutton)
-      - [Usage](#usage-5)
-      - [Component Props](#component-props-4)
-    - [Pagination.JumpToLastButton](#paginationjumptolastbutton)
-      - [Usage](#usage-6)
-      - [Component Props](#component-props-5)
-    - [Pagination.PageList](#paginationpagelist)
-      - [Usage](#usage-7)
-      - [Component Props](#component-props-6)
-    - [Pagination.PageListItem](#paginationpagelistitem)
-      - [Usage](#usage-8)
-      - [Component Props](#component-props-7)
-    - [Pagination.PageButton](#paginationpagebutton)
-      - [Usage](#usage-9)
-      - [Component Props](#component-props-8)
-    - [Pagination.GoToForm](#paginationgotoform)
-      - [Usage](#usage-10)
-      - [Component Props](#component-props-9)
-    - [Pagination.GoToTextInput](#paginationgototextinput)
-      - [Usage](#usage-11)
-      - [Component Props](#component-props-10)
-    - [Pagination.GoToLabel](#paginationgotolabel)
-      - [Usage](#usage-12)
-      - [Component Props](#component-props-11)
-    - [Pagination.AdditionalDetails](#paginationadditionaldetails)
-      - [Usage](#usage-13)
-      - [Component Props](#component-props-12)
-  - [Models, Hooks, & Utils](#models-hooks--utils)
-    - [PaginationModel](#paginationmodel)
-      - [State](#state)
-      - [Events](#events)
-    - [usePaginationModel Hook](#usepaginationmodel-hook)
-      - [Configuration](#configuration)
-      - [Usage](#usage-14)
-    - [getLastPage](#getlastpage)
-    - [getRangeMin](#getrangemin)
-    - [getRangeMax](#getrangemax)
-    - [getVisibleResultsMin](#getvisibleresultsmin)
-    - [getVisibleResultsMax](#getvisibleresultsmax)
-    - [PaginationContext](#paginationcontext)
+[compound component](/getting-started/for-developers/resources/compound-components/) that allows
+users to navigate between pages in a range.
+
+[> Workday Design Reference](https://design.workday.com/components/navigation/pagination)
 
 ## Installation
 
@@ -88,118 +33,71 @@ yarn add @workday/canvas-kit-react
 
 ## Usage
 
-`Pagination` is a compound component, meaning it can be put together and used in a variety of
-different ways. We'll first cover [basic usage](#basic-usage) examples followed by
-[advanced usage](#advanced-usage). Each of the examples is intended to be standalone, so you can
-skip to the section that best fits your use case.
+### Basic Example
 
-These examples are designed to provide copy-and-paste snippets to help you get up and running
-quickly without much explanation. Further detail on individual component props, behavior, and
-accessibility can be found in the [Components](#components) section.
+`Pagination` includes a container `Pagination` component and a number of subcomponents which can be
+composed in a variety of ways.
 
----
+In this example, we set up a basic `Pagination` component with the default range of five pages, as
+well as step controls (`Pagination.StepToPreviousButton` and `Pagination.StepToNextButton`) that
+allow you to move to the previous page or the next page.
 
-### Basic Usage
+<ExampleCodeBlock code={Basic} />
 
-Below are examples we expect will work for most use cases. Please refer to the
-[Advanced Usage](#advanced-usage) section for details on supporting custom implementations.
+Note that you must include `Pagination.AdditionalDetails` to meet accessibility standards (with one
+exception, see [`Pagination.AdditionalDetails`](#paginationadditionaldetails) for more information).
+It is an `aria-live` region that announces the current page update to screen readers. If you wish to
+prevent it from displaying (as we've done in the remaining examples), you may set its
+`shouldHideDetails` prop to `true`. The visually hidden region will still be accessible to screen
+readers.
 
-#### Step Controls
+### Hoisted Model
 
-In this example, the component uses step controls (`Pagination.StepToPreviousButton` and
-`Pagination.StepToNextButton`) that allow you to move to the next page and previous pages.
+By default, `Pagination` will create and use its own [model](#model) internally. Alternatively, you
+may configure your own model with `usePaginationModel` and pass it to `Pagination` via the `model`
+prop. This pattern is referred to as
+[hoisting the model](/getting-started/for-developers/resources/compound-components/#configuring-a-model)
+and provides direct access to its `state` and `events` outside of the `Pagination` component.
 
-<ExampleCodeBlock code={StepControls} />
+In this example, we set up external observation of the model state and create an external button to
+trigger an event to change the current page.
 
----
+<ExampleCodeBlock code={HoistedModel} />
 
-#### Jump Controls
+### Jump Controls
 
 This example adds jump controls (`Pagination.JumpToFirstButton` and `Pagination.JumpToLastButton`)
-that allow you to skip to the first and last items in the range.
+that allow you to skip to the first and last pages in the range.
 
 <ExampleCodeBlock code={JumpControls} />
 
----
-
-#### GoTo Form
+### GoTo Form
 
 This example adds a form (`Pagination.GoToForm`) that allows you to skip to a specific page within
 the range.
 
 <ExampleCodeBlock code={GoToForm} />
 
----
-
-#### Additional Details
-
-This example adds a visible section (`Pagination.AdditionalDetails`). It is an `aria-live` region
-that announces the current page update to screen readers. Because of that, it's important to
-**always†** include it in your `Pagination` component.
-
-In the case where you would also have multiple `Pagination` components sharing the same state and
-you'd like to keep the `AdditionalDetails` component on multiple, you will need to set
-`shouldAnnounceToScreenReader` to `false` on all but one component to prevent announcement.
-
-> **†** _The only exception to this rule is when you have multiple `Pagination` components that are
-> sharing the same state and rendered on the page. You can then safely remove all but one of the
-> `AdditionalDetails` sections. This will prevent a screenreader from announcing updates multiple
-> times to a user._
-
-<ExampleCodeBlock code={ShowAdditionalDetails} />
-
----
+### Right-to-Left (RTL)
 
-#### RTL (Right-to-Left)
-
-This example shows how the component supports right-to-left languages.
+`Pagination` supports right-to-left languages when specified in the `CanvasProvider` `theme`.
 
 <ExampleCodeBlock code={RTL} />
 
----
-
-#### Custom Range
+### Custom Range
 
 This example uses a custom range that allows you to control the width of the component.
 
 <ExampleCodeBlock code={CustomRange} />
 
----
-
-### Advanced Usage
-
-Below are examples for more advanced / custom usage of these components. We expect most people won't
-need to read this section, but if you're needing to go beyond our basic examples or just curious,
-feel free to explore this section. While this section is not exhaustive, it provides additional
-insight into what's possible.
-
-#### Hoisted Model Pattern
-
-If you're unfamiliar with compound components, the pagination model, or the `usePaginationModel`
-hook, we would recommend reviewing the [PaginationModel](#paginationmodel) section first.
-
-If you want the `Pagination` component to handle its state and events internally and hook into page
-change events, the basic usage examples above should be sufficient. However, if you need external
-access to the model, you can use the hoisted model pattern. You can create a model outside of the
-component with the `usePaginationModel` hook.
-
-For this example, we'll create a `Pagination` component that handles 128 total items with 10 items
-per page.
-
-<ExampleCodeBlock code={HoistedModel} />
-
 ## Components
 
 ### Pagination
 
-The `Pagination` component is a wrapper for a React context provider and `nav` element. Child
-components such as `Pagination.StepToPreviousButton`, `Pagination.PageList`, etc. subscribe to that
-context.
-
 #### Usage
 
-`Pagination` can be used with or without providing a model. For basic usage, you only need to
-provide a configuration as in the example below.
+`Pagination` is a container component rendered as a `<nav>` element that is responsible for creating
+a `PaginationModel` and sharing it with its subcomponents using React context.
 
 ```tsx
 <Pagination
@@ -209,172 +107,143 @@ provide a configuration as in the example below.
   rangeSize={3}
   onPageChange={pageNumber => console.log(pageNumber)}
 >
-  {/* child components go here */}
+  {/* Child components */}
 </Pagination>
 ```
 
-However, if you'd like to provide a model, you can follow the example below. This is called the
-hoisted model pattern. Note that in this pattern, the only props needed are `model` and
-`aria-label`.
+Alternatively, you may pass in a model using the hoisted model pattern.
 
 ```tsx
-const modelConfig = {
+const model = usePaginationModel({
   lastPage: 100,
   initialCurrentPage: 6,
   rangeSize: 3,
   onPageChange: pageNumber => console.log(pageNumber),
-};
-const model = usePaginationModel(modelConfig);
+});
 
 return (
   <Pagination aria-label="Pagination" model={model}>
-    {/* child components go here */}
+    {/* Child components */}
   </Pagination>
 );
 ```
 
-#### Component Props
+#### Props
 
-Given that there are two ways to configure `Pagination`, there are also two props tables. For the
-configuration pattern, follow this table:
+Undocumented props are spread to the underlying `<nav>` element.
 
-| name               | type                           | required?  | default | recommended                              |
-| ------------------ | ------------------------------ | ---------- | ------- | ---------------------------------------- |
-| aria-label         | `string`                       | ✅ `true`  | n/a     | "Pagination" (and translated equivalent) |
-| lastPage           | `number`                       | ✅ `true`  | n/a     | n/a                                      |
-| initialCurrentPage | `number`                       | 🚫 `false` | 1       | n/a                                      |
-| rangeSize          | `number`                       | 🚫 `false` | 5       | n/a                                      |
-| firstPage          | `number`                       | 🚫 `false` | 1       | n/a                                      |
-| onPageChange       | `(pageNumber: number) => void` | 🚫 `false` | n/a     | n/a                                      |
+<ArgsTable of={PaginationModelConfigComponent} />
 
-And for the hoisted model pattern, follow this table:
+If you're using the hoisted model pattern, follow this table instead (refer to the [Model](#model)
+section for more information about `PaginationModel`):
 
-| name       | type              | required? | default | recommended                              |
-| ---------- | ----------------- | --------- | ------- | ---------------------------------------- |
-| aria-label | `string`          | ✅ `true` | n/a     | "Pagination" (and translated equivalent) |
-| model      | `PaginationModel` | ✅ `true` | n/a     | n/a                                      |
+<ArgsTable of={PaginationHoistedComponent} />
 
-This component also supports
-[all native HTMLElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes).
-The `aria-label` prop is required for accessibility. We recommend using `"Pagination"` as seen in
-the example.
-
----
+Note that you must set `aria-label` in either case to meet accessibility standards. We recommend
+setting it to `Pagination` or the translated equivalent.
 
 ### Pagination.Controls
 
-`Pagination.Controls` is a styled `div` wrapper that provides proper alignment and spacing between
-elements inside `Pagination`. It does not handle any internal business logic or state.
-
 #### Usage
 
+`Pagination.Controls` is a styled `<div>` element that provides proper alignment and spacing between
+elements inside `Pagination`. It does not handle any internal business logic or state.
+
 ```tsx
-<Pagination.Controls>{/* child components go here */}</Pagination.Controls>
+<Pagination.Controls>{/* Child components */}</Pagination.Controls>
 ```
 
-#### Component Props
+#### Props
 
-This component supports
-[all native HTMLDivElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#Attributes).
+`Pagination.Controls` does not have any documented props.
 
----
+Undocumented props are spread to the underlying `<div>` element.
 
 ### Pagination.JumpToFirstButton
 
-`Pagination.JumpToFirstButton` is an `IconButton` that subscribes to `Pagination`'s context. This
-allows it to know when to disable and set `currentPage` to the first page.
-
 #### Usage
 
+`Pagination.JumpToFirstButton` is an `IconButton` that subscribes to the `Pagination` context. This
+allows it to know when to disable and set `currentPage` to the first page.
+
 ```tsx
 <Pagination.JumpToFirstButton aria-label="First" />
 ```
 
-#### Component Props
-
-| name       | type     | required? | default | recommended                         |
-| ---------- | -------- | --------- | ------- | ----------------------------------- |
-| aria-label | `string` | ✅ `true` | n/a     | "First" (and translated equivalent) |
+#### Props
 
-This component also supports all `IconButton` props.
+Undocumented props are spread to the underlying `<button>` element. Note that you must set
+`aria-label` to meet accessibility standards. We recommend setting it to `First` or the translated
+equivalent.
 
----
+`Pagination.JumpToFirstButton` supports all `IconButton` props.
 
 ### Pagination.StepToPreviousButton
 
-`Pagination.StepToPreviousButton` is an `IconButton` that subscribes to `Pagination`'s context. This
-allows it to know when to disable and decrement the `currentPage`.
-
 #### Usage
 
+`Pagination.StepToPreviousButton` is an `IconButton` that subscribes to the `Pagination` context.
+This allows it to know when to disable and decrement the `currentPage`.
+
 ```tsx
 <Pagination.StepToPreviousButton aria-label="Previous" />
 ```
 
-#### Component Props
+#### Props
 
-| name       | type     | required? | default | recommended                            |
-| ---------- | -------- | --------- | ------- | -------------------------------------- |
-| aria-label | `string` | ✅ `true` | n/a     | "Previous" (and translated equivalent) |
+Undocumented props are spread to the underlying `<button>` element. Note that you must set
+`aria-label` to meet accessibility standards. We recommend setting it to `Previous` or the
+translated equivalent.
 
-This component also supports all `IconButton` props.
-
----
+`Pagination.StepToPreviousButton` supports all `IconButton` props.
 
 ### Pagination.StepToNextButton
 
-`Pagination.StepToNextButton` is an `IconButton` that subscribes to `Pagination`'s context. This
-allows it to know when to disable and increment the `currentPage`.
-
 #### Usage
 
+`Pagination.StepToNextButton` is an `IconButton` that subscribes to the `Pagination` context. This
+allows it to know when to disable and increment the `currentPage`.
+
 ```tsx
 <Pagination.StepToNextButton aria-label="Next" />
 ```
 
-#### Component Props
-
-| name       | type     | required? | default | recommended                        |
-| ---------- | -------- | --------- | ------- | ---------------------------------- |
-| aria-label | `string` | ✅ `true` | n/a     | "Next" (and translated equivalent) |
+#### Props
 
-This component also supports all `IconButton` props.
+Undocumented props are spread to the underlying `<button>` element. Note that you must set
+`aria-label` to meet accessibility standards. We recommend setting it to `Next` or the translated
+equivalent.
 
----
+`Pagination.StepToNextButton` supports all `IconButton` props.
 
 ### Pagination.JumpToLastButton
 
-`Pagination.JumpToLastButton` is an `IconButton` that subscribes to `Pagination`'s context. This
-allows it to know when to disable and set `currentPage` to the last page.
-
 #### Usage
 
+`Pagination.JumpToLastButton` is an `IconButton` that subscribes to the `Pagination` context. This
+allows it to know when to disable and set `currentPage` to the last page.
+
 ```tsx
 <Pagination.JumpToLastButton aria-label="Last" />
 ```
 
-#### Component Props
-
-| name       | type     | required? | default | recommended                        |
-| ---------- | -------- | --------- | ------- | ---------------------------------- |
-| aria-label | `string` | ✅ `true` | n/a     | "Last" (and translated equivalent) |
+#### Props
 
-This component also supports all `IconButton` props.
+Undocumented props are spread to the underlying `<button>` element. Note that you must set
+`aria-label` to meet accessibility standards. We recommend setting it to `Last` or the translated
+equivalent.
 
----
+`Pagination.JumpToLastButton` supports all `IconButton` props.
 
 ### Pagination.PageList
 
-`Pagination.PageList` is an ordered list (`ol`) that subscribes to `Pagination`'s context. This
-allows it generate the `range` of page numbers. It also handles spacing between the child elements.
-This component will accept either child elements or functional children (sometimes called the render
-prop pattern). It's likely you'll want to use the functional children, but in the off-chance you
-need a static list of items, this component will support it. The usage section below will provide
-examples of both.
-
 #### Usage
 
-The functional children snippet below will likely be the most common use case.
+`Pagination.PageList` is an `<ol>` element that subscribes to the `Pagination` context. This allows
+it generate the `range` of page numbers. It also handles spacing between the child elements.
+
+This component will accept either child elements or a render prop. In most cases, you'll want to use
+the render prop so you can access the `Pagination` model in order to generate the proper list items.
 
 ```tsx
 <Pagination.PageList>
@@ -388,151 +257,135 @@ The functional children snippet below will likely be the most common use case.
 </Pagination.PageList>
 ```
 
-#### Component Props
-
-| name     | type                                                             | required?  | default | recommended |
-| -------- | ---------------------------------------------------------------- | ---------- | ------- | ----------- |
-| children | (model: PaginationModel) => React.ReactNode[] \| React.ReactNode | 🚫 `false` | n/a     | n/a         |
+#### Props
 
-This component also supports
-[all native HTMLOLElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol#Attributes).
+Undocumented props are spread to the underlying `<ol>` element.
 
----
+<ArgsTable of={PageListComponent} />
 
 ### Pagination.PageListItem
 
-`Pagination.PageListItem` is a styled `li` element. It provides a child semantic element for the
+#### Usage
+
+`Pagination.PageListItem` is a styled `<li>` element. It provides a semantic child element for the
 `PageList` component and is important for accessibility. It does not handle any internal business
 logic or state.
 
-#### Usage
-
 ```tsx
-<Pagination.PageListItem>{/* child element goes here */}</Pagination.PageListItem>
+<Pagination.PageListItem>{/* Child element */}</Pagination.PageListItem>
 ```
 
-#### Component Props
+#### Props
 
-This component also supports
-[all native HTMLLIElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li#Attributes).
+`Pagination.PageListItem` does not have any documented props.
 
----
+Undocumented props are spread to the underlying `<li>` element.
 
 ### Pagination.PageButton
 
-`Pagination.PageButton` is an `IconButton` that subscribes to `Pagination`'s context. This allows it
-to know set the `toggled` styling when it is the current item and update the `currentPage`.
-
 #### Usage
 
-`PageButton` will render the `pageNumber` as its children.
+`Pagination.PageButton` is an `IconButton` that subscribes to the `Pagination` context. This allows
+it to update the `currentPage` and set the `toggled` styling when it is the current item.
+
+`Pagination.PageButton` will render `pageNumber` as its children.
 
 ```tsx
 <Pagination.PageButton aria-label="Page 2" pageNumber={2} />
 ```
 
-#### Component Props
+#### Props
 
-| name       | type     | required? | default | recommended                                      |
-| ---------- | -------- | --------- | ------- | ------------------------------------------------ |
-| aria-label | `string` | ✅ `true` | n/a     | `Page ${pageNumber}` (and translated equivalent) |
-| pageNumber | `number` | ✅ `true` | n/a     | n/a                                              |
+Undocumented props are spread to the underlying `<button>` element. Note that you must set
+`aria-label` to meet accessibility standards. We recommend setting it to `Page ${pageNumber}` or the
+translated equivalent.
 
-This component also supports all `IconButton` props.
+<ArgsTable of={PageButtonComponent} />
 
----
+`Pagination.PageButton` also supports all `IconButton` props.
 
 ### Pagination.GoToForm
 
-`Pagination.GoToForm` is a wrapper for a React context provider and `form` element. Child components
-such as `Pagination.GoToTextInput` and `Pagination.GoToLabel` subscribe to that context to manage
-the form state and behavior as well as update the `currentPage` in the `Pagination` component.
-
 #### Usage
 
+`Pagination.GoToForm` is a wrapper for a React context provider rendered as a `<form>` element.
+Child components such as `Pagination.GoToTextInput` and `Pagination.GoToLabel` subscribe to that
+context to manage the form state and behavior as well as update the `currentPage` in the
+`Pagination` component.
+
 ```tsx
-<Pagination.GoToForm>{/* child elements go here */}</Pagination.GoToForm>
+<Pagination.GoToForm>{/* Child elements */}</Pagination.GoToForm>
 ```
 
-#### Component Props
+#### Props
 
-This component supports
-[all native HTMLFormElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#Attributes).
+`Pagination.GoToForm` does not have any documented props.
 
----
+Undocumented props are spread to the underlying `<form>` element.
 
 ### Pagination.GoToTextInput
 
 #### Usage
 
+`Pagination.GoToTextInput` is a `TextInput`.
+
 ```tsx
 <Pagination.GoToTextInput aria-label="Go to page number" />
 ```
 
-#### Component Props
-
-| name       | type                 | required?  | default | recommended                                     |
-| ---------- | -------------------- | ---------- | ------- | ----------------------------------------------- |
-| aria-label | `string`             | ✅ `true`  | n/a     | `Go to page number` (and translated equivalent) |
-| value      | `string` \| `number` | 🚫 `false` | ""      | n/a                                             |
+#### Props
 
-This component also supports all `TextInput` props.
+Undocumented props are spread to the underlying `<input type="text">` element. Note that you must
+set `aria-label` to meet accessibility standards. We recommend setting it to `Go to page number` or
+the translated equivalent.
 
----
+`Pagination.GoToTextInput` supports all `TextInput` props.
 
 ### Pagination.GoToLabel
 
-`Pagination.GoToLabel` is a styled `label` element that subscribes to the `Pagination` context. This
-allows it to pass the `Pagination` context to child elements.
-
 #### Usage
 
-This component will accept either child elements or functional children (sometimes called the render
-prop pattern). It's likely you'll want to use the functional children, but in the off-chance you
-need static child elements, this component will support it. Examples of both patterns are provided
-below.
-
-**Functional Children**
+`Pagination.GoToLabel` is a styled `<label>` element that subscribes to the `Pagination` context.
+This allows it to pass the `Pagination` context to child elements.
 
-Use this pattern when you need access to the state in the `Pagination` context for your text.
+This component will accept either child elements or a render prop. In most cases, you'll want to use
+the render prop so you can access the `Pagination` model when generating the label text.
 
 ```tsx
-<Pagination.GoToLabel>{({state}) => `of ${state.lastPage} results`}</Pagination.GoToLabel>
+<Pagination.GoToLabel>{({state}) => `of ${state.lastPage} pages`}</Pagination.GoToLabel>
 ```
 
-#### Component Props
-
-| name     | type                                                           | required?  | default | recommended |
-| -------- | -------------------------------------------------------------- | ---------- | ------- | ----------- |
-| htmlFor  | `string`                                                       | 🚫 `false` | n/a     | n/a         |
-| children | (model: PaginationModel) => React.ReactNode \| React.ReactNode | 🚫 `false` | n/a     | n/a         |
+#### Props
 
-This component also supports
-[all native HTMLLabelElement props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#Attributes).
+Undocumented props are spread to the underlying `<label>` element.
 
----
+<ArgsTable of={Pagination.GoToLabel} />
 
 ### Pagination.AdditionalDetails
 
-`Pagination.AdditionalDetails` is a styled `div` container that subscribes to the `Pagination`
+#### Usage
+
+`Pagination.AdditionalDetails` is a styled `<div>` element that subscribes to the `Pagination`
 context. This allows it to pass the `Pagination` context to child elements. It is also an
-`aria-live` region that announces the current page update to screen readers. Because of that, it's
-important to always\* include it in your `Pagination` component.
+`aria-live` region that announces the current page update to screen readers.
 
-_\* The only exception to this rule is when you have multiple `Pagination` components that are
-sharing the same state and rendered on the page. You can then safely remove all but one of the
-`AdditionalDetails` sections. This will prevent a screenreader from announcing updates multiple
-times to a user._
+`Pagination.AdditionalDetails` must be included in your `Pagination` component to meet accessibility
+standards (with one exception, see below). If you wish to prevent it from displaying, you may set
+its `shouldHideDetails` prop to `true`. The visually hidden region will still be accessible to
+screen readers.
 
-In the case where you would also have multiple `Pagination` components sharing the same state and
-you'd like to keep the `AdditionalDetails` component on multiple, you will need to set
-`shouldAnnounceToScreenReader` to `false` on all but one component to prevent announcement.
+If you have multiple `Pagination` components sharing the same state and rendered on the same page,
+you may do either of the following to prevent screen readers from announcing the same update
+multiple times:
 
-#### Usage
+- Exclude `Pagination.AdditionalDetails` from all but one of the `Pagination` components. This is
+  the one case where you may exclude `Pagination.AdditionalDetails` from a `Pagination` component.
+- Include `Pagination.AdditionalDetails` in every `Pagination` component (i.e., you want it to be
+  visible for every component), but set the `shouldAnnounceToScreenReader` prop to `false` on all
+  but one of them.
 
-This component will accept either child elements or functional children (sometimes called the render
-prop pattern). It's likely you'll want to use the functional children, but in the off-chance you
-need static child elements, this component will support it.
+This component will accept either child elements or a render prop. In most cases, you'll want to use
+the render prop so you can access the `Pagination` model in order to generate the appropriate text.
 
 ```tsx
 <Pagination.AdditionalDetails>
@@ -546,145 +399,89 @@ need static child elements, this component will support it.
 </Pagination.AdditionalDetails>
 ```
 
-#### Component Props
-
-| name                         | type                                                           | required?  | default | recommended |
-| ---------------------------- | -------------------------------------------------------------- | ---------- | ------- | ----------- |
-| shouldHideDetails            | `boolean`                                                      | 🚫 `false` | false   | n/a         |
-| shouldAnnounceToScreenReader | `boolean`                                                      | 🚫 `false` | true    | n/a         |
-| children                     | (model: PaginationModel) => React.ReactNode \| React.ReactNode | ✅ `true`  | n/a     | n/a         |
-
-## Models, Hooks, & Utils
+#### Props
 
-### PaginationModel
+Undocumented props are spread to the underlying `<div>` element.
 
-> **Note:** The model and compound component pattern presented here will be updated and solidified
-> in v5 of canvas-kit. While the general concepts are the same, there will be some breaking changes
-> in v5. If you'd like to learn about models and compound components in v5, please refer to
-> [this doc](https://github.com/Workday/canvas-kit/blob/master/modules/docs/mdx/COMPOUND_COMPONENTS.mdx).
+<ArgsTable of={AdditionalDetailsComponent} />
 
-The `PaginationModel` is the core of the `Pagination` component. That said, if you're using the
-higher-level context API components and following the basic usage guidelines, you shouldn't need to
-know how the model operates to successfully implement the component. But if you have an advanced use
-case or you're feeling curious, this section is for you.
+## Model
 
 If `Pagination` was stripped of all its markup, attributes, and styling, what would remain is the
-model. The `PaginationModel` is how we describe the state and behavior of the component. You could
-completely swap out the underlying elements, attributes, and styles, and the model would remain the
-same. `PaginationModel` is an object that is composed of two parts: `state` and `events`. The
-model's `state` describes the current state of the component, and `events` are functions that act on
-that state (also called behaviors). Below is an example `Pagination` model:
-
-```tsx
-const paginationModel = {
-  state: {
-    firstPage,
-    currentPage,
-    lastPage,
-    range,
-    rangeSize,
-  },
-  events: {
-    first,
-    last,
-    next,
-    previous,
-    setCurrentPage,
-    goTo,
-  };
-};
-
-```
-
-#### State
-
-The `state` describes the current state of the `Pagination` component. As events are fired, the
-state is updated, and the component will re-render. Below are the `state` keys and descriptions of
-their values:
-
-- `firstPage` - the page number for the first page
-- `currentPage` - the page number for the current page
-- `lastPage` - the page number for the last page (it can also be used as a total page count)
-- `range` - an array of page numbers included in the pagination range
-- `rangeSize` - the size of the pagination range
-
-#### Events
-
-The model's `events` describe behaviors that act on `state`. Below are the `events` keys and
-descriptions of their values:
+[model](/getting-started/for-developers/resources/compound-components/#models). The model is an
+object composed of two parts: `state` which describes the current snapshot in time of the component
+and `events` which describes events that can be sent to the model.
 
-- `first` - sets the current page to the first page
-- `last` - sets the current page to the last page
-- `next` - increments the current page by 1
-- `previous` - decrements the current page by 1
-- `goTo` - sets the current page to a given page number\* (with safeguards)
-- `setCurrentPage` - sets the current page to a given page number (no safeguards)
+By default, `Pagination` will create a model and share it internally with its subcomponents using
+React context. You may subscribe to `PaginationContext` if you wish to create a custom subcomponent
+for your implementation. Here's a simple example.
 
-\* _`goTo` is very similar to `setCurrentPage`, but it has some built-in safeguards. If the page
-number provided is below the first page (e.g: `0`), `currentPage` will be set to the `firstPage`.
-Similarly, if the number provided is larger than the `lastPage`, it will set `currentPage` to the
-`lastPage`._
+```tsx
+import * as React from 'react';
+import {Pagination, PaginationContext} from '@workday/canvas-kit-react/pagination';
 
----
+const CustomButton = (props: React.HTMLAttributes<HTMLButtonElement>) => {
+  const model = React.useContext(PaginationContext);
 
-### usePaginationModel Hook
+  const handleClick = (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+    // If onClick is provided, pass the event along
+    props.onClick?.(e);
+    model.events.goTo(10);
+  };
 
-The `Pagination` model can be created with the `usePaginationModel` hook. Normally `Pagination` will
-create it for you under the hood with the configuration props you provide the component, but you can
-also hoist the model outside of the component depending on your use case.
+  return (
+    <button onClick={handleClick} {...props}>
+      Go To Page 10
+    </button>
+  );
+};
 
-#### Configuration
+export const CustomPagination = () => {
+  return (
+    <Pagination aria-label="Pagination" lastPage={20}>
+      <CustomButton aria-label="Page 10" />
+      {/* Other subcomponents */}
+    </Pagination>
+  );
+};
+```
 
-The hook configuration is identical to the `Pagination` component configuration. The only value you
-need to provide is `lastPage`, but you can also provide others. The full list is below:
+Alternatively, if you need direct access to the model's `state` and `events` outside of the
+`Pagination` component, you may configure your own model with `usePaginationModel` and pass it to
+`Pagination` via a pattern called
+[hoisting the model](/getting-started/for-developers/resources/compound-components/#configuring-a-model).
 
-| name                | type                           | required   | default |
-| ------------------- | ------------------------------ | ---------- | ------- |
-| lastPage            | `number`                       | ✅ `true`  | n/a     |
-| firstPage?          | `number`                       | 🚫 `false` | 1       |
-| initialCurrentPage? | `number`                       | 🚫 `false` | n/a     |
-| onPageChange?       | `(pageNumber: number) => void` | 🚫 `false` | n/a     |
-| rangeSize?          | `number`                       | 🚫 `false` | 5       |
+```tsx
+const model = usePaginationModel({
+  lastPage,
+  onPageChange: number => console.log(number),
+});
+
+<Pagination aria-label="Pagination" model={model}>
+  {/* Child components */}
+</Pagination>;
+```
 
-#### Usage
+### Config
 
-Using this hook is fairly straightforward. Create a configuration, pass it to the hook, and it
-returns a model.
+`usePaginationModel` accepts a configuration object with the following properties and returns a
+`PaginationModel` with `state` and `events` properties.
 
-```ts
-const paginationConfig = {
-  lastPage: 100,
-  rangeSize: 3,
-  onPageChange: pageNumber => console.log(pageNumber),
-};
+<ArgsTable of={PaginationModelConfigComponent} />
 
-const model = usePaginationModel(paginationConfig);
-```
+### State
 
-Voilà! Now you can pass the model to `Pagination` like so:
+The `PaginationModel` `state` is an object with the following properties.
 
-```tsx
-const paginationConfig = {
-  lastPage: 100,
-  rangeSize: 3,
-  onPageChange: pageNumber => console.log(pageNumber),
-};
+<ArgsTable of={PaginationStateComponent} />
 
-const model = usePaginationModel(paginationConfig);
+### Events
 
-return (
-  <Pagination aria-label="Pagination" model={model}>
-    {/* child components go here */}
-  </Pagination>
-);
-```
+The `PaginationModel` `events` is an object with the following properties.
 
-If you're hoisting the model, it's presumably because you need more access to the model's `state`
-and `events` outside of the component. You could have an external button trigger events to update
-the state, or have another component use the model's state. See the
-[Advanced Usage](#advanced-usage) section for more detailed information.
+<ArgsTable of={PaginationEventsComponent} />
 
----
+## Utilities
 
 ### getLastPage
 
@@ -699,8 +496,6 @@ const totalCount = 128;
 const lastPage = getLastPage(resultCount, totalCount); //=> 13
 ```
 
----
-
 ### getRangeMin
 
 This function takes the pagination range and returns its minimum value. Here's an example:
@@ -712,8 +507,6 @@ const range = [1, 2, 3, 4, 5];
 const rangeMin = getRangeMin(range); //=> 1
 ```
 
----
-
 ### getRangeMax
 
 This function takes the pagination range and returns its maximum value. Here's an example:
@@ -725,8 +518,6 @@ const range = [1, 2, 3, 4, 5];
 const rangeMin = getRangeMax(range); //=> 5
 ```
 
----
-
 ### getVisibleResultsMin
 
 This function takes the current page, and number of results per page, and returns the minimum value
@@ -740,8 +531,6 @@ const resultCount = 10;
 const pageMin = getVisibleResultsMin(currentPage, resultCount); //=> 41
 ```
 
----
-
 ### getVisibleResultsMax
 
 This function takes the current page, number of results per page, and the total number of results,
@@ -755,42 +544,4 @@ const currentPage = 5;
 const resultCount = 10;
 const totalCount = 42;
 const pageMax = getVisibleResultsMax(currentPage, resultCount, totalCount); //=> 42
-```
-
----
-
-### PaginationContext
-
-You can also subscribe directly to `PaginationContext`. This is useful if you want to create a new,
-custom subcomponent for your implementation and want it to subscribe to `Pagination`'s context.
-Here's a simple example:
-
-```tsx
-import * as React from 'react';
-import {Pagination, PaginationContext} from '@workday/canvas-kit-react/pagination';
-
-const CustomButton = (props: React.HTMLAttributes<HTMLButtonElement>) => {
-  const model = React.useContext(PaginationContext);
-
-  const handleClick = (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
-    // if onClick is provided, pass the event along
-    props.onClick?.(e);
-    model.events.goTo(10);
-  };
-
-  return (
-    <button onClick={handleClick} {...props}>
-      Go To Page 10
-    </button>
-  );
-};
-
-export const CustomPagination = () => {
-  return (
-    <Pagination aria-label="Pagination" lastPage={20}>
-      <CustomButton aria-label="Page 10" />
-      {/* other child components go here */}
-    </Pagination>
-  );
-};
 ```