Skip to content

Commit f85620c

Browse files
fabiobiondifabiobiondi
committed
docs(pagination): add and fix examples
1 parent fd0965e commit f85620c

File tree

5 files changed

+155
-93
lines changed

5 files changed

+155
-93
lines changed

‎apps/website/src/routes/docs/headless/(components)/pagination/examples.tsx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import CustomButtonLabels from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/customButtonLabels';
22
import HidePrevNextButtons from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/hidePrevNextButtons';
3+
import Styling from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/styling';
34
import { JSXNode, component$ } from '@builder.io/qwik';
45
import { PreviewCodeExampleTabs } from '../../../_components/preview-code-example/preview-code-example-tabs';
56

@@ -9,6 +10,7 @@ import basicCode from './examples/basic?raw';
910
import interactiveCode from './examples/interactive?raw';
1011
import hidePrevNextButtonsCode from './examples/hidePrevNextButtons?raw';
1112
import customButtonLabelsCode from './examples/customButtonLabels?raw';
13+
import stylingCode from './examples/styling?raw';
1214

1315
export type Example = {
1416
component: JSXNode;
@@ -33,6 +35,10 @@ export const examples: Record<string, Example> = {
3335
component: <CustomButtonLabels />,
3436
code: customButtonLabelsCode,
3537
},
38+
styling: {
39+
component: <Styling />,
40+
code: stylingCode,
41+
},
3642
};
3743

