division-ds 0.1.1 → 0.2.0

package/public/docs/components/navbar.md

@@ -0,0 +1,142 @@
+# Navbar
+
+> The top of a page: the brand, the main links and a few actions. When its container gets narrow, the links move into a menu sheet. Nothing gets cut off, and nothing is hidden for good.
+
+- **Best for:** The top of a site: the brand, up to about six main links and a few actions.
+- **Not for:** App navigation across many grouped pages: use Sidebar.
+- Organism. Source: `src/components/organisms/navbar/Navbar.tsx`
+- Rendered docs page: `/components/navbar`
+
+## Import
+
+```tsx
+import { Navbar } from 'src/components/organisms/navbar/Navbar'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the navigation region. |
+| `brand` | `ReactNode` |  | Required. The wordmark or logo, usually a link to the home page. |
+| `items` | `NavbarItem[]` |  | Required. Each item has label, href and current. |
+| `actions` | `ReactNode` |  | Controls on the right: icon buttons, a cart link, an account menu. Keep them small, because they stay visible at every width. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Pass your router's link component here. Map href to its own prop, and pass className, aria-current and onClick through. |
+| `menuLabel` | `string` | `'Menu'` | The menu button's name for screen readers, and the sheet's title. |
+| `menuFooter` | `ReactNode` |  | Shown in the menu sheet under the links. Use it for an action that doesn't fit in actions on a narrow bar. Hide the matching copy in actions below the breakpoint by wrapping it in an element with the classes hidden @2xl:flex. |
+| `className` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | The header element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type NavbarItem = { label: string; href: string; current?: boolean }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Store navigation
+
+```tsx
+const ITEMS = [
+  { label: 'Replicas', href: '#replicas' },
+  { label: 'Optics', href: '#optics', current: true },
+  { label: 'Parts', href: '#parts' },
+  { label: 'Care', href: '#care' },
+  { label: 'Field notes', href: '#field-notes' },
+]
+
+const BRAND = (
+  <a
+    href="#home"
+    className="inline-flex items-center min-h-10 font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]"
+  >
+    Hexline
+  </a>
+)
+
+const ACTIONS = (
+  <>
+    <IconButton label="Search" variant="ghost">
+      <Search aria-hidden="true" className="w-5 h-5" />
+    </IconButton>
+    <IconButton label="Cart, 2 items" variant="ghost" asChild>
+      <a href="#cart">
+        <ShoppingBag aria-hidden="true" className="w-5 h-5" />
+      </a>
+    </IconButton>
+  </>
+)
+
+<Navbar label="Store navigation" brand={BRAND} items={ITEMS} actions={ACTIONS} />
+```
+
+### A narrow container
+
+```tsx
+const ITEMS = [
+  { label: 'Replicas', href: '#replicas' },
+  { label: 'Optics', href: '#optics', current: true },
+  { label: 'Parts', href: '#parts' },
+  { label: 'Care', href: '#care' },
+  { label: 'Field notes', href: '#field-notes' },
+]
+
+const BRAND = (
+  <a
+    href="#home"
+    className="inline-flex items-center min-h-10 font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]"
+  >
+    Hexline
+  </a>
+)
+
+const ACTIONS = (
+  <>
+    <IconButton label="Search" variant="ghost">
+      <Search aria-hidden="true" className="w-5 h-5" />
+    </IconButton>
+    <IconButton label="Cart, 2 items" variant="ghost" asChild>
+      <a href="#cart">
+        <ShoppingBag aria-hidden="true" className="w-5 h-5" />
+      </a>
+    </IconButton>
+  </>
+)
+
+<div className="max-w-sm">
+  <Navbar label="Store navigation, narrow" brand={BRAND} items={ITEMS} actions={ACTIONS} />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the brand, each link and the actions, then the menu button when it shows. |
+| `Enter` | Follows a link, or opens the menu. |
+| `Esc` | Closes the menu and sends focus back to its button. |
+
+## Do
+
+- Mark exactly one item as current.
+- Keep actions to icon buttons with names, or one short button.
+- If a page has more than one navbar, give each its own label.
+
+## Don't
+
+- Don't put more than about six links in the bar. Group the rest under a page.
+- Don't hide an action inside the menu that the bar shows at wide widths only.
+- Don't mark a link as current with colour alone. The fill and aria-current both move with it.
+
+## Anatomy
+
+- **Header**: The page's banner landmark, a region screen readers can jump straight to, at the top level of the page.
+- **Brand**: The wordmark or logo, usually a link to the home page.
+- **Links**: A named navigation region. The current page gets the signal fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on.
+- **Actions**: They stay visible at every width.
+- **Menu**: When the container is narrower than 42rem (rem is a unit based on the root text size, usually 16 pixels), an icon button opens the same links in a Sheet. If the container widens past that breakpoint while the sheet is open, the sheet stays open. It doesn't close itself when the links reappear in the bar.

