@xsolla/xui-pagination 0.99.0 → 0.100.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +188 -18
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,43 +1,213 @@
1
- # @xsolla/xui-pagination
1
+ ---
2
+ title: Pagination
3
+ subtitle: A navigation component for paged content.
4
+ description: A cross-platform React pagination component with page numbers, ellipsis, and navigation arrows.
5
+ ---
2
6
 
3
- Page navigation control with ellipsis truncation, prev/next arrows, and size variants.
7
+ # Pagination
8
+
9
+ A cross-platform React pagination component for navigating through paged content. Features adaptive page number display with ellipsis for large page counts.
4
10
 
5
11
  ## Installation
6
12
 
7
13
  ```bash
14
+ npm install @xsolla/xui-pagination
15
+ # or
8
16
  yarn add @xsolla/xui-pagination
9
17
  ```
10
18
 
11
- ## Usage
19
+ ## Demo
20
+
21
+ ### Basic Pagination
12
22
 
13
23
  ```tsx
24
+ import * as React from 'react';
14
25
  import { Pagination } from '@xsolla/xui-pagination';
15
26
 
16
- function MyComponent() {
17
- const [currentPage, setCurrentPage] = React.useState(1);
27
+ export default function BasicPagination() {
28
+ const [page, setPage] = React.useState(1);
18
29
 
19
30
  return (
20
31
  <Pagination
32
+ currentPage={page}
21
33
  totalPages={10}
22
- currentPage={currentPage}
23
- onPageChange={setCurrentPage}
34
+ onPageChange={setPage}
24
35
  />
25
36
  );
26
37
  }
27
38
  ```
28
39
 
29
- ## Props
40
+ ### Large Page Count
41
+
42
+ ```tsx
43
+ import * as React from 'react';
44
+ import { Pagination } from '@xsolla/xui-pagination';
45
+
46
+ export default function LargePagination() {
47
+ const [page, setPage] = React.useState(1);
48
+
49
+ return (
50
+ <Pagination
51
+ currentPage={page}
52
+ totalPages={100}
53
+ onPageChange={setPage}
54
+ siblingCount={1}
55
+ />
56
+ );
57
+ }
58
+ ```
59
+
60
+ ### Stretched Layout
61
+
62
+ ```tsx
63
+ import * as React from 'react';
64
+ import { Pagination } from '@xsolla/xui-pagination';
65
+
66
+ export default function StretchedPagination() {
67
+ const [page, setPage] = React.useState(5);
68
+
69
+ return (
70
+ <div style={{ width: '100%' }}>
71
+ <Pagination
72
+ currentPage={page}
73
+ totalPages={20}
74
+ onPageChange={setPage}
75
+ stretched={true}
76
+ />
77
+ </div>
78
+ );
79
+ }
80
+ ```
81
+
82
+ ## Anatomy
83
+
84
+ ```jsx
85
+ import { Pagination } from '@xsolla/xui-pagination';
86
+
87
+ <Pagination
88
+ currentPage={1} // Current active page
89
+ totalPages={10} // Total number of pages
90
+ onPageChange={setPage} // Page change handler
91
+ siblingCount={1} // Pages shown on each side
92
+ showNavigation={true} // Show prev/next arrows
93
+ stretched={false} // Center and stretch
94
+ disabled={false} // Disabled state
95
+ size="md" // Size variant
96
+ />
97
+ ```
98
+
99
+ ## Examples
100
+
101
+ ### Pagination Sizes
102
+
103
+ ```tsx
104
+ import * as React from 'react';
105
+ import { Pagination } from '@xsolla/xui-pagination';
106
+
107
+ export default function PaginationSizes() {
108
+ return (
109
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
110
+ <Pagination size="sm" currentPage={3} totalPages={10} />
111
+ <Pagination size="md" currentPage={3} totalPages={10} />
112
+ <Pagination size="lg" currentPage={3} totalPages={10} />
113
+ </div>
114
+ );
115
+ }
116
+ ```
117
+
118
+ ### Without Navigation Arrows
119
+
120
+ ```tsx
121
+ import * as React from 'react';
122
+ import { Pagination } from '@xsolla/xui-pagination';
123
+
124
+ export default function NoArrowsPagination() {
125
+ const [page, setPage] = React.useState(1);
126
+
127
+ return (
128
+ <Pagination
129
+ currentPage={page}
130
+ totalPages={10}
131
+ onPageChange={setPage}
132
+ showNavigation={false}
133
+ />
134
+ );
135
+ }
136
+ ```
137
+
138
+ ### More Sibling Pages
139
+
140
+ ```tsx
141
+ import * as React from 'react';
142
+ import { Pagination } from '@xsolla/xui-pagination';
143
+
144
+ export default function MoreSiblingsPagination() {
145
+ const [page, setPage] = React.useState(10);
146
+
147
+ return (
148
+ <Pagination
149
+ currentPage={page}
150
+ totalPages={50}
151
+ onPageChange={setPage}
152
+ siblingCount={2}
153
+ />
154
+ );
155
+ }
156
+ ```
157
+
158
+ ### Disabled Pagination
159
+
160
+ ```tsx
161
+ import * as React from 'react';
162
+ import { Pagination } from '@xsolla/xui-pagination';
163
+
164
+ export default function DisabledPagination() {
165
+ return (
166
+ <Pagination
167
+ currentPage={5}
168
+ totalPages={10}
169
+ disabled={true}
170
+ />
171
+ );
172
+ }
173
+ ```
174
+
175
+ ## API Reference
30
176
 
