vicdev-ui-lib

Biblioteca de componentes React reutilizables con sistema de tema centralizado y soporte para Tailwind CSS.

🚀 Características

• ✨ Sistema de tema centralizado: Configura todos los colores desde un solo lugar
• 🎨 Integración con Tailwind CSS: Compatible con Tailwind CSS v3 y v4
• 📦 Componentes listos para usar: Modales, formularios, tablas, botones y más
• 🔧 TypeScript: Completamente tipado para mejor experiencia de desarrollo
• 🎯 Peer Dependencies: Las dependencias se resuelven desde tu proyecto

📦 Instalación

npm install vicdev-ui-lib
# o
yarn add vicdev-ui-lib
# o
pnpm add vicdev-ui-lib

Dependencias Peer

Esta biblioteca requiere las siguientes dependencias en tu proyecto:

npm install react react-dom
npm install tailwindcss@^3.0.0  # o tailwindcss@^4.0.0 para v4

# Opcionales (según los componentes que uses)
npm install framer-motion      # Para animaciones
npm install lucide-react      # Para iconos
npm install primereact        # Para componentes de tabla
npm install primeicons        # Para iconos de PrimeReact

Nota: La biblioteca es compatible con Tailwind CSS v3 y v4. Ver THEME.md para instrucciones específicas según tu versión.

Configuración Automática de Tailwind

Si tu proyecto no tiene Tailwind CSS configurado, puedes usar el script de configuración automática:

# Desde el proyecto que usa la biblioteca
npx vicdev-ui-lib setup:tailwind

Este script:

• ✅ Verifica si Tailwind CSS está instalado (si no, lo instala)
• ✅ Crea la configuración de Tailwind si no existe
• ✅ Te guía para completar la configuración con los colores del tema

🎨 Configuración del Tema

Los componentes leen automáticamente las variables CSS de tu proyecto. Solo necesitas definir las variables CSS en tu archivo CSS global.

Opción 1: Usar tus propias variables CSS (Recomendado)

Define las variables CSS en tu archivo CSS global y los componentes las usarán automáticamente:

/* src/index.css */
@import "tailwindcss";

:root {
  --primary: #3b82f6;
  --primary-foreground: #ffffff;
  --secondary: #f1f5f9;
  --secondary-foreground: #0f172a;
  --background: #ffffff;
  --foreground: #0f172a;
  --card: #ffffff;
  --card-foreground: #0f172a;
  --border: #e2e8f0;
  --input: #e2e8f0;
  --ring: #3b82f6;
  --muted: #f1f5f9;
  --muted-foreground: #64748b;
  --popover: #ffffff;
  --popover-foreground: #0f172a;
  --radio: #e2e8f0;
  --radio-foreground: #0f172a;
  /* ... más variables según necesites ... */
}

// App.tsx - No necesitas ThemeProvider
import { ActionButton, Modal } from 'vicdev-ui-lib';
import './index.css'; // Importar tu CSS con las variables

function App() {
  return (
    <div>
      <ActionButton variant="primary" label="Click me" />
      {/* Los componentes usan automáticamente tus variables CSS */}
    </div>
  );
}

Opción 2: Usar ThemeProvider (Opcional)

Si prefieres configurar el tema desde JavaScript o cambiar el tema dinámicamente:

import { ThemeProvider, createTheme } from 'vicdev-ui-lib';

const customTheme = createTheme({
  primary: '#3b82f6',
  primaryForeground: '#f8fafc',
  destructive: '#ef4444',
  // ... personaliza más colores según necesites (en formato hexadecimal)
});

function App() {
  return (
    <ThemeProvider theme={customTheme} injectCSS={true}>
      {/* injectCSS={true} inyecta las variables CSS automáticamente */}
      {/* Tu aplicación */}
    </ThemeProvider>
  );
}

Opciones del ThemeProvider:

• theme (opcional): Configuración del tema
• injectCSS (opcional, por defecto: true): Si es false, solo mantiene el contexto sin inyectar CSS (útil si ya tienes las variables en tu CSS global)

Configurar Tailwind CSS

Para Tailwind CSS v4

/* src/index.css */
@import "tailwindcss";

:root {
  --primary: #3b82f6;
  /* ... más variables ... */
}

@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... mapear todas las variables a Tailwind ... */
}

Para Tailwind CSS v3

// tailwind.config.js
const { getTailwindConfig } = require('vicdev-ui-lib/theme');

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: getTailwindConfig(),
  },
  plugins: [],
};

Ver THEME.md para documentación completa del sistema de tema.

📚 Componentes Disponibles

Modales

import { Modal, DeleteConfirmModal } from 'vicdev-ui-lib';

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Mi Modal"
  tamaño="lg"
>
  Contenido del modal
</Modal>

<DeleteConfirmModal
  isOpen={isOpen}
  onClose={(confirmed) => setIsOpen(false)}
  onConfirm={handleDelete}
  entidad={{ tipo: 'producto', nombre: 'Producto 1' }}
/>

Botones

import { ActionButton } from 'vicdev-ui-lib';
import { Plus } from 'lucide-react';

<ActionButton
  variant="primary"
  icon={Plus}
  label="Agregar"
  onClick={handleClick}
/>

Formularios

import { FormField, SearchBar, FileUpload, ToggleSwitch, MultiSelectCheckbox } from 'vicdev-ui-lib';

<FormField
  label="Nombre"
  type="text"
  value={value}
  onChange={handleChange}
  required
/>

<SearchBar
  value={search}
  onChange={setSearch}
  placeholder="Buscar..."
/>

Tablas

import { DataTable } from 'vicdev-ui-lib';

const columns = [
  { field: 'id', header: 'ID', sortable: true },
  { field: 'name', header: 'Nombre', sortable: true },
];

<DataTable
  value={data}
  columns={columns}
  paginator
  rows={10}
  loading={loading}
/>

Toast

import { Toast } from 'vicdev-ui-lib';

<Toast
  message="Operación exitosa"
  variant="success"
  open={showToast}
  onClose={() => setShowToast(false)}
  autoClose={3000}
/>

Otros Componentes

import { CurrencyDisplay, Logo, FileViewerModal, FileLink } from 'vicdev-ui-lib';

<CurrencyDisplay value={50000} bold primary />
<Logo size="large" variant="whiteNoBg" />

🎨 Sistema de Tema

La biblioteca incluye un sistema de tema completo que permite personalizar todos los colores desde un solo lugar. Ver THEME.md para documentación completa.

Colores Disponibles

• primary / primaryForeground
• secondary / secondaryForeground
• accent / accentForeground
• destructive / destructiveForeground
• background / foreground
• card / cardForeground
• border / input / ring
• muted / mutedForeground
• popover / popoverForeground
• radio / radioForeground

Uso del Hook useTheme

import { useTheme } from 'vicdev-ui-lib';

function MyComponent() {
  const { theme, setTheme } = useTheme();
  
  return (
    <div style={{ color: theme.colors.primary }}>
      Mi componente con tema personalizado
    </div>
  );
}

📖 Documentación

• THEME.md - Documentación completa del sistema de tema
• tailwind.config.example.js - Ejemplo de configuración de Tailwind

🔧 Desarrollo

# Instalar dependencias
npm install

# Modo desarrollo
npm run dev

# Construir biblioteca
npm run build

# Linter
npm run lint

📝 Licencia

Este proyecto es privado.

🤝 Contribuir

Este es un proyecto privado. Para contribuciones, contacta al mantenedor del proyecto.