3844
export type ShowExampleProps = {

‎apps/website/src/routes/docs/headless/(components)/pagination/examples/interactive.tsx

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,7 @@ export default component$(() => {
2121
onPageChange$={(page) => {
2222
selectedPage.value = page;
2323
}}
24-
defaultClass="border-2 border-sky-400 p-4"
25-
selectedClass="border-2 border-red-500 bg-red-500 p-4"
26-
dividerClass="p-4"
24+
selectedClass="text-sky-500 font-bold px-3"
2725
hidePrevButton={hidePrevButton.value}
2826
hideNextButton={hideNextButton.value}
2927
gap={'10px'}

‎apps/website/src/routes/docs/headless/(components)/pagination/examples/styling.tsx

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { component$, useSignal } from '@builder.io/qwik';
2+
import { Pagination } from '@qwik-ui/headless';
3+
4+
export default component$(() => {
5+
const selectedPage = useSignal(1);
6+
const totalPages = useSignal(10);
7+
8+
return (
9+
<div class="mt-4 flex flex-col gap-6">
10+
<Pagination
11+
selectedPage={selectedPage.value}
12+
totalPages={totalPages.value}
13+
onPageChange$={(page) => {
14+
selectedPage.value = page;
15+
}}
16+
class="border-2 border-white p-2"
17+
defaultClass="border-2 border-sky-400 p-4"
18+
selectedClass="border-2 border-red-500 bg-red-500 p-4"
19+
dividerClass="p-4"
20+
/>
21+
</div>
22+
);
23+
});

‎apps/website/src/routes/docs/headless/(components)/pagination/index.mdx

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,66 +27,87 @@ import testImage from '../../../../../../public/images/test-image.png'
2727
- Pagination ranges
2828
- Custom Arrows
2929
- Custom Button Labels
30-
- Support custom styles (default, selected and divider)
30+
- Fully Customizable
3131

3232
## Interactive Example
3333

3434
<ShowExample example="interactive" />
3535

3636

3737
### 🎨 Properties
38-
<AnatomyTable
38+
39+
40+
## API
41+
42+
The Pagination component API provides a set of properties that allow you to customize the behavior and appearance of the pagination.
43+
44+
Here are the notable properties for this component:
45+
46+
<APITable
3947
propDescriptors={[
4048
{
4149
name: 'selectedPage',
50+
type: 'number',
4251
description: 'Current Page Index (start from 1)',
4352
},
4453
{
4554
name: 'totalPages',
55+
type: 'number',
4656
description: 'The total of available pages',
4757
},
4858
{
4959
name: 'onPageChange$',
60+
type: 'function',
5061
description: `Emitted when a button is clicked`,
5162
},
5263
{
5364
name: 'siblingCount',
65+
type: 'number',
5466
description: `set sibling items close to the selected value`,
5567
},
5668
{
5769
name: 'boundaryCount',
70+
type: 'number',
5871
description: `set adjacent items to the start and end page number`,
5972
},
6073
{
6174
name: 'hidePrevButton',
75+
type: 'boolean',
6276
description: `hide the previous button`,
6377
},
6478
{
6579
name: 'hideNextButton',
80+
type: 'boolean',
6681
description: `hide the next button`,
6782
},
6883
{
6984
name: 'customArrowTexts',
70-
description: `customize the PREVIOUS and NEXT button labels`,
85+
type: 'ArrowLabels',
86+
description: `customize the PREVIOUS and NEXT button labels `,
7187
},
7288
{
7389
name: 'gap',
74-
description: `set the gap between items`,
90+
type: 'string',
91+
description: `set the gap between items (i.e. '10px', '1rem', ...)`,
7592
},
7693
{
77-
name: 'wrapperClass',
78-
description: `(TODO) allow to apply a custom class to the pagination wrapper `,
94+
name: 'class',
95+
type: 'string',
96+
description: `custom class for pagination wrapper `,
7997
},
8098
{
8199
name: 'defaultClass',
82-
description: `custom class for the pagination item`,
100+
type: 'string',
101+
description: `custom class for each pagination item`,
83102
},
84103
{
85104
name: 'selectedClass',
105+
type: 'string',
86106
description: `custom class for the selected item`,
87107
},
88108
{
89109
name: 'dividerClass',
110+
type: 'string',
90111
description: `custom class for the divider item`,
91112
}
92113
]}
@@ -98,6 +119,10 @@ import testImage from '../../../../../../public/images/test-image.png'
98119

99120
<ShowExample example="basic" />
100121

122+
## Styling
123+
124+
<ShowExample example="styling" />
125+
101126
## Hide Next/Prev Buttons
102127

103128
<ShowExample example="hidePrevNextButtons" />
@@ -107,4 +132,3 @@ import testImage from '../../../../../../public/images/test-image.png'
107132
<ShowExample example="customButtonLabels" />
108133

109134

110-
## TODO (Snippet di codice)

‎packages/kit-headless/src/components/pagination/pagination.tsx

Lines changed: 93 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ import { component$, Slot, useSignal, useTask$, useVisibleTask$ } from '@builder
66
* TODO
77
* disabled: enable/disable paginator
88
*/
9+
10+
type ArrowLabels = {
11+
previous: string;
12+
next: string;
13+
};
14+
915
export interface PaginationProps {
1016
selectedPage: number;
1117
totalPages: number;
@@ -16,18 +22,18 @@ export interface PaginationProps {
1622
boundaryCount?: number;
1723
hidePrevButton?: boolean;
1824
hideNextButton?: boolean;
19-
customArrowTexts?: { previous: string; next: string };
25+
customArrowTexts?: ArrowLabels;
2026

2127
// styling
2228
class?: string;
23-
gap?: number | string;
29+
gap?: string;
2430
defaultClass?: string;
2531
selectedClass?: string;
2632
dividerClass?: string;
2733
}
2834

29-
export const Pagination = component$<PaginationProps>(
30-
({
35+
export const Pagination = component$<PaginationProps>((props) => {
36+
const {
3137
selectedPage,
3238
totalPages,
3339
onPageChange$,
@@ -46,87 +52,92 @@ export const Pagination = component$<PaginationProps>(
4652
defaultClass,
4753
selectedClass,
4854
dividerClass,
49-
}) => {
50-
const visibleItems = useSignal<(string | number)[]>([]);
55+
} = props;
5156

52-
useTask$(({ track }) => {
53-
track(() => [selectedPage, totalPages, siblingCount, boundaryCount]);
57+
const visibleItems = useSignal<(string | number)[]>([]);
58+
const isPrevButtonVisible = () => !hidePrevButton && selectedPage > 1;
59+
const isNextButtonVisible = () => !hideNextButton && selectedPage !== totalPages;
5460

55-
visibleItems.value = usePagination(
56-
totalPages,
57-
selectedPage,
58-
siblingCount,
59-
boundaryCount,
60-
);
61-
});
61+
useTask$(({ track }) => {
62+
track(() => [
63+
props.selectedPage,
64+
props.totalPages,
65+
props.siblingCount,
66+
props.boundaryCount,
67+
]);
6268

63-
const isPrevButtonVisible = () => !hidePrevButton && selectedPage > 1;
64-
const isNextButtonVisible = () => !hideNextButton && selectedPage !== totalPages;
69+
visibleItems.value = usePagination(
70+
props.totalPages,
71+
props.selectedPage,
72+
props.siblingCount,
73+
props.boundaryCount,
74+
);
75+
});
6576

66-
return (
67-
<nav
68-
role="navigation"
69-
aria-label="pagination"
70-
data-testid="pagination"
71-
style={{ display: 'flex', alignItems: 'center', gap: gap }}
72-
>
73-
{/* Prev Button */}
74-
{isPrevButtonVisible() && (
75-
<button
76-
type="button"
77-
aria-label={'prevAriaLabel'}
78-
disabled={selectedPage <= 1}
79-
onClick$={() => {
80-
if (selectedPage > 1) {
81-
onPageChange$(selectedPage - 1);
82-
}
83-
}}
84-
>
85-
<Slot name="prefix" />
86-
<span>{previousButtonLabel}</span>
87-
</button>
88-
)}
77+
return (
78+
<nav
79+
role="navigation"
80+
aria-label="pagination"
81+
data-testid="pagination"
82+
class={_class}
83+
style={{ display: 'flex', alignItems: 'center', gap: gap }}
84+
>
85+
{/* Prev Button */}
86+
{isPrevButtonVisible() && (
87+
<button
88+
type="button"
89+
aria-label={'prevAriaLabel'}
90+
disabled={selectedPage <= 1}
91+
onClick$={() => {
92+
if (selectedPage > 1) {
93+
onPageChange$(selectedPage - 1);
94+
}
95+
}}
96+
>
97+
<Slot name="prefix" />
98+
<span>{previousButtonLabel}</span>
99+
</button>
100+
)}
89101

90-
{/* Button List */}
91-
{visibleItems.value.map((item: string | number, index: number) => {
92-
return (
93-
<span key={index}>
94-
{typeof item === 'string' ? (
95-
<button class={dividerClass}>...</button>
96-
) : (
97-
<button
98-
class={[selectedPage === item ? selectedClass : defaultClass]}
99-
type="button"
100-
aria-label={`Page ${item} of ${totalPages}`}
101-
aria-current={selectedPage === item}
102-
onClick$={() => {
103-
onPageChange$(item);
104-
}}
105-
>
106-
{item}
107-
</button>
108-
)}
109-
</span>
110-
);
111-
})}
102+
{/* Button List */}
103+
{visibleItems.value.map((item: string | number, index: number) => {
104+
return (
105+
<span key={index}>
106+
{typeof item === 'string' ? (
107+
<button class={dividerClass}>...</button>
108+
) : (
109+
<button
110+
class={[selectedPage === item ? selectedClass : defaultClass]}
111+
type="button"
112+
aria-label={`Page ${item} of ${totalPages}`}
113+
aria-current={selectedPage === item}
114+
onClick$={() => {
115+
onPageChange$(item);
116+
}}
117+
>
118+
{item}
119+
</button>
120+
)}
121+
</span>
122+
);
123+
})}
112124

113-
{/* Next Button */}
114-
{isNextButtonVisible() && (
115-
<button
116-
type="button"
117-
aria-label={'nextAriaLabel'}
118-
disabled={selectedPage >= totalPages}
119-
onClick$={() => {
120-
if (selectedPage < totalPages) {
121-
onPageChange$(selectedPage + 1);
122-
}
123-
}}
124-
>
125-
<span>{nextButtonLabel}</span>
126-
<Slot name="suffix" />
127-
</button>
128-
)}
129-
</nav>
130-
);
131-
},
132-
);
125+
{/* Next Button */}
126+
{isNextButtonVisible() && (
127+
<button
128+
type="button"
129+
aria-label={'nextAriaLabel'}
130+
disabled={selectedPage >= totalPages}
131+
onClick$={() => {
132+
if (selectedPage < totalPages) {
133+
onPageChange$(selectedPage + 1);
134+
}
135+
}}
136+
>
137+
<span>{nextButtonLabel}</span>
138+
<Slot name="suffix" />
139+
</button>
140+
)}
141+
</nav>
142+
);
143+
});

0 commit comments

Comments
 (0)