anima-ds-nucleus

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

npm install anima-ds-nucleus

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

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):

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

  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

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

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

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

<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í:

// 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):

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:

   npm install -D tailwindcss postcss autoprefixer
   npx tailwindcss init -p

2. Configura tailwind.config.js para incluir los componentes de Anima DS:

   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:

   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)

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.