@codeplex-sac/superposiciones

Utilidades de posicionamiento, portales y transiciones para aplicaciones React, basadas en Material UI. API en Español con retrocompatibilidad silenciosa para props en inglés.

Instalación

bun add @codeplex-sac/superposiciones @codeplex-sac/tema @mui/material @emotion/react @emotion/styled

Componentes

CodeplexPortal

Renderiza hijos fuera de la jerarquía DOM del componente padre (útil para modales, tooltips y overlays).

Ejemplo:

import { CodeplexPortal } from '@codeplex-sac/superposiciones';

export const Ejemplo = () => (
  <CodeplexPortal idContenedor="portal-root">
    <div>Esto se renderiza dentro de #portal-root, no del padre React.</div>
  </CodeplexPortal>
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | contenedor | Element \| (() => Element) \| null | — | Nodo DOM de destino. | | idContenedor | string | — | ID del nodo DOM de destino (alternativa a contenedor). | | deshabilitarPortal | boolean | false | Si true, renderiza en el lugar original. | | children | ReactNode | — | Contenido a teletransportar. |

CodeplexPosicionador

Popper con Panel flotante que se posiciona relativo a un elemento ancla.

Ejemplo:

import { CodeplexPosicionador } from '@codeplex-sac/superposiciones';
import { useState, useRef } from 'react';

export const Ejemplo = () => {
  const [abierto, setAbierto] = useState(false);
  const ancla = useRef<HTMLButtonElement>(null);

  return (
    <>
      <button ref={ancla} onClick={() => setAbierto(!abierto)}>Opciones</button>
      <CodeplexPosicionador
        abierto={abierto}
        elementoAncla={ancla.current}
        colocacion="bottom-start"
        cerrarAlClicFuera
        alCerrar={() => setAbierto(false)}
        titulo="Acciones disponibles"
      >
        <p>Contenido del panel flotante</p>
      </CodeplexPosicionador>
    </>
  );
};

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | abierto | boolean | — | Controla la visibilidad del panel. | | elementoAncla | PopperProps['anchorEl'] | — | Elemento de referencia para posicionarse. | | colocacion | PopperPlacementType | 'bottom-start' | Posición relativa al ancla. | | titulo | ReactNode | — | Cabecera del panel. | | estiloContenido | SxProps | — | Estilos del contenedor interno. | | conFondo | boolean | true | Envuelve el contenido en un Paper. | | transicion | boolean | true | Activa animación Fade al abrir/cerrar. | | distancia | number | 4 | Separación en px del elemento ancla. | | cerrarAlClicFuera | boolean | false | Cierra el panel al clicar fuera. | | alCerrar | (e: MouseEvent \| TouchEvent) => void | — | Callback al clicar fuera (requiere cerrarAlClicFuera). | | hijos | ReactNode | — | Contenido del panel (alias de children). |

CodeplexDetectorClicFuera

Wrapper que ejecuta un callback cuando el usuario hace clic fuera del área envuelta.

Ejemplo:

import { CodeplexDetectorClicFuera } from '@codeplex-sac/superposiciones';
import { useState } from 'react';

export const Ejemplo = () => {
  const [abierto, setAbierto] = useState(true);

  return (
    <CodeplexDetectorClicFuera alClickFuera={() => setAbierto(false)}>
      {abierto && (
        <div style={{ background: 'white', padding: 16, border: '1px solid #ccc' }}>
          Haz clic fuera para cerrar este panel.
        </div>
      )}
    </CodeplexDetectorClicFuera>
  );
};

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | alClickFuera | (e: MouseEvent \| TouchEvent) => void | — | Callback al detectar clic exterior. | | deshabilitado | boolean | false | Desactiva la detección. | | children | ReactNode | — | Área a monitorear. |

Transiciones

Wrappers en Español para las transiciones nativas de MUI: Collapse, Fade, Grow, Slide, Zoom.

Componentes exportados:

• CodeplexColapso → Collapse
• CodeplexDesvanecer → Fade
• CodeplexCrecer → Grow
• CodeplexDeslizar → Slide
• CodeplexZoom → Zoom

Ejemplo con CodeplexDesvanecer:

import { CodeplexDesvanecer } from '@codeplex-sac/superposiciones';
import { useState } from 'react';

export const Ejemplo = () => {
  const [visible, setVisible] = useState(true);

  return (
    <>
      <button onClick={() => setVisible(!visible)}>Toggle</button>
      <CodeplexDesvanecer visible={visible} duracion={400}>
        <div>Contenido que aparece y desaparece con fade.</div>
      </CodeplexDesvanecer>
    </>
  );
};

Props comunes a todas las transiciones: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | visible | boolean | — | Controla si el elemento es visible. | | duracion | number \| { enter?, exit? } | { enter: 300, exit: 200 } | Duración de la animación en ms. | | duracionEntrada | number | — | Duración de la animación de entrada. | | duracionSalida | number | — | Duración de la animación de salida. | | children | ReactNode | — | Elemento a animar. |

Props específicas de CodeplexDeslizar: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | direccion | 'arriba' \| 'abajo' \| 'izquierda' \| 'derecha' | 'abajo' | Dirección del deslizamiento. |

Licencia

Propiedad privada de Codeplex SAC. Todos los derechos reservados.