ucol-ui

Una librería completa de componentes React para crear interfaces de usuario modernas y dinámicas

Demo en vivo | Documentación | Reportar un error

📋 Tabla de Contenidos

• Características
• Instalación
• Componentes Principales
• Guía de Inicio Rápido
• Documentación de Componentes
• Hooks Personalizados
• API y Configuración
• Desarrollo
• Scripts Disponibles
• Tecnologías
• Contribuir
• Licencia

✨ Características

• 🎨 Componentes Dinámicos: Formularios, tablas y CRUD completamente configurables
• 🔐 Sistema de Permisos: Control granular de acceso basado en roles
• 📊 Exportación de Datos: Soporte para Excel y PDF
• 📤 Carga Masiva: Importación de datos mediante archivos Excel/CSV
• 🎯 TypeScript First: Totalmente tipado para mejor experiencia de desarrollo
• 🚀 React Query: Gestión de estado del servidor integrada
• 💅 Estilos Modernos: Combinación de Ant Design y Tailwind CSS
• 📱 Responsive: Diseño adaptable a todos los dispositivos
• 🎭 Storybook: Documentación interactiva de componentes
• ⚡ Optimizado: Bundle optimizado con Vite

📦 Instalación

Usando npm

npm install ucol-ui

Usando pnpm

pnpm install ucol-ui

Usando yarn

yarn add ucol-ui

📚 Peer Dependencies

La librería requiere las siguientes dependencias instaladas en tu proyecto:

{
  "antd": "^5.24.0",
  "axios": "^1.7.9",
  "dayjs": "^1.11.13",
  "react": "19.0.0",
  "react-dom": "19.0.0"
}

Instalación de Peer Dependencies

npm install antd axios dayjs react react-dom

Importar estilos

No olvides importar los estilos CSS en tu aplicación:

import 'ucol-ui/dist/style.css';

🧩 Componentes Principales

🎯 DynamicCrud

Componente completo CRUD con tabla, formulario modal y acciones personalizables.

import { DynamicCrud } from 'ucol-ui';

<DynamicCrud
  title="Gestión de Usuarios"
  description="Administra los usuarios del sistema"
  columns={[
    { title: 'Nombre', dataIndex: 'name', key: 'name' },
    { title: 'Email', dataIndex: 'email', key: 'email' },
  ]}
  fields={[
    { name: 'name', label: 'Nombre', type: 'text', required: true },
    { name: 'email', label: 'Email', type: 'email', required: true },
  ]}
  data={users}
  onCreate={handleCreate}
  onEdit={handleEdit}
  onDelete={handleDelete}
/>

📝 DynamicForm

Formulario dinámico generado a partir de configuración JSON.

import { DynamicForm } from 'ucol-ui';

<DynamicForm
  mode="create"
  title="Nuevo Usuario"
  layout="vertical"
  cols={2}
  fields={[
    { name: 'name', label: 'Nombre', type: 'text', required: true },
    { name: 'email', label: 'Email', type: 'email', required: true },
    { name: 'age', label: 'Edad', type: 'number' },
    { name: 'active', label: 'Activo', type: 'switch' },
  ]}
  onSubmit={handleSubmit}
/>

📊 DynamicTable

Tabla configurable con búsqueda, filtros, paginación y exportación.

import { DynamicTable } from 'ucol-ui';

<DynamicTable
  title="Lista de Productos"
  columns={columns}
  data={products}
  loading={isLoading}
  showCreateButton
  onCreate={handleCreate}
  onEdit={handleEdit}
  onDelete={handleDelete}
  exportToExcel={{
    fileName: 'productos',
    sheetName: 'Productos',
    data: products,
    columns: columns
  }}
  searchConfig={{
    searchableFields: ['name', 'category', 'price']
  }}
/>

🔘 Btn (Button)

Botón versátil con presets, variantes de color e iconos.

import { Btn } from 'ucol-ui';

// Botón con preset
<Btn preset="save" variant="success">Guardar</Btn>
<Btn preset="delete" variant="danger">Eliminar</Btn>
<Btn preset="edit" variant="info">Editar</Btn>

// Botón personalizado
<Btn 
  icon={<CustomIcon />} 
  variant="warning"
  size="large"
>
  Acción Personalizada
</Btn>

// Solo icono
<Btn preset="add" iconOnly />

🔐 PermissionsProvider

Sistema de gestión de permisos basado en roles.

import { PermissionsProvider, usePermissions } from 'ucol-ui';

// Configurar permisos
const permissionsConfig = {
  users: {
    admin: ['create', 'read', 'update', 'delete'],
    user: ['read'],
  }
};

// Envolver tu aplicación
<PermissionsProvider role="admin" config={permissionsConfig}>
  <App />
</PermissionsProvider>

// Usar en componentes
function UserActions() {
  const { canCreate, canDelete } = usePermissions('users');
  
  return (
    <>
      {canCreate && <Btn preset="add">Crear</Btn>}
      {canDelete && <Btn preset="delete">Eliminar</Btn>}
    </>
  );
}

📤 BulkUploadModal

Modal para carga masiva de datos con validación.

import { BulkUploadModal } from 'ucol-ui';