31
177
  ### Pagination
32
178
 
179
+ **Pagination Props:**
180
+
33
181
  | Prop | Type | Default | Description |
34
- |------|------|---------|-------------|
35
- | `currentPage` | `number` | `1` | Active page (1-indexed) |
36
- | `totalPages` | `number` | `1` | Total number of pages |
37
- | `onPageChange` | `(page: number) => void` | — | Called when a page is selected |
38
- | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
39
- | `siblingCount` | `number` | `1` | Page buttons shown either side of current page |
40
- | `showNavigation` | `boolean` | `true` | Show prev/next arrow buttons |
41
- | `disabled` | `boolean` | `false` | Disable all interactions |
42
- | `stretched` | `boolean` | `false` | Stretch to fill container width |
43
- | `backgroundColor` | `string` | — | Custom background colour |
182
+ | :--- | :--- | :------ | :---------- |
183
+ | currentPage | `number` | `1` | Current active page (1-indexed). |
184
+ | totalPages | `number` | `1` | Total number of pages. |
185
+ | onPageChange | `(page: number) => void` | - | Page change handler. |
186
+ | siblingCount | `number` | `1` | Number of pages shown on each side of current. |
187
+ | showNavigation | `boolean` | `true` | Show previous/next arrow buttons. |
188
+ | stretched | `boolean` | `false` | Center content and stretch to full width. |
189
+ | disabled | `boolean` | `false` | Disabled state. |
190
+ | size | `"sm" \| "md" \| "lg"` | `"md"` | Size variant. |
191
+ | backgroundColor | `string` | - | Background color. |
192
+ | testID | `string` | - | Test identifier. |
193
+
194
+ ## Behavior
195
+
196
+ - Ellipsis appears when page count exceeds visible slots
197
+ - First and last pages always shown when ellipsis present
198
+ - Navigation arrows disabled at first/last page
199
+ - Active page is visually highlighted
200
+
201
+ ## Page Number Display Logic
202
+
203
+ Given `siblingCount=1` and `totalPages=20`:
204
+ - Page 1: `1 2 3 4 5 ... 20`
205
+ - Page 10: `1 ... 9 10 11 ... 20`
206
+ - Page 20: `1 ... 16 17 18 19 20`
207
+
208
+ ## Accessibility
209
+
210
+ - Page buttons have `aria-label` describing page number
211
+ - Current page has `aria-current="page"`
212
+ - Navigation buttons have descriptive `aria-label`
213
+ - All buttons have `role="button"`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-pagination",
3
- "version": "0.99.0",
3
+ "version": "0.100.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -10,8 +10,8 @@
10
10
  "build:native": "PLATFORM=native tsup"
11
11
  },
12
12
  "dependencies": {
13
- "@xsolla/xui-core": "0.99.0",
14
- "@xsolla/xui-primitives-core": "0.99.0"
13
+ "@xsolla/xui-core": "0.100.0",
14
+ "@xsolla/xui-primitives-core": "0.100.0"
15
15
  },
16
16
  "peerDependencies": {
17
17
  "react": ">=16.8.0"