siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,286 @@
+import React, { useMemo } from 'react';
+import type { PaginationProps, PageButtonProps } from './Pagination.types';
+import { ArrowLeftIcon, ArrowRightIcon } from './icons';
+
+/**
+ * Componente Pagination del sistema de diseño Siesa
+ * Basado en especificaciones de Figma con Tailwind CSS
+ *
+ * Mejores prácticas implementadas:
+ * - Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+ * - Dark mode con estrategia 'class' (darkMode: 'class')
+ * - Tokens de color consistentes con la documentación
+ * - Type safety con TypeScript estricto
+ * - Accesibilidad con ARIA labels
+ * - Algoritmo de paginación inteligente
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label Small)
+ * @see docs/spacing.md - Sistema de espaciado
+ *
+ * @example
+ * ```tsx
+ * <Pagination
+ *   currentPage={1}
+ *   totalPages={66}
+ *   onPageChange={(page) => console.log(page)}
+ * />
+ * ```
+ */
+export const Pagination: React.FC<PaginationProps> = ({
+  currentPage = 1,
+  totalPages,
+  onPageChange,
+  backText = 'Atrás',
+  nextText = 'Siguiente',
+  siblingCount = 1,
+  showBackButton = true,
+  showNextButton = true,
+  className = '',
+  ariaLabel = 'Paginación',
+}) => {
+  /**
+   * Genera el array de páginas a mostrar
+   * Algoritmo: [1] ... [currentPage-1] [currentPage] [currentPage+1] ... [totalPages]
+   */
+  const paginationRange = useMemo(() => {
+    const totalNumbers = siblingCount * 2 + 3; // Página actual + siblings + primera + última
+    const totalBlocks = totalNumbers + 2; // + 2 separadores "..."
+
+    // Si el total de páginas es menor que el total de bloques, mostrar todas
+    if (totalPages <= totalBlocks) {
+      return Array.from({ length: totalPages }, (_, i) => i + 1);
+    }
+
+    const leftSiblingIndex = Math.max(currentPage - siblingCount, 1);
+    const rightSiblingIndex = Math.min(currentPage + siblingCount, totalPages);
+
+    const shouldShowLeftDots = leftSiblingIndex > 2;
+    const shouldShowRightDots = rightSiblingIndex < totalPages - 1;
+
+    const firstPageIndex = 1;
+    const lastPageIndex = totalPages;
+
+    // No mostrar dots a la izquierda
+    if (!shouldShowLeftDots && shouldShowRightDots) {
+      const leftItemCount = 3 + 2 * siblingCount;
+      const leftRange = Array.from({ length: leftItemCount }, (_, i) => i + 1);
+      return [...leftRange, '...', totalPages];
+    }
+
+    // No mostrar dots a la derecha
+    if (shouldShowLeftDots && !shouldShowRightDots) {
+      const rightItemCount = 3 + 2 * siblingCount;
+      const rightRange = Array.from(
+        { length: rightItemCount },
+        (_, i) => totalPages - rightItemCount + i + 1
+      );
+      return [firstPageIndex, '...', ...rightRange];
+    }
+
+    // Mostrar ambos dots
+    if (shouldShowLeftDots && shouldShowRightDots) {
+      const middleRange = Array.from(
+        { length: rightSiblingIndex - leftSiblingIndex + 1 },
+        (_, i) => leftSiblingIndex + i
+      );
+      return [firstPageIndex, '...', ...middleRange, '...', lastPageIndex];
+    }
+
+    return [];
+  }, [currentPage, totalPages, siblingCount]);
+
+  /**
+   * Handler para cambio de página
+   */
+  const handlePageChange = (page: number) => {
+    if (page >= 1 && page <= totalPages && page !== currentPage) {
+      onPageChange?.(page);
+    }
+  };
+
+  /**
+   * Componente interno: Botón de página
+   */
+  const PageButton: React.FC<PageButtonProps> = ({
+    page,
+    isActive = false,
+    disabled = false,
+    onClick,
+    ariaLabel: buttonAriaLabel,
+  }) => {
+    const isDots = page === '...';
+
+    // ===== CLASES BASE =====
+    const baseClasses = `
+      inline-flex
+      items-center
+      justify-center
+      gap-3
+      px-3
+      py-2
+      rounded-md
+      font-bold
+      text-sm
+      whitespace-nowrap
+      transition-all
+      duration-150
+    `;
+
+    // ===== CLASES DE ESTADO =====
+    const stateClasses = isDots
+      ? `
+          text-primary-custom-600
+          dark:text-primary-custom-600
+          cursor-default
+          pointer-events-none
+        `
+      : isActive
+      ? `
+          bg-primary-custom-100
+          text-primary-custom-600
+          dark:bg-primary-custom-100
+          dark:text-primary-custom-600
+        `
+      : `
+          text-primary-custom-600
+          hover:bg-primary-custom-100
+          active:scale-95
+          dark:text-primary-custom-600
+          dark:hover:bg-primary-custom-100
+          dark:active:scale-95
+        `;
+
+    // ===== CLASES DE DISABLED =====
+    const disabledClasses = disabled
+      ? `
+          opacity-50
+          cursor-not-allowed
+          pointer-events-none
+        `
+      : '';
+
+    // ===== COMBINAR CLASES =====
+    const buttonClasses = [baseClasses, stateClasses, disabledClasses]
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    return (
+      <button
+        type="button"
+        className={buttonClasses}
+        onClick={onClick}
+        disabled={disabled || isDots}
+        aria-label={buttonAriaLabel}
+        aria-current={isActive ? 'page' : undefined}
+      >
+        {page}
+      </button>
+    );
+  };
+
+  // ===== CLASES DEL CONTAINER =====
+  const containerClasses = `
+    inline-flex
+    items-center
+    justify-between
+    gap-0
+    ${className}
+  `
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return (
+    <nav className={containerClasses} aria-label={ariaLabel} role="navigation">
+      {/* ===== BOTÓN BACK ===== */}
+      {showBackButton && (
+        <button
+          type="button"
+          className={`
+            inline-flex
+            items-center
+            justify-center
+            gap-3
+            px-3
+            py-2
+            rounded-md
+            font-bold
+            text-sm
+            text-primary-custom-600
+            hover:bg-primary-custom-100
+            active:scale-95
+            dark:text-primary-custom-600
+            dark:hover:bg-primary-custom-100
+            dark:active:scale-95
+            transition-all
+            duration-150
+            ${currentPage === 1 ? 'opacity-50 cursor-not-allowed pointer-events-none' : ''}
+          `
+            .replace(/\s+/g, ' ')
+            .trim()}
+          onClick={() => handlePageChange(currentPage - 1)}
+          disabled={currentPage === 1}
+          aria-label={`${backText} page`}
+        >
+          <ArrowLeftIcon className="w-4 h-4" />
+          {backText}
+        </button>
+      )}
+
+      {/* ===== NÚMEROS DE PÁGINA ===== */}
+      <div className="inline-flex items-center">
+        {paginationRange.map((page, index) => (
+          <PageButton
+            key={`${page}-${index}`}
+            page={page}
+            isActive={page === currentPage}
+            onClick={() => typeof page === 'number' && handlePageChange(page)}
+            ariaLabel={
+              typeof page === 'number' ? `Go to page ${page}` : `Page ${page}`
+            }
+          />
+        ))}
+      </div>
+
+      {/* ===== BOTÓN NEXT ===== */}
+      {showNextButton && (
+        <button
+          type="button"
+          className={`
+            inline-flex
+            items-center
+            justify-center
+            gap-3
+            px-3
+            py-2
+            rounded-md
+            font-bold
+            text-sm
+            text-primary-custom-600
+            hover:bg-primary-custom-100
+            active:scale-95
+            dark:text-primary-custom-600
+            dark:hover:bg-primary-custom-100
+            dark:active:scale-95
+            transition-all
+            duration-150
+            ${
+              currentPage === totalPages
+                ? 'opacity-50 cursor-not-allowed pointer-events-none'
+                : ''
+            }
+          `
+            .replace(/\s+/g, ' ')
+            .trim()}
+          onClick={() => handlePageChange(currentPage + 1)}
+          disabled={currentPage === totalPages}
+          aria-label={`${nextText} page`}
+        >
+          {nextText}
+          <ArrowRightIcon className="w-4 h-4" />
+        </button>
+      )}
+    </nav>
+  );
+};

