@letkode/flyonui-react

Biblioteca de componentes React sobre FlyonUI 2.x + Tailwind CSS v4.

Instalación

npm install @letkode/flyonui-react
# o
pnpm add @letkode/flyonui-react

Peer dependencies requeridas

pnpm add react react-dom flyonui

Peer dependencies opcionales

Instala solo las que necesites según los componentes que uses:

| Componente | Paquete | |---|---| | Datepicker | flatpickr | | RangeSlider | nouislider | | Rating | raty-js | | DragDrop | sortablejs | | FileUpload | dropzone | | NotyfToasts | notyf | | Charts | apexcharts | | Calendar | fullcalendar @fullcalendar/daygrid @fullcalendar/timegrid @fullcalendar/list @fullcalendar/interaction | | WYSIWYGEditor | @editorjs/editorjs | | CopyToClipboard | clipboard | | DataTable | jquery datatables.net | | WaveEffect | node-waves |

Uso rápido

import { Button, Modal, Tabs } from '@letkode/flyonui-react'

export default function App() {
  return <Button variant="primary">Hola FlyonUI</Button>
}

Toasts globales

Monta <NotyfToasts /> una vez en tu layout raíz:

import { NotyfToasts, toast } from '@letkode/flyonui-react'

// En tu layout:
<NotyfToasts position="top-right" duration={3000} />

// Desde cualquier parte:
await toast.success('Operación completada')
await toast.error('Ha ocurrido un error')
await toast.info('Nuevo mensaje')
await toast.warning('Sesión próxima a expirar')

Componentes

Core

| Export | Descripción | |--------|-------------| | useFlyonUI | Hook base para integración con plugins HS*. Gestiona loadPlugin, el ciclo autoInit/destroy y el containerRef. | | loadPlugin | Carga singleton de un plugin FlyonUI por path. Garantiza que cada script se carga una sola vez. | | PLUGINS | Mapa de claves semánticas a paths de plugins FlyonUI (accordion, modal, tabs, etc.) |

