feat(pagination): support custom labels

Author: fabiobiondi

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

@@ -1,3 +1,4 @@
+import CustomButtonLabels from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/customButtonLabels';
 import HidePrevNextButtons from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/hidePrevNextButtons';
 import { JSXNode, component$ } from '@builder.io/qwik';
 import { PreviewCodeExampleTabs } from '../../../_components/preview-code-example/preview-code-example-tabs';
@@ -7,6 +8,7 @@ import Interactive from './examples/interactive';
 import basicCode from './examples/basic?raw';
 import interactiveCode from './examples/interactive?raw';
 import hidePrevNextButtonsCode from './examples/hidePrevNextButtons?raw';
+import customButtonLabelsCode from './examples/customButtonLabels?raw';
 
 export type Example = {
   component: JSXNode;
@@ -27,6 +29,10 @@ export const examples: Record<string, Example> = {
     component: <HidePrevNextButtons />,
     code: hidePrevNextButtonsCode,
   },
+  customButtonLabels: {
+    component: <CustomButtonLabels />,
+    code: customButtonLabelsCode,
+  },
 };
 
 export type ShowExampleProps = {

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

@@ -0,0 +1,20 @@
+import { component$, useSignal } from '@builder.io/qwik';
+import { Pagination } from '@qwik-ui/headless';
+
+export default component$(() => {
+  const selectedPage = useSignal(1);
+  const totalPages = useSignal(10);
+
+  return (
+    <div class="mt-4 flex flex-col gap-6">
+      <Pagination
+        selectedPage={selectedPage.value}
+        totalPages={totalPages.value}
+        onPageChange$={(page) => {
+          selectedPage.value = page;
+        }}
+        customArrowTexts={{ previous: 'LEFT', next: 'RIGHT' }}
+      />
+    </div>
+  );
+});

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

@@ -4,7 +4,7 @@ import { Toggle } from '@qwik-ui/tailwind';
 
 export default component$(() => {
   const selectedPage = useSignal(1);
-  const totalPages = useSignal(10);
+  const totalPages = useSignal(20);
 
   const hideNextButton = useSignal(false);
   const hidePrevButton = useSignal(false);

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

@@ -11,9 +11,9 @@ import {
   statusByComponent,
   ShowExample,
   BackdropCss,
-  BuildingBlocksSnip,
   PageLoadSnip,
-  AnimationSnip
+  AnimationSnip,
+  Basics
 } from './exports';
 
 import testImage from '../../../../../../public/images/test-image.png'
@@ -22,14 +22,89 @@ import testImage from '../../../../../../public/images/test-image.png'
 
 # Pagination
 
+## ✨ Features
+
+- Pagination ranges
+- Custom Arrows
+- Custom Button Labels
+- Support custom styles (default, selected and divider)
+
 ## Interactive Example
 
 <ShowExample example="interactive" />
 
+
+### 🎨 Properties
+  <AnatomyTable
+  propDescriptors={[
+    {
+      name: 'selectedPage',
+      description: 'Current Page Index (start from 1)',
+    },
+    {
+      name: 'totalPages',
+      description: 'The total of available pages',
+    },
+    {
+      name: 'onPageChange$',
+      description: `Emitted when a button is clicked`,
+    },
+    {
+      name: 'siblingCount',
+      description: `set sibling items close to the selected value`,
+    },
+    {
+      name: 'boundaryCount',
+      description: `set adjacent items to the start and end page number`,
+    },
+    {
+      name: 'hidePrevButton',
+      description: `hide the previous button`,
+    },
+    {
+      name: 'hideNextButton',
+      description: `hide the next button`,
+    },
+    {
+      name: 'customArrowTexts',
+      description: `customize the PREVIOUS and NEXT button labels`,
+    },
+    {
+      name: 'gap',
+      description: `set the gap between items`,
+    },
+    {
+      name: 'wrapperClass',
+      description: `(TODO) allow to apply a custom class to the pagination wrapper `,
+    },
+    {
+      name: 'defaultClass',
+      description: `custom class for the pagination item`,
+    },
+    {
+      name: 'selectedClass',
+      description: `custom class for the selected item`,
+    },
+    {
+      name: 'dividerClass',
+      description: `custom class for the divider item`,
+    }
+  ]}
+/>
+
+
+
 ## Basic Example
 
 <ShowExample example="basic" />
 
 ## Hide Next/Prev Buttons
 
 <ShowExample example="hidePrevNextButtons" />
+
+## Custom Button Labels
+
+<ShowExample example="customButtonLabels" />
+
+
+## TODO (Snippet di codice)

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

@@ -4,12 +4,8 @@ import { component$, Slot, useSignal, useTask$, useVisibleTask$ } from '@builder
 
 /**
  * TODO
- * show / hide PREV / NEXT buttons
- * customArrowTexts: { previous: '...', next: '... }
  * disabled: enable/disable paginator
- *
  */
-
 export interface PaginationProps {
   selectedPage: number;
   totalPages: number;
@@ -20,8 +16,9 @@ export interface PaginationProps {
   boundaryCount?: number;
   hidePrevButton?: boolean;
   hideNextButton?: boolean;
+  customArrowTexts?: { previous: string; next: string };
 
-  // styles
+  // styling
   class?: string;
   gap?: number | string;
   defaultClass?: string;
@@ -34,12 +31,16 @@ export const Pagination = component$<PaginationProps>(
     selectedPage,
     totalPages,
     onPageChange$,
-
+    // configuration
     siblingCount = 1,
     boundaryCount = 1,
     hidePrevButton = false,
     hideNextButton = false,
-
+    customArrowTexts: {
+      previous: previousButtonLabel = 'PREV',
+      next: nextButtonLabel = 'NEXT',
+    } = {},
+    // styling
     class: _class,
     gap = '10px',
     defaultClass,
@@ -65,7 +66,7 @@ export const Pagination = component$<PaginationProps>(
         data-testid="pagination"
         style={{ display: 'flex', alignItems: 'center', gap: gap }}
       >
-        {/* PREV BUTTON */}
+        {/* Prev Button */}
         {isPrevButtonVisible() && (
           <button
             type="button"
@@ -78,9 +79,11 @@ export const Pagination = component$<PaginationProps>(
             }}
           >
             <Slot name="prefix" />
-            <span>PREV</span>
+            <span>{previousButtonLabel}</span>
           </button>
         )}
+
+        {/* Button List */}
         {visibleItems.value.map((item: string | number, index: number) => {
           return (
             <span key={index}>
@@ -103,7 +106,7 @@ export const Pagination = component$<PaginationProps>(
           );
         })}
 
-        {/* NEXT BUTTON */}
+        {/* Next Button */}
         {isNextButtonVisible() && (
           <button
             type="button"
@@ -115,7 +118,7 @@ export const Pagination = component$<PaginationProps>(
               }
             }}
           >
-            <span>NEXT</span>
+            <span>{nextButtonLabel}</span>
             <Slot name="suffix" />
           </button>
         )}