package/src/components/Pagination/Pagination.types.ts

@@ -0,0 +1,93 @@
+import type { MouseEvent } from 'react';
+
+/**
+ * Props del componente Pagination
+ */
+export interface PaginationProps {
+  /**
+   * Página actual (basada en 1)
+   * @default 1
+   */
+  currentPage?: number;
+
+  /**
+   * Número total de páginas
+   * @default 1
+   */
+  totalPages: number;
+
+  /**
+   * Callback cuando cambia la página
+   */
+  onPageChange?: (page: number) => void;
+
+  /**
+   * Texto del botón "Atrás"
+   * @default 'Atrás'
+   */
+  backText?: string;
+
+  /**
+   * Texto del botón "Siguiente"
+   * @default 'Siguiente'
+   */
+  nextText?: string;
+
+  /**
+   * Número de páginas visibles alrededor de la página actual
+   * @default 1
+   */
+  siblingCount?: number;
+
+  /**
+   * Si se debe mostrar el botón "Atrás"
+   * @default true
+   */
+  showBackButton?: boolean;
+
+  /**
+   * Si se debe mostrar el botón "Siguiente"
+   * @default true
+   */
+  showNextButton?: boolean;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+
+  /**
+   * Label para accesibilidad (ARIA)
+   */
+  ariaLabel?: string;
+}
+
+/**
+ * Props internas para el botón de página
+ */
+export interface PageButtonProps {
+  /**
+   * Número de página o "..."
+   */
+  page: number | string;
+
+  /**
+   * Si es la página activa
+   */
+  isActive?: boolean;
+
+  /**
+   * Si el botón está deshabilitado
+   */
+  disabled?: boolean;
+
+  /**
+   * Handler para click
+   */
+  onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * Label para accesibilidad
+   */
+  ariaLabel?: string;
+}

