@nexo2/ui

Libreria de componentes con Atomic Design para React + Tailwind CSS. Lista para produccion, completamente tipada, con dark mode integrado.

English version

Caracteristicas

• 97 componentes organizados en cuatro capas de Atomic Design (atoms, molecules, organisms, templates)
• 25 hooks para patrones comunes de UI (toast, paginacion, filtros, modales y mas)
• TypeScript first con declaraciones de tipos completas para cada componente y hook
• Dark mode integrado via estrategia class de Tailwind CSS
• Soporte i18n con presets en espanol e ingles, extensible a cualquier idioma
• Tree-shakeable builds ESM y CJS
• Sin dependencias de logica de negocio -- UI pura, lista para cualquier proyecto React
• Tema personalizable via CSS custom properties y un preset de Tailwind
• MCP server incluido -- asistentes IA (Claude Code) pueden consultar documentacion automaticamente

Instalacion

npm install @nexo2/ui

Peer Dependencies

| Paquete | Version | Requerido | |---------|---------|-----------| | react | ^18.0.0 \|\| ^19.0.0 | Si | | react-dom | ^18.0.0 \|\| ^19.0.0 | Si | | lucide-react | >=0.300.0 | Si | | clsx | ^2.0.0 | Si | | tailwind-merge | ^2.0.0 | Si | | framer-motion | ^11.0.0 | Opcional -- animaciones en Drawer, Modal | | vaul | >=0.9.0 | Opcional -- Drawer mobile-friendly | | zustand | ^5.0.0 | Opcional -- useModalManager, useToast | | @tanstack/react-query | ^5.0.0 | Opcional -- AsyncBoundary | | focus-trap-react | ^10.0.0 | Opcional -- focus trapping en Modal | | react-dropzone | ^14.0.0 | Opcional -- FileUpload | | html5-qrcode | ^2.3.0 | Opcional -- BarcodeScanner |

Instalar peers requeridos:

npm install react react-dom lucide-react clsx tailwind-merge

Configuracion de Tailwind CSS

Agrega el preset de @nexo2/ui a tu configuracion de Tailwind para que los estilos de componentes (colores, animaciones, dark mode) funcionen correctamente:

// tailwind.config.js
const nexoPreset = require('@nexo2/ui/tailwind');

module.exports = {
  presets: [nexoPreset],
  content: [
    './src/**/*.{js,tsx}',
    './node_modules/@nexo2/ui/dist/**/*.{js,mjs}',
  ],
};

El preset provee:

• Escalas de color primary-* y secondary-* controladas por CSS custom properties (--color-primary-500, etc.), para tematizar toda la libreria con unas pocas variables CSS.
• Dark mode basado en class (darkMode: 'class').
• Animaciones: fade-in, slide-up, slide-down, scan-line.
• Inter como fuente sans-serif por defecto.

Personalizar Colores

Configura CSS custom properties en :root (o cualquier scope) para cambiar la paleta:

:root {
  --color-primary-500: #3b6cf7;
  --color-secondary-500: #8446ff;
}

Configuracion de UILibraryProvider

La libreria no depende de ningun router especifico. En su lugar, inyectas funciones de navegacion a traves de un context provider:

import { UILibraryProvider } from '@nexo2/ui/providers';
import { useNavigate, useLocation } from 'react-router-dom';

function App() {
  const navigate = useNavigate();
  const location = useLocation();

  return (
    <UILibraryProvider
      navigate={navigate}
      currentPath={location.pathname}
    >
      <TuApp />
    </UILibraryProvider>
  );
}

Componentes como BackButton, Breadcrumb y GenericNavTabs usan este contexto internamente, asi que configurarlo una vez en el root es suficiente.

Uso

Imports basicos

import { Button, Input, Badge } from '@nexo2/ui';

Sub-path Imports

Cada capa de Atomic Design esta disponible como un entry point dedicado para imports mas granulares:

import { Button, IconButton } from '@nexo2/ui/atoms';
import { SearchInput, Alert } from '@nexo2/ui/molecules';
import { DataTable, Modal } from '@nexo2/ui/organisms';
import { ListadoCRUDPage } from '@nexo2/ui/templates';

Hooks

import { useToast, useDisclosure, useFilters } from '@nexo2/ui/hooks';

Ejemplo rapido -- DataTable

import { DataTable, Pagination, Badge } from '@nexo2/ui';
import { usePagination } from '@nexo2/ui/hooks';

const columns = [
  { key: 'nombre', header: 'Nombre' },
  {
    key: 'estado',
    header: 'Estado',
    render: (row) => (
      <Badge variant={row.estado === 'activo' ? 'success' : 'default'}>
        {row.estado}
      </Badge>
    ),
  },
];

function ListaUsuarios({ usuarios, pagination }) {
  return (
    <>
      <DataTable columns={columns} data={usuarios} />
      <Pagination {...pagination} />
    </>
  );
}

MCP Server (Integracion con Claude Code)

El paquete incluye un MCP server (Model Context Protocol) bundleado que permite a asistentes IA como Claude Code consultar documentacion de componentes, props, hooks y ejemplos de uso automaticamente.

Configuracion

Agrega lo siguiente al .mcp.json de tu proyecto:

{
  "mcpServers": {
    "nexo-ui": {
      "command": "node",
      "args": ["./node_modules/@nexo2/ui/dist/mcp/index.js"]
    }
  }
}

Luego reinicia Claude Code. El MCP server provee estas herramientas:

| Herramienta | Descripcion | |-------------|-------------| | search_components | Buscar componentes y hooks por nombre o concepto | | get_component_doc | Documentacion completa de un componente (props, tipos, ejemplos) | | get_hook_doc | Documentacion completa de un hook (firma, return type, ejemplos) | | list_components | Listar todos los componentes por capa | | get_setup_guide | Guias de instalacion, provider, tailwind, i18n e imports |

Alternativa: npx

Tambien puedes ejecutar el MCP server directamente:

npx nexo-ui-mcp

Componentes por Capa

Atoms (17)

Elementos UI fundamentales sin dependencias internas.

| Componente | Descripcion | |------------|-------------| | Button | Boton de accion con variantes, tamanos y estado de carga | | IconButton | Boton de solo icono con soporte de tooltip | | Input | Input de texto con prefijo/sufijo y estado de error | | Textarea | Input de texto multi-linea | | Select | Select dropdown nativo | | Checkbox | Input checkbox | | Radio | Input radio | | Badge | Etiquetas de estado y categoria | | Label | Label de campo de formulario | | Card | Contenedor con header/footer opcional | | Divider | Separador horizontal o vertical | | Avatar | Avatar de usuario con iniciales de fallback | | Text | Primitiva tipografica | | Skeleton | Placeholder de carga | | Spinner | Indicador de carga inline | | PageLoader | Indicador de carga de pagina completa | | LoadingSpinner | Deprecado -- usar PageLoader |

Molecules (29)

Combinaciones funcionales de atoms.