components/ — UI Core (24 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | Accordion | Secciones colapsables con soporte múltiple y items con defaultOpen | → | | Alert | Alertas dismissibles con variantes de color e icono opcional | → | | Avatar | Avatar con imagen o iniciales, tamaños y badge de estado de presencia | → | | Badge | Etiquetas de estado con variantes, tamaños y modo outline/dot | → | | Button | Botón con variantes, tamaños, estado loading y modo iconOnly | → | | Card | Tarjeta con imagen, título, subtítulo, cuerpo y acciones | → | | Carousel | Carrusel de slides con autoplay, flechas y puntos de paginación | → | | ChatBubble | Burbuja de chat con soporte start/end, avatar, emisor y timestamp | → | | Collapse | Contenido colapsable con trigger personalizable | → | | Diff | Comparador visual before/after con resizer arrastrable | → | | Indicator | Indicador/badge posicionado sobre otro elemento | → | | ListGroup | Lista agrupada de items | → | | Loading | Indicador de carga con spinner, dots, ring, etc. | → | | Progress | Barra de progreso con variantes de color | → | | RadialProgress | Progreso circular con valor numérico | → | | RemoveElement | Wrapper para eliminar su contenido del DOM con animación | → | | Skeleton | Placeholder de carga con efecto shimmer | → | | Stack | Apilado de elementos con soporte de profundidad | → | | Stat | Bloque de estadística con título, valor y descripción | → | | Status | Indicador de estado (dot con color) | → | | Swap | Toggle entre dos estados visuales; soporta rotate y flip | → | | ThemeController | Toggle dark/light mode que actualiza data-theme en el HTML | → | | Timeline | Línea de tiempo con items verticales u horizontales | → | | TreeView | Árbol jerárquico con nodos colapsables e iconos | → |

form/ — Formularios básicos (9 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | Input | Input de texto con label, error, icono, floating label y validación visual | → | | Textarea | Área de texto con label, error y autosize opcional | → | | Checkbox | Casilla con variantes de color, tamaños y soporte indeterminate | → | | Radio | Botón de radio con variantes y tamaños | → | | Switch | Toggle switch con variantes de color y tamaños | → | | Range | Input range nativo de FlyonUI con estilos | → | | FileInput | Input de archivo nativo con estilos FlyonUI | → | | Filter | Grupo de filtros tipo chip/pill para selección única | → | | Join | Agrupa inputs y botones en una línea sin bordes intermedios | → |

advanced-forms/ — Formularios avanzados (8 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | AdvancedSelect | Select mejorado con búsqueda, múltiple selección y grupos de opciones | → | | ComboBox | Input con autocompletado y lista de sugerencias | → | | PinInput | Input de código PIN/OTP con N dígitos | → | | InputNumber | Input numérico con botones +/− y step configurable | → | | StrongPassword | Indicador de fortaleza de contraseña vinculado a un input | → | | TogglePassword | Botón para mostrar/ocultar contraseña en un input | → | | CopyMarkup | Botón que copia el contenido de un elemento al portapapeles | → | | FormWizard | Re-export de Stepper con semántica de asistente de formulario | → |

navigations/ — Navegación (9 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | Tabs | Pestañas con variantes: default, pills, lifted, boxed | → | | Stepper | Asistente paso a paso, horizontal o vertical, con barra de progreso | → | | Breadcrumb | Ruta de navegación con soporte de hrefs e iconos | → | | Pagination | Paginación controlada con botones primera/última página opcionales | → | | Footer | Pie de página con secciones, logo, copyright y redes sociales | → | | Menu | Menú de navegación con submenús, iconos, badges; horizontal u vertical | → | | Navbar | Barra de navegación sticky con slots start, center y end | → | | Scrollspy | Menú lateral que resalta el item según la sección visible en pantalla | → | | Sidebar | Barra lateral con items anidados colapsables, header y footer | → |

overlays/ — Overlays (6 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | Modal | Diálogo modal controlado (open/onClose) con tamaños y footer | → | | Drawer | Panel lateral controlado con placement configurable | → | | Dropdown | Menú desplegable con placement configurable e items divider | → | | Tooltip | Tooltip de texto con placement (top/bottom/left/right) | → | | Popover | Popover con título, contenido React y trigger click/hover | → | | ContextMenu | Menú contextual (clic derecho) con posición dinámica y cierre automático | → |

tables/

| Componente | Descripción | Docs | |------------|-------------|------| | DataTable | Tabla con paginación, búsqueda, ordenación, carga AJAX y callback onRowClick | → |

mockups/ (4 componentes)

| Componente | Descripción | Docs | |------------|-------------|------| | BrowserMockup | Mockup de navegador con barra de URL | → | | CodeMockup | Mockup de terminal/editor de código | → | | PhoneMockup | Mockup de smartphone | → | | WindowMockup | Mockup de ventana de escritorio | → |

third-party/ — Plugins de terceros (13 componentes)

| Componente | Librería | Descripción | Docs | |------------|----------|-------------|------| | Datepicker | flatpickr | Selector de fechas: single, multiple, range; con hora; inline | → | | RangeSlider | nouislider | Slider de rango simple o doble con tooltips y callbacks | → | | Rating | raty-js | Valoración por estrellas con medias estrellas y modo readOnly | → | | DragDrop | sortablejs | Lista ordenable drag & drop; soporta grupos entre listas | → | | FileUpload | dropzone | Zona de subida con arrastrar/soltar, validación tipo/tamaño | → | | NotyfToasts | notyf | Sistema de toasts con API ref y singleton global toast | → | | Charts | apexcharts | 13 tipos de gráficos; series y options reactivos | → | | Calendar | @fullcalendar | Calendario completo: mes/semana/día/lista, editable, selectable | → | | WYSIWYGEditor | @editorjs/editorjs | Editor de bloques tipo Notion; datos como JSON estructurado | → | | CopyToClipboard | clipboard | Wrapper que copia texto al portapapeles con callback de resultado | → | | Animation | CSS/Tailwind | Wrapper de animaciones CSS: fade, slide, zoom, bounce, pulse, spin | → | | WaveEffect | node-waves | Efecto ripple/wave al hacer clic; carga lazy | → | | DataMaps | — | Contenedor para mapas geográficos; reemplazar con Leaflet/Mapbox | → |

Convenciones

• React.memo() — todos los componentes están memoizados para evitar re-renders innecesarios
• Plugins HS* — inicializados con useLayoutEffect scoped al containerRef, sin contaminación global del DOM
• IDs autogenerados — useId() de React garantiza IDs únicos sin colisiones entre instancias
• Estilos — solo clases FlyonUI y Tailwind CSS, sin CSS custom ni estilos inline
• Lazy loading — todas las librerías de terceros se importan con await import(...), sin penalización en el bundle inicial

Versiones

| Librería | Versión | |----------|---------| | React | >=18 | | FlyonUI | >=2 | | Tailwind CSS | ^4 |

Licencia

MIT