siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/Pagination/README.md

@@ -1,298 +1,298 @@
-# Pagination Component
-
-Componente de paginación del sistema de diseño **Siesa UI Kit**, implementado pixel-perfect según especificaciones de Figma con soporte completo de dark mode.
-
-## 📋 Características
-
-- ✅ **Soporte completo de dark mode** - Tokens adaptativos para light/dark
-- ✅ **Algoritmo inteligente** - Muestra páginas relevantes con separadores "..."
-- ✅ **TypeScript estricto** - Types completos para máxima seguridad
-- ✅ **Accesibilidad** - ARIA labels y navegación por teclado
-- ✅ **Personalizable** - Textos, siblingCount, botones opcionales
-- ✅ **Pixel-perfect** - Implementado exactamente según Figma
-- ✅ **Transiciones suaves** - Animaciones en hover y active
-
----
-
-## 🎨 Especificaciones de Diseño
-
-### Tokens Utilizados
-
-| Propiedad | Token | Valor Light | Valor Dark |
-|-----------|-------|-------------|------------|
-| **Texto** | `text-primary-custom-600` | `#0e79fd` | `#0e79fd` |
-| **Hover BG** | `hover:bg-primary-custom-100` | `#dbeefe` | `#dbeefe` |
-| **Active BG** | `bg-primary-custom-100` | `#dbeefe` | `#dbeefe` |
-| **Font** | `text-sm font-bold` | 14px Bold | 14px Bold |
-| **Padding** | `px-3 py-2` | 12px 8px | 12px 8px |
-| **Border Radius** | `rounded-md` | 6px | 6px |
-
-### Estados
-
-- **Default**: Transparente, texto azul
-- **Hover**: Fondo azul claro (`primary-custom-100`)
-- **Active**: Fondo azul claro (página actual)
-- **Disabled**: Opacidad 50% (Back/Next en primera/última página)
-
----
-
-## 📦 Uso Básico
-
-```tsx
-import { Pagination } from '@/components/Pagination';
-import { useState } from 'react';
-
-function MyComponent() {
-  const [currentPage, setCurrentPage] = useState(1);
-
-  return (
-    <Pagination
-      currentPage={currentPage}
-      totalPages={66}
-      onPageChange={(page) => setCurrentPage(page)}
-    />
-  );
-}
-```
-
----
-
-## 🔧 Props
-
-### PaginationProps
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `currentPage` | `number` | `1` | Página actual (basada en 1) |
-| `totalPages` | `number` | **Requerido** | Número total de páginas |
-| `onPageChange` | `(page: number) => void` | - | Callback cuando cambia la página |
-| `backText` | `string` | `'Back'` | Texto del botón "Back" |
-| `nextText` | `string` | `'Next'` | Texto del botón "Next" |
-| `siblingCount` | `number` | `1` | Páginas visibles alrededor de la actual |
-| `showBackButton` | `boolean` | `true` | Si se muestra el botón "Back" |
-| `showNextButton` | `boolean` | `true` | Si se muestra el botón "Next" |
-| `className` | `string` | `''` | Clases CSS adicionales |
-| `ariaLabel` | `string` | `'Pagination'` | Label para accesibilidad |
-
----
-
-## 📖 Ejemplos
-
-### 1. Paginación Básica
-
-```tsx
-<Pagination
-  currentPage={1}
-  totalPages={10}
-  onPageChange={(page) => console.log(page)}
-/>
-```
-
-### 2. Con Textos Personalizados (Español)
-
-```tsx
-<Pagination
-  currentPage={5}
-  totalPages={66}
-  backText="Anterior"
-  nextText="Siguiente"
-  onPageChange={(page) => console.log(page)}
-/>
-```
-
-### 3. Más Páginas Visibles (siblingCount)
-
-```tsx
-// siblingCount = 1 (default): [1] ... [4] [5] [6] ... [66]
-<Pagination currentPage={5} totalPages={66} siblingCount={1} />
-
-// siblingCount = 2: [1] ... [3] [4] [5] [6] [7] ... [66]
-<Pagination currentPage={5} totalPages={66} siblingCount={2} />
-
-// siblingCount = 0: [1] ... [5] ... [66]
-<Pagination currentPage={5} totalPages={66} siblingCount={0} />
-```
-
-### 4. Solo Números (Sin Back/Next)
-
-```tsx
-<Pagination
-  currentPage={5}
-  totalPages={66}
-  showBackButton={false}
-  showNextButton={false}
-/>
-```
-
-### 5. Con Tabla
-
-```tsx
-function TableWithPagination() {
-  const [currentPage, setCurrentPage] = useState(1);
-  const itemsPerPage = 10;
-  const totalItems = 156;
-  const totalPages = Math.ceil(totalItems / itemsPerPage);
-
-  const startItem = (currentPage - 1) * itemsPerPage + 1;
-  const endItem = Math.min(currentPage * itemsPerPage, totalItems);
-
-  return (
-    <div>
-      {/* Tu tabla aquí */}
-      <table>{/* ... */}</table>
-
-      {/* Footer con info y paginación */}
-      <div className="flex items-center justify-between mt-4">
-        <p className="text-xs text-gray-500">
-          Mostrando {startItem} a {endItem} de {totalItems} resultados
-        </p>
-        <Pagination
-          currentPage={currentPage}
-          totalPages={totalPages}
-          onPageChange={setCurrentPage}
-        />
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-## 🧠 Algoritmo de Paginación
-
-El componente usa un algoritmo inteligente para mostrar solo las páginas relevantes:
-
-### Pocas páginas (≤ 7)
-```
-[1] [2] [3] [4] [5]
-```
-
-### Cerca del inicio
-```
-[1] [2] [3] [4] [5] ... [66]
-```
-
-### Cerca del final
-```
-[1] ... [62] [63] [64] [65] [66]
-```
-
-### En el medio
-```
-[1] ... [9] [10] [11] ... [66]
-```
-
-**Reglas:**
-- Siempre muestra la **primera** y **última** página
-- Muestra la **página actual** y sus **siblings** (1 a cada lado por default)
-- Usa "**...**" para indicar páginas ocultas
-
----
-
-## ♿ Accesibilidad
-
-- ✅ Navegación por teclado (Tab, Enter, Space)
-- ✅ ARIA labels descriptivos (`aria-label`, `aria-current`)
-- ✅ Estados disabled claros
-- ✅ Focus rings visibles
-- ✅ Semantic HTML (`<nav>`, `<button>`)
-
-```tsx
-<Pagination
-  currentPage={5}
-  totalPages={66}
-  ariaLabel="Paginación de resultados"
-/>
-```
-
----
-
-## 🌓 Dark Mode
-
-El componente se adapta automáticamente al dark mode usando el modificador `dark:`:
-
-```tsx
-// Los colores se adaptan automáticamente
-<Pagination currentPage={1} totalPages={66} />
-```
-
-**Tokens usados:**
-- Texto: `text-primary-custom-600` (mismo en ambos modos)
-- Hover: `hover:bg-primary-custom-100` / `dark:hover:bg-primary-custom-100`
-
----
-
-## 🎯 Mejores Prácticas
-
-### ✅ Hacer
-
-```tsx
-// ✅ currentPage basado en 1
-<Pagination currentPage={1} totalPages={10} />
-
-// ✅ Mostrar información de contexto
-<div>
-  <p>Mostrando 1 a 10 de 156 resultados</p>
-  <Pagination currentPage={1} totalPages={16} />
-</div>
-
-// ✅ siblingCount responsive
-<Pagination
-  currentPage={5}
-  totalPages={66}
-  siblingCount={window.innerWidth < 768 ? 0 : 1}
-/>
-
-// ✅ Implementar onPageChange
-<Pagination
-  currentPage={currentPage}
-  totalPages={10}
-  onPageChange={(page) => {
-    setCurrentPage(page);
-    fetchData(page);
-    window.scrollTo(0, 0); // Scroll to top
-  }}
-/>
-```
-
-### ❌ Evitar
-
-```tsx
-// ❌ currentPage basado en 0
-<Pagination currentPage={0} totalPages={10} />
-
-// ❌ siblingCount muy alto
-<Pagination currentPage={5} totalPages={66} siblingCount={10} />
-
-// ❌ Sin onPageChange
-<Pagination currentPage={1} totalPages={10} />
-// El componente no cambiará páginas solo
-
-// ❌ Paginación para muy pocos items
-<Pagination currentPage={1} totalPages={2} />
-// Considera mostrar todo en lugar de paginar
-```
-
----
-
-## 📚 Referencias
-
-- **Figma**: [Pagination Component](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4168-16023)
-- **Código**: `src/components/Pagination/Pagination.tsx`
-- **Types**: `src/components/Pagination/Pagination.types.ts`
-- **Stories**: `src/components/Pagination/Pagination.stories.tsx`
-- **Docs**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`
-
----
-
-## 🔄 Historial de Cambios
-
-| Versión | Fecha | Cambios |
-|---------|-------|---------|
-| 1.0.0 | 2025-11-11 | Implementación inicial con dark mode completo |
-
----
-
-**Última actualización**: 2025-11-11
-**Mantenido por**: Equipo Siesa UI Kit
+# Pagination Component
+
+Componente de paginación del sistema de diseño **Siesa UI Kit**, implementado pixel-perfect según especificaciones de Figma con soporte completo de dark mode.
+
+## 📋 Características
+
+- ✅ **Soporte completo de dark mode** - Tokens adaptativos para light/dark
+- ✅ **Algoritmo inteligente** - Muestra páginas relevantes con separadores "..."
+- ✅ **TypeScript estricto** - Types completos para máxima seguridad
+- ✅ **Accesibilidad** - ARIA labels y navegación por teclado
+- ✅ **Personalizable** - Textos, siblingCount, botones opcionales
+- ✅ **Pixel-perfect** - Implementado exactamente según Figma
+- ✅ **Transiciones suaves** - Animaciones en hover y active
+
+---
+
+## 🎨 Especificaciones de Diseño
+
+### Tokens Utilizados
+
+| Propiedad | Token | Valor Light | Valor Dark |
+|-----------|-------|-------------|------------|
+| **Texto** | `text-primary-custom-600` | `#0e79fd` | `#0e79fd` |
+| **Hover BG** | `hover:bg-primary-custom-100` | `#dbeefe` | `#dbeefe` |
+| **Active BG** | `bg-primary-custom-100` | `#dbeefe` | `#dbeefe` |
+| **Font** | `text-sm font-bold` | 14px Bold | 14px Bold |
+| **Padding** | `px-3 py-2` | 12px 8px | 12px 8px |
+| **Border Radius** | `rounded-md` | 6px | 6px |
+
+### Estados
+
+- **Default**: Transparente, texto azul
+- **Hover**: Fondo azul claro (`primary-custom-100`)
+- **Active**: Fondo azul claro (página actual)
+- **Disabled**: Opacidad 50% (Back/Next en primera/última página)
+
+---
+
+## 📦 Uso Básico
+
+```tsx
+import { Pagination } from '@/components/Pagination';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [currentPage, setCurrentPage] = useState(1);
+
+  return (
+    <Pagination
+      currentPage={currentPage}
+      totalPages={66}
+      onPageChange={(page) => setCurrentPage(page)}
+    />
+  );
+}
+```
+
+---
+
+## 🔧 Props
+
+### PaginationProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `currentPage` | `number` | `1` | Página actual (basada en 1) |
+| `totalPages` | `number` | **Requerido** | Número total de páginas |
+| `onPageChange` | `(page: number) => void` | - | Callback cuando cambia la página |
+| `backText` | `string` | `'Back'` | Texto del botón "Back" |
+| `nextText` | `string` | `'Next'` | Texto del botón "Next" |
+| `siblingCount` | `number` | `1` | Páginas visibles alrededor de la actual |
+| `showBackButton` | `boolean` | `true` | Si se muestra el botón "Back" |
+| `showNextButton` | `boolean` | `true` | Si se muestra el botón "Next" |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `ariaLabel` | `string` | `'Pagination'` | Label para accesibilidad |
+
+---
+
+## 📖 Ejemplos
+
+### 1. Paginación Básica
+
+```tsx
+<Pagination
+  currentPage={1}
+  totalPages={10}
+  onPageChange={(page) => console.log(page)}
+/>
+```
+
+### 2. Con Textos Personalizados (Español)
+
+```tsx
+<Pagination
+  currentPage={5}
+  totalPages={66}
+  backText="Anterior"
+  nextText="Siguiente"
+  onPageChange={(page) => console.log(page)}
+/>
+```
+
+### 3. Más Páginas Visibles (siblingCount)
+
+```tsx
+// siblingCount = 1 (default): [1] ... [4] [5] [6] ... [66]
+<Pagination currentPage={5} totalPages={66} siblingCount={1} />
+
+// siblingCount = 2: [1] ... [3] [4] [5] [6] [7] ... [66]
+<Pagination currentPage={5} totalPages={66} siblingCount={2} />
+
+// siblingCount = 0: [1] ... [5] ... [66]
+<Pagination currentPage={5} totalPages={66} siblingCount={0} />
+```
+
+### 4. Solo Números (Sin Back/Next)
+
+```tsx
+<Pagination
+  currentPage={5}
+  totalPages={66}
+  showBackButton={false}
+  showNextButton={false}
+/>
+```
+
+### 5. Con Tabla
+
+```tsx
+function TableWithPagination() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const itemsPerPage = 10;
+  const totalItems = 156;
+  const totalPages = Math.ceil(totalItems / itemsPerPage);
+
+  const startItem = (currentPage - 1) * itemsPerPage + 1;
+  const endItem = Math.min(currentPage * itemsPerPage, totalItems);
+
+  return (
+    <div>
+      {/* Tu tabla aquí */}
+      <table>{/* ... */}</table>
+
+      {/* Footer con info y paginación */}
+      <div className="flex items-center justify-between mt-4">
+        <p className="text-xs text-gray-500">
+          Mostrando {startItem} a {endItem} de {totalItems} resultados
+        </p>
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          onPageChange={setCurrentPage}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 🧠 Algoritmo de Paginación
+
+El componente usa un algoritmo inteligente para mostrar solo las páginas relevantes:
+
+### Pocas páginas (≤ 7)
+```
+[1] [2] [3] [4] [5]
+```
+
+### Cerca del inicio
+```
+[1] [2] [3] [4] [5] ... [66]
+```
+
+### Cerca del final
+```
+[1] ... [62] [63] [64] [65] [66]
+```
+
+### En el medio
+```
+[1] ... [9] [10] [11] ... [66]
+```
+
+**Reglas:**
+- Siempre muestra la **primera** y **última** página
+- Muestra la **página actual** y sus **siblings** (1 a cada lado por default)
+- Usa "**...**" para indicar páginas ocultas
+
+---
+
+## ♿ Accesibilidad
+
+- ✅ Navegación por teclado (Tab, Enter, Space)
+- ✅ ARIA labels descriptivos (`aria-label`, `aria-current`)
+- ✅ Estados disabled claros
+- ✅ Focus rings visibles
+- ✅ Semantic HTML (`<nav>`, `<button>`)
+
+```tsx
+<Pagination
+  currentPage={5}
+  totalPages={66}
+  ariaLabel="Paginación de resultados"
+/>
+```
+
+---
+
+## 🌓 Dark Mode
+
+El componente se adapta automáticamente al dark mode usando el modificador `dark:`:
+
+```tsx
+// Los colores se adaptan automáticamente
+<Pagination currentPage={1} totalPages={66} />
+```
+
+**Tokens usados:**
+- Texto: `text-primary-custom-600` (mismo en ambos modos)
+- Hover: `hover:bg-primary-custom-100` / `dark:hover:bg-primary-custom-100`
+
+---
+
+## 🎯 Mejores Prácticas
+
+### ✅ Hacer
+
+```tsx
+// ✅ currentPage basado en 1
+<Pagination currentPage={1} totalPages={10} />
+
+// ✅ Mostrar información de contexto
+<div>
+  <p>Mostrando 1 a 10 de 156 resultados</p>
+  <Pagination currentPage={1} totalPages={16} />
+</div>
+
+// ✅ siblingCount responsive
+<Pagination
+  currentPage={5}
+  totalPages={66}
+  siblingCount={window.innerWidth < 768 ? 0 : 1}
+/>
+
+// ✅ Implementar onPageChange
+<Pagination
+  currentPage={currentPage}
+  totalPages={10}
+  onPageChange={(page) => {
+    setCurrentPage(page);
+    fetchData(page);
+    window.scrollTo(0, 0); // Scroll to top
+  }}
+/>
+```
+
+### ❌ Evitar
+
+```tsx
+// ❌ currentPage basado en 0
+<Pagination currentPage={0} totalPages={10} />
+
+// ❌ siblingCount muy alto
+<Pagination currentPage={5} totalPages={66} siblingCount={10} />
+
+// ❌ Sin onPageChange
+<Pagination currentPage={1} totalPages={10} />
+// El componente no cambiará páginas solo
+
+// ❌ Paginación para muy pocos items
+<Pagination currentPage={1} totalPages={2} />
+// Considera mostrar todo en lugar de paginar
+```
+
+---
+
+## 📚 Referencias
+
+- **Figma**: [Pagination Component](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4168-16023)
+- **Código**: `src/components/Pagination/Pagination.tsx`
+- **Types**: `src/components/Pagination/Pagination.types.ts`
+- **Stories**: `src/components/Pagination/Pagination.stories.tsx`
+- **Docs**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`
+
+---
+
+## 🔄 Historial de Cambios
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 1.0.0 | 2025-11-11 | Implementación inicial con dark mode completo |
+
+---
+
+**Última actualización**: 2025-11-11
+**Mantenido por**: Equipo Siesa UI Kit