@dropi/ui-react
v0.1.13
Published
React wrappers for @dropi/ui web components — Dropi Design System
Downloads
997
Readme
@dropi/ui-react
React wrappers tipados para los Web Components de @dropi/ui.
Provee componentes React con props explícitas, eventos estilo React (onDropiChange) e IntelliSense completo en VSCode.
Instalación
npm install @dropi/ui-react
@dropi/uise instala automáticamente como dependencia.
Setup (main.tsx)
import '@dropi/ui/dist/dropi-ui/dropi-ui.css'No hace falta llamar
defineCustomElements(). Cada wrapper de@dropi/ui-reactregistra su propio custom element automáticamente al importarse.
Vite (vite.config.ts)
export default defineConfig({
optimizeDeps: {
exclude: ['@dropi/ui/loader', '@dropi/ui']
}
})Íconos — copiar sprite a public/
node_modules/@dropi/ui/dist/dropi-ui/assets/icons/symbol/svg/sprite.css.svg
→ public/assets/icons/symbol/svg/sprite.css.svgUso
import { DropiButton, DropiInput, DropiSelect } from '@dropi/ui-react'
import type { SelectOption } from '@dropi/ui-react'
const options: SelectOption[] = [
{ id: 1, label: 'Colombia' },
{ id: 2, label: 'México' },
]
function App() {
return (
<>
<DropiButton text="Guardar" onDropiClick={(e) => console.log(e.detail)} />
<DropiInput label="Nombre" onDropiInput={(e) => console.log(e.detail)} />
<DropiSelect label="País" options={options} onDropiChange={(e) => console.log(e.detail)} />
</>
)
}Los eventos emiten
CustomEvent— el valor siempre está ene.detail.
📋 Soporte para Formularios Nativos (FormData)
¡Olvídate de manejar 20 estados useState para un solo formulario!
Todos los componentes de entrada en @dropi/ui-react se integran automáticamente con el estándar FormData del navegador. Solo necesitas ponerle un name al componente.
const RegisterForm = () => {
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const data = Object.fromEntries(new FormData(e.currentTarget));
console.log(data); // { email: "...", country: "CO", phone: "+57..." }
};
return (
<form onSubmit={handleSubmit}>
<DropiInput name="email" label="Email" required />
<DropiCountrySelector name="country" label="País" />
<DropiPhoneInput name="phone" label="Celular" />
<DropiButton nativeType="submit" text="Crear Cuenta" />
</form>
);
};🏛️ Componentes Disponibles (65+)
Esta librería incluye más de 65 componentes listos para usar en React.
Para ver la lista completa de componentes, sus propiedades (Props) y eventos (Events), por favor consulta el:
👉 Catálogo Maestro de @dropi/ui
Next.js (SSR)
Instalación del plugin
npm install @stencil/ssrConfiguración (next.config.ts)
import type { NextConfig } from "next";
import withStencil from "@stencil/ssr/next";
const nextConfig: NextConfig = {};
export default withStencil({
from: "@dropi/ui-react",
module: import("@dropi/ui-react/next"),
hydrateModule: import("@dropi/ui/hydrate"),
})(nextConfig);Entry point para Server Components
En Server Components (sin "use client"), importar siempre de @dropi/ui-react/next:
// page.tsx — Server Component
import { DropiButton, DropiBadge } from "@dropi/ui-react/next";
export default function Page() {
return <DropiButton text="Guardar" severity="primary" />;
}Íconos en Next.js
Copiar el sprite SVG al directorio public/:
node_modules/@dropi/ui/dist/dropi-ui/assets/icons/symbol/svg/sprite.css.svg
→ public/assets/icons/symbol/svg/sprite.css.svgAtajo con script en package.json:
"scripts": {
"postinstall": "cp -r node_modules/@dropi/ui/dist/dropi-ui/assets/icons public/assets/icons"
}Lottie en Next.js
Agregar el script en app/layout.tsx:
<Script
src="https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js"
strategy="beforeInteractive"
/>Estabilidad visual (Zero Flash en Next.js 15+)
Sigue estos pasos obligatorios para garantizar una carga instantánea sin parpadeos:
1. Configurar el Layout (Crítico)
Añade suppressHydrationWarning a la etiqueta <body> en src/app/layout.tsx. Esto evita que el DevTools o las extensiones rompan la hidratación al inyectar clases o estilos dinámicos.
// src/app/layout.tsx
export default function RootLayout({ children }) {
return (
<html>
<body suppressHydrationWarning>{children}</body>
</html>
);
}2. Usar el Entry Point /next
Importa todos los componentes desde @dropi/ui-react/next, tanto en Server Components como en Client Components ("use client"). Esto activa el Declarative Shadow DOM (DSD).
import { DropiBannerExternal } from '@dropi/ui-react/next';3. Evitar el Flash con Props Dinámicas (Uso de Alias)
Cuando un componente tiene props que dependen del estado o variables dinámicas en un archivo "use client", el plugin de build-time de Stencil puede generar un Shadow DOM vacío antes de la hidratación.
Solución: Usa un alias al importar el componente. Esto hace que el plugin ignore la llamada en build-time y React tome el control total en runtime con los valores correctos.
"use client";
// El alias (ActionButton) evita que withStencil intercepte el JSX en build-time
import { DropiButton as ActionButton } from "@dropi/ui-react/next";
export function ClientComp({ nombre }: { nombre: string }) {
return <ActionButton text={nombre} />;
}Causa raíz:
withStencildetecta componentes por el nombre de variable exacto (ej.DropiButton). Si lo renombras mediante un alias, el plugin no lo intercepta y evitas que se serialice con propsnulldurante la fase de compilación.
4. Resets CSS Necesarios
Añade esto a globals.css para reservar el espacio de los iconos y evitar saltos de layout:
/* Reserva espacio para iconos antes de la hidratación */
dropi-icon:not(.hydrated) {
width: 20px;
height: 20px;
display: inline-flex;
}Componentes excluidos del SSR (No requieren alias ni /next obligatoriamente):
DropiAlertModal, DropiModal, DropiToast, DropiDrawer.
Estos componentes son overlays/portales y se renderizan exclusivamente en el cliente.