@codeplex-sac/utils 0.0.4 → 0.0.7

package/README.md

@@ -1,93 +1,243 @@
 # @codeplex-sac/utils
 
-Utilidades de bajo nivel y componentes auxiliares para la construcción de interfaces complejas.
+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**.
 
-## 📦 Instalación
+## 🚀 Instalación
+
+Se recomienda el uso de [bun](https://bun.sh) para una gestión de dependencias óptima.
 
 ```bash
-pnpm add @mui/material @codeplex-sac/utils
+bun add @codeplex-sac/utils @mui/material @emotion/react @emotion/styled
 ```
 
 ---
 
-## 🛠️ Utilidades de Comportamiento
+## 🏗️ Utilidades y Componentes Lógicos
+
+### 🪟 Grupo 1: Estructura y Capas
 
-### `<CodeplexDetectorClickFuera />` (Click Away Listener)
-Detecta clics fuera del elemento hijo. Ideal para cerrar menús o dropdowns customizados.
+#### CodeplexModal
+Componente de diálogo avanzado con soporte para arrastre (Drag), redimensionamiento (Resize) y modo sin bloqueo (Modeless).
 
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexDetectorClickFuera alHacerClickFuera={() => setAbierto(false)}>
-    <div className="menu-dropdown">
-        ...
-    </div>
-</CodeplexDetectorClickFuera>
+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>
+);
 ```
-| Propiedad | Descripción |
-| :--- | :--- |
-| `alHacerClickFuera` | Callback ejecutado al detectar clic fuera. |
 
-### `<CodeplexPortal />`
-Renderiza hijos en un nodo DOM diferente (react portals).
+**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. |
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `containerId` | ID del elemento DOM destino. |
-| `container` | Referencia directa al nodo DOM (opcional). |
+---
+
+#### 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. |
 
 ---
 
-## 🪟 Ventanas y Capas
-
-### `<CodeplexModal />`
-Wrapper simplificado para Modales.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `titulo` | Título pre-estilizado en la cabecera. |
-| `descripcion` | Texto descriptivo (`aria-describedby`). |
-| `ancho` | Ancho del modal (default: 400). |
-| `mostrarIconoCierre` | `boolean`. Botón "X" en la esquina. |
-
-### `<CodeplexPopover />`
-Popups anclados a elementos.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `title` | Título del popover. |
-| `showCloseIcon` | Muestra botón de cierre. |
-| `anchorEl` | Elemento al que se ancla. |
-
-### `<CodeplexPopper />`
-Posicionamiento avanzado (base de Tooltips/Popovers) usando Popper.js.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `withPaper` | `boolean`. Envuelve el contenido en un Paper elevado. |
-| `closeOnClickAway` | `boolean`. Cierra al hacer clic fuera. |
+#### 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. |
 
 ---
 
-## 📝 Entradas Especiales
+### 🛠️ Grupo 2: Comportamiento y Posicionamiento
 
-### `<CodeplexTextareaAutosize />`
-Textarea que crece con el contenido pero mantiene el estilo visual de los Inputs de Material UI.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `variant` | `'outlined' \| 'filled' \| 'standard'`. |
-| `minRows` | Filas mínimas iniciales. |
-| `error` | Estado visual de error (borde rojo). |
+#### 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. |
 
 ---
 
-## 🎞️ Transiciones
+#### 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. |
 
-Wrappers con timeouts por defecto suavizados para animaciones consistentes. Use las props estándar de MUI como `in`, `mountOnEnter`, `unmountOnExit`.
+---
 
-*   `CodeplexColapso` (Collapse)
-*   `CodeplexDesvanecimiento` (Fade)
-*   `CodeplexCrecimiento` (Grow)
-*   `CodeplexZoom`
-*   `CodeplexDeslizamiento` (Slide) - Prop extra: `direction` ('up', 'down', 'left', 'right').
+#### 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
-<CodeplexDesvanecimiento in={visible}>
-    <div>Contenido animado</div>
-</CodeplexDesvanecimiento>
+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';