npm package: @nexo2/ui
Description: Nexo UI Library - Atomic Design components for React with Tailwind CSS
Latest version: 0.1.17

# @nexo2/ui

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

![npm version](https://img.shields.io/npm/v/@nexo2/ui)
![license](https://img.shields.io/npm/l/@nexo2/ui)

[English version](./README-eng.md)

---

## 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

```bash
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:

```bash
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:

```js
// 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:

```css
: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:

```tsx
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

```tsx
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:

```tsx
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

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

### Ejemplo rapido -- DataTable

```tsx
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:

```json
{
  "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:

```bash
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.).

```tsx
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

```bash
# 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](./LICENSE)