@adamosuiteservices/ui 2.11.16 → 2.11.18

package/docs/components/ui/pagination.md

@@ -1,650 +1,650 @@
-# Pagination
-
-Controles de navegación para contenido paginado. Incluye Previous/Next, números de página, ellipsis para gaps y estado activo.
-
-## Descripción
-
-El componente `Pagination` proporciona controles de navegación para contenido paginado.
-
-## Importación
-
-```typescript
-import {
-  Pagination,
-  PaginationContent,
-  PaginationEllipsis,
-  PaginationItem,
-  PaginationLink,
-  PaginationNext,
-  PaginationPrevious,
-} from "@adamosuiteservices/ui/pagination";
-```
-
-## Anatomía
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        2
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-**Componentes**: 7 (Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis)
-
-## Props Principales
-
-### Pagination (Root)
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Nota**: `<nav>` con `role="navigation"` y `aria-label="pagination"`
-
-### PaginationContent
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Nota**: `<ul>` con flex y gap-1
-
-### PaginationItem
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Nota**: `<li>` wrapper simple
-
-### PaginationLink
-
-| Prop        | Tipo          | Default  | Descripción              |
-| ----------- | ------------- | -------- | ------------------------ |
-| `isActive`  | `boolean`     | `false`  | Marca página como activa |
-| `size`      | Button size   | `"icon"` | Tamaño del link          |
-| `href`      | `string`      | -        | URL destino              |
-| `onClick`   | `(e) => void` | -        | Click handler            |
-| `className` | `string`      | -        | Clases CSS adicionales   |
-
-**Nota**: `<a>` estilizado como Button
-
-### PaginationPrevious
-
-| Prop        | Tipo          | Default      | Descripción            |
-| ----------- | ------------- | ------------ | ---------------------- |
-| `children`  | `ReactNode`   | `"Previous"` | Texto del botón        |
-| `href`      | `string`      | -            | URL destino            |
-| `onClick`   | `(e) => void` | -            | Click handler          |
-| `className` | `string`      | -            | Clases CSS adicionales |
-
-**Nota**: PaginationLink con chevron_left icon (Material Symbol), texto "Previous" oculto en mobile
-
-### PaginationNext
-
-| Prop        | Tipo          | Default  | Descripción            |
-| ----------- | ------------- | -------- | ---------------------- |
-| `children`  | `ReactNode`   | `"Next"` | Texto del botón        |
-| `href`      | `string`      | -        | URL destino            |
-| `onClick`   | `(e) => void` | -        | Click handler          |
-| `className` | `string`      | -        | Clases CSS adicionales |
-
-**Nota**: PaginationLink con chevron_right icon (Material Symbol), texto "Next" oculto en mobile
-
-### PaginationEllipsis
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Nota**: `<span>` con more_horiz icon (Material Symbol) y `aria-hidden`
-
-## Patrones de Uso
-
-### Básico
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        2
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Simple (Sin Ellipsis)
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">2</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Con Ellipsis Doble
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">10</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        11
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">12</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">50</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Primera Página (Disabled Previous)
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" className="pointer-events-none opacity-50" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        1
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">2</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">25</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Última Página (Disabled Next)
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">23</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#">24</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        25
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" className="pointer-events-none opacity-50" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Página Única
-
-```tsx
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" className="pointer-events-none opacity-50" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive>
-        1
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" className="pointer-events-none opacity-50" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Compacto (Solo Previous/Next)
-
-```tsx
-<Pagination className="justify-start">
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious href="#" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>
-```
-
-### Con Información de Página
-
-```tsx
-<div className="space-y-4">
-  <div className="flex items-center justify-between text-sm text-muted-foreground">
-    <span>Showing 1-10 of 250 results</span>
-    <span>Page 2 of 25</span>
-  </div>
-
-  <Pagination>
-    <PaginationContent>
-      <PaginationItem>
-        <PaginationPrevious href="#" />
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationLink href="#">1</PaginationLink>
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationLink href="#" isActive>
-          2
-        </PaginationLink>
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationLink href="#">3</PaginationLink>
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationEllipsis />
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationLink href="#">25</PaginationLink>
-      </PaginationItem>
-      <PaginationItem>
-        <PaginationNext href="#" />
-      </PaginationItem>
-    </PaginationContent>
-  </Pagination>
-</div>
-```
-
-### Interactivo (Con Estado)
-
-```tsx
-import { useState } from "react";
-
-function App() {
-  const [currentPage, setCurrentPage] = useState(5);
-  const totalPages = 20;
-
-  const generatePageNumbers = () => {
-    const pages = [];
-
-    // Always show first page
-    pages.push(1);
-
-    // Add ellipsis if there's a gap
-    if (currentPage > 4) {
-      pages.push(-1); // -1 represents ellipsis
-    }
-
-    // Show pages around current page
-    const start = Math.max(2, currentPage - 1);
-    const end = Math.min(totalPages - 1, currentPage + 1);
-
-    for (let i = start; i <= end; i++) {
-      if (i !== 1 && i !== totalPages) {
-        pages.push(i);
-      }
-    }
-
-    // Add ellipsis if there's a gap
-    if (currentPage < totalPages - 3) {
-      pages.push(-2); // -2 represents ellipsis
-    }
-
-    // Always show last page if more than 1 page
-    if (totalPages > 1) {
-      pages.push(totalPages);
-    }
-
-    return pages;
-  };
-
-  const pages = generatePageNumbers();
-
-  const handlePageClick = (page: number) => {
-    setCurrentPage(page);
-  };
-
-  const handlePrevious = () => {
-    if (currentPage > 1) {
-      setCurrentPage(currentPage - 1);
-    }
-  };
-
-  const handleNext = () => {
-    if (currentPage < totalPages) {
-      setCurrentPage(currentPage + 1);
-    }
-  };
-
-  return (
-    <div className="space-y-4">
-      <p className="text-center text-sm text-muted-foreground">
-        Page {currentPage} of {totalPages}
-      </p>
-
-      <Pagination>
-        <PaginationContent>
-          <PaginationItem>
-            <PaginationPrevious
-              href="#"
-              onClick={(e) => {
-                e.preventDefault();
-                handlePrevious();
-              }}
-              className={
-                currentPage === 1 ? "pointer-events-none opacity-50" : ""
-              }
-            />
-          </PaginationItem>
-
-          {pages.map((page, index) => (
-            <PaginationItem key={index}>
-              {page < 0 ? (
-                <PaginationEllipsis />
-              ) : (
-                <PaginationLink
-                  href="#"
-                  isActive={page === currentPage}
-                  onClick={(e) => {
-                    e.preventDefault();
-                    handlePageClick(page);
-                  }}
-                >
-                  {page}
-                </PaginationLink>
-              )}
-            </PaginationItem>
-          ))}
-
-          <PaginationItem>
-            <PaginationNext
-              href="#"
-              onClick={(e) => {
-                e.preventDefault();
-                handleNext();
-              }}
-              className={
-                currentPage === totalPages
-                  ? "pointer-events-none opacity-50"
-                  : ""
-              }
-            />
-          </PaginationItem>
-        </PaginationContent>
-      </Pagination>
-    </div>
-  );
-}
-```
-
-### Tamaños Personalizados
-
-```tsx
-{
-  /* Small */
-}
-<Pagination>
-  <PaginationContent className="gap-0.5">
-    <PaginationItem>
-      <PaginationPrevious href="#" className="h-8 px-2 text-xs" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" className="h-8 w-8 text-xs">
-        1
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive className="h-8 w-8 text-xs">
-        2
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" className="h-8 px-2 text-xs" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>;
-
-{
-  /* Large */
-}
-<Pagination>
-  <PaginationContent className="gap-2">
-    <PaginationItem>
-      <PaginationPrevious href="#" className="h-12 px-4 text-base" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" className="h-12 w-12 text-base">
-        1
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink href="#" isActive className="h-12 w-12 text-base">
-        2
-      </PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext href="#" className="h-12 px-4 text-base" />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>;
-```
-
-## Casos de Uso Comunes
-
-**Tables**: Paginación de tablas con muchas filas  
-**Lists**: Listas largas de items (productos, usuarios, posts)  
-**Search results**: Resultados de búsqueda paginados  
-**Galleries**: Galerías de imágenes o archivos  
-**Admin panels**: Dashboards con data paginada  
-**API results**: Navegación de resultados de API con offset/limit
-
-## Estados y Data Attributes
-
-### PaginationLink
-
-- **Active**: `isActive` → variant outline, `aria-current="page"`
-- **Inactive**: variant ghost
-
-### Disabled (Previous/Next)
-
-No hay prop disabled nativa, se simula con:
-
-```tsx
-className = "pointer-events-none opacity-50";
-```
-
-## Estilos Base
-
-### Pagination (Root)
-
-- **Layout**: `mx-auto flex w-full justify-center`
-- **Semantic**: `<nav role="navigation" aria-label="pagination">`
-
-### PaginationContent
-
-- **Layout**: `flex flex-row items-center gap-1`
-
-### PaginationLink
-
-- **Size default**: `size="icon"` (h-9 w-9)
-- **Variants**: ghost (inactive), outline (active)
-
-### PaginationPrevious/Next
-
-- **Size**: `size="default"`
-- **Padding**: `px-2.5`
-- **Responsive**: Texto oculto en mobile (`hidden sm:block`)
-- **Gap**: `gap-1` entre icono y texto
-
-### PaginationEllipsis
-
-- **Size**: `size-9`
-- **Icon**: more_horiz (Material Symbol) con `text-lg`
-- **Layout**: `flex items-center justify-center`
-- **ARIA**: `aria-hidden`
-
-## Responsive
-
-- **Mobile**: Previous/Next solo muestran icono
-- **Desktop (sm+)**: Previous/Next muestran icono + texto
-
-## Accesibilidad
-
-- ✅ **Semantic**: `<nav role="navigation" aria-label="pagination">`
-- ✅ **Current page**: `aria-current="page"` en página activa
-- ✅ **Screen readers**: Ellipsis tiene `<span className="sr-only">More pages</span>`
-- ✅ **Keyboard**: Navegación con Tab, activación con Enter/Space
-- ✅ **Labels**: Previous/Next tienen `aria-label` descriptivo
-- ⚠️ **Disabled**: Usa `pointer-events-none opacity-50` + previene click en handler
-
-## Notas de Implementación
-
-- **Links**: PaginationLink es `<a>` no `<button>`, usa Button styles
-- **Icons**: chevron_left, chevron_right, more_horiz (Material Symbols)
-- **Responsive text**: Previous/Next usan `hidden sm:block` en texto
-- **No state**: Componente stateless, maneja estado externamente
-- **Ellipsis logic**: Representación negativa (-1, -2) común para identificar ellipsis
-- **Disabled**: No hay prop disabled, usa className manual
-- **Centering**: Root tiene `mx-auto justify-center`
-
-## Algoritmo de Generación de Páginas
-
-Patrón común para mostrar páginas con ellipsis:
-
-```tsx
-const generatePageNumbers = (current: number, total: number) => {
-  const pages = [];
-
-  // Siempre primera página
-  pages.push(1);
-
-  // Ellipsis izquierda si hay gap
-  if (current > 4) pages.push(-1);
-
-  // Páginas alrededor de current
-  const start = Math.max(2, current - 1);
-  const end = Math.min(total - 1, current + 1);
-  for (let i = start; i <= end; i++) {
-    if (i !== 1 && i !== total) pages.push(i);
-  }
-
-  // Ellipsis derecha si hay gap
-  if (current < total - 3) pages.push(-2);
-
-  // Siempre última página
-  if (total > 1) pages.push(total);
-
-  return pages;
-};
-```
-
-## Troubleshooting
-
-**Previous/Next no se deshabilitan**: No hay prop disabled, usa `className="pointer-events-none opacity-50"` y previene click en handler  
-**Active no se ve**: Verifica `isActive` prop y que solo una página lo tenga  
-**Texto Previous/Next no se ve en mobile**: Comportamiento esperado, usa `hidden sm:block`  
-**Ellipsis clickeable**: Ellipsis no debe ser clickeable, es `<span>` no link  
-**Spacing inconsistente**: PaginationContent tiene `gap-1`, ajusta con className  
-**No centrado**: Root tiene `justify-center`, override con `className="justify-start"` si necesario  
-**Links no funcionan**: PaginationLink usa `<a>`, asegúrate de pasar `href` o `onClick`  
-**Too many pages**: Usa ellipsis y lógica de generación de páginas para mostrar subset
-
-## Referencias
-
-- **shadcn/ui Pagination**: <https://ui.shadcn.com/docs/components/pagination>
-- **WAI-ARIA Pagination**: <https://www.w3.org/WAI/ARIA/apg/patterns/pagination/>
+# Pagination
+
+Controles de navegación para contenido paginado. Incluye Previous/Next, números de página, ellipsis para gaps y estado activo.
+
+## Descripción
+
+El componente `Pagination` proporciona controles de navegación para contenido paginado.
+
+## Importación
+
+```typescript
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@adamosuiteservices/ui/pagination";
+```
+
+## Anatomía
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">3</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+**Componentes**: 7 (Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis)
+
+## Props Principales
+
+### Pagination (Root)
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Nota**: `<nav>` con `role="navigation"` y `aria-label="pagination"`
+
+### PaginationContent
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Nota**: `<ul>` con flex y gap-1
+
+### PaginationItem
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Nota**: `<li>` wrapper simple
+
+### PaginationLink
+
+| Prop        | Tipo          | Default  | Descripción              |
+| ----------- | ------------- | -------- | ------------------------ |
+| `isActive`  | `boolean`     | `false`  | Marca página como activa |
+| `size`      | Button size   | `"icon"` | Tamaño del link          |
+| `href`      | `string`      | -        | URL destino              |
+| `onClick`   | `(e) => void` | -        | Click handler            |
+| `className` | `string`      | -        | Clases CSS adicionales   |
+
+**Nota**: `<a>` estilizado como Button
+
+### PaginationPrevious
+
+| Prop        | Tipo          | Default      | Descripción            |
+| ----------- | ------------- | ------------ | ---------------------- |
+| `children`  | `ReactNode`   | `"Previous"` | Texto del botón        |
+| `href`      | `string`      | -            | URL destino            |
+| `onClick`   | `(e) => void` | -            | Click handler          |
+| `className` | `string`      | -            | Clases CSS adicionales |
+
+**Nota**: PaginationLink con chevron_left icon (Material Symbol), texto "Previous" oculto en mobile
+
+### PaginationNext
+
+| Prop        | Tipo          | Default  | Descripción            |
+| ----------- | ------------- | -------- | ---------------------- |
+| `children`  | `ReactNode`   | `"Next"` | Texto del botón        |
+| `href`      | `string`      | -        | URL destino            |
+| `onClick`   | `(e) => void` | -        | Click handler          |
+| `className` | `string`      | -        | Clases CSS adicionales |
+
+**Nota**: PaginationLink con chevron_right icon (Material Symbol), texto "Next" oculto en mobile
+
+### PaginationEllipsis
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Nota**: `<span>` con more_horiz icon (Material Symbol) y `aria-hidden`
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">3</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Simple (Sin Ellipsis)
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">2</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">3</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Con Ellipsis Doble
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">10</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        11
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">12</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">50</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Primera Página (Disabled Previous)
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" className="pointer-events-none opacity-50" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        1
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">2</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">3</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">25</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Última Página (Disabled Next)
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">23</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">24</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        25
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" className="pointer-events-none opacity-50" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Página Única
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" className="pointer-events-none opacity-50" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        1
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" className="pointer-events-none opacity-50" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Compacto (Solo Previous/Next)
+
+```tsx
+<Pagination className="justify-start">
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+### Con Información de Página
+
+```tsx
+<div className="space-y-4">
+  <div className="flex items-center justify-between text-sm text-muted-foreground">
+    <span>Showing 1-10 of 250 results</span>
+    <span>Page 2 of 25</span>
+  </div>
+
+  <Pagination>
+    <PaginationContent>
+      <PaginationItem>
+        <PaginationPrevious href="#" />
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationLink href="#">1</PaginationLink>
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationLink href="#" isActive>
+          2
+        </PaginationLink>
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationLink href="#">3</PaginationLink>
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationEllipsis />
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationLink href="#">25</PaginationLink>
+      </PaginationItem>
+      <PaginationItem>
+        <PaginationNext href="#" />
+      </PaginationItem>
+    </PaginationContent>
+  </Pagination>
+</div>
+```
+
+### Interactivo (Con Estado)
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [currentPage, setCurrentPage] = useState(5);
+  const totalPages = 20;
+
+  const generatePageNumbers = () => {
+    const pages = [];
+
+    // Always show first page
+    pages.push(1);
+
+    // Add ellipsis if there's a gap
+    if (currentPage > 4) {
+      pages.push(-1); // -1 represents ellipsis
+    }
+
+    // Show pages around current page
+    const start = Math.max(2, currentPage - 1);
+    const end = Math.min(totalPages - 1, currentPage + 1);
+
+    for (let i = start; i <= end; i++) {
+      if (i !== 1 && i !== totalPages) {
+        pages.push(i);
+      }
+    }
+
+    // Add ellipsis if there's a gap
+    if (currentPage < totalPages - 3) {
+      pages.push(-2); // -2 represents ellipsis
+    }
+
+    // Always show last page if more than 1 page
+    if (totalPages > 1) {
+      pages.push(totalPages);
+    }
+
+    return pages;
+  };
+
+  const pages = generatePageNumbers();
+
+  const handlePageClick = (page: number) => {
+    setCurrentPage(page);
+  };
+
+  const handlePrevious = () => {
+    if (currentPage > 1) {
+      setCurrentPage(currentPage - 1);
+    }
+  };
+
+  const handleNext = () => {
+    if (currentPage < totalPages) {
+      setCurrentPage(currentPage + 1);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <p className="text-center text-sm text-muted-foreground">
+        Page {currentPage} of {totalPages}
+      </p>
+
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious
+              href="#"
+              onClick={(e) => {
+                e.preventDefault();
+                handlePrevious();
+              }}
+              className={
+                currentPage === 1 ? "pointer-events-none opacity-50" : ""
+              }
+            />
+          </PaginationItem>
+
+          {pages.map((page, index) => (
+            <PaginationItem key={index}>
+              {page < 0 ? (
+                <PaginationEllipsis />
+              ) : (
+                <PaginationLink
+                  href="#"
+                  isActive={page === currentPage}
+                  onClick={(e) => {
+                    e.preventDefault();
+                    handlePageClick(page);
+                  }}
+                >
+                  {page}
+                </PaginationLink>
+              )}
+            </PaginationItem>
+          ))}
+
+          <PaginationItem>
+            <PaginationNext
+              href="#"
+              onClick={(e) => {
+                e.preventDefault();
+                handleNext();
+              }}
+              className={
+                currentPage === totalPages
+                  ? "pointer-events-none opacity-50"
+                  : ""
+              }
+            />
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+}
+```
+
+### Tamaños Personalizados
+
+```tsx
+{
+  /* Small */
+}
+<Pagination>
+  <PaginationContent className="gap-0.5">
+    <PaginationItem>
+      <PaginationPrevious href="#" className="h-8 px-2 text-xs" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" className="h-8 w-8 text-xs">
+        1
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive className="h-8 w-8 text-xs">
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" className="h-8 px-2 text-xs" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>;
+
+{
+  /* Large */
+}
+<Pagination>
+  <PaginationContent className="gap-2">
+    <PaginationItem>
+      <PaginationPrevious href="#" className="h-12 px-4 text-base" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" className="h-12 w-12 text-base">
+        1
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive className="h-12 w-12 text-base">
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" className="h-12 px-4 text-base" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>;
+```
+
+## Casos de Uso Comunes
+
+**Tables**: Paginación de tablas con muchas filas  
+**Lists**: Listas largas de items (productos, usuarios, posts)  
+**Search results**: Resultados de búsqueda paginados  
+**Galleries**: Galerías de imágenes o archivos  
+**Admin panels**: Dashboards con data paginada  
+**API results**: Navegación de resultados de API con offset/limit
+
+## Estados y Data Attributes
+
+### PaginationLink
+
+- **Active**: `isActive` → variant outline, `aria-current="page"`
+- **Inactive**: variant ghost
+
+### Disabled (Previous/Next)
+
+No hay prop disabled nativa, se simula con:
+
+```tsx
+className = "pointer-events-none opacity-50";
+```
+
+## Estilos Base
+
+### Pagination (Root)
+
+- **Layout**: `mx-auto flex w-full justify-center`
+- **Semantic**: `<nav role="navigation" aria-label="pagination">`
+
+### PaginationContent
+
+- **Layout**: `flex flex-row items-center gap-1`
+
+### PaginationLink
+
+- **Size default**: `size="icon"` (h-9 w-9)
+- **Variants**: ghost (inactive), outline (active)
+
+### PaginationPrevious/Next
+
+- **Size**: `size="default"`
+- **Padding**: `px-2.5`
+- **Responsive**: Texto oculto en mobile (`hidden sm:block`)
+- **Gap**: `gap-1` entre icono y texto
+
+### PaginationEllipsis
+
+- **Size**: `size-9`
+- **Icon**: more_horiz (Material Symbol) con `text-lg`
+- **Layout**: `flex items-center justify-center`
+- **ARIA**: `aria-hidden`
+
+## Responsive
+
+- **Mobile**: Previous/Next solo muestran icono
+- **Desktop (sm+)**: Previous/Next muestran icono + texto
+
+## Accesibilidad
+
+- ✅ **Semantic**: `<nav role="navigation" aria-label="pagination">`
+- ✅ **Current page**: `aria-current="page"` en página activa
+- ✅ **Screen readers**: Ellipsis tiene `<span className="sr-only">More pages</span>`
+- ✅ **Keyboard**: Navegación con Tab, activación con Enter/Space
+- ✅ **Labels**: Previous/Next tienen `aria-label` descriptivo
+- ⚠️ **Disabled**: Usa `pointer-events-none opacity-50` + previene click en handler
+
+## Notas de Implementación
+
+- **Links**: PaginationLink es `<a>` no `<button>`, usa Button styles
+- **Icons**: chevron_left, chevron_right, more_horiz (Material Symbols)
+- **Responsive text**: Previous/Next usan `hidden sm:block` en texto
+- **No state**: Componente stateless, maneja estado externamente
+- **Ellipsis logic**: Representación negativa (-1, -2) común para identificar ellipsis
+- **Disabled**: No hay prop disabled, usa className manual
+- **Centering**: Root tiene `mx-auto justify-center`
+
+## Algoritmo de Generación de Páginas
+
+Patrón común para mostrar páginas con ellipsis:
+
+```tsx
+const generatePageNumbers = (current: number, total: number) => {
+  const pages = [];
+
+  // Siempre primera página
+  pages.push(1);
+
+  // Ellipsis izquierda si hay gap
+  if (current > 4) pages.push(-1);
+
+  // Páginas alrededor de current
+  const start = Math.max(2, current - 1);
+  const end = Math.min(total - 1, current + 1);
+  for (let i = start; i <= end; i++) {
+    if (i !== 1 && i !== total) pages.push(i);
+  }
+
+  // Ellipsis derecha si hay gap
+  if (current < total - 3) pages.push(-2);
+
+  // Siempre última página
+  if (total > 1) pages.push(total);
+
+  return pages;
+};
+```
+
+## Troubleshooting
+
+**Previous/Next no se deshabilitan**: No hay prop disabled, usa `className="pointer-events-none opacity-50"` y previene click en handler  
+**Active no se ve**: Verifica `isActive` prop y que solo una página lo tenga  
+**Texto Previous/Next no se ve en mobile**: Comportamiento esperado, usa `hidden sm:block`  
+**Ellipsis clickeable**: Ellipsis no debe ser clickeable, es `<span>` no link  
+**Spacing inconsistente**: PaginationContent tiene `gap-1`, ajusta con className  
+**No centrado**: Root tiene `justify-center`, override con `className="justify-start"` si necesario  
+**Links no funcionan**: PaginationLink usa `<a>`, asegúrate de pasar `href` o `onClick`  
+**Too many pages**: Usa ellipsis y lógica de generación de páginas para mostrar subset
+
+## Referencias
+
+- **shadcn/ui Pagination**: <https://ui.shadcn.com/docs/components/pagination>
+- **WAI-ARIA Pagination**: <https://www.w3.org/WAI/ARIA/apg/patterns/pagination/>