package/public/docs/components/newsletter-form.md

@@ -0,0 +1,110 @@
+# NewsletterForm
+
+> An email field, a line saying what you're agreeing to, and a button. It checks input the same way every form here does, is honest about waiting while it sends, and tells you when it worked.
+
+- **Best for:** Collecting one email address for a newsletter, with a consent line.
+- **Not for:** Creating an account: use AuthForm.
+- Organism. Source: `src/components/organisms/newsletter-form/NewsletterForm.tsx`
+- Rendered docs page: `/components/newsletter-form`
+
+## Import
+
+```tsx
+import { NewsletterForm } from 'src/components/organisms/newsletter-form/NewsletterForm'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The form's accessible name, the name screen readers say, e.g. "Newsletter sign-up". Leaving it out is a compile error. |
+| `onSubmit` | `(email: string) => void \| Promise<void>` |  | Required. Called with the trimmed address once it passes validation. Resolve (finish successfully) to show the success state. Reject (fail) to show the alert, and what was typed stays in the field. |
+| `consent` | `ReactNode` |  | Required. The consent line. Leaving it out is a compile error. |
+| `fieldLabel` | `string` | `'Email'` | The field's label and the name screen readers say for it, as one string. Say what the address is for when the page might have another email field, such as a footer under a sign-in form. |
+| `submitLabel` | `string` | `'Subscribe'` | The button text. |
+| `busyLabel` | `string` | `'Subscribing'` | What a screen reader hears while onSubmit is pending. |
+| `successTitle` | `string` | `'You are subscribed'` | The success heading. |
+| `successBody` | `(email: string) => ReactNode` | `email => `Updates go to ${email}.`` | The line under the success heading. It receives the subscribed address. |
+| `headingLevel` | `2 \| 3 \| 4` | `3` | The level of the error summary heading and the success heading. Make it one below the heading of the section the form sits in. |
+| `className` | `string` |  | Added to the root element. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed to the root element, which stays on the page when the success message replaces the form. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A sign-up that succeeds
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+const CONSENT = 'One email a month. Every one has an unsubscribe link.'
+
+async function accept() {
+  await wait(700)
+}
+
+<div className="flex w-full flex-col gap-3">
+  <p className="font-body text-sm text-[var(--color-text-secondary)]">
+    Demo: any address is accepted after a short wait. Nothing is sent.
+  </p>
+  <NewsletterForm label="Field notes by email" consent={CONSENT} onSubmit={accept} headingLevel={4} />
+</div>
+```
+
+### A sign-up that fails
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+async function refuse() {
+  await wait(700)
+  throw new Error('The demo server is switched off.')
+}
+
+<div className="flex w-full flex-col gap-3">
+  <p className="font-body text-sm text-[var(--color-text-secondary)]">
+    Demo: this one rejects every address, so you can see the alert, and the address you typed stays in the field.
+  </p>
+  <NewsletterForm
+    label="Restock alerts by email"
+    consent="An email when a sold-out replica is back. Nothing else."
+    submitLabel="Notify me"
+    busyLabel="Signing you up"
+    onSubmit={refuse}
+    headingLevel={4}
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the field, then the button. Screen readers read the consent line with the button. |
+| `Enter` | In the field or on the button, it submits, and it does nothing while a submit is pending. On the error summary entry, it moves focus to the field. |
+
+## Do
+
+- Say in the consent line how often you write and how to stop.
+- Start the section it sits in with a heading that says what the emails are about.
+- Reject onSubmit when the request fails. The form shows the alert and keeps the address.
+- Set headingLevel to one below the section heading above it.
+
+## Don't
+
+- Don't pre-tick anything, or sign people up as a side effect of another form.
+- Don't put network code in it. onSubmit belongs to you; the form handles busy, failure and success.
+- Don't place it on a raised panel and remove its fill. Field errors sit on surface.base.
+- Don't ask for a name. Having just one field is the point.
+
+## Anatomy
+
+- **Form**: Screen readers name it by the label prop. It sits on opaque surface.base, in a hairline frame with the corner crosshair.
+- **Error summary**: Appears when a submit fails and takes focus. Its entry moves focus to the field. It waits for someone to try submitting: leaving the field (a blur) never brings it up on its own.
+- **Email**: A FormField wrapped around an Input, set to type email, autocomplete email and required.
+- **Consent**: Required. What subscribing means and how to stop. Screen readers read it as the submit button's description.
+- **Submit**: A Button that keeps focus and shows it's busy while onSubmit is pending. aria-busy and aria-disabled, two ARIA attributes (Accessible Rich Internet Applications, the labels screen readers rely on), tell screen readers the same.
+- **Submit error**: An alert region that is always there and gets its text when onSubmit fails. The visible message only appears then. It clears before the next try.
+- **Success**: Takes the place of the form: a check icon, a heading that takes focus, and the address that was subscribed.
+- **Status**: Hidden from view and present from the start. It announces the success only if focus had already left the form.

