## anima-ds-nucleus

**Anima DS** es una librería de componentes React (Design System) que incluye:
- **Atoms / Inputs / Layout / DataDisplay / Views** listas para usar.
- Soporte de **i18next / react-i18next**.
- Componentes avanzados como **tablas (MUI DataGrid)** y **gráficos (ApexCharts)**.

### Instalación

```bash
npm install anima-ds-nucleus
```

Además, el proyecto que la use debe tener instaladas (peer dependencies):

```bash
npm install react react-dom
```

### Dependencias por componente

**⚠️ IMPORTANTE**: Algunos componentes requieren dependencias adicionales:

| Componente | Dependencias Requeridas |
|------------|------------------------|
| **Input, Select, Textarea, DatePicker, FileUpload** | `i18next`, `react-i18next` |
| **DBGrid** | `@mui/material`, `@mui/x-data-grid`, `@emotion/react`, `@emotion/styled`, `i18next`, `react-i18next` |
| **AreaChart, BarChart, LineChart, PieChart, DonutChart, ColumnChart** | `apexcharts`, `react-apexcharts` |
| **LoginForm, ChangePasswordForm, Chat** | `i18next`, `react-i18next` |
| **Sidebar, Header** | `i18next`, `react-i18next` |

**Componentes que requieren @heroicons/react**: Icon (y todos los componentes que usan Icon internamente: Breadcrumbs, Sidebar, Accordion, Drawer, Dropdown, Pagination, Stepper, EmptyState, StatCard, Timeline, Toast, Chat).

**Componentes que NO requieren dependencias extra**: Button, Card, Badge, Typography, Modal, Tabs, Avatar, Spinner, Progress, Divider, Skeleton, Tooltip, Alert, List, TagList, Layout.

**Instalación completa (si usas todos los componentes):**
```bash
# Instalar la librería
npm install anima-ds-nucleus

# Instalar todas las dependencias opcionales
npm install @heroicons/react i18next react-i18next @mui/material @mui/x-data-grid @emotion/react @emotion/styled apexcharts react-apexcharts
```

**Nota**: Estas dependencias son "peer dependencies" - deben estar instaladas en tu proyecto si usas los componentes que las requieren. Esto evita duplicación y reduce el tamaño del bundle.

### Requisitos de integración

- **React 18 o superior** en el proyecto que consume la librería.
- **Tailwind CSS configurado** - Los componentes usan clases de Tailwind. Debes tener Tailwind instalado y configurado en tu proyecto.
- **Importar los estilos** - Después de instalar, importa los estilos en tu entry point:
  ```jsx
  import 'anima-ds-nucleus/styles';
  // O si prefieres importar manualmente:
  import 'anima-ds-nucleus/dist/anima-ds-nucleus.css';
  ```
- **Internacionalización con i18next** - Si usas componentes que requieren i18n, debes configurar i18next con las keys de traducción. La librería incluye traducciones en `es-AR` y `pt-BR` que puedes usar como referencia. Ver sección "Configuración de i18n" abajo.

### Uso básico

```jsx
// Importar estilos (IMPORTANTE)
import 'anima-ds-nucleus/styles';

// Importar componentes
import { Button, Layout, Card, I18nProvider } from 'anima-ds-nucleus';

function App() {
  return (
    <I18nProvider language="es-AR">
      <Layout>
        <Card title="Ejemplo">
          <Button tipo="Primary" color="Teal">
            Click aquí
          </Button>
        </Card>
      </Layout>
    </I18nProvider>
  );
}
```

También puedes usar el API más típico:

```jsx
<Button variant="Primary">Enviar</Button>
```

### HeaderCore: resultados de búsqueda tipo persona

`HeaderCore` soporta la prop `searchResultVariant`. Por defecto usa `"default"` y mantiene compatibilidad con el renderer textual anterior. Para búsquedas de personas, usar `searchResultVariant="persona"` evita definir `renderSearchResultItem` en el proyecto consumidor.

```jsx
<HeaderCore
  searchValue={query}
  onSearch={setQuery}
  searchResults={people}
  isSearchResultsOpen={query.trim().length > 0}
  searchResultVariant="persona"
  onSearchResultClick={(person) => setQuery(person.nombre ?? person.name)}
/>
```

