@sistemas-ucol-mx/ucol-dynamic 1.0.0

package/README.md

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

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@sistemas-ucol-mx/ucol-dynamic",
+  "version": "1.0.0",
+  "description": "Biblioteca de componentes React con Ant Design y Tailwind CSS",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/ucol-dynamic.umd.cjs",
+  "module": "./dist/ucol-dynamic.js",
+  "types": "./dist/ucol-dynamic.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/ucol-dynamic.js",
+      "require": "./dist/ucol-dynamic.umd.cjs",
+      "types": "./dist/ucol-dynamic.d.ts"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sistemas-ucol-mx/capi_ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sistemas-ucol-mx/capi_ui/issues"
+  },
+  "homepage": "https://ucol-dynamic.netlify.app/",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "vite",
+    "tailwindcss",
+    "antd",
+    "components",
+    "ui-library"
+  ],
+  "author": "Innovardix",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "antd": "6.3.0",
+    "axios": "^1.13.5",
+    "dayjs": "^1.11.13",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "dependencies": {
+    "@ant-design/icons": "^6.1.0",
+    "@tailwindcss/vite": "^4.1.11",
+    "@tanstack/react-query": "^5.67.3",
+    "ajv": "^8.17.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.29.0",
+    "jspdf": "^2.5.2",
+    "jspdf-autotable": "^3.8.4",
+    "react-icons": "^5.4.0",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^3.2.6",
+    "@eslint/js": "^9.17.0",
+    "@storybook/addon-docs": "^8.6.14",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-onboarding": "^8.6.14",
+    "@storybook/addon-storysource": "^8.6.14",
+    "@storybook/addon-styling-webpack": "^1.0.1",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@storybook/test": "^8.6.14",
+    "@tailwindcss/postcss": "^4.0.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
+    "antd": "^6.3.0",
+    "autoprefixer": "^10.4.20",
+    "axios": "^1.13.5",
+    "dayjs": "^1.11.19",
+    "eslint": "^9.17.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "eslint-plugin-storybook": "^0.11.6",
+    "globals": "^15.14.0",
+    "postcss": "^8.4.49",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "storybook": "^8.6.14",
+    "storybook-addon-customize-antd-theme": "^1.1.0",
+    "tailwindcss": "^4.1.11",
+    "terser": "^5.37.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.18.2",
+    "vite": "^7.2.7",
+    "vite-plugin-dts": "^4.5.0"
+  },
+  "eslintConfig": {
+    "extends": [
+      "plugin:storybook/recommended"
+    ]
+  }
+}