Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(pagination): add editable input variant with page/row navigation mode (#4505)

freddymeta7bb95426c5d8
diff --git a/.changeset/pagination-input-variant.md b/.changeset/pagination-input-variant.md
new file mode 100644
index 0000000000..e5bbc82a99
--- /dev/null
+++ b/.changeset/pagination-input-variant.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Pagination: add an `input` variant — an editable page-number box (a `NumberInput`, so it clamps to `[1, totalPages]` with integer-only semantics) flanked by first/last («/») buttons, rendering `Page [ n ] / N`. Navigation is page-based via the existing `onChange`. The leading noun is set with an open `pageLabel` prop (defaults to the localized "Page"; pass `pageLabel="Row"` to relabel it). Also adds a `step` prop controlling how many pages the prev/next buttons advance per click (default 1, clamped to range); when greater than 1 the buttons' accessible names reflect the stride. Adds `chevronsLeft`/`chevronsRight` icons. The first/last/prev/next carets now also carry a hover tooltip (the same localized, step-aware label already used as their accessible name), so sighted users get the affordance the icon-only buttons previously exposed only to assistive tech. (#4248)
+
+@freddymeta
diff --git a/apps/storybook/stories/Pagination.stories.tsx b/apps/storybook/stories/Pagination.stories.tsx
index a87049796e..4caf4d177c 100644
--- a/apps/storybook/stories/Pagination.stories.tsx
+++ b/apps/storybook/stories/Pagination.stories.tsx
@@ -16,9 +16,22 @@ const meta: Meta<typeof Pagination> = {
},
variant: {
control: 'select',
- options: ['pages', 'count', 'compact', 'dots', 'none'],
+ options: ['pages', 'count', 'compact', 'dots', 'input', 'none'],
description: 'Visual variant',
},
+ pageLabel: {
+ control: 'text',
+ description:
+ "input variant: noun before the editable box (e.g. 'Page' or 'Row')",
+ },
+ hasFirstLast: {
+ control: 'boolean',
+ description: 'input variant: show first/last («/») buttons',
+ },
+ step: {
+ control: 'number',
+ description: 'pages the prev/next buttons advance per click',
+ },
size: {
control: 'select',
options: ['sm', 'md'],
@@ -99,6 +112,57 @@ export const NoneVariant: Story = {
render: () => <PaginationDemo page={1} totalPages={5} variant="none" />,
};
+export const InputVariant: Story = {
+ name: 'Variant: Input',
+ render: () => (
+ // The editable box: « ‹ Page [ n ] / N › »
+ <PaginationDemo page={3} totalItems={200} pageSize={20} variant="input" />
+ ),
+};
+
+export const InputVariantCustomLabel: Story = {
+ name: 'Variant: Input (custom pageLabel)',
+ render: () => (
+ // A "Row" label relabels the same page-navigated box: « ‹ Row [ n ] / N › »
+ <PaginationDemo
+ page={3}
+ totalItems={200}
+ pageSize={10}
+ variant="input"
+ pageLabel="Row"
+ />
+ ),
+};
+
+export const InputVariantNoFirstLast: Story = {
+ name: 'Variant: Input (no first/last)',
+ render: () => (
+ // Just ‹ Page [ n ] / N › — first/last buttons hidden.
+ <PaginationDemo
+ page={3}
+ totalItems={200}
+ pageSize={10}
+ variant="input"
+ hasFirstLast={false}
+ />
+ ),
+};
+
+export const InputVariantStep: Story = {
+ name: 'Variant: Input (step by 5)',
+ render: () => (
+ // ‹/› advance 5 pages per click (clamped to 1..N). 500 items at 25/page =
+ // 20 pages, so from page 6 next jumps to 11, prev back to 1.
+ <PaginationDemo
+ page={6}
+ totalItems={500}
+ pageSize={25}
+ variant="input"
+ step={5}
+ />
+ ),
+};
+
export const WithPageSizeSelector: Story = {
name: 'With Page Size Selector',
render: () => (
@@ -156,6 +220,7 @@ export const AllVariants: Story = {
totalItems={100}
pageSize={10}
variant="pages"
+ label="Pages variant"
/>
</div>
<div>
@@ -165,19 +230,45 @@ export const AllVariants: Story = {
totalItems={100}
pageSize={10}
variant="count"
+ label="Count variant"
/>
</div>
<div>
<p style={{marginBottom: 8, fontWeight: 500}}>compact</p>
- <PaginationDemo page={3} totalPages={10} variant="compact" />
+ <PaginationDemo
+ page={3}
+ totalPages={10}
+ variant="compact"
+ label="Compact variant"
+ />
</div>
<div>
<p style={{marginBottom: 8, fontWeight: 500}}>dots</p>
- <PaginationDemo page={3} totalPages={8} variant="dots" />
+ <PaginationDemo
+ page={3}
+ totalPages={8}
+ variant="dots"
+ label="Dots variant"
+ />
+ </div>
+ <div>
+ <p style={{marginBottom: 8, fontWeight: 500}}>input</p>
+ <PaginationDemo
+ page={3}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ label="Input variant"
+ />
</div>
<div>
<p style={{marginBottom: 8, fontWeight: 500}}>none</p>
- <PaginationDemo page={3} totalPages={10} variant="none" />
+ <PaginationDemo
+ page={3}
+ totalPages={10}
+ variant="none"
+ label="None variant"
+ />
</div>
</div>
),
diff --git a/packages/cli/assets/docs/icons.doc.mjs b/packages/cli/assets/docs/icons.doc.mjs
index 35e2e7e09e..b1925a81f6 100644
--- a/packages/cli/assets/docs/icons.doc.mjs
+++ b/packages/cli/assets/docs/icons.doc.mjs
@@ -29,6 +29,8 @@ export const docs = {
['chevronDown', 'Dropdown triggers, expand/collapse'],
['chevronLeft', 'Navigate back, previous'],
['chevronRight', 'Navigate forward, next'],
+ ['chevronsLeft', 'Jump to first, skip to start'],
+ ['chevronsRight', 'Jump to last, skip to end'],
['check', 'Checkbox checked, confirm'],
['success', 'Success status indicator'],
['error', 'Error status indicator'],
diff --git a/packages/cli/assets/templates/themes/butter/icons.tsx b/packages/cli/assets/templates/themes/butter/icons.tsx
index 516f53195f..b20f421dcc 100644
--- a/packages/cli/assets/templates/themes/butter/icons.tsx
+++ b/packages/cli/assets/templates/themes/butter/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const butterIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/chocolate/icons.tsx b/packages/cli/assets/templates/themes/chocolate/icons.tsx
index 5ce9f3042d..15ec323f17 100644
--- a/packages/cli/assets/templates/themes/chocolate/icons.tsx
+++ b/packages/cli/assets/templates/themes/chocolate/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const chocolateIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/gothic/icons.tsx b/packages/cli/assets/templates/themes/gothic/icons.tsx
index 4fc5fb653d..b71af76ad6 100644
--- a/packages/cli/assets/templates/themes/gothic/icons.tsx
+++ b/packages/cli/assets/templates/themes/gothic/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const gothicIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/matcha/icons.tsx b/packages/cli/assets/templates/themes/matcha/icons.tsx
index b5a9a83cde..4de1bca1c0 100644
--- a/packages/cli/assets/templates/themes/matcha/icons.tsx
+++ b/packages/cli/assets/templates/themes/matcha/icons.tsx
@@ -8,6 +8,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -42,6 +44,8 @@ export const matchaIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/neutral/icons.tsx b/packages/cli/assets/templates/themes/neutral/icons.tsx
index ea093d9b58..83d243854c 100644
--- a/packages/cli/assets/templates/themes/neutral/icons.tsx
+++ b/packages/cli/assets/templates/themes/neutral/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const neutralIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/stone/icons.tsx b/packages/cli/assets/templates/themes/stone/icons.tsx
index 88c0f1a9ca..6a80ea5c0f 100644
--- a/packages/cli/assets/templates/themes/stone/icons.tsx
+++ b/packages/cli/assets/templates/themes/stone/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const stoneIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/cli/assets/templates/themes/y2k/icons.tsx b/packages/cli/assets/templates/themes/y2k/icons.tsx
index 6240795740..b84634e1f4 100644
--- a/packages/cli/assets/templates/themes/y2k/icons.tsx
+++ b/packages/cli/assets/templates/themes/y2k/icons.tsx
@@ -8,6 +8,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -42,6 +44,8 @@ export const y2kIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 01280f9b71..ab83efdfd3 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -11,10 +11,38 @@
"defaultMessage": "Go to next page",
"description": "Aria label for the next-page button."
},
+ "@astryx.pagination.previousBy": {
+ "defaultMessage": "Go back {step, number} {step, plural, one {page} other {pages}}",
+ "description": "Aria label for the previous button when it advances more than one page per click (the `step` prop > 1). `step` is the number of pages skipped."
+ },
+ "@astryx.pagination.nextBy": {
+ "defaultMessage": "Go forward {step, number} {step, plural, one {page} other {pages}}",
+ "description": "Aria label for the next button when it advances more than one page per click (the `step` prop > 1). `step` is the number of pages skipped."
+ },
+ "@astryx.pagination.first": {
+ "defaultMessage": "Go to first page",
+ "description": "Aria label for the first-page button (« double chevron) in the input pagination variant."
+ },
+ "@astryx.pagination.last": {
+ "defaultMessage": "Go to last page",
+ "description": "Aria label for the last-page button (» double chevron) in the input pagination variant."
+ },
"@astryx.pagination.goToPage": {
"defaultMessage": "Go to page {page, number}",
"description": "Aria label for an individual page-number button. `page` is 1-based."
},
+ "@astryx.pagination.goToPageInput": {
+ "defaultMessage": "Go to page",
+ "description": "Aria label for the editable page/row number box in the input pagination variant. No number — the box holds the value itself."
+ },
+ "@astryx.pagination.pageLabel": {
+ "defaultMessage": "Page",
+ "description": "Visible label before the editable box in the input pagination variant. Example: \"Page [ 1 ] / 10\"."
+ },
+ "@astryx.pagination.ofTotalPages": {
+ "defaultMessage": "/ {total, number}",
+ "description": "Visible total shown after the editable box in the input pagination variant. Example: the \"/ 10\" in \"Page [ 1 ] / 10\"."
+ },
"@astryx.pagination.pageIndicators": {
"defaultMessage": "Page indicators",
"description": "Aria label for the dots-variant page-indicator group."
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index 8e798bdf7f..b418723dfc 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -19,7 +19,7 @@ export const docs = {
{
name: 'icon',
type: 'IconName | ComponentType<SVGProps>',
- description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+ description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
required: true,
},
{
@@ -77,7 +77,7 @@ export const docsZh = {
{
name: 'icon',
type: 'IconName | ComponentType<SVGProps>',
- description: '语义图标名称或 SVG 组件。有效语义名称:close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+ description: '语义图标名称或 SVG 组件。有效语义名称:close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
required: true,
},
{
@@ -145,7 +145,7 @@ export const docsDense = {
],
},
propDescriptions: {
- icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
+ icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
color: 'Color variant mapped to Astryx icon color tokens.',
size: 'Icon size.',
label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index 9f28fdb1e7..eab3729ccb 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -82,6 +82,20 @@ export const defaultIcons: IconRegistry = {
</svg>
),
+ /** « — double left chevron (first / jump to start) */
+ chevronsLeft: (
+ <svg {...svgProps}>
+ <path d="M18 6l-6 6 6 6M11 6l-6 6 6 6" />
+ </svg>
+ ),
+
+ /** » — double right chevron (last / jump to end) */
+ chevronsRight: (
+ <svg {...svgProps}>
+ <path d="M6 6l6 6-6 6M13 6l6 6-6 6" />
+ </svg>
+ ),
+
/** ✓ — checkmark */
check: (
<svg {...svgProps}>
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index 03dfe86d98..1970edf3b4 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -32,6 +32,8 @@ export type IconName =
| 'chevronDown'
| 'chevronLeft'
| 'chevronRight'
+ | 'chevronsLeft'
+ | 'chevronsRight'
| 'check'
| 'success'
| 'error'
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 452fcfe85b..d6b69e95a6 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -64,11 +64,31 @@ export const docs = {
},
{
name: 'variant',
- type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+ type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
description:
- "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'none' shows just prev/next buttons.",
+ "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label — 'Page [ n ] / N' — flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
default: "'pages'",
},
+ {
+ name: 'pageLabel',
+ type: 'string',
+ description:
+ "The noun rendered before the editable box in the 'input' variant, e.g. 'Page' or 'Row'. Navigation is always page-based (via onChange); this only relabels the box. Defaults to the localized 'Page'.",
+ },
+ {
+ name: 'hasFirstLast',
+ type: 'boolean',
+ description:
+ "Whether to show first/last («/») double-chevron buttons flanking prev/next. Only applies to the 'input' variant; omitted when the page count is unknown (cursor/hasMore pagination).",
+ default: 'true',
+ },
+ {
+ name: 'step',
+ type: 'number',
+ description:
+ 'Number of pages the previous/next buttons advance per click. Clamped to the valid page range, so a step that would overshoot lands on the first/last page. When greater than 1, the buttons\' accessible names reflect the stride. Non-integer or values < 1 fall back to 1.',
+ default: '1',
+ },
{
name: 'siblingCount',
type: 'number',
@@ -105,6 +125,8 @@ export const docs = {
targets: [
{className: 'astryx-pagination', visualProps: ['size', 'variant']},
{className: 'astryx-pagination-dot', visualProps: ['size'], states: ['active']},
+ {className: 'astryx-pagination-input-label', visualProps: ['size']},
+ {className: 'astryx-pagination-input-total', visualProps: ['size']},
],
},
playground: {
@@ -192,11 +214,31 @@ export const docsZh = {
},
{
name: 'variant',
- type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+ type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
description:
- "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮,'count' 显示 'X-Y of Z' 文本,'compact' 显示 'Page X of Y','dots' 显示点指示器,'none' 仅显示上一页/下一页按钮。",
+ "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮,'count' 显示 'X-Y of Z' 文本,'compact' 显示 'Page X of Y','dots' 显示点指示器,'input' 显示带前置标签的可编辑页码框——'Page [ n ] / N'——默认两侧带首页/末页按钮,'none' 仅显示上一页/下一页按钮。",
default: "'pages'",
},
+ {
+ name: 'pageLabel',
+ type: 'string',
+ description:
+ "'input' 变体中可编辑框前显示的名词,如 'Page' 或 'Row'。导航始终基于页码(通过 onChange);此项仅用于重新标注。默认为本地化的 'Page'。",
+ },
+ {
+ name: 'hasFirstLast',
+ type: 'boolean',
+ description:
+ "是否显示首页/末页(«/»)双箭头按钮,位于上一页/下一页两侧。仅适用于 'input' 变体;当页数未知(游标/hasMore 分页)时省略。",
+ default: 'true',
+ },
+ {
+ name: 'step',
+ type: 'number',
+ description:
+ '上一页/下一页按钮每次点击前进的页数。会被限制在有效页码范围内,因此超出范围的步进会落在首页/末页。大于 1 时,按钮的无障碍名称会反映跨步页数。非整数或小于 1 的值回退为 1。',
+ default: '1',
+ },
{
name: 'siblingCount',
type: 'number',
@@ -233,6 +275,8 @@ export const docsZh = {
targets: [
{className: 'astryx-pagination', visualProps: ['size', 'variant']},
{className: 'astryx-pagination-dot', visualProps: ['size'], states: ['active']},
+ {className: 'astryx-pagination-input-label', visualProps: ['size']},
+ {className: 'astryx-pagination-input-total', visualProps: ['size']},
],
},
usage: {
@@ -280,7 +324,10 @@ export const docsDense = {
pageSize: 'Items per page; coerced to positive integer, non-finite falls back to default',
pageSizeOptions: 'Page size options. Shows selector dropdown when provided.',
onPageSizeChange: 'Called on page size change. Auto resets to page 1.',
- variant: 'Display between prev/next buttons.',
+ variant: "Display between prev/next. 'input' = 'Page [n] / N' + first/last.",
+ pageLabel: "Noun before the 'input' box (e.g. 'Page' or 'Row'). Navigation stays page-based. Default localized 'Page'.",
+ hasFirstLast: "Show first/last («/») buttons in the 'input' variant. Omitted when total unknown.",
+ step: 'Pages the prev/next buttons advance per click. Clamped to range; < 1 or non-integer falls back to 1.',
siblingCount: "Page buttons each side of current; only variant='pages'.",
size: 'Control size.',
isDisabled: 'Component disabled.',
diff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsx
index cc41b673f4..6e9ed6b6b5 100644
--- a/packages/core/src/Pagination/Pagination.test.tsx
+++ b/packages/core/src/Pagination/Pagination.test.tsx
@@ -119,6 +119,29 @@ describe('Pagination', () => {
).toBeInTheDocument();
});
+ it('gives the prev/next carets a hover tooltip matching their accessible name', () => {
+ // The carets are icon-only, so sighted users need a visible label on
+ // hover, not just the accessible name. The tooltip reuses the same
+ // localized string, so it is reachable via aria-describedby.
+ render(<Pagination page={3} onChange={() => {}} totalPages={5} />);
+ const prev = screen.getByRole('button', {name: 'Go to previous page'});
+ const next = screen.getByRole('button', {name: 'Go to next page'});
+ const tooltips = screen.getAllByRole('tooltip', {hidden: true});
+ const tooltipIds = new Set(tooltips.map(el => el.id));
+ expect(
+ prev
+ .getAttribute('aria-describedby')
+ ?.split(' ')
+ .some(id => tooltipIds.has(id)),
+ ).toBe(true);
+ expect(
+ next
+ .getAttribute('aria-describedby')
+ ?.split(' ')
+ .some(id => tooltipIds.has(id)),
+ ).toBe(true);
+ });
+
it('renders with data-testid', () => {
render(
<Pagination
@@ -517,6 +540,445 @@ describe('Pagination', () => {
});
});
+ // ---------------------------------------------------------------------------
+ // Variant: input
+ // ---------------------------------------------------------------------------
+
+ describe('variant: input', () => {
+ it('renders "Page [ n ] / N" with an editable box in page mode', () => {
+ render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ expect(box).toBeInTheDocument();
+ expect(box).toHaveValue(3);
+ // Visible leading "Page" label and trailing "/ N" total (10 pages).
+ expect(screen.getByText('Page')).toBeInTheDocument();
+ expect(screen.getByText('/ 10')).toBeInTheDocument();
+ // No page-number buttons and no range readout ("Showing 1–N of M").
+ expect(
+ screen.queryByRole('button', {name: /Go to page \d/}),
+ ).not.toBeInTheDocument();
+ expect(screen.queryByText(/Showing/i)).not.toBeInTheDocument();
+ // Flanked by first/prev/next/last.
+ expect(
+ screen.getByRole('button', {name: 'Go to first page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to previous page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to next page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to last page'}),
+ ).toBeInTheDocument();
+ });
+
+ it('bounds the editable box to [1, totalPages] via a NumberInput', () => {
+ render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ // The box is a NumberInput (a spinbutton) whose min/max clamp entries to
+ // the valid page range without hand-rolled parsing in Pagination.
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ expect(box).toHaveAttribute('min', '1');
+ expect(box).toHaveAttribute('max', '10');
+ });
+
+ it('commits a typed page on Enter and rejects an over-range entry', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={1}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ await user.clear(box);
+ await user.type(box, '4{Enter}');
+ expect(onChange).toHaveBeenCalledWith(4);
+
+ onChange.mockClear();
+ await user.clear(box);
+ // The box is a NumberInput bounded to [1, totalPages]: an over-max entry
+ // is rejected and never navigates past the last page.
+ await user.type(box, '99{Enter}');
+ expect(onChange).not.toHaveBeenCalledWith(99);
+ });
+
+ it('commits on blur', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={1}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ await user.clear(box);
+ await user.type(box, '5');
+ await user.tab();
+ expect(onChange).toHaveBeenCalledWith(5);
+ });
+
+ it('reverts to the current page on an invalid or empty entry', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={3}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ // A number input rejects non-numeric characters, so an invalid entry
+ // never navigates and reverts to the committed page on blur.
+ await user.clear(box);
+ await user.type(box, 'abc');
+ await user.tab();
+ expect(onChange).not.toHaveBeenCalled();
+ expect(box).toHaveValue(3);
+
+ // Emptying the box and blurring reverts to the committed page too.
+ await user.clear(box);
+ await user.tab();
+ expect(onChange).not.toHaveBeenCalled();
+ expect(box).toHaveValue(3);
+ });
+
+ it('announces the committed page to screen readers', async () => {
+ const user = userEvent.setup();
+ render(
+ <Pagination
+ page={1}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ await user.clear(box);
+ await user.type(box, '4{Enter}');
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('Page 4 of 10');
+ });
+ });
+
+ it('is disabled and does not commit when isDisabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={2}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ isDisabled
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ expect(box).toBeDisabled();
+ // Disabled input never fires a change.
+ await user.type(box, '5{Enter}');
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('rejects a below-range entry rather than navigating out of range', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={5}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ await user.clear(box);
+ // The box is bounded to [1, totalPages]: 0 (and negatives) are below the
+ // minimum, so they are rejected and never navigate.
+ await user.type(box, '0{Enter}');
+ expect(onChange).not.toHaveBeenCalledWith(0);
+ });
+
+ it('disables the input when the total is unknown (cursor/hasMore)', () => {
+ render(
+ <Pagination page={2} onChange={() => {}} hasMore variant="input" />,
+ );
+ // With no known page count there is no range to clamp against, so the
+ // editable box is inert rather than accepting entries it can't resolve.
+ expect(
+ screen.getByRole('spinbutton', {name: 'Go to page'}),
+ ).toBeDisabled();
+ });
+
+ it('renders the localized "Page" label by default and a custom pageLabel', () => {
+ const {rerender} = render(
+ <Pagination
+ page={2}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ // Default: the localized "Page" noun precedes the box.
+ expect(screen.getByText('Page')).toBeInTheDocument();
+
+ // A custom pageLabel relabels the box without changing navigation.
+ rerender(
+ <Pagination
+ page={2}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ pageLabel="Row"
+ />,
+ );
+ expect(screen.getByText('Row')).toBeInTheDocument();
+ expect(screen.queryByText('Page')).not.toBeInTheDocument();
+ // The trailing "/ N" total stays regardless of the label.
+ expect(screen.getByText('/ 10')).toBeInTheDocument();
+ });
+
+ it('navigates by page (via onChange) even with a custom pageLabel', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={1}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ pageLabel="Row"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ // The box holds the page number, and committing drives page navigation.
+ expect(box).toHaveValue(1);
+ await user.clear(box);
+ await user.type(box, '4{Enter}');
+ expect(onChange).toHaveBeenCalledWith(4);
+ });
+
+ // -------------------------------------------------------------------------
+ // First / Last buttons
+ // -------------------------------------------------------------------------
+
+ describe('first/last buttons', () => {
+ it('first jumps to page 1, last jumps to the final page', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={5}
+ onChange={onChange}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go to first page'}),
+ );
+ expect(onChange).toHaveBeenCalledWith(1);
+
+ onChange.mockClear();
+ await user.click(screen.getByRole('button', {name: 'Go to last page'}));
+ // 100 items / 10 per page → 10 pages.
+ expect(onChange).toHaveBeenCalledWith(10);
+ });
+
+ it('disables first on the first page and last on the last page', () => {
+ const {rerender} = render(
+ <Pagination
+ page={1}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go to first page'}),
+ ).toBeDisabled();
+ expect(
+ screen.getByRole('button', {name: 'Go to last page'}),
+ ).not.toBeDisabled();
+
+ rerender(
+ <Pagination
+ page={10}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go to last page'}),
+ ).toBeDisabled();
+ expect(
+ screen.getByRole('button', {name: 'Go to first page'}),
+ ).not.toBeDisabled();
+ });
+
+ it('hides first/last when hasFirstLast is false', () => {
+ render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ hasFirstLast={false}
+ />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Go to first page'}),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Go to last page'}),
+ ).not.toBeInTheDocument();
+ // prev/next still present.
+ expect(
+ screen.getByRole('button', {name: 'Go to previous page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to next page'}),
+ ).toBeInTheDocument();
+ });
+
+ it('omits first/last when the total page count is unknown', () => {
+ render(
+ <Pagination page={2} onChange={() => {}} hasMore variant="input" />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Go to first page'}),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Go to last page'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('renders the double-chevron icons for first/last', () => {
+ const {container} = render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="input"
+ />,
+ );
+ // Each default double-chevron icon draws two chevron paths in one <path>
+ // ("M...M..."); assert both first and last render an svg with two moves.
+ const first = screen.getByRole('button', {name: 'Go to first page'});
+ const last = screen.getByRole('button', {name: 'Go to last page'});
+ for (const btn of [first, last]) {
+ const path = btn.querySelector('svg path');
+ expect(path).not.toBeNull();
+ const d = path?.getAttribute('d') ?? '';
+ expect((d.match(/M/g) ?? []).length).toBe(2);
+ }
+ expect(container).toBeTruthy();
+ });
+
+ it('does not add first/last to other variants (e.g. pages)', () => {
+ render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={100}
+ pageSize={10}
+ variant="pages"
+ />,
+ );
+ expect(
+ screen.queryByRole('button', {name: 'Go to first page'}),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Go to last page'}),
+ ).not.toBeInTheDocument();
+ });
+ });
+
+ // -------------------------------------------------------------------------
+ // Custom label via pageLabel
+ // -------------------------------------------------------------------------
+
+ describe('pageLabel', () => {
+ it('renders a custom noun while keeping the "/ N" total', () => {
+ render(
+ <Pagination
+ page={3}
+ onChange={() => {}}
+ totalItems={200}
+ pageSize={20}
+ variant="input"
+ pageLabel="Row"
+ />,
+ );
+ // The custom noun replaces the default "Page"; the total stays.
+ expect(screen.getByText('Row')).toBeInTheDocument();
+ expect(screen.queryByText('Page')).not.toBeInTheDocument();
+ expect(screen.getByText('/ 10')).toBeInTheDocument();
+ // The box still holds the 1-based page number.
+ expect(
+ screen.getByRole('spinbutton', {name: 'Go to page'}),
+ ).toHaveValue(3);
+ });
+
+ it('keeps the input page-navigating with a custom label', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={1}
+ onChange={onChange}
+ totalPages={10}
+ variant="input"
+ pageLabel="Row"
+ />,
+ );
+ const box = screen.getByRole('spinbutton', {name: 'Go to page'});
+ await user.clear(box);
+ await user.type(box, '5{Enter}');
+ expect(onChange).toHaveBeenCalledWith(5);
+ });
+ });
+ });
+
// ---------------------------------------------------------------------------
// Page change callbacks
// ---------------------------------------------------------------------------
@@ -596,6 +1058,111 @@ describe('Pagination', () => {
});
});
+ describe('step', () => {
+ it('advances next by step pages', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination page={1} onChange={onChange} totalPages={20} step={5} />,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go forward 5 pages'}),
+ );
+ expect(onChange).toHaveBeenCalledWith(6);
+ });
+
+ it('moves previous by step pages', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination page={11} onChange={onChange} totalPages={20} step={5} />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Go back 5 pages'}));
+ expect(onChange).toHaveBeenCalledWith(6);
+ });
+
+ it('clamps a next step that would overshoot to the last page', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination page={18} onChange={onChange} totalPages={20} step={5} />,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go forward 5 pages'}),
+ );
+ expect(onChange).toHaveBeenCalledWith(20);
+ });
+
+ it('clamps a previous step that would undershoot to the first page', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination page={3} onChange={onChange} totalPages={20} step={5} />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Go back 5 pages'}));
+ expect(onChange).toHaveBeenCalledWith(1);
+ });
+
+ it('falls back to a single-page step for non-integer or < 1 values', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const {rerender} = render(
+ <Pagination page={5} onChange={onChange} totalPages={20} step={0} />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+ expect(onChange).toHaveBeenLastCalledWith(6);
+
+ rerender(
+ <Pagination page={5} onChange={onChange} totalPages={20} step={2.5} />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+ expect(onChange).toHaveBeenLastCalledWith(6);
+ });
+
+ it('steps the input variant by step pages', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Pagination
+ page={1}
+ onChange={onChange}
+ totalItems={500}
+ pageSize={25}
+ variant="input"
+ step={5}
+ />,
+ );
+ await user.click(
+ screen.getByRole('button', {name: 'Go forward 5 pages'}),
+ );
+ expect(onChange).toHaveBeenCalledWith(6);
+ });
+
+ it('names the prev/next buttons for the stride when step > 1', () => {
+ render(
+ <Pagination page={5} onChange={() => {}} totalPages={20} step={5} />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go forward 5 pages'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go back 5 pages'}),
+ ).toBeInTheDocument();
+ });
+
+ it('keeps the single-page names when step is 1', () => {
+ render(
+ <Pagination page={5} onChange={() => {}} totalPages={20} step={1} />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go to next page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to previous page'}),
+ ).toBeInTheDocument();
+ });
+ });
+
// ---------------------------------------------------------------------------
// changeAction (interruptible, optimistic)
// ---------------------------------------------------------------------------
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index c9db597dd4..351945044d 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -5,7 +5,9 @@
/**
* @file Pagination.tsx
* @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
- * Prev/next chevrons mirror under RTL via the shared rtlStyles.mirror (CSS scaleX), not a JS direction read.
+ * Prev/next and first/last chevrons mirror under RTL via the shared rtlStyles.mirror
+ * (CSS scaleX), not a JS direction read. The input variant uses the chevronsLeft/chevronsRight
+ * (first/last) icons.
* @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
* @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
*
@@ -16,8 +18,8 @@
* - /packages/cli/assets/templates/blocks/components/Pagination/ (showcase blocks)
*
* Last synced props: page, onChange, changeAction, totalItems, totalPages, hasMore,
- * pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled,
- * label, data-testid, xstyle
+ * pageSize, pageSizeOptions, onPageSizeChange, variant, pageLabel,
+ * hasFirstLast, step, siblingCount, size, isDisabled, label, data-testid, xstyle
*/
import {useOptimistic, useTransition} from 'react';
@@ -33,6 +35,7 @@ import {
} from '../theme/tokens.stylex';
import {Button} from '../Button';
import {Icon} from '../Icon';
+import {NumberInput} from '../NumberInput';
import {Selector} from '../Selector';
import {Text} from '../Text';
import {useAnnounce} from '../hooks/useAnnounce';
@@ -103,10 +106,34 @@ export interface PaginationProps extends Omit<
* - count: "X–Y of Z" text
* - compact: "Page X of Y" text
* - dots: Dot indicators
+ * - input: An editable number box rendering "Page [ n ] / N". The leading
+ * noun is controlled by `pageLabel`. First/last double-chevron buttons
+ * flank prev/next by default (see hasFirstLast).
* - none: Just prev/next buttons
* @default 'pages'
*/
variant?: PaginationVariant;
+ /**
+ * The noun rendered before the editable box in the `input` variant, e.g.
+ * "Page" or "Row". Navigation is always page-based (via `onChange`); this
+ * only relabels the box. @default the localized "Page"
+ */
+ pageLabel?: string;
+ /**
+ * Whether to show first/last («/») double-chevron buttons flanking
+ * prev/next. Only applies to the `input` variant; other variants ignore it.
+ * The last button needs a known total — it is omitted when the page count is
+ * unknown (cursor/hasMore pagination). @default true
+ */
+ hasFirstLast?: boolean;
+ /**
+ * Number of pages the previous/next («‹ ›») buttons advance per click.
+ * Clamped to the valid page range, so a step that would overshoot lands on
+ * the first/last page. When greater than 1, the buttons' accessible names
+ * reflect the stride (e.g. "Go forward 5 pages"). Non-integer or values < 1
+ * fall back to 1. @default 1
+ */
+ step?: number;
/**
* Number of page buttons to show on each side of the current page.
* Only applies when variant='pages'. @default 1
@@ -211,6 +238,28 @@ const styles = stylex.create({
backgroundColor: colorVars['--color-neutral'],
fontWeight: fontWeightVars['--font-weight-medium'],
},
+ inputGroup: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ whiteSpace: 'nowrap',
+ },
+ inputLabel: {
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-label-size'],
+ userSelect: 'none',
+ },
+ inputLabelSm: {
+ fontSize: typeScaleVars['--text-supporting-size'],
+ },
+ inputTotal: {
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-label-size'],
+ userSelect: 'none',
+ },
+ inputTotalSm: {
+ fontSize: typeScaleVars['--text-supporting-size'],
+ },
pageSizeSelector: {
display: 'flex',
alignItems: 'center',
@@ -323,6 +372,9 @@ export function Pagination({
pageSizeOptions,
onPageSizeChange,
variant = 'pages',
+ pageLabel,
+ hasFirstLast = true,
+ step: stepProp = 1,
siblingCount = 1,
size = 'md',
isDisabled = false,
@@ -339,11 +391,13 @@ export function Pagination({
// Resolve system strings once per render. Prop overrides win.
const t = useTranslator();
const label = labelFromProps ?? t('@astryx.pagination.label');
- const previousLabel = t('@astryx.pagination.previous');
- const nextLabel = t('@astryx.pagination.next');
+ const firstLabel = t('@astryx.pagination.first');
+ const lastLabel = t('@astryx.pagination.last');
const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
+ const goToPageLabel = t('@astryx.pagination.goToPageInput');
+ const inputLabelText = pageLabel ?? t('@astryx.pagination.pageLabel');
// pageSize is typed as number, so 0, NaN, and negatives are valid at the
// type level but yield Infinity/NaN page counts, and
@@ -353,6 +407,23 @@ export function Pagination({
? Math.max(1, Math.floor(pageSizeProp))
: 10;
+ // Prev/next stride. Same guard as pageSize: non-integer or < 1 falls back to
+ // a single-page step so a bad value never freezes or reverses navigation.
+ const step = Number.isInteger(stepProp) && stepProp >= 1 ? stepProp : 1;
+
+ // The prev/next buttons advance `step` pages, so their accessible names must
+ // reflect the stride: a plain "previous/next page" for the default single
+ // step, or an explicit "back/forward N pages" so a screen reader never
+ // announces a single-page move for a multi-page jump.
+ const previousLabel =
+ step > 1
+ ? t('@astryx.pagination.previousBy', {step})
+ : t('@astryx.pagination.previous');
+ const nextLabel =
+ step > 1
+ ? t('@astryx.pagination.nextBy', {step})
+ : t('@astryx.pagination.next');
+
// Announce page changes politely (navigation-10). The controls carry no
// live region, so page transitions were previously silent to screen readers.
// Only user-driven changes go through handlePageChange, so initial mount is
@@ -378,7 +449,6 @@ export function Pagination({
orientation: 'horizontal',
});
- // Compute pagination state
const computedTotalPages =
totalPagesProp ??
(totalItems != null ? Math.ceil(totalItems / pageSize) : undefined);
@@ -389,7 +459,6 @@ export function Pagination({
? optimisticPage < computedTotalPages
: (hasMore ?? false);
- // Return null for empty state
if (totalItems != null && totalItems <= 0) {
return null;
}
@@ -443,15 +512,37 @@ export function Pagination({
}
};
+ // Clamp a target page into the valid range. The lower bound is always 1; the
+ // upper bound only exists when the page count is known (cursor/hasMore mode
+ // leaves it open-ended).
+ const clampPage = (target: number): number => {
+ const lower = Math.max(target, 1);
+ return computedTotalPages != null
+ ? Math.min(lower, computedTotalPages)
+ : lower;
+ };
+
const handlePrevious = () => {
if (hasPrevious) {
- handlePageChange(optimisticPage - 1);
+ handlePageChange(clampPage(optimisticPage - step));
}
};
const handleNext = () => {
if (hasNext) {
- handlePageChange(optimisticPage + 1);
+ handlePageChange(clampPage(optimisticPage + step));
+ }
+ };
+
+ const handleFirst = () => {
+ if (hasPrevious) {
+ handlePageChange(1);
+ }
+ };
+
+ const handleLast = () => {
+ if (hasNext && computedTotalPages != null) {
+ handlePageChange(computedTotalPages);
}
};
@@ -462,6 +553,19 @@ export function Pagination({
handlePageChange(1);
};
+ // The value currently shown in the input box is the committed page number.
+ const inputCommittedValue = optimisticPage;
+
+ // NumberInput owns the typing/pending state and clamps to [min, max] with
+ // integer-only semantics, so it only ever hands back a valid page here.
+ // Navigation is page-based via onChange.
+ const handleInputCommit = (nextPage: number) => {
+ if (isDisabled || nextPage === optimisticPage) {
+ return;
+ }
+ handlePageChange(nextPage);
+ };
+
// Item range for count display
const rangeStart = (optimisticPage - 1) * pageSize + 1;
const rangeEnd =
@@ -472,6 +576,11 @@ export function Pagination({
const buttonSize = size === 'sm' ? 'sm' : 'md';
const isSm = size === 'sm';
+ // First/last buttons only exist in the input variant, and only when the page
+ // count is known (they'd have no target otherwise).
+ const showFirstLast =
+ hasFirstLast && variant === 'input' && computedTotalPages != null;
+
const renderIndicator = () => {
switch (variant) {
case 'pages': {
@@ -607,6 +716,61 @@ export function Pagination({
);
}
+ case 'input': {
+ // The editable box needs a known page count to clamp against; in
+ // cursor/hasMore mode (no total) there is no valid range, so the box is
+ // disabled rather than accepting entries it can't resolve — matching the
+ // convention that a typeable page box requires a known total.
+ const isInputDisabled = isDisabled || computedTotalPages == null;
+
+ const inputNode = (
+ <NumberInput
+ label={goToPageLabel}
+ isLabelHidden
+ value={inputCommittedValue}
+ onChange={handleInputCommit}
+ min={1}
+ max={computedTotalPages ?? undefined}
+ isIntegerOnly
+ size={size}
+ width={
+ isSm
+ ? sizeVars['--size-element-sm']
+ : sizeVars['--size-element-md']
+ }
+ isDisabled={isInputDisabled}
+ data-testid={testId != null ? `${testId}-input` : undefined}
+ />
+ );
+
+ // Label wording: "Page [ n ] / N". The leading noun comes from
+ // `pageLabel`; the trailing "/ N" total is omitted when unknown.
+ return (
+ <span {...stylex.props(styles.inputGroup)}>
+ <span
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('pagination-input-label', {size}),
+ stylex.props(styles.inputLabel, isSm && styles.inputLabelSm),
+ )}>
+ {inputLabelText}
+ </span>
+ {inputNode}
+ {computedTotalPages != null && (
+ <span
+ {...mergeProps(
+ themeProps('pagination-input-total', {size}),
+ stylex.props(styles.inputTotal, isSm && styles.inputTotalSm),
+ )}>
+ {t('@astryx.pagination.ofTotalPages', {
+ total: computedTotalPages,
+ })}
+ </span>
+ )}
+ </span>
+ );
+ }
+
case 'none':
default:
return null;
@@ -641,8 +805,26 @@ export function Pagination({
</div>
)}
<div {...stylex.props(styles.controls)}>
+ {showFirstLast && (
+ <Button
+ label={firstLabel}
+ tooltip={isDisabled || !hasPrevious ? undefined : firstLabel}
+ variant="ghost"
+ size={buttonSize}
+ icon={
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronsLeft" size={isSm ? 'sm' : 'md'} />
+ </span>
+ }
+ onClick={handleFirst}
+ isDisabled={isDisabled || !hasPrevious}
+ isIconOnly
+ />
+ )}
+
<Button
label={previousLabel}
+ tooltip={isDisabled || !hasPrevious ? undefined : previousLabel}
variant="ghost"
size={buttonSize}
icon={
@@ -659,6 +841,7 @@ export function Pagination({
<Button
label={nextLabel}
+ tooltip={isDisabled || !hasNext ? undefined : nextLabel}
variant="ghost"
size={buttonSize}
icon={
@@ -670,6 +853,23 @@ export function Pagination({
isDisabled={isDisabled || !hasNext}
isIconOnly
/>
+
+ {showFirstLast && (
+ <Button
+ label={lastLabel}
+ tooltip={isDisabled || !hasNext ? undefined : lastLabel}
+ variant="ghost"
+ size={buttonSize}
+ icon={
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronsRight" size={isSm ? 'sm' : 'md'} />
+ </span>
+ }
+ onClick={handleLast}
+ isDisabled={isDisabled || !hasNext}
+ isIconOnly
+ />
+ )}
</div>
</nav>
);
diff --git a/packages/core/src/Pagination/index.ts b/packages/core/src/Pagination/index.ts
index c18b78ffc0..93357b8cd2 100644
--- a/packages/core/src/Pagination/index.ts
+++ b/packages/core/src/Pagination/index.ts
@@ -27,6 +27,7 @@ export interface PaginationVariantMap {
count: true;
compact: true;
dots: true;
+ input: true;
none: true;
}
diff --git a/packages/core/src/Table/useTableRowStatus.doc.mjs b/packages/core/src/Table/useTableRowStatus.doc.mjs
index 49c61da607..c4f76f8088 100644
--- a/packages/core/src/Table/useTableRowStatus.doc.mjs
+++ b/packages/core/src/Table/useTableRowStatus.doc.mjs
@@ -13,7 +13,7 @@ export const docs = {
name: 'getStatus',
type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
description:
- 'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+ 'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
required: true,
},
],
diff --git a/packages/themes/butter/src/icons.tsx b/packages/themes/butter/src/icons.tsx
index 516f53195f..b20f421dcc 100644
--- a/packages/themes/butter/src/icons.tsx
+++ b/packages/themes/butter/src/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const butterIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/chocolate/src/icons.tsx b/packages/themes/chocolate/src/icons.tsx
index 5ce9f3042d..15ec323f17 100644
--- a/packages/themes/chocolate/src/icons.tsx
+++ b/packages/themes/chocolate/src/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const chocolateIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/gothic/src/icons.tsx b/packages/themes/gothic/src/icons.tsx
index 4fc5fb653d..b71af76ad6 100644
--- a/packages/themes/gothic/src/icons.tsx
+++ b/packages/themes/gothic/src/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const gothicIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/matcha/src/icons.tsx b/packages/themes/matcha/src/icons.tsx
index b5a9a83cde..4de1bca1c0 100644
--- a/packages/themes/matcha/src/icons.tsx
+++ b/packages/themes/matcha/src/icons.tsx
@@ -8,6 +8,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -42,6 +44,8 @@ export const matchaIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsx
index ea093d9b58..83d243854c 100644
--- a/packages/themes/neutral/src/icons.tsx
+++ b/packages/themes/neutral/src/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const neutralIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/stone/src/icons.tsx b/packages/themes/stone/src/icons.tsx
index 88c0f1a9ca..6a80ea5c0f 100644
--- a/packages/themes/stone/src/icons.tsx
+++ b/packages/themes/stone/src/icons.tsx
@@ -18,6 +18,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -52,6 +54,8 @@ export const stoneIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,
diff --git a/packages/themes/y2k/src/icons.tsx b/packages/themes/y2k/src/icons.tsx
index 6240795740..b84634e1f4 100644
--- a/packages/themes/y2k/src/icons.tsx
+++ b/packages/themes/y2k/src/icons.tsx
@@ -8,6 +8,8 @@ import {
ChevronDown,
ChevronLeft,
ChevronRight,
+ ChevronsLeft,
+ ChevronsRight,
Check,
CheckCircle,
XCircle,
@@ -42,6 +44,8 @@ export const y2kIconRegistry: IconRegistry = {
chevronDown: <ChevronDown {...iconProps} />,
chevronLeft: <ChevronLeft {...iconProps} />,
chevronRight: <ChevronRight {...iconProps} />,
+ chevronsLeft: <ChevronsLeft {...iconProps} />,
+ chevronsRight: <ChevronsRight {...iconProps} />,
check: <Check {...iconProps} />,
success: <CheckCircle {...iconProps} />,
error: <XCircle {...iconProps} />,