react-card-component-library

v0.0.11

Published

3 months ago

Librería de componentes React con Tailwind CSS, diseñada siguiendo las mejores prácticas de Clean Code y principios SOLID.

0High
0Medium
0Low

darkar9512

React Card Component Library 🎴

Librería de componentes React con Tailwind CSS, diseñada siguiendo las mejores prácticas de Clean Code y principios SOLID.

🚀 Características

✅ TypeScript - Type safety completo
✅ Tailwind CSS - Estilos utility-first
✅ Storybook - Documentación interactiva
✅ Vitest - Testing unitario
✅ Clean Code - Código limpio y mantenible
✅ SOLID - Principios de diseño aplicados
✅ Accesibilidad - ARIA labels y semántica HTML

📦 Instalación

# Clonar el repositorio
git clone [url-del-repositorio]
cd react-card-component-library

# Instalar dependencias
npm install

🛠️ Scripts Disponibles

Desarrollo

npm run dev          # Inicia servidor de desarrollo (http://localhost:5173)
npm run storybook    # Inicia Storybook (http://localhost:6006)

Testing

npm run test         # Ejecuta tests unitarios
npm run test:ui      # Ejecuta tests con interfaz visual
npm run test:coverage # Genera reporte de cobertura

Build

npm run build           # Construye para producción
npm run build-storybook # Construye Storybook estático
npm run lint           # Ejecuta ESLint

🧩 Componente Card

Propiedades

| Prop | Tipo | Default | Descripción | | --------------- | ---------------------------------------- | ----------- | ----------------------------------------- | | title | string | - | Título de la tarjeta (requerido) | | description | string | - | Descripción de la tarjeta (requerido) | | imageUrl | string | undefined | URL de la imagen | | imageAlt | string | title | Texto alternativo para la imagen | | buttonText | string | 'Ver más' | Texto del botón | | onButtonClick | () => void | undefined | Callback al hacer click en el botón | | variant | 'primary' \| 'secondary' \| 'outlined' | 'primary' | Variante de estilo | | size | 'small' \| 'medium' \| 'large' | 'medium' | Tamaño de la tarjeta | | className | string | undefined | Clases CSS adicionales |

Ejemplo de Uso

import { Card } from "@/components";

function App() {
  return (
    <Card
      title="Mi Tarjeta"
      description="Esta es una descripción de ejemplo"
      imageUrl="https://example.com/image.jpg"
      imageAlt="Descripción de la imagen"
      buttonText="Leer más"
      onButtonClick={() => console.log("Click!")}
      variant="primary"
      size="medium"
      className="custom-class"
    />
  );
}

🎨 Variantes

Primary (Por defecto)

Borde azul con botón azul - ideal para acciones principales

Secondary

Borde gris con botón gris - ideal para acciones secundarias

Outlined

Borde gris claro con botón azul - ideal para estilos sutiles

📏 Tamaños

Small: 250px max-width - perfecto para sidebars
Medium: 350px max-width (por defecto) - uso general
Large: 450px max-width - destacar contenido importante

🎭 Storybook

Visualiza todos los estados del componente:

npm run storybook

Abre http://localhost:6006 para ver:

✨ Todas las variantes
📐 Todos los tamaños
🎯 Diferentes estados
📚 Documentación interactiva

✅ Testing

Cobertura de Tests

El componente incluye tests exhaustivos que cubren:

✅ Renderizado con props básicas
✅ Renderizado con imagen
✅ Click en botón
✅ Sin botón cuando no hay callback
✅ Variantes de estilo (primary, secondary, outlined)
✅ Tamaños (small, medium, large)
✅ Clases personalizadas
✅ Accesibilidad (ARIA labels)

# Ejecutar todos los tests
npm run test

# Modo watch
npm run test -- --watch

# Con UI
npm run test:ui

# Con coverage
npm run test:coverage

🏗️ Estructura del Proyecto

