@codeplex-sac/utils

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

Se recomienda el uso de bun para una gestión de dependencias óptima.

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:

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:

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):

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:

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:

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:

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:

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.