feat(pagination): add disable feature and improve doc

Author: fabiobiondi

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

@@ -1,16 +1,20 @@
-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 Styling from '@/apps/website/src/routes/docs/headless/(components)/pagination/examples/styling';
+import CustomArrows from './examples/custom-arrows';
+import CustomButtonLabels from './examples/custom-button-labels';
+import Disabled from './examples/disabled';
+import HidePrevNextButtons from './examples/hide-prev-next-buttons';
+import Styling from './examples/styling';
 import { JSXNode, component$ } from '@builder.io/qwik';
 import { PreviewCodeExampleTabs } from '../../../_components/preview-code-example/preview-code-example-tabs';
 
 import Basic from './examples/basic';
 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';
+import hidePrevNextButtonsCode from './examples/hide-prev-next-buttons?raw';
+import customButtonLabelsCode from './examples/custom-button-labels?raw';
 import stylingCode from './examples/styling?raw';
+import customArrowsCode from './examples/custom-arrows?raw';
+import disabledCode from './examples/disabled?raw';
 
 export type Example = {
   component: JSXNode;
@@ -39,6 +43,14 @@ export const examples: Record<string, Example> = {
     component: <Styling />,
     code: stylingCode,
   },
+  customArrows: {
+    component: <CustomArrows />,
+    code: customArrowsCode,
+  },
+  disabled: {
+    component: <Disabled />,
+    code: disabledCode,
+  },
 };
 
 export type ShowExampleProps = {

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

@@ -0,0 +1,22 @@
+import { component$, useSignal } from '@builder.io/qwik';
+import { Pagination } from '@qwik-ui/headless';
+
+export default component$(() => {
+  const selectedPage = useSignal(5);
+  const totalPages = useSignal(20);
+
+  return (
+    <div class="mt-4 flex flex-col gap-6">
+      <Pagination
+        selectedPage={selectedPage.value}
+        totalPages={totalPages.value}
+        onPageChange$={(page) => {
+          selectedPage.value = page;
+        }}
+      >
+        <span q:slot="prefix"> 👈 </span>
+        <span q:slot="suffix"> 👉 </span>
+      </Pagination>
+    </div>
+  );
+});

apps/website/src/routes/docs/headless/(components)/pagination/examples/customButtonLabels.tsx renamed to apps/website/src/routes/docs/headless/(components)/pagination/examples/custom-button-labels.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}
+        disabled
+        onPageChange$={(page) => {
+          selectedPage.value = page;
+        }}
+      />
+    </div>
+  );
+});

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

@@ -3,7 +3,7 @@ import { Pagination } from '@qwik-ui/headless';
 import { Toggle } from '@qwik-ui/tailwind';
 
 export default component$(() => {
-  const selectedPage = useSignal(1);
+  const selectedPage = useSignal(5);
   const totalPages = useSignal(20);
 
   const hideNextButton = useSignal(false);
@@ -25,10 +25,9 @@ export default component$(() => {
         hidePrevButton={hidePrevButton.value}
         hideNextButton={hideNextButton.value}
         gap={'10px'}
-      >
-        <span q:slot="prefix">👈</span>
-        <span q:slot="suffix">👉</span>
-      </Pagination>
+      />
+
+      <hr />
 
       <div
         class="flex flex-col items-stretch gap-2"

apps/website/src/routes/docs/headless/(components)/pagination/examples/hidePrevNextButtons.tsx renamed to apps/website/src/routes/docs/headless/(components)/pagination/examples/hide-prev-next-buttons.tsx

@@ -34,7 +34,6 @@ import testImage from '../../../../../../public/images/test-image.png'
 <ShowExample example="interactive" />
 
 
-### 🎨 Properties
 
 
 ## API
@@ -80,6 +79,11 @@ Here are the notable properties for this component:
       type: 'boolean',
       description: `hide the next button`,
     },
+    {
+      name: 'disabled',
+      type: 'boolean',
+      description: `disable mouse events`,
+    },
     {
       name: 'customArrowTexts',
       type: 'ArrowLabels',
@@ -123,12 +127,23 @@ Here are the notable properties for this component:
 
 <ShowExample example="styling" />
 
+## Custom Button Labels
+
+<ShowExample example="customButtonLabels" />
+
+
+## Custom Arrows
+
+<ShowExample example="customArrows" />
+
+
 ## Hide Next/Prev Buttons
 
 <ShowExample example="hidePrevNextButtons" />
 
-## Custom Button Labels
 
-<ShowExample example="customButtonLabels" />
+## Disabled
+
+<ShowExample example="disabled" />
 
 

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

@@ -22,6 +22,7 @@ export interface PaginationProps {
   boundaryCount?: number;
   hidePrevButton?: boolean;
   hideNextButton?: boolean;
+  disabled?: boolean;
   customArrowTexts?: ArrowLabels;
 
   // styling
@@ -38,10 +39,9 @@ export const Pagination = component$<PaginationProps>((props) => {
     totalPages,
     onPageChange$,
     // configuration
-    siblingCount = 1,
-    boundaryCount = 1,
     hidePrevButton = false,
     hideNextButton = false,
+    disabled = false,
     customArrowTexts: {
       previous: previousButtonLabel = 'PREV',
       next: nextButtonLabel = 'NEXT',
@@ -69,8 +69,8 @@ export const Pagination = component$<PaginationProps>((props) => {
     visibleItems.value = usePagination(
       props.totalPages,
       props.selectedPage,
-      props.siblingCount,
-      props.boundaryCount,
+      props.siblingCount || 1,
+      props.boundaryCount || 1,
     );
   });
 
@@ -80,7 +80,12 @@ export const Pagination = component$<PaginationProps>((props) => {
       aria-label="pagination"
       data-testid="pagination"
       class={_class}
-      style={{ display: 'flex', alignItems: 'center', gap: gap }}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap,
+        pointerEvents: disabled ? 'none' : 'inherit',
+      }}
     >
       {/* Prev Button */}
       {isPrevButtonVisible() && (