react-card-component-library/
├── .storybook/              # Configuración de Storybook
├── .vscode/                 # Configuración del workspace
│   ├── settings.json
│   └── extensions.json
├── src/
│   ├── components/
│   │   └── Card/
│   │       ├── Card.tsx           # Componente principal
│   │       ├── Card.test.tsx      # Tests unitarios
│   │       ├── Card.stories.tsx   # Storybook stories
│   │       └── index.ts           # Exportaciones
│   ├── types/
│   │   └── index.ts              # TypeScript types
│   ├── utils/
│   │   ├── cn.ts                 # Utilidad para Tailwind
│   │   └── index.ts
│   ├── tests/
│   │   └── setup.ts              # Configuración de tests
│   ├── App.tsx                   # Aplicación de ejemplo
│   ├── main.tsx                  # Entry point
│   └── index.css                 # Tailwind imports
├── tailwind.config.js          # Configuración de Tailwind
├── vite.config.ts              # Configuración de Vite
├── tsconfig.json               # Configuración de TypeScript
├── package.json
└── README.md

🎯 Mejores Prácticas Aplicadas

Clean Code

✨ Nombres descriptivos y semánticos
🎯 Funciones pequeñas y enfocadas (SRP)
📝 Comentarios cuando aportan valor
🔍 Código autoexplicativo y legible

SOLID Principles

Single Responsibility

Cada componente tiene una sola responsabilidad. El componente Card solo se encarga de mostrar una tarjeta.

Open/Closed

Extensible mediante props (variant, size, className) sin modificar el código fuente.

Liskov Substitution

Props opcionales con valores por defecto garantizan que el componente funcione en cualquier contexto.

Interface Segregation

Interfaces TypeScript específicas y mínimas (CardProps).

Dependency Inversion

Depende de abstracciones (tipos TypeScript) en lugar de implementaciones concretas.

Accesibilidad (a11y)

♿ ARIA labels en botones (aria-label)
🖼️ Imágenes con alt text descriptivo
🏷️ Semántica HTML correcta (h3, button, p)
👁️ Estados de focus visibles
⌨️ Navegación por teclado

🔧 Tecnologías

React 19 - Librería UI
TypeScript 5 - Type safety
Tailwind CSS 4 - Estilos utility-first
Vite 7 - Build tool y dev server
Vitest 4 - Testing framework
Testing Library - Testing utilities
Storybook 10 - Documentación de componentes
clsx + tailwind-merge - Manejo de clases CSS

📝 Notas de Desarrollo

Personalización de Tailwind

Puedes personalizar los colores, sombras y más en tailwind.config.js:

theme: {
  extend: {
    colors: {
      primary: {
        500: '#3b82f6', // Cambia el color principal
        // ... más colores
      }
    },
    boxShadow: {
      'card': '0 2px 8px rgba(0, 0, 0, 0.1)',
    }
  }
}

Estilos Personalizados

Usa la prop className para añadir estilos adicionales:

<Card
  title="Mi Tarjeta"
  description="Descripción"
  className="shadow-2xl ring-2 ring-purple-500"
/>

Utilidad `cn()`

La función cn() combina clsx y tailwind-merge para manejar clases condicionales y evitar conflictos:

import { cn } from "@/utils";

// Combina clases sin conflictos
cn("base-class", condition && "conditional-class", className);

🚀 Despliegue

Build para Producción

npm run build

Los archivos optimizados se generarán en dist/.

Publicar Storybook

npm run build-storybook

Los archivos estáticos de Storybook se generarán en storybook-static/.

📋 Checklist de Calidad

✅ TypeScript sin errores
✅ Tests con cobertura completa
✅ Accesibilidad verificada (a11y addon)
✅ ESLint sin warnings
✅ Storybook con todas las variantes
✅ Documentación completa
✅ Ejemplos funcionales

🤝 Contribuir

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📄 Licencia

MIT License

👤 Autor

Desarrollado como ejercicio técnico para demostrar:

Desarrollo de componentes React
Implementación de diseños de Figma
Mejores prácticas (Clean Code, SOLID)
Testing exhaustivo
Documentación profesional

¿Necesitas ayuda?

📚 Revisa la documentación en Storybook
🧪 Ejecuta los tests para ver ejemplos de uso
💬 Abre un issue en GitHub