| Componente | Descripcion | |------------|-------------| | Alert | Banner de mensaje contextual | | Toast | Notificacion transitoria | | SearchInput | Input con icono de busqueda y debounce | | FormGroup | Label + input + wrapper de error | | InputField | FormGroup + Input compuesto | | SelectField | FormGroup + Select compuesto | | TextareaField | FormGroup + Textarea compuesto | | ProgressBar | Indicador de progreso horizontal | | LimitProgressBar | Barra de progreso para limites de uso | | ToggleSwitch | Toggle booleano | | EmptyState | Placeholder para vistas sin datos | | Breadcrumb | Trail de navegacion breadcrumb | | BackButton | Boton de retroceso con router | | RecordNavigation | Navegacion anterior/siguiente de registros | | StatCard | Tarjeta de metrica individual | | StatCardGrid | Grid de StatCards | | SkeletonStatCard | Estado de carga para StatCard | | SkeletonTable | Estado de carga para tablas | | SkeletonCard | Estado de carga para cards | | SkeletonList | Estado de carga para listas | | FilterChip | Tag de filtro removible | | FilterField | Input de filtro unificado (texto, select, fecha, etc.) | | FilterSection | Grupo de filtros colapsable | | CheckboxGroup | Grupo de checkboxes | | CheckboxField | Checkbox + label compuesto | | RadioGroup | Grupo de radio buttons | | Tooltip | Tooltip en hover con portal | | Popover | Contenido flotante activado por click | | SmartButtons | Grid de botones responsive | | OverlayHeader | Header unificado para modales/drawers | | FileUpload | Zona de carga drag-and-drop |

Organisms (30+)

Secciones de interfaz complejas y autocontenidas.

| Componente | Descripcion | |------------|-------------| | Modal | Overlay de dialogo con focus trapping | | Drawer | Panel lateral deslizante (con vaul) | | FormDrawer | Drawer con footer de formulario integrado | | ConfirmDialog | Modal de confirmacion | | DeleteConfirmDialog | Confirmacion de accion destructiva | | DataTable | Tabla de datos con ordenamiento y seleccion | | DataTableActions | Botones de accion para filas de tabla | | Pagination | Controles de paginacion | | FilterPanel | Sidebar de filtros colapsable | | AdvancedFilterPanel | Panel de filtros con busquedas guardadas | | StandardFilterGrid | Grid de campos de filtro | | SearchFilterBar | Busqueda + filtros combinados | | Accordion | Secciones de contenido expandibles | | ExpandableSection | Seccion colapsable individual | | ExpandableCrudSection | Seccion expandible con CRUD | | GenericNavTabs | Tabs de navegacion horizontal | | ViewTabs | Tabs para cambiar vista de contenido | | StateNavTabs | Tabs de navegacion por estado con conteos | | NavDropdown | Navegacion estilo dropdown | | MobileNavSelector | Selector de navegacion mobile | | DropdownMenu | Menu contextual / dropdown | | MultiSelect | Select multi-valor con busqueda | | IconPicker | Selector de iconos | | BarcodeScanner | Escaner de codigos de barras/QR por camara | | ToastContainer | Contenedor global de notificaciones toast | | StandardRowActions | Botones de editar/eliminar para filas | | ThemeToggle | Toggle de modo claro/oscuro | | TreeView | Vista jerarquica de arbol | | ChunkErrorBoundary | Error boundary para lazy-load | | GlobalErrorBoundary | Error boundary a nivel de aplicacion |

Templates (8)

Patrones de layout a nivel de pagina.

| Componente | Descripcion | |------------|-------------| | BasePageLayout | Shell de pagina estandar | | ListadoCRUDPage | Template completo de pagina CRUD con listado | | BaseDetailLayout | Layout de pagina de detalle | | BaseFormLayout | Layout de formulario con stepper | | AsyncBoundary | Wrapper de Suspense + error boundary | | PageHeader | Header de pagina consistente | | createModuleLayout | Factory para layouts especificos de modulo | | DetailHeader / FormHeader / FormFooter / FormWizardStepper | Sub-componentes para templates de detalle y formulario |

Hooks (25)

Logica reutilizable extraida de componentes. Todos disponibles desde @nexo2/ui/hooks.

