From 2046abb27e1b6a0492cf6915bb308a3755a483ae Mon Sep 17 00:00:00 2001
From: Jessen Reinhart <jessen_1206@yahoo.com>
Date: Mon, 29 Jun 2026 17:30:59 +0700
Subject: [PATCH 1/3] fix(Pagination): fix broken rendering for single-page
 pagination

Resolves #1048: Pagination component was incorrectly hiding the '1' button
when totalPages=1 due to a hardcoded clamping logic.
---
 .../components/Pagination/Pagination.test.tsx |  6 ++++
 .../src/components/Pagination/Pagination.tsx  | 32 +++++++++++++------
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.test.tsx b/packages/ui/src/components/Pagination/Pagination.test.tsx
index 8367cd51c..1bbe43e7a 100644
--- a/packages/ui/src/components/Pagination/Pagination.test.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.test.tsx
@@ -176,6 +176,12 @@ describe("Pagination", () => {
 
       expect(pages()).toHaveLength(0);
     });
+    it("should render page 1 when totalPages is 1", () => {
+      render(<Pagination currentPage={1} totalPages={1} onPageChange={() => undefined} />);
+      expect(pages()).toHaveLength(1);
+      expect(pages()[0]).toBe(1);
+    });
+
 
     it("should change previous and next text when provided", () => {
       render(
diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index a4fd4c9ee..7f998a3ba 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -102,6 +102,7 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
 
   const lastPage = Math.min(Math.max(layout === "pagination" ? currentPage + 2 : currentPage + 4, 5), totalPages);
   const firstPage = Math.max(1, lastPage - 4);
+  const lastPageInRange = Math.max(lastPage, firstPage);
 
   function goToNextPage() {
     onPageChange(Math.min(currentPage + 1, totalPages));
@@ -125,16 +126,27 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
           </PaginationNavigation>
         </li>
         {layout === "pagination" &&
-          range(firstPage, lastPage).map((page: number) => (
-            <li aria-current={page === currentPage ? "page" : undefined} key={page}>
-              {renderPaginationButton({
-                className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
-                active: page === currentPage,
-                onClick: () => onPageChange(page),
-                children: page,
-              })}
-            </li>
-          ))}
+          (totalPages <= 5
+            ? Array.from({ length: totalPages }, (_, i) => i + 1).map((page: number) => (
+                <li aria-current={page === currentPage ? "page" : undefined} key={page}>
+                  {renderPaginationButton({
+                    className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
+                    active: page === currentPage,
+                    onClick: () => onPageChange(page),
+                    children: page,
+                  })}
+                </li>
+              ))
+            : range(firstPage, lastPageInRange).map((page: number) => (
+                <li aria-current={page === currentPage ? "page" : undefined} key={page}>
+                  {renderPaginationButton({
+                    className: twMerge(theme.pages.selector.base, currentPage === page && theme.pages.selector.active),
+                    active: page === currentPage,
+                    onClick: () => onPageChange(page),
+                    children: page,
+                  })}
+                </li>
+              )))}
         <li>
           <PaginationNavigation
             className={twMerge(theme.pages.next.base, showIcon && theme.pages.showIcon)}

From f16b1dd2778c8882c39c42e0e1305c07764c9484 Mon Sep 17 00:00:00 2001
From: Jessen Reinhart <jessen_1206@yahoo.com>
Date: Mon, 29 Jun 2026 17:44:00 +0700
Subject: [PATCH 2/3] fix(Pagination): add JSDoc for docstring coverage

- Add JSDoc to DefaultPagination and TablePagination components
- Resolves CI docstring coverage warning
---
 packages/ui/src/components/Pagination/Pagination.tsx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index 7f998a3ba..ee2b1efbe 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -71,6 +71,12 @@ export const Pagination = forwardRef<HTMLElement, PaginationProps>((props, ref)
   return <DefaultPagination {...props} ref={ref} />;
 });
 
+/**
+ * Default pagination component.
+ * @param props - Pagination props (currentPage, totalPages, layout, etc.)
+ * @param ref - Ref to the nav element.
+ * @returns The rendered navigation component.
+ */
 const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props, ref) => {
   const provider = useThemeProvider();
   const theme = useResolveTheme(
@@ -162,6 +168,12 @@ const DefaultPagination = forwardRef<HTMLElement, DefaultPaginationProps>((props
   );
 });
 
+/**
+ * Table pagination component.
+ * @param props - Pagination props (currentPage, itemsPerPage, totalItems, etc.)
+ * @param ref - Ref to the nav element.
+ * @returns The rendered navigation component.
+ */
 const TablePagination = forwardRef<HTMLElement, TablePaginationProps>((props, ref) => {
   const provider = useThemeProvider();
   const theme = useResolveTheme(

From 9be842f8198db7315faab22e665e1f4dc59bcaf2 Mon Sep 17 00:00:00 2001
From: Jessen Reinhart <jessen_1206@yahoo.com>
Date: Tue, 30 Jun 2026 09:06:15 +0700
Subject: [PATCH 3/3] fix(Pagination): add JSDoc to main export for docstring
 coverage

---
 packages/ui/src/components/Pagination/Pagination.test.tsx | 1 -
 packages/ui/src/components/Pagination/Pagination.tsx      | 7 +++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/Pagination/Pagination.test.tsx b/packages/ui/src/components/Pagination/Pagination.test.tsx
index 1bbe43e7a..5f6e2d27a 100644
--- a/packages/ui/src/components/Pagination/Pagination.test.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.test.tsx
@@ -182,7 +182,6 @@ describe("Pagination", () => {
       expect(pages()[0]).toBe(1);
     });
 
-
     it("should change previous and next text when provided", () => {
       render(
         <Pagination
diff --git a/packages/ui/src/components/Pagination/Pagination.tsx b/packages/ui/src/components/Pagination/Pagination.tsx
index ee2b1efbe..eb573573b 100644
--- a/packages/ui/src/components/Pagination/Pagination.tsx
+++ b/packages/ui/src/components/Pagination/Pagination.tsx
@@ -66,6 +66,13 @@ export interface TablePaginationProps extends BasePaginationProps {
 
 export type PaginationProps = DefaultPaginationProps | TablePaginationProps;
 
+/**
+ * Top-level Pagination component. Switches between Default and Table variants
+ * based on the `layout` prop.
+ * @param props - Discriminated union of DefaultPaginationProps and TablePaginationProps.
+ * @param ref - Ref forwarded to the underlying nav element.
+ * @returns The rendered pagination navigation.
+ */
 export const Pagination = forwardRef<HTMLElement, PaginationProps>((props, ref) => {
   if (props.layout === "table") return <TablePagination {...props} ref={ref} />;
   return <DefaultPagination {...props} ref={ref} />;