npm package: @sistemas-ucol-mx/ucol-dynamic
Description: Biblioteca de componentes React con Ant Design y Tailwind CSS
Author: Direccion De Sistemas Universidad de Colima
Latest version: 1.2.3

# ucol-dynamic

<div align="center">

![Version](https://img.shields.io/badge/version-0.1.23-blue.svg)
![React](https://img.shields.io/badge/react-19.0.0-61dafb.svg)
![TypeScript](https://img.shields.io/badge/typescript-5.7.3-blue.svg)
![Ant Design](https://img.shields.io/badge/antd-5.24.0-1890ff.svg)
![TailwindCSS](https://img.shields.io/badge/tailwindcss-4.1.11-38bdf8.svg)

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

[Demo en vivo](https://ucol-dynamic.netlify.app/) | [Documentación](https://github.com/8Wada/ucol-dynamic) | [Reportar un error](https://github.com/8Wada/ucol-dynamic/issues)

</div>

---

## 📋 Tabla de Contenidos

- [Características](#-características)
- [Instalación](#-instalación)
- [Componentes Principales](#-componentes-principales)
- [Guía de Inicio Rápido](#-guía-de-inicio-rápido)
- [Documentación de Componentes](#-documentación-de-componentes)
- [Hooks Personalizados](#-hooks-personalizados)
- [API y Configuración](#-api-y-configuración)
- [Desarrollo](#-desarrollo)
- [Scripts Disponibles](#-scripts-disponibles)
- [Tecnologías](#-tecnologías)
- [Contribuir](#-contribuir)
- [Licencia](#-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

```bash
npm install @sistemas-ucol-mx/ucol-dynamic
```

### Usando bun

```bash
bun add @sistemas-ucol-mx/ucol-dynamic

### Usando pnpm

```bash
pnpm install @sistemas-ucol-mx/ucol-dynamic
```


o

```bash
pnpm add @sistemas-ucol-mx/ucol-dynamic
```

### Usando yarn

```bash
yarn add @sistemas-ucol-mx/ucol-dynamic
```

## 📚 Peer Dependencies

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

```json
{
  "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

```bash
npm install antd axios dayjs react react-dom
```

### Importar estilos

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

```tsx
import '@sistemas-ucol-mx/ucol-dynamic/dist/style.css';
```

## 🧩 Componentes Principales

### 🎯 DynamicCrud

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

```tsx
import { DynamicCrud } from '@sistemas-ucol-mx/ucol-dynamic';

<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.

```tsx
import { DynamicForm } from '@sistemas-ucol-mx/ucol-dynamic';

<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.

```tsx
import { DynamicTable } from '@sistemas-ucol-mx/ucol-dynamic';

<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.

```tsx
import { Btn } from '@sistemas-ucol-mx/ucol-dynamic';

// 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.

```tsx
import { PermissionsProvider, usePermissions } from '@sistemas-ucol-mx/ucol-dynamic';

// 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.

```tsx
import { BulkUploadModal } from '@sistemas-ucol-mx/ucol-dynamic';

<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.

```tsx
import { SharedField } from '@sistemas-ucol-mx/ucol-dynamic';

<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.

```tsx
import { useCrudOperations } from '@sistemas-ucol-mx/ucol-dynamic';

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.

```tsx
import { useFetchQuery } from '@sistemas-ucol-mx/ucol-dynamic';

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.

```tsx
import { openNotification } from '@sistemas-ucol-mx/ucol-dynamic';

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.

```tsx
import { useAsync } from '@sistemas-ucol-mx/ucol-dynamic';

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

```tsx
<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

```tsx
{
  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'
}
```

## 🚀 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

## 👥 Autores

- **@RKamey** - *Colaborador*
- **@8Wada** - *Colaborador*

---

<div align="center">

**Hecho con ❤️ por el equipo de Innovardix**

</div>