| Hook | Descripcion | |------|-------------| | useToast | Mostrar, cerrar y gestionar notificaciones toast | | useDisclosure | Estado booleano open/close | | useSimpleModal | Estado de modal simple con datos tipados | | useModalManager | Abrir/cerrar multiples modales con datos asociados | | useDeleteConfirmation | Flujo de confirmar + ejecutar eliminacion | | useFilters | Estado de filtros con persistencia opcional | | usePagination | Pagina, pageSize, total, handlers | | useExportCSV | Exportar arrays de datos a archivos CSV | | useDebounce | Valor con debounce | | useDebouncedCallback | Invocacion de funcion con debounce | | useMediaQuery | Deteccion de breakpoints responsive | | useIsMobile | Conveniencia: viewport menor a 768px | | useIsTablet | Conveniencia: viewport menor a 1024px | | useClickOutside | Detectar clicks fuera de un ref | | useClickOutsideRef | Como useClickOutside con ref existente | | useEscapeKey | Escuchar tecla Escape | | useBarcodeScanner | Logica de escaneo de codigos de barras por camara | | useExpandableCrudLogic | Expandir/colapsar + estado CRUD | | useFloatingPosition | Calcular posicion de elemento flotante | | useFloatingDismiss | Auto-dismiss de elementos flotantes | | useCombineRefs | Combinar multiples refs en uno | | usePrevious | Rastrear valor previo de una variable | | useProgressColor | Derivar color de un porcentaje de progreso | | useIconPickerLogic | Busqueda y seleccion para IconPicker | | useTreeExpansion | Estado expandir/colapsar para TreeView (desde organisms) |

i18n

La libreria incluye un sistema de mensajes para strings de UI traducibles (labels de botones, empty states, texto de paginacion, etc.).

import {
  UILibraryProvider,
  UILibraryMessagesProvider,
  enMessages,
} from '@nexo2/ui/providers';

function App() {
  return (
    <UILibraryProvider navigate={navigate} currentPath={pathname}>
      <UILibraryMessagesProvider messages={enMessages}>
        <TuApp />
      </UILibraryMessagesProvider>
    </UILibraryProvider>
  );
}

• Idioma por defecto: Espanol (esMessages).
• Presets incluidos: esMessages, enMessages.
• Mensajes personalizados: Pasa un objeto parcial o completo de UILibraryMessages para sobreescribir cualquier string.
• Acceso en componentes: Usa el hook useUIMessages().

Sub-path Exports

El paquete expone entry points granulares para importar solo lo que necesitas:

| Entry point | Contenido | |-------------|-----------| | @nexo2/ui | Todos los componentes, hooks, providers y tipos | | @nexo2/ui/atoms | 17 componentes atom | | @nexo2/ui/molecules | 29 componentes molecule | | @nexo2/ui/organisms | 30+ componentes organism | | @nexo2/ui/templates | 8 componentes template | | @nexo2/ui/hooks | 25 hooks | | @nexo2/ui/providers | UILibraryProvider, i18n | | @nexo2/ui/constants | Design tokens | | @nexo2/ui/lib | Utilidades (cn, formatters, etc.) | | @nexo2/ui/tailwind | Preset de Tailwind CSS |

Desarrollo

# Instalar dependencias
npm install

# Watch mode (rebuild en cambios)
npm run dev

# Ejecutar tests
npm run test

# Tests en watch mode
npm run test:watch

# Tests con coverage
npm run test:coverage

# Verificacion de tipos
npm run typecheck

# Lint
npm run lint

# Storybook (documentacion visual)
npm run storybook

# Build de produccion (componentes + MCP server)
npm run build

Estructura del Proyecto

src/
  atoms/          # 17 componentes fundamentales
  molecules/      # 29 componentes compuestos
  organisms/      # 30+ componentes complejos
  templates/      # 8 layouts de pagina
  hooks/          # 25 hooks reutilizables
  providers/      # UILibraryProvider, i18n
  constants/      # Design tokens y constantes de estilo
  lib/            # Funciones utilitarias (cn, formatters, etc.)
  types/          # Tipos TypeScript compartidos
mcp-server/       # Fuente del MCP server (bundleado en dist/mcp/)
__tests__/        # Tests (Vitest + @testing-library/react)
tailwind/         # Preset de Tailwind CSS

Licencia

MIT