package/src/components/Pagination/README.md

@@ -0,0 +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

package/src/components/Pagination/icons.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+
+/**
+ * Icono de flecha izquierda (ChevronLeft)
+ * Usado en el botón "Back"
+ * Heroicons Micro (16x16px)
+ */
+export const ArrowLeftIcon: React.FC<{ className?: string }> = ({ className = '' }) => {
+  return (
+    <svg
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path
+        fillRule="evenodd"
+        d="M9.78 4.22a.75.75 0 0 1 0 1.06L7.06 8l2.72 2.72a.75.75 0 1 1-1.06 1.06L5.47 8.53a.75.75 0 0 1 0-1.06l3.25-3.25a.75.75 0 0 1 1.06 0Z"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+};
+
+/**
+ * Icono de flecha derecha (ChevronRight)
+ * Usado en el botón "Next"
+ * Heroicons Micro (16x16px)
+ */
+export const ArrowRightIcon: React.FC<{ className?: string }> = ({ className = '' }) => {
+  return (
+    <svg
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path
+        fillRule="evenodd"
+        d="M6.22 4.22a.75.75 0 0 1 1.06 0l3.25 3.25a.75.75 0 0 1 0 1.06l-3.25 3.25a.75.75 0 0 1-1.06-1.06L8.94 8 6.22 5.28a.75.75 0 0 1 0-1.06Z"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+};