carconnect-gatherleads-ui-lib 2.4.0 → 2.4.2

package/README.md

@@ -2614,3 +2614,399 @@ const apiData = await fetch('/api/users').then((r) => r.json());
 ```
 
 Esta guía completa cubre todos los aspectos de GatherTable, desde uso básico hasta implementaciones avanzadas con ordenamiento, filtrado y renderizado personalizado.
+
+# 🪟 Guía Completa de GatherModal
+
+## 🎯 Introducción
+
+`GatherModal` es un componente modal genérico y altamente personalizable que proporciona diálogos flexibles con soporte completo para diferentes posiciones, tamaños, animaciones y accesibilidad avanzada.
+
+## 🏗️ Características Principales
+
+- **Posiciones**: center, left, right (ideal para paneles laterales)
+- **Tamaños**: sm, md, lg, xl, full
+- **Header personalizable**: Título simple o contenido completamente custom
+- **Footer flexible**: Botones por defecto o contenido personalizado
+- **Accesibilidad avanzada**: Focus management, keyboard navigation
+- **Animaciones**: Transiciones suaves configurables
+- **Portal rendering**: Se renderiza fuera del árbol DOM
+
+## 📋 Uso Básico
+
+### Modal Simple de Confirmación
+
+```tsx
+import { GatherModal } from '@/base/modal';
+import { useState } from 'react';
+
+const BasicModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Abrir Modal</button>
+
+      <GatherModal
+        open={isOpen}
+        onClose={() => setIsOpen(false)}
+        header={{
+          title: 'Confirmar Acción',
+          subtitle: '¿Estás seguro de continuar?',
+        }}
+        footer={{
+          acceptText: 'Confirmar',
+          cancelText: 'Cancelar',
+          acceptVariant: 'gather-primary',
+          cancelVariant: 'gather-outline',
+          onAccept: () => {
+            console.log('Confirmado');
+            setIsOpen(false);
+          },
+          onCancel: () => setIsOpen(false),
+        }}
+      >
+        <p>Esta acción no se puede deshacer.</p>
+      </GatherModal>
+    </>
+  );
+};
+```
+
+### Modal de Formulario
+
+```tsx
+const FormModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async () => {
+    setLoading(true);
+    try {
+      // Simular API call
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      setIsOpen(false);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <GatherModal
+      open={isOpen}
+      onClose={() => setIsOpen(false)}
+      size='lg'
+      header={{
+        title: 'Nuevo Usuario',
+        subtitle: 'Complete los datos del usuario',
+      }}
+      footer={{
+        acceptText: 'Guardar',
+        cancelText: 'Cancelar',
+        acceptLoading: loading,
+        acceptDisabled: loading,
+        onAccept: handleSubmit,
+        onCancel: () => setIsOpen(false),
+      }}
+    >
+      <div className='space-y-4'>
+        <div>
+          <label className='mb-1 block text-sm font-medium'>
+            Nombre completo
+          </label>
+          <input
+            type='text'
+            className='w-full rounded border p-2'
+            placeholder='Juan Pérez'
+          />
+        </div>
+        <div>
+          <label className='mb-1 block text-sm font-medium'>Email</label>
+          <input
+            type='email'
+            className='w-full rounded border p-2'
+            placeholder='juan@ejemplo.com'
+          />
+        </div>
+      </div>
+    </GatherModal>
+  );
+};
+```
+
+## 🎨 Posiciones y Tamaños
+
+### Modal Centrado (Por Defecto)
+
+```tsx
+<GatherModal
+  open={isOpen}
+  position='center' // Por defecto
+  size='md' // Tamaño mediano
+  onClose={() => setIsOpen(false)}
+>
+  <p>Modal centrado en la pantalla</p>
+</GatherModal>
+```
+
+### Panel Lateral Derecho
+
+```tsx
+<GatherModal
+  open={isOpen}
+  position='right'
+  size='lg'
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Panel de Configuración',
+  }}
+>
+  <div className='space-y-4'>
+    <h3>Configuraciones</h3>
+    <div>Contenido del panel lateral...</div>
+  </div>
+</GatherModal>
+```
+
+### Modal de Pantalla Completa
+
+```tsx
+<GatherModal
+  open={isOpen}
+  size='full'
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Vista Completa',
+  }}
+  scrollBehavior={{
+    bodyScrollable: true,
+    bodyMaxHeight: '80vh',
+  }}
+>
+  <div>Contenido que ocupa toda la pantalla...</div>
+</GatherModal>
+```
+
+## 🔧 Configuración Avanzada
+
+### Modal con Contenido Personalizado
+
+```tsx
+<GatherModal
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  header={{
+    children: (
+      <div className='flex items-center gap-3'>
+        <div className='flex h-8 w-8 items-center justify-center rounded-full bg-blue-500'>
+          <span className='text-sm text-white'>!</span>
+        </div>
+        <div>
+          <h2 className='text-lg font-semibold'>Advertencia</h2>
+          <p className='text-sm text-gray-600'>Acción requerida</p>
+        </div>
+      </div>
+    ),
+    showCloseButton: true,
+  }}
+  footer={{
+    children: (
+      <div className='flex w-full justify-between'>
+        <span className='text-sm text-gray-500'>
+          Última actualización: hace 5 min
+        </span>
+        <div className='flex gap-2'>
+          <button className='rounded px-4 py-2 text-gray-600 hover:bg-gray-100'>
+            Ignorar
+          </button>
+          <button className='rounded bg-red-500 px-4 py-2 text-white hover:bg-red-600'>
+            Resolver
+          </button>
+        </div>
+      </div>
+    ),
+  }}
+>
+  <p>Contenido del modal con header y footer personalizados.</p>
+</GatherModal>
+```
+
+### Modal con Scroll Personalizado
+
+```tsx
+<GatherModal
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  header={{
+    title: 'Contenido Extenso',
+    scrollable: true,
+    maxHeight: '150px',
+  }}
+  scrollBehavior={{
+    bodyScrollable: true,
+    bodyMaxHeight: '400px',
+    modalScrollable: false,
+  }}
+  footer={{
+    scrollable: true,
+    maxHeight: '100px',
+  }}
+>
+  <div className='space-y-4'>
+    {Array.from({ length: 20 }, (_, i) => (
+      <p key={i}>
+        Párrafo {i + 1}: Lorem ipsum dolor sit amet consectetur adipisicing
+        elit...
+      </p>
+    ))}
+  </div>
+</GatherModal>
+```
+
+## ⚙️ Props Principales
+
+### Props del Modal
+
+```tsx
+interface GatherModalProps {
+  // ESTADO
+  open: boolean; // Si el modal está abierto
+  onClose?: () => void; // Función de cierre
+
+  // DISEÑO
+  position?: 'center' | 'left' | 'right'; // Posición
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full'; // Tamaño
+
+  // COMPORTAMIENTO
+  closeOnOverlayClick?: boolean; // Cerrar al hacer clic fuera
+  closeOnEscape?: boolean; // Cerrar con tecla Escape
+  preventBodyScroll?: boolean; // Prevenir scroll del body
+  autoFocus?: boolean; // Enfocar automáticamente
+
+  // CONTENIDO
+  header?: GatherModalHeaderProps; // Configuración del header
+  footer?: GatherModalFooterProps; // Configuración del footer
+  children: React.ReactNode; // Contenido principal
+
+  // ACCESIBILIDAD Y ANIMACIÓN
+  animationDuration?: number; // Duración de animaciones (ms)
+  zIndex?: number; // Z-index base
+  scrollBehavior?: ScrollConfig; // Configuración de scroll
+}
+```
+
+### Props del Header
+
+```tsx
+interface GatherModalHeaderProps {
+  title?: string; // Título del modal
+  subtitle?: string; // Subtítulo
+  showCloseButton?: boolean; // Mostrar botón X
+  onClose?: () => void; // Función del botón cerrar
+  closeIcon?: React.ReactNode; // Ícono personalizado
+  scrollable?: boolean; // Si el header hace scroll
+  children?: React.ReactNode; // Contenido personalizado
+}
+```
+
+### Props del Footer
+
+```tsx
+interface GatherModalFooterProps {
+  // BOTONES POR DEFECTO
+  acceptText?: string; // Texto botón aceptar
+  cancelText?: string; // Texto botón cancelar
+  onAccept?: () => void; // Acción de aceptar
+  onCancel?: () => void; // Acción de cancelar
+
+  // ESTADOS DE LOS BOTONES
+  acceptLoading?: boolean; // Loading en botón aceptar
+  acceptDisabled?: boolean; // Deshabilitar aceptar
+
+  // VARIANTES Y DISEÑO
+  acceptVariant?: ButtonVariant; // Estilo del botón aceptar
+  cancelVariant?: ButtonVariant; // Estilo del botón cancelar
+  buttonsOrder?: 'normal' | 'reverse'; // Orden de botones
+  buttonsAlignment?: 'start' | 'center' | 'end' | 'between';
+
+  // PERSONALIZACIÓN
+  children?: React.ReactNode; // Footer completamente personalizado
+  scrollable?: boolean; // Si el footer hace scroll
+}
+```
+
+## 🎯 Casos de Uso Comunes
+
+### Modal de Confirmación de Eliminación
+
+```tsx
+const DeleteConfirmModal = ({ item, onConfirm, onCancel }) => (
+  <GatherModal
+    open={!!item}
+    onClose={onCancel}
+    size='sm'
+    header={{
+      title: 'Confirmar Eliminación',
+      subtitle: '¿Estás seguro de eliminar este elemento?',
+    }}
+    footer={{
+      acceptText: 'Eliminar',
+      cancelText: 'Cancelar',
+      acceptVariant: 'gather-error',
+      onAccept: () => onConfirm(item),
+      onCancel: onCancel,
+    }}
+  >
+    <p>Esta acción no se puede deshacer.</p>
+    {item && (
+      <div className='mt-3 rounded bg-gray-50 p-3'>
+        <strong>{item.name}</strong>
+      </div>
+    )}
+  </GatherModal>
+);
+```
+
+### Panel de Detalles Lateral
+
+```tsx
+const DetailsSidebar = ({ user, isOpen, onClose }) => (
+  <GatherModal
+    open={isOpen}
+    onClose={onClose}
+    position='right'
+    size='lg'
+    header={{
+      title: 'Detalles del Usuario',
+      subtitle: user?.name,
+    }}
+    preventBodyScroll={true}
+  >
+    {user && (
+      <div className='space-y-6'>
+        <div className='text-center'>
+          <img
+            src={user.avatar}
+            alt={user.name}
+            className='mx-auto mb-4 h-20 w-20 rounded-full'
+          />
+          <h3 className='text-xl font-semibold'>{user.name}</h3>
+          <p className='text-gray-600'>{user.email}</p>
+        </div>
+
+        <div className='space-y-4'>
+          <div>
+            <label className='font-medium'>Departamento</label>
+            <p>{user.department}</p>
+          </div>
+          <div>
+            <label className='font-medium'>Rol</label>
+            <p>{user.role}</p>
+          </div>
+        </div>
+      </div>
+    )}
+  </GatherModal>
+);
+```
+
+Esta guía cubre los aspectos principales de GatherModal, proporcionando ejemplos prácticos para implementaciones comunes desde modales simples hasta paneles laterales complejos.