@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/pagination.md

@@ -0,0 +1,516 @@
+# Pagination
+
+Moves between pages of a long list.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Pagination.tsx)
+
+## Overview
+
+Pagination renders a navigation landmark with links to each page of a list, plus previous and next steps.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Pagination } from '@tempoxyz/ds'
+
+function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
+  return (
+    <Pagination size={props.size}>
+      <Pagination.Previous disabled={props.current === 1} href="#" />
+      <Pagination.Page current={props.current === 1} href="#">
+        1
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 4} href="#">
+        4
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 9} href="#">
+        9
+      </Pagination.Page>
+      <Pagination.Next disabled={props.current === 9} href="#" />
+    </Pagination>
+  )
+}
+
+export function Demo() {
+  return <Pages current={4} />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { Pagination, Stack } from '@tempoxyz/ds'
+
+function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
+  return (
+    <Pagination size={props.size}>
+      <Pagination.Previous disabled={props.current === 1} href="#" />
+      <Pagination.Page current={props.current === 1} href="#">
+        1
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 4} href="#">
+        4
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 9} href="#">
+        9
+      </Pagination.Page>
+      <Pagination.Next disabled={props.current === 9} href="#" />
+    </Pagination>
+  )
+}
+
+export function Demo() {
+  return (
+    <Stack gap="16">
+      <Pages current={4} size="small" />
+      <Pages current={4} size="medium" />
+      <Pages current={4} size="large" />
+    </Stack>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Size.tsx)
+
+### Current
+
+Set `current` on exactly one `Pagination.Page`. `Pagination.Previous` and `Pagination.Next` take `disabled` at either end.
+
+```tsx
+import { Pagination, Stack } from '@tempoxyz/ds'
+
+function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
+  return (
+    <Pagination size={props.size}>
+      <Pagination.Previous disabled={props.current === 1} href="#" />
+      <Pagination.Page current={props.current === 1} href="#">
+        1
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 4} href="#">
+        4
+      </Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page current={props.current === 9} href="#">
+        9
+      </Pagination.Page>
+      <Pagination.Next disabled={props.current === 9} href="#" />
+    </Pagination>
+  )
+}
+
+export function Demo() {
+  return (
+    <Stack gap="16">
+      <Pages current={1} />
+      <Pages current={4} />
+      <Pages current={9} />
+    </Stack>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Current.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Pagination } from '@tempoxyz/ds'
+
+<Pagination>
+  <Pagination.Previous />
+  <Pagination.Page />
+  <Pagination.Ellipsis />
+  <Pagination.Next />
+</Pagination>
+```
+
+## Guidelines
+
+### When to Use
+
+* Split long lists that people scan, sort, and revisit, such as transaction history or webhook deliveries.
+* Paginate tables where position matters, such as a shared link to page 3.
+
+### When Not to Use
+
+* Use a `secondary` [Button](/docs/components/button) labelled Load more at the end of a feed, such as wallet Activity.
+* Use [Stepper](/docs/components/stepper) for progress through a flow.
+* Use [Tabs](/docs/components/tabs) to split a list by category, such as Incoming and Outgoing.
+* Use a [Table](/docs/components/table) or [ListGroup](/docs/components/list-group) without pagination when the list fits on one screen.
+
+### Choose Pagination or Load More
+
+* **Pagination (Tables and logs):** Each page has a URL, readers jump to any page, and the footer stays reachable.
+* **Load More (Feeds):** New items append below the last one. The footer is reachable after each load.
+
+Avoid infinite scroll on the web. It pushes the footer out of reach and gives keyboard users no stopping point.
+
+### Link Every Page
+
+Give each `Pagination.Page` an `href` with its number. Links then survive a reload, open in a new tab, and work with Back. Pass `render` to use your router's link.
+
+**Do:** Put the page number in the URL, such as `?page=3`.
+
+```tsx
+/**
+ * Do example for "Link Every Page" on the Pagination page.
+ * Put the page number in the URL, such as `?page=3`.
+ * @module
+ */
+import { Pagination, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <span {...styles.address()}>console.tempo.xyz/activity?page=3</span>
+      <Pagination size="small">
+        <Pagination.Previous href="#" />
+        <Pagination.Page href="#">2</Pagination.Page>
+        <Pagination.Page current href="#">
+          3
+        </Pagination.Page>
+        <Pagination.Page href="#">4</Pagination.Page>
+        <Pagination.Next href="#" />
+      </Pagination>
+    </div>
+  )
+}
+
+namespace styles {
+  export const address = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    color: 'content.secondary',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+
+  export const page = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '16',
+  })
+}
+```
+
+**Don't:** Change pages without changing the URL.
+
+```tsx
+/**
+ * Don't example for "Link Every Page" on the Pagination page.
+ * Don't change pages without changing the URL.
+ * @module
+ */
+import { Pagination, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <span {...styles.address()}>console.tempo.xyz/activity</span>
+      <Pagination size="small">
+        <Pagination.Previous href="#" />
+        <Pagination.Page href="#">2</Pagination.Page>
+        <Pagination.Page current href="#">
+          3
+        </Pagination.Page>
+        <Pagination.Page href="#">4</Pagination.Page>
+        <Pagination.Next href="#" />
+      </Pagination>
+    </div>
+  )
+}
+
+namespace styles {
+  export const address = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'full',
+    color: 'content.secondary',
+    cornerShape: 'round',
+    paddingBlock: '4',
+    paddingInline: '12',
+    typography: 'body.b3',
+  })
+
+  export const page = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '16',
+  })
+}
+```
+
+### Truncate Long Ranges
+
+* **Always show:** The first, last, and current pages.
+* **Skipped ranges:** Replace each with a `Pagination.Ellipsis`.
+* **Limit:** Keep about seven page items, with the current page's neighbors when there is room.
+
+**Do:** Keep the first and last pages around the current one.
+
+```tsx
+/**
+ * Do example for "Truncate Long Ranges" on the Pagination page.
+ * Keep the first and last pages around the current one.
+ * @module
+ */
+import { Pagination } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Pagination size="small">
+      <Pagination.Previous href="#" />
+      <Pagination.Page href="#">1</Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page href="#">4</Pagination.Page>
+      <Pagination.Page current href="#">
+        5
+      </Pagination.Page>
+      <Pagination.Page href="#">6</Pagination.Page>
+      <Pagination.Ellipsis />
+      <Pagination.Page href="#">49</Pagination.Page>
+      <Pagination.Next href="#" />
+    </Pagination>
+  )
+}
+```
+
+**Don't:** Show only the pages next to the current one.
+
+```tsx
+/**
+ * Don't example for "Truncate Long Ranges" on the Pagination page.
+ * Don't show only the pages next to the current one.
+ * @module
+ */
+import { Pagination } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Pagination size="small">
+      <Pagination.Previous href="#" />
+      <Pagination.Page href="#">4</Pagination.Page>
+      <Pagination.Page current href="#">
+        5
+      </Pagination.Page>
+      <Pagination.Page href="#">6</Pagination.Page>
+      <Pagination.Next href="#" />
+    </Pagination>
+  )
+}
+```
+
+### Keep Previous and Next in Place
+
+Render `Pagination.Previous` and `Pagination.Next` on every page. Set `disabled` at either end instead of removing them, so the page links do not shift.
+
+**Do:** Disable Previous on the first page.
+
+```tsx
+/**
+ * Do example for "Keep Previous and Next in Place" on the Pagination page.
+ * Disable Previous on the first page.
+ * @module
+ */
+import { Pagination } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Pagination size="small">
+      <Pagination.Previous disabled />
+      <Pagination.Page current href="#">
+        1
+      </Pagination.Page>
+      <Pagination.Page href="#">2</Pagination.Page>
+      <Pagination.Page href="#">3</Pagination.Page>
+      <Pagination.Next href="#" />
+    </Pagination>
+  )
+}
+```
+
+**Don't:** Remove Previous, which moves every page link when it returns.
+
+```tsx
+/**
+ * Don't example for "Keep Previous and Next in Place" on the Pagination page.
+ * Don't remove Previous, which moves every page link when it returns.
+ * @module
+ */
+import { Pagination } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Pagination size="small">
+      <Pagination.Page current href="#">
+        1
+      </Pagination.Page>
+      <Pagination.Page href="#">2</Pagination.Page>
+      <Pagination.Page href="#">3</Pagination.Page>
+      <Pagination.Next href="#" />
+    </Pagination>
+  )
+}
+```
+
+### Show the Range You're Viewing
+
+Place a count beside the control, directly below its list.
+
+**Do:** Show the rows on screen and the total, such as Showing 51–75 of 1,204 transactions.
+
+```tsx
+/**
+ * Do example for "Show the Range You're Viewing" on the Pagination page.
+ * Show the rows on screen and the total, such as Showing 51–75 of 1,204 transactions.
+ * @module
+ */
+import { Pagination, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.count()}>Showing 51–75 of 1,204 transactions</span>
+      <Pagination size="small">
+        <Pagination.Previous href="#" />
+        <Pagination.Page href="#">2</Pagination.Page>
+        <Pagination.Page current href="#">
+          3
+        </Pagination.Page>
+        <Pagination.Page href="#">4</Pagination.Page>
+        <Pagination.Next href="#" />
+      </Pagination>
+    </div>
+  )
+}
+
+namespace styles {
+  export const count = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Show page numbers without the count.
+
+```tsx
+/**
+ * Don't example for "Show the Range You're Viewing" on the Pagination page.
+ * Don't show page numbers without the count.
+ * @module
+ */
+import { Pagination, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Pagination size="small">
+        <Pagination.Previous href="#" />
+        <Pagination.Page href="#">2</Pagination.Page>
+        <Pagination.Page current href="#">
+          3
+        </Pagination.Page>
+        <Pagination.Page href="#">4</Pagination.Page>
+        <Pagination.Next href="#" />
+      </Pagination>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    justifyContent: 'space-between',
+    width: '100% !custom',
+  })
+}
+```
+
+### Match Size to the List
+
+* **Small (32px):** Under dense tables, like Tempo Performance runs.
+* **Medium (40px):** The default.
+* **Large (56px):** Touch-first layouts.
+
+## Content
+
+* **Steps:** Keep the default Previous and Next. If children replace them, keep both descriptive, such as Newer and Older.
+* **Count:** Name the rows of the list, such as transactions or deliveries.
+* **Numbers:** Use numerals, and group the digits of large totals, such as 1,204.
+
+## Accessibility
+
+The current page and disabled steps carry ARIA states.
+
+### Semantics
+
+* **Root (navigation):** A landmark named "Pagination" that wraps a list of pages.
+* **Parts (li):** Each part is a list item. Pages and steps render links by default.
+* **Current Page (aria-current):** Set by `current`. Screen readers announce the page as current.
+* **Disabled Steps (aria-disabled):** Renders as text and leaves the tab order. With `render`, it keeps your element.
+* **Pagination.Ellipsis:** Plain text that takes no focus. The chevron icons are hidden from assistive technology.
+
+### Keyboard
+
+* **Move Between Links (Tab):** Moves through the links in order. Skips ellipses and disabled steps without `render`.
+* **Follow a Link (Enter):** Follows the focused link.
+
+### Your Responsibilities
+
+* **Mark One Current Page (current):** Set it on exactly one page.
+* **Block Disabled Custom Links (render):** For a custom disabled step, block navigation and remove it from the tab order yourself.
+* **Name Each Pagination (aria-label):** If a page holds more than one, give each a distinct name, such as "Deliveries pagination".
+* **Name Page Links (SC 2.4.4):** Consider an `aria-label` such as "Page 4". A bare number means little out of context.
+* **Handle In-Place Loads:** After a client-side page change, move focus to the start of the results, such as the heading.
+
+## Related
+
+[Table](/docs/components/table)
+
+Use for the rows you paginate.
+
+[ListGroup](/docs/components/list-group)
+
+Use for lists of records.
+
+[Button](/docs/components/button)
+
+Use for a Load more action.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers sorting, filtering, and paging data.