La variante `persona` acepta datos con keys tolerantes: `id | personId`, `nombre | name | fullName | label`, `email`, `documento | document`, `estado | statusLabel | status` y `foto | avatar | image | userAvatar`. Si se pasa `renderSearchResultItem`, ese renderer custom sigue teniendo prioridad.

### Tabla y ListaPersonas: filtros aplicados

`Tabla` y `ListaPersonas` soportan filtros aplicados nativos con chips responsive. El consumidor solo pasa datos y callbacks; el DS resuelve estilos, scroll mobile y contador del botón `Filtros` cuando no se controla explícitamente con `activeFiltersCount`.

```jsx
<Tabla
  showFiltersButton
  appliedFilters={[
    { id: 'documento', label: 'Documento contiene 345' },
    { id: 'persona', label: 'Persona contiene Lau' },
  ]}
  onAppliedFilterRemove={(filter) => removeFilter(filter.id)}
  onAppliedFiltersClear={clearFilters}
/>
```

`appliedFilters` acepta strings u objetos `{ id, label }`. Si se informa `filtersArea`, ese contenido custom tiene prioridad y reemplaza el render nativo.

### Ejemplo de uso en un proyecto demo (Button)

Supongamos un proyecto React creado con Vite o Create React App.  
Luego de instalar la librería y React, puedes usar el `Button` así:

```jsx
// src/App.jsx
import React from 'react';
// Importar estilos primero
import 'anima-ds-nucleus/styles';
import { Button } from 'anima-ds-nucleus';

function App() {
  const handleClick = () => {
    alert('Botón de Anima DS clickeado');
  };

  return (
    <div style={{ padding: '2rem' }}>
      <h1>Proyecto Demo con Anima DS</h1>
      <Button variant="Primary" onClick={handleClick}>
        Usar Button de la librería
      </Button>
    </div>
  );
}

export default App;
```

Y en el entry point del proyecto (`main.jsx` o `index.jsx`):

```jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

### Configuración de Tailwind CSS

**IMPORTANTE**: Esta librería requiere Tailwind CSS configurado en tu proyecto. Los componentes usan clases de Tailwind directamente.

1. Instala Tailwind en tu proyecto:
   ```bash
   npm install -D tailwindcss postcss autoprefixer
   npx tailwindcss init -p
   ```

2. Configura `tailwind.config.js` para incluir los componentes de Anima DS:
   ```js
   content: [
     "./src/**/*.{js,jsx}",
     "./node_modules/anima-ds-nucleus/**/*.{js,jsx}", // Agregar esta línea
   ],
   ```

3. Importa los estilos de Anima DS en tu `main.jsx` o `index.js`:
   ```jsx
   import 'anima-ds-nucleus/styles';
   ```

### Configuración de i18n (Internacionalización)

Si usas componentes que requieren i18n (Input, Select, DBGrid, LoginForm, etc.), necesitas configurar i18next en tu proyecto.

**Opción 1: Usar el I18nProvider de la librería (recomendado)**
```jsx
import { I18nProvider } from 'anima-ds-nucleus';

function App() {
  return (
    <I18nProvider language="es-AR">
      {/* Tu app */}
    </I18nProvider>
  );
}
```

**Opción 2: Configurar tu propio i18next**
La librería espera estas keys de traducción (puedes ver todas en `node_modules/anima-ds-nucleus/src/i18n/config.js`):
- `form.*` (email, password, login, etc.)
- `placeholder.*` (email, password, search, etc.)
- `table.*` (id, name, email, role, etc.)
- `nav.*` (home, dashboard, profile, etc.)
- `chat.*` (typeMessage, send, etc.)

### Notas importantes

- **Los componentes que usan i18n fallarán si i18next no está configurado** - Asegúrate de usar `I18nProvider` o configurar tu propio i18next antes de usar esos componentes.
- **Dependencias como peer dependencies** - MUI, ApexCharts, i18next son "peer dependencies". Debes instalarlas en tu proyecto si usas los componentes que las requieren. Esto evita duplicación y reduce el tamaño del bundle.

### Scripts de desarrollo

- **`npm run dev`**: entorno de desarrollo con Vite.
- **`npm run build`**: build de la librería (ESM + CJS en `dist/`).
- **`npm run storybook`**: arranca Storybook con todos los componentes.
