@codeplex-sac/utils 0.0.3 → 0.0.6

package/README.md

@@ -1,7 +1,243 @@
-# utils
+# @codeplex-sac/utils
 
-This library was generated with [Nx](https://nx.dev).
+Paquete de utilidades transversales y componentes lógicos esenciales para el ecosistema **Codeplex-SAC**. Incluye herramientas para gestión de modales, portales, animaciones y detección de eventos DOM, todas optimizadas para un rendimiento superior y una API en **Español**.
 
-## Running unit tests
+## 🚀 Instalación
 
-Run `nx test utils` to execute the unit tests via [Vitest](https://vitest.dev/).
+Se recomienda el uso de [bun](https://bun.sh) para una gestión de dependencias óptima.
+
+```bash
+bun add @codeplex-sac/utils @mui/material @emotion/react @emotion/styled
+```
+
+---
+
+## 🏗️ Utilidades y Componentes Lógicos
+
+### 🪟 Grupo 1: Estructura y Capas
+
+#### CodeplexModal
+Componente de diálogo avanzado con soporte para arrastre (Drag), redimensionamiento (Resize) y modo sin bloqueo (Modeless).
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexModal } from '@codeplex-sac/utils';
+import { CodeplexBoton } from '@codeplex-sac/ui';
+
+export const MiModal = () => (
+  <CodeplexModal 
+    open={true} 
+    title="Configuración Avanzada" 
+    subtitle="Ajuste los parámetros del sistema"
+    draggable
+    resizable
+    footer={<CodeplexBoton texto="Guardar" />}
+  >
+    Contenido del modal aquí...
+  </CodeplexModal>
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | - | Controla la visibilidad. |
+| `onClose` | `Function` | - | Evento al cerrar (X, Esc, Click fuera). |
+| `title` | `ReactNode` | - | Título superior. |
+| `subtitle` | `string` | - | Texto informativo bajo el título. |
+| `footer` | `ReactNode` | - | Acciones en la parte inferior. |
+| `draggable` | `boolean` | `false` | Permite mover el modal arrastrando el encabezado. |
+| `resizable` | `boolean` | `false` | Permite cambiar el tamaño desde la esquina inferior. |
+| `locked` | `boolean` | `false` | Impide cerrar al hacer clic fuera o presionar ESC. |
+| `modeless` | `boolean` | `false` | Modal sin fondo oscuro que permite interactuar con lo de atrás. |
+| `maxWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'sm'` | Ancho máximo predefinido. |
+
+---
+
+#### CodeplexPortal
+Permite renderizar contenido en un nodo DOM fuera de la jerarquía actual, ideal para romper el flujo de capas (z-index).
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexPortal } from '@codeplex-sac/utils';
+
+export const Ejemplo = () => (
+  <CodeplexPortal idContenedor="capa-notificaciones">
+    <div>Este contenido se renderiza fuera de su padre.</div>
+  </CodeplexPortal>
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `idContenedor`| `string` | - | ID del elemento DOM donde se insertará el contenido. |
+| `contenedor` | `Element` | `document.body` | Referencia directa al nodo DOM. |
+| `deshabilitarPortal` | `boolean` | `false` | Si es true, renderiza el contenido en su posición original. |
+
+---
+
+#### CodeplexTransiciones
+Suite de componentes para animar la entrada y salida de elementos con una API simplificada.
+
+**Componentes Disponibles:**
+- `CodeplexColapso` (Collapse): Anima la altura.
+- `CodeplexDesvanecimiento` (Fade): Anima la opacidad.
+- `CodeplexCrecimiento` (Grow): Anima escala y opacidad.
+- `CodeplexZoom` (Zoom): Anima escala desde el centro.
+- `CodeplexDeslizamiento` (Slide): Desplaza desde un borde.
+
+**Ejemplo (Deslizamiento):**
+```tsx
+import { CodeplexDeslizamiento } from '@codeplex-sac/utils';
+
+export const Ejemplo = ({ mostrar }) => (
+  <CodeplexDeslizamiento visible={mostrar} direccion="arriba">
+    <div>Contenido animado</div>
+  </CodeplexDeslizamiento>
+);
+```
+
+**Propiedades Comunes:**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `visible` | `boolean` | - | Activa la animación de entrada. |
+| `duracion` | `number \| {enter, exit}` | `300/200` | Tiempo en milisegundos. |
+| `entrada` | `number` | - | Duración específica de entrada. |
+| `salida` | `number` | - | Duración específica de salida. |
+| `direccion`| `'arriba' \| 'abajo' \| 'izquierda' \| 'derecha'` | `'arriba'` | (Solo Slide) Origen del movimiento. |
+
+---
+
+### 🛠️ Grupo 2: Comportamiento y Posicionamiento
+
+#### CodeplexDetectorClicFuera
+Componente invisible que detecta cuando el usuario hace clic o toca fuera de su elemento hijo.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexDetectorClicFuera } from '@codeplex-sac/utils';
+
+export const MenuDesplegable = ({ abierto, alCerrar }) => (
+  <CodeplexDetectorClicFuera alClicFuera={alCerrar}>
+    <div style={{ display: abierto ? 'block' : 'none' }}>
+      Contenido del Menú
+    </div>
+  </CodeplexDetectorClicFuera>
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `alClicFuera` | `Function` | - | Función que se ejecuta al detectar el clic fuera. |
+| `eventoMouse` | `'onClick' \| 'onMouseDown' \| 'onMouseUp' \| false` | `'onClick'` | Evento de ratón a escuchar. |
+| `deshabilitarArbolReact` | `boolean` | `false` | Si es true, ignora si el clic fue dentro del árbol de React. |
+
+---
+
+#### CodeplexVentanaEmergente (Popover)
+Muestra contenido flotante anclado a un elemento. A diferencia del posicionador, este bloquea la interacción con el fondo.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexVentanaEmergente, CodeplexBoton } from '@codeplex-sac/ui';
+
+export const Ejemplo = () => {
+  const [ancla, setAncla] = useState(null);
+  return (
+    <>
+      <CodeplexBoton texto="Abrir Popover" alHacerClick={(e) => setAncla(e.currentTarget)} />
+      <CodeplexVentanaEmergente 
+        abierto={Boolean(ancla)} 
+        elementoAncla={ancla}
+        alCerrar={() => setAncla(null)}
+        titulo="Detalles de Usuario"
+        mostrarIconoCierre
+      >
+        Información detallada aquí...
+      </CodeplexVentanaEmergente>
+    </>
+  );
+};
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `abierto` | `boolean` | - | Visibilidad de la ventana. |
+| `elementoAncla`| `HTMLElement` | - | Elemento que sirve de referencia para la posición. |
+| `titulo` | `ReactNode` | - | Cabecera de la ventana. |
+| `mostrarIconoCierre`| `boolean` | `false` | Muestra la 'X' en la esquina superior. |
+| `alCerrar` | `Function` | - | Callback de cierre. |
+
+---
+
+#### CodeplexPosicionador (Popper)
+Coloca contenido flotante relativo a otro elemento sin bloquear el fondo. Ideal para tooltips personalizados o menús contextuales.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexPosicionador } from '@codeplex-sac/utils';
+
+export const Ejemplo = ({ ancla, abierto }) => (
+  <CodeplexPosicionador 
+    abierto={abierto} 
+    elementoAncla={ancla} 
+    colocacion="right-start" 
+    distancia={10}
+    conFondo
+  >
+    Texto informativo flotante.
+  </CodeplexPosicionador>
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `abierto` | `boolean` | - | Visibilidad. |
+| `elementoAncla`| `HTMLElement` | - | Referencia de posición. |
+| `colocacion` | `string` | `'bottom-start'`| Posición relativa (top, bottom, left, right + start/end). |
+| `conFondo` | `boolean` | `true` | Aplica sombra y fondo blanco (estilo Paper). |
+| `cerrarAlClicFuera` | `boolean` | `false` | Activa detector de clic fuera automáticamente. |
+| `distancia` | `number` | `4` | Separación en píxeles del ancla. |
+
+---
+
+#### CodeplexAreaTextoAjustable
+Área de texto (Textarea) que ajusta su altura automáticamente según el contenido.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexAreaTextoAjustable } from '@codeplex-sac/utils';
+
+export const Comentario = () => (
+  <CodeplexAreaTextoAjustable 
+    etiqueta="Comentarios" 
+    marcador="Escriba aquí..."
+    filasMinimas={3}
+    filasMaximas={10}
+  />
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `variante` | `'contorneado' \| 'relleno' \| 'estandar'` | `'contorneado'` | Estilo visual del campo. |
+| `etiqueta` | `ReactNode` | - | Label superior. |
+| `filasMinimas` | `number` | `3` | Altura inicial. |
+| `filasMaximas` | `number` | - | Altura máxima antes de scroll. |
+| `error` | `boolean` | `false` | Activa estado de error visual. |
+| `mensajeError` | `ReactNode` | - | Texto informativo de error. |
+
+---
+
+## 🎨 Personalización
+
+Los componentes de `@codeplex-sac/utils` están diseñados para integrarse fluidamente con el sistema de temas de **Codeplex-SAC**, heredando colores y tipografías globales.
+
+## 📄 Licencia
+
+Este proyecto es propiedad privada de **Codeplex SAC**. Todos los derechos reservados.

package/index.d.ts

@@ -1,7 +1,7 @@
-export * from './lib/click-away-listener/click-away-listener';
+export * from './lib/detector-clic-fuera/detector-clic-fuera';
 export * from './lib/modal/modal';
-export * from './lib/popover/popover';
-export * from './lib/popper/popper';
+export * from './lib/ventana-emergente/ventana-emergente';
+export * from './lib/posicionador/posicionador';
 export * from './lib/portal/portal';
-export * from './lib/textarea-autosize/textarea-autosize';
-export * from './lib/transitions/transitions';
+export * from './lib/area-texto-ajustable/area-texto-ajustable';
+export * from './lib/transiciones/transiciones';