<BulkUploadModal
  title="Importar Usuarios"
  visible={showModal}
  config={{
    allowedFormats: ['xlsx', 'csv'],
    maxFileSize: 5,
    templateFields: [
      { name: 'name', label: 'Nombre', required: true },
      { name: 'email', label: 'Email', required: true },
    ]
  }}
  onValidateData={validateUsers}
  onFinish={importUsers}
  onCancel={() => setShowModal(false)}
/>

🔍 SharedField

Campo de formulario compartido con validación y tipos múltiples.

import { SharedField } from 'ucol-ui';

<SharedField
  name="username"
  label="Usuario"
  type="text"
  required={true}
  placeholder="Ingresa tu usuario"
  validations={{
    minLength: 3,
    maxLength: 20,
    pattern: /^[a-zA-Z0-9]+$/
  }}
/>

🎣 Hooks Personalizados

useCrudOperations

Hook para operaciones CRUD con React Query integrado.

import { useCrudOperations } from 'ucol-ui';

function UserManagement() {
  const {
    data: users,
    isLoading,
    createItemAsync,
    updateItemAsync,
    deleteItemAsync,
    refetch
  } = useCrudOperations({
    getAll: () => api.getUsers(),
    create: (user) => api.createUser(user),
    update: (user) => api.updateUser(user),
    delete: (user) => api.deleteUser(user.id),
    idField: 'id',
    entityName: 'usuario'
  });

  const handleCreate = async (values) => {
    await createItemAsync(values);
  };

  return <DynamicTable data={users} loading={isLoading} />;
}

useFetchQuery

Hook wrapper de React Query con configuración predeterminada.

import { useFetchQuery } from 'ucol-ui';

const { data, isLoading, error } = useFetchQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  config: {
    onSuccess: (data) => console.log('Datos cargados:', data),
    onError: (error) => console.error('Error:', error)
  }
});

useNotification

Hook para mostrar notificaciones del sistema.

import { openNotification } from 'ucol-ui';

openNotification('success', 'Operación exitosa', 'Los datos se guardaron correctamente');
openNotification('error', 'Error', 'No se pudo completar la operación');
openNotification('warning', 'Advertencia', 'Revisa los datos ingresados');
openNotification('info', 'Información', 'Proceso en curso');

useAsync

Hook para manejar operaciones asíncronas.

import { useAsync } from 'ucol-ui';

function DataDisplay() {
  const { data, loading, error } = useAsync(
    async () => await fetchData(),
    [dependency]
  );

  if (loading) return <Spin />;
  if (error) return <Alert type="error" message={error.message} />;
  
  return <div>{JSON.stringify(data)}</div>;
}

⚙️ API y Configuración

Configuración de API en DynamicForm

<DynamicForm
  apiConfig={{
    url: 'https://api.example.com/users',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
      'Content-Type': 'application/json'
    },
    responseDataPath: 'data.user'
  }}
/>

Tipos de Campos de Formulario

• text - Campo de texto
• textarea - Área de texto
• number - Número
• email - Email
• password - Contraseña
• select - Lista desplegable
• multiselect - Selección múltiple
• checkbox - Casilla de verificación
• radio - Botones de radio
• switch - Interruptor
• date - Selector de fecha
• daterange - Rango de fechas
• time - Selector de hora
• upload - Carga de archivos
• slider - Deslizador
• color - Selector de color

Validaciones

{
  required: true,
  minLength: 5,
  maxLength: 50,
  min: 0,
  max: 100,
  pattern: /^[A-Z]/,
  email: true,
  url: true,
  customValidator: (value) => value !== 'admin' || 'No se permite este valor'
}

🛠️ Desarrollo

Clonar el repositorio

git clone https://github.com/8Wada/ucol-ui.git
cd ucol-ui

Instalar dependencias

pnpm install

Iniciar el entorno de desarrollo

pnpm dev

Ejecutar Storybook

pnpm storybook

📜 Scripts Disponibles

| Script | Descripción | |--------|-------------| | pnpm dev | Inicia el servidor de desarrollo con Vite | | pnpm build | Construye la librería para producción | | pnpm lint | Ejecuta ESLint para revisar el código | | pnpm preview | Previsualiza la build de producción | | pnpm storybook | Inicia Storybook en el puerto 6006 | | pnpm build-storybook | Construye Storybook para producción |

🚀 Tecnologías

• React 19 - Librería de UI
• TypeScript 5.7 - Tipado estático
• Vite 6 - Build tool y dev server
• Ant Design 5 - Framework de componentes UI
• Tailwind CSS 4 - Framework de utilidades CSS
• TanStack Query (React Query) - Gestión de estado del servidor
• Storybook 8 - Desarrollo y documentación de componentes
• React Icons - Iconos
• Axios - Cliente HTTP
• Day.js - Manejo de fechas
• jsPDF & jsPDF-AutoTable - Generación de PDFs
• XLSX - Manejo de archivos Excel
• AJV - Validación de esquemas JSON

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea tu rama de características (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la licencia que especifique el repositorio.

👥 Autores

• @RKamey - Colaborador
• @8Wada - Colaborador

🔗 Enlaces

• Repositorio en GitHub
• Demo en vivo
• Reportar Issues
• NPM Package

Hecho con ❤️ por el equipo de calvos-tsx