npm package: @oticsw/ui
Description: Otic library
Latest version: 0.1.2

# @oticsw/ui

Biblioteca de componentes y utilidades para Otic SW. Incluye providers para gestión de temas y configuración global, wrappers para Ant Design, utilidades comunes y cualquier herramienta necesaria para el desarrollo de aplicaciones en Otic.

## 📦 Instalación

```bash
npm install @oticsw/ui antd react react-dom
# o
pnpm install @oticsw/ui antd react react-dom
```

## 🚀 Inicio Rápido

### Configuración Básica

Envuelve tu aplicación con el `UIProvider` para aplicar la configuración de tema y localización:

```tsx
import { UIProvider } from '@oticsw/ui';
import { App } from './App';

function Root() {
  return (
    <UIProvider>
      <App />
    </UIProvider>
  );
}
```

### Configuración Personalizada

```tsx
import { UIProvider } from '@oticsw/ui';
import { theme } from 'antd';

function Root() {
  return (
    <UIProvider
      theme={{
        token: {
          colorPrimary: '#00b96b',
          borderRadius: 4,
        },
        algorithm: theme.darkAlgorithm, // Tema oscuro
      }}
      locale={esES} // Localización española por defecto
    >
      <App />
    </UIProvider>
  );
}
```

## 📚 Estructura del Proyecto

```
src/
├── providers/          # Providers de React para contextos globales
│   └── theme/         # Provider de tema y configuración de Ant Design
│       ├── UIProvider.tsx
│       └── defaultToken.ts
├── components/        # Componentes reutilizables (próximamente)
├── utils/            # Funciones de utilidad (próximamente)
└── index.ts          # Punto de entrada principal
```

## 🎨 Providers

### UIProvider

Provider principal que configura el tema global de Ant Design y la localización de la aplicación.

**Props:**

| Prop | Tipo | Por Defecto | Descripción |
|------|------|-------------|-------------|
| `theme` | `ThemeConfig` | `defaultTokens` | Configuración personalizada del tema de Ant Design |
| `locale` | `Locale` | `esES` | Configuración de idioma/localización |
| `children` | `ReactNode` | - | Componentes hijos |

**Características:**
- ✅ Merge inteligente de tokens personalizados con tokens por defecto
- ✅ Soporte para algoritmos de tema (claro, oscuro, compacto)
- ✅ Localización española por defecto
- ✅ Configuración de componentes específicos de Ant Design

**Tema por Defecto:**

```typescript
{
  token: {
    colorPrimary: '#1677ff',
    colorBgContainer: '#ffffff',
    borderRadius: 8,
    fontFamily: 'Inter, sans-serif',
    colorText: '#141414',
    colorTextSecondary: '#595959',
  }
}
```

### Próximos Providers

- **AuthProvider**: Gestión de autenticación y autorización
- **DataProvider**: Gestión de estado global y caché de datos
- **NotificationProvider**: Sistema de notificaciones y mensajes
- **LayoutProvider**: Configuración de layout y navegación

## 🛠️ Utilidades (Próximamente)

La librería incluirá utilidades para:

- **Formateo**: Fechas, números, monedas
- **Validación**: Formularios, datos, reglas de negocio
- **Helpers**: Funciones comunes para manipulación de datos
- **Hooks**: Custom hooks de React para funcionalidades comunes

## 🧩 Componentes (Próximamente)

Wrappers y componentes personalizados basados en Ant Design:

- **Formularios**: Inputs, selects, date pickers con validación integrada
- **Tablas**: Tablas con filtros, ordenamiento y paginación
- **Modales**: Modales con variantes predefinidas
- **Botones**: Botones con estados y variantes personalizadas
- **Layouts**: Componentes de layout responsive

## 🔧 Desarrollo

### Instalación de Dependencias

```bash
pnpm install
```

### Scripts Disponibles

```bash
# Modo desarrollo con Vite
pnpm dev

# Compilar la librería con tsdown
pnpm build

# Vista previa de la build
pnpm preview

# Publicar nueva versión (patch)
pnpm release
```

### Estructura de Build

La librería se compila en múltiples formatos para máxima compatibilidad:

- **ESM**: `dist/index.js` - Módulos ES6
- **UMD**: `dist/index.umd.cjs` - CommonJS para Node.js
- **Types**: `dist/index.d.ts` - Definiciones de TypeScript

## 📝 Configuración de TypeScript

El proyecto utiliza path aliases para imports limpios:

```typescript
import { UIProvider } from '@/providers/theme/UIProvider';
// en lugar de
import { UIProvider } from '../../providers/theme/UIProvider';
```

## 🤝 Contribución

1. Crea una rama para tu feature: `git checkout -b feature/nueva-funcionalidad`
2. Realiza tus cambios y commitea: `git commit -m 'feat: nueva funcionalidad'`
3. Push a la rama: `git push origin feature/nueva-funcionalidad`
4. Abre un Pull Request

## 📄 Licencia

MIT

## 🔗 Dependencias Principales

- **React** ^18.0.0
- **Ant Design** ^5.0.0
- **TypeScript** ^5.2.2

## 🏗️ Herramientas de Build

- **[tsdown](https://tsdown.dev/)** - Bundler moderno y ultrarrápido para librerías TypeScript
  - Genera múltiples formatos (ESM, CJS, UMD) automáticamente
  - Optimizado para librerías React
  - Zero-config con soporte completo de TypeScript

## 📦 Publicación

```bash
# Incrementar versión patch y publicar
pnpm release

# O manualmente
npm version [patch|minor|major]
pnpm build
npm publish --access public
```