package/public/docs/components/page-header.md

@@ -0,0 +1,149 @@
+# PageHeader
+
+> The top of a screen. It holds the page’s one h1 (the main, level-1 heading), and can add an eyebrow, a description, a breadcrumb trail and the page’s own actions at the far edge.
+
+- **Best for:** The top of every screen: its one h1, with eyebrow, description, breadcrumbs and page actions.
+- **Not for:** A section inside a page: use SectionHeading.
+- Molecule. Source: `src/components/molecules/page-header/PageHeader.tsx`
+- Rendered docs page: `/components/page-header`
+
+## Import
+
+```tsx
+import { PageHeader } from 'src/components/molecules/page-header/PageHeader'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The page’s name, shown as its h1. |
+| `eyebrow` | `ReactNode` |  | A short label above the title: the area the page belongs to. |
+| `description` | `ReactNode` |  | One or two sentences under the title. |
+| `actions` | `ReactNode` |  | The page’s own actions, usually one or two Buttons. The component lays out the row and its gap. |
+| `breadcrumbs` | `ReactNode` |  | A Breadcrumbs element, drawn above the eyebrow. |
+| `id` | `string` |  | Goes on the h1, not the wrapper, so main can point aria-labelledby at it. That ARIA (Accessible Rich Internet Applications) attribute lets the main area take its name from the heading. |
+| `level` | `1 \| 2` | `1` | Use 2 only for a page-style header inside a page that already has its h1 (a pane, a tab panel). It looks the same either way. |
+| `className` | `string` |  | Extra CSS classes, merged onto the outer element. When two Tailwind classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the outer element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Title and description
+
+```tsx
+<PageHeader level={2} title="Orders" description="Every order from the last 90 days, newest first." />
+```
+
+### With an eyebrow and actions
+
+```tsx
+<PageHeader
+  level={2}
+  eyebrow="Operations"
+  title="Inventory"
+  description="Stock across both depots, counted at close of day."
+  actions={
+    <>
+      <Button variant="secondary">Export</Button>
+      <Button>Add replica</Button>
+    </>
+  }
+/>
+```
+
+### Under a breadcrumb trail
+
+```tsx
+<PageHeader
+  level={2}
+  breadcrumbs={
+    <Breadcrumbs
+      items={[
+        { label: 'Account', href: '#account' },
+        { label: 'Settings', href: '#settings' },
+        { label: 'Notifications' },
+      ]}
+    />
+  }
+  title="Notifications"
+  description="What we send, and where."
+  actions={<Button variant="secondary">Reset to defaults</Button>}
+/>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the breadcrumb links, then the actions. The header itself never takes keyboard focus. |
+
+## Do
+
+- Use one per screen, at the top, inside main.
+- Keep the eyebrow to the area’s name (“Operations”), and the title to the page’s.
+- Put the page’s primary action last in the actions row, so it lands at the far edge.
+- When the page has more than one landmark (a named region screen readers can jump to), give the h1 an id and use it to name main.
+
+## Don't
+
+- Don’t use it for a section inside a page. That’s a SectionHeading.
+- Don’t put the page’s filters or tabs in the actions slot. They belong to the content under it.
+- Don’t repeat the title in the eyebrow. The eyebrow names where the page sits, and the title names the page.
+- Don’t add a second h1 inside the description or the actions.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<PageHeader level={2} title="Orders" />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Orders" />
+```
+
+The examples on this page pass level={2} only because they sit inside this docs page, which has its own h1. A screen’s own header is its h1, so leave level out.
+
+Wrong:
+
+```tsx
+<PageHeader title="Inventory" />
+<PageHeader title="Low stock" />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Inventory" />
+<SectionHeading level={2} title="Low stock" />
+```
+
+A page has one h1. Every heading under it is a SectionHeading, at the level the page’s outline of headings needs.
+
+Wrong:
+
+```tsx
+<PageHeader title="Inventory" breadcrumbs={[{ label: "Operations" }]} />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Inventory" breadcrumbs={<Breadcrumbs items={[{ label: "Operations", href: "/ops" }, { label: "Inventory" }]} />} />
+```
+
+breadcrumbs is a slot, not an array. Pass a Breadcrumbs element, which keeps its own renderLink and maxItems.
+
+## Anatomy
+
+- **Breadcrumbs**: Optional. A Breadcrumbs trail above everything else, first in reading order.
+- **Eyebrow**: Optional. A small label: JetBrains Mono, 12px (pixels), semibold, uppercase, in text.muted. It's a paragraph above the h1 and isn't part of the heading's name.
+- **Title**: The page’s h1. Oxanium, semibold, 24px, growing to 30px when the header gets 48rem or more of width (a rem is the base text size, usually 16px).
+- **Description**: Optional. 16px body text in text.secondary, with lines no longer than 64 characters.
+- **Actions**: Optional. The page’s own controls at the far edge, in a row with a 12px gap. The row drops under the title when it runs out of room.

package/public/docs/components/pagination.md

@@ -0,0 +1,210 @@
+# Pagination
+
+> Moves through a long list one page at a time. The current page gets the signal fill. Where there are too many pages to fit, a gap stands in for the run that's hidden.
+
+- **Best for:** Moving through a long list or table one page at a time.
+- **Not for:** Steps in a form: use Stepper. Fewer than two pages: don't render anything.
+- Molecule. Source: `src/components/molecules/pagination/Pagination.tsx`
+- Rendered docs page: `/components/pagination`
+
+## Import
+
+```tsx
+import { Pagination, paginationRange } from 'src/components/molecules/pagination/Pagination'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `page` | `number` |  | Counts from 1. A number outside the range is pulled back into it. |
+| `pageCount` | `number` |  | Below 1, nothing renders. |
+| `onPageChange` | `(page: number) => void` |  | It's never called with the page you're already on. |
+| `variant` | `'numbered' \| 'compact' \| 'select'` | `'numbered'` | What sits between Previous and Next: the page buttons, a 'Page 3 of 20' readout (which screen readers announce politely, without interrupting, when it changes), or a page Select. Only use 'select' up to a few dozen pages. |
+| `siblings` | `number` | `1` | How many pages show on each side of the current page, for 'numbered'. |
+| `showFirstLast` | `boolean` | `false` | Adds First page and Last page icon buttons at the ends. Like Previous and Next, they go aria-disabled at the first and last page. |
+| `showLabels` | `boolean` | `false` | Shows Previous and Next as text buttons ('Previous', 'Next') with their chevrons, instead of icons alone. |
+| `showJump` | `boolean` | `false` | Adds a 'Go to page' field. Enter or Go jumps there, and a number past either end goes to that end. |
+| `totalItems` | `number` |  | Together with pageSize, it shows the range on view ('21–40 of 400') at the start and lays the control out as a table footer. |
+| `pageSize` | `number` |  | Items per page, used for the range text and the rows-per-page Select. |
+| `onPageSizeChange` | `(pageSize: number) => void` |  | Together with pageSize, it shows a rows-per-page Select. When it fires, reset page to 1: the old page may not exist any more. |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | The rows-per-page choices. |
+| `label` | `string` | `'Pagination'` | The name of the nav landmark (a region screen readers can jump to). |
+| `className` | `string` |  | Added to the nav element. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the nav DOM node (the element in the page). |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+/** Pure. 1-based. Always includes page 1, the last page, the current page and `siblings` pages
+ *  either side of it. A gap stands for two or more hidden pages; a single hidden page is shown
+ *  instead, because a gap that hides one number costs the same space as the number. */
+export function paginationRange(page: number, pageCount: number, siblings = 1): (number | 'gap')[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Few pages
+
+```tsx
+<Pagination page={2} pageCount={5} onPageChange={() => {}} label="Pagination, few pages" />
+```
+
+### Many pages
+
+```tsx
+function ManyPagesExample() {
+  const [page, setPage] = useState(1)
+  const perPage = 20
+  const total = 400
+  const from = (page - 1) * perPage + 1
+  const to = Math.min(page * perPage, total)
+
+  return (
+    <div>
+      <Pagination page={page} pageCount={20} onPageChange={setPage} label="Pagination, many pages" />
+      <p className="font-mono text-xs text-[var(--color-text-muted)] mt-3">
+        Showing {from} to {to} of {total} depots
+      </p>
+    </div>
+  )
+}
+
+<ManyPagesExample />
+```
+
+### Wider context: two page numbers on each side of the current page
+
+```tsx
+<Pagination
+  page={10}
+  pageCount={20}
+  siblings={2}
+  onPageChange={() => {}}
+  label="Pagination, wider context"
+/>
+```
+
+### First and last
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={20} showFirstLast label="Pagination, first and last" />
+```
+
+### With labels
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={20} showLabels label="Pagination, with labels" />
+```
+
+### Compact
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live variant="compact" pageCount={20} showFirstLast label="Pagination, compact" />
+```
+
+### Page select
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live variant="select" pageCount={12} label="Pagination, page select" />
+```
+
+### Go to page
+
+```tsx
+function Live(props: Omit<Parameters<typeof Pagination>[0], 'page' | 'onPageChange'>) {
+  const [page, setPage] = useState(4)
+  return <Pagination {...props} page={page} onPageChange={setPage} />
+}
+
+<Live pageCount={48} showJump label="Pagination, go to page" />
+```
+
+### Table footer
+
+```tsx
+function TableFooterExample() {
+  const total = 397
+  const [page, setPage] = useState(2)
+  const [pageSize, setPageSize] = useState(20)
+  return (
+    <div className="w-full">
+      <Pagination
+        page={page}
+        pageCount={Math.ceil(total / pageSize)}
+        onPageChange={setPage}
+        totalItems={total}
+        pageSize={pageSize}
+        onPageSizeChange={size => {
+          setPageSize(size)
+          setPage(1)
+        }}
+        showFirstLast
+        label="Pagination, table footer"
+      />
+    </div>
+  )
+}
+
+<TableFooterExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves across Previous, each page, and Next. |
+| `Enter` `Space` | Goes to that page. |
+| `Enter` | In the Go to page field, jumps to the page you typed. |
+
+## Do
+
+- Say how many results there are somewhere near it: 'Showing 41 to 60 of 312'.
+- After a change, move focus to the top of the new page of results.
+- Keep siblings at 1 on narrow layouts.
+- Under a data table, pass totalItems and pageSize. The footer then says what's on view, so you don't need a separate line of text.
+- Use variant 'compact' where space is tight, such as a card or a phone layout.
+
+## Don't
+
+- Don't paginate fewer than two pages; render nothing.
+- Don't disable the current page; Tab would skip it.
+- Don't use pagination for steps in a form.
+- Don't use variant 'select' for hundreds of pages. A list that long needs showJump instead.
+- Don't round the buttons into circles or pills; the square and the cut corner are this system's shape.
+
+## Anatomy
+
+- **nav**: The navigation region, named 'Pagination'.
+- **Previous / Next**: Ghost IconButtons (icon-only buttons with no fill). At the first and last page they're aria-disabled rather than disabled. ARIA (Accessible Rich Internet Applications) attributes tell screen readers about a control, and aria-disabled only marks the button as unavailable. It stays a real stop when you press Tab, so keyboard focus never drops to the page body when one stops working.
+- **Page**: A small Button named 'Page n', with tabular figures (digits that all take the same width).
+- **Current page**: The primary fill, with aria-current=page so screen readers say it's the current one. It isn't disabled, so Tab still reaches it.
+- **Gap**: An ellipsis that stands for two or more hidden pages. It's aria-hidden, so screen readers skip it.
+- **First / Last**: Optional (showFirstLast). Ghost IconButtons, aria-disabled at the first and last page.
+- **Readout or page Select**: Takes the place of the page buttons when variant is 'compact' or 'select'.
+- **Range and rows per page**: Optional (totalItems, pageSize, onPageSizeChange). These turn the control into a table footer: the range at the start, the controls at the end.
+- **Go to page**: Optional (showJump). A small number Input with a visible label, and a Go button.