siesa-ui-kit 1.0.0 → 1.0.1

package/src/components/Pagination/Pagination.tsx

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

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

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

@@ -1,47 +0,0 @@
-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>
-  );
-};