# 🎨 @imj_media/ui

# AUTHOR: Oscar Rubio - IMJ

Biblioteca de componentes UI moderna y accesible para React, construida con TypeScript y Tailwind CSS.

> **Versión publicada:** `1.8.2` — actualizar este número y `CHANGELOG.md` antes de cada release (orden y scripts: regla **`imj-ui-obligations-release`**; atajo `npm run publish:patch|minor|major` o pasos `bump:*` → `release:git` → `release:publish`).

## 📦 Instalación

```bash
npm install @imj_media/ui
# o
yarn add @imj_media/ui
# o
pnpm add @imj_media/ui
```

## 🚀 Uso Básico

```tsx
import { Button, Input, Modal } from '@imj_media/ui'
import '@imj_media/orbit-tokens/css/tokens.css'
import '@imj_media/orbit-tokens/themes/light.css'
import '@imj_media/orbit-tokens/themes/dark.css'
import '@imj_media/ui/index.css'

function App() {
  return (
    <div>
      <Button variant="button" color="blue">
        Hola Mundo
      </Button>
      <Input label="Email" placeholder="tu@email.com" />
    </div>
  )
}
```

Modo oscuro: con los imports anteriores, fija el tema en el documento (por ejemplo `document.documentElement.setAttribute('data-theme', 'dark')`) o usa **`THEME_DARK`** / **`THEME_LIGHT`** exportados por **`@imj_media/ui`**. Los componentes que usan utilidades `ui-*` seguirán los tokens semánticos resueltos por Orbit.

## 🎯 Características Principales

- **TypeScript First**: Tipos completamente tipados para una mejor experiencia de desarrollo
- **Tailwind CSS**: Sistema de diseño consistente; el **`theme.extend`** compartido viene del preset de **`@imj_media/orbit-tokens`** (no duplicar tokens ni claves de tema en este paquete — ver **`DEVELOPMENT_GUIDE.md`**, sección *Orbit — Tailwind preset*, y **`packages/orbit-tokens/README.md`**)
- **Accesibilidad**: Componentes construidos siguiendo las mejores prácticas de a11y
- **Responsive**: Diseño adaptable a todos los tamaños de pantalla
- **Tema Personalizable**: Sistema de colores y estilos fácilmente configurable
- **Storybook**: Documentación interactiva de todos los componentes

## 🏗️ Estructura del Paquete

```
src/
├── modules/          # Componentes principales
├── shared/           # Utilidades y tipos compartidos
│   ├── types/        # Definiciones de tipos TypeScript
│   ├── utils/        # Funciones utilitarias
│   ├── styles/       # Estilos CSS y variables
│   ├── hooks/        # Hooks personalizados
│   └── assets/       # Recursos estáticos
└── index.ts          # Punto de entrada principal
```

## 🧩 Componentes Disponibles

### 🎨 Componentes de Navegación

#### Accordion
```tsx
import { Accordion } from '@imj_media/ui'

<Accordion>
  <Accordion.Item title="Sección 1">
    Contenido de la sección 1
  </Accordion.Item>
</Accordion>
```

#### Breadcrumbs
```tsx
import { Breadcrumbs } from '@imj_media/ui'

<Breadcrumbs
  items={[
    { label: 'Inicio', href: '/' },
    { label: 'Productos', href: '/productos' }
  ]}
/>
```

#### Drawer
```tsx
import { Drawer } from '@imj_media/ui'

<Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
  Contenido del drawer
</Drawer>
```

#### Modal
```tsx
import { Modal } from '@imj_media/ui'

<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="md">
  <Modal.Header title="Título del Modal" />
  <Modal.Body>
    Contenido del modal
  </Modal.Body>
  <Modal.Footer>
    <Button onClick={onCancel}>Cancelar</Button>
    <Button onClick={onSuccess}>Confirmar</Button>
  </Modal.Footer>
</Modal>
```

#### Popup
```tsx
import { Popup } from '@imj_media/ui'

<Popup
  trigger={<Button>Abrir Popup</Button>}
  content="Contenido del popup"
  position="top"
/>
```

### 🎯 Componentes de Formulario

#### Button
```tsx
import { Button } from '@imj_media/ui'

<Button
  variant="button"
  color="blue"
  size="md"
  icon="check"
  onClick={handleClick}
>
  Botón Principal
</Button>
```

**Variantes disponibles:**
- `button`: Botón estándar con fondo
- `text`: Botón de texto sin fondo
- `outlined`: Botón con borde
- `soft`: Botón con fondo suave
- `icon`: Botón solo con icono

**Colores disponibles:**
- `blue`, `green`, `orange`, `red`
- `white`, `black`, `neutral`
- `yellow`, `blue-dark`, `blue-light`
- `transparent`

**Tamaños disponibles:**
- `xs`, `sm`, `md`, `lg`, `xl`, `2xl`

#### ButtonGroup
```tsx
import { ButtonGroup } from '@imj_media/ui'

<ButtonGroup>
  <Button variant="outlined">Izquierda</Button>
  <Button variant="outlined">Centro</Button>
  <Button variant="outlined">Derecha</Button>
</ButtonGroup>
```

#### Input
```tsx
import { Input } from '@imj_media/ui'

<Input
  label="Email"
  placeholder="tu@email.com"
  size="md"
  color="blue"
  leftSlot="mail"
  error="Email inválido"
  helperText="Ingresa tu email corporativo"
/>
```

**Características:**
- Soporte para slots izquierdo y derecho
- Validación de errores
- Texto de ayuda
- Auto-redimensionamiento
- Diferentes tamaños y colores

#### Textarea
```tsx
import { Textarea } from '@imj_media/ui'

<Textarea
  label="Descripción"
  placeholder="Describe tu proyecto..."
  rows={4}
  maxLength={500}
/>
```

#### Switch
```tsx
import { Switch } from '@imj_media/ui'

<Switch
  checked={isEnabled}
  onChange={setIsEnabled}
  label="Habilitar notificaciones"
/>
```

#### RadioButton
```tsx
import { RadioButton } from '@imj_media/ui'

<RadioButton
  name="tipo"
  value="personal"
  checked={tipo === 'personal'}
  onChange={(value) => setTipo(value)}
  label="Proyecto Personal"
/>
```

#### DatePicker
```tsx
import { DatePicker } from '@imj_media/ui'

<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  placeholder="Selecciona una fecha"
  format="DD/MM/YYYY"
/>
```

### 🎨 Componentes de Visualización

#### Badge
```tsx
import { Badge } from '@imj_media/ui'

<Badge color="green" size="md" label="Activo" />
```

#### Tag
```tsx
import { Tag } from '@imj_media/ui'

<Tag
  color="blue"
  size="md"
  onDelete={() => handleDelete()}
  label="Etiqueta"
/>
```

#### Avatar
```tsx
import { Avatar } from '@imj_media/ui'

<Avatar
  src="/avatar.jpg"
  alt="Usuario"
  size="md"
  fallback="U"
/>
```

#### Logo
```tsx
import { Logo } from '@imj_media/ui'

<Logo
  src="/logo.svg"
  alt="IMJ Media"
  size="lg"
/>
```

#### Picture
```tsx
import { Picture } from '@imj_media/ui'

<Picture
  src="/image.jpg"
  alt="Descripción"
  size="lg"
  fallback="/placeholder.jpg"
/>
```

#### Visual
```tsx
import { Visual } from '@imj_media/ui'

<Visual
  type="icon"
  name="star"
  size="lg"
  color="yellow"
/>
```

### 📊 Componentes de Datos

#### Lists
```tsx
import { Lists } from '@imj_media/ui'

<Lists>
  <Lists.Item>Elemento 1</Lists.Item>
  <Lists.Item>Elemento 2</Lists.Item>
  <Lists.Item>Elemento 3</Lists.Item>
</Lists>
```

#### Pagination
```tsx
import { Pagination } from '@imj_media/ui'

<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={setCurrentPage}
  showFirstLast={true}
/>
```

#### ProgressBar
```tsx
import { ProgressBar } from '@imj_media/ui'

<ProgressBar
  value={75}
  max={100}
  color="blue"
  size="md"
  showLabel={true}
/>
```

#### Stepper
```tsx
import { Stepper } from '@imj_media/ui'

<Stepper
  steps={[
    { label: 'Paso 1', status: 'completed' },
    { label: 'Paso 2', status: 'active' },
    { label: 'Paso 3', status: 'pending' }
  ]}
  currentStep={1}
/>
```

**Estados disponibles:**
- `completed`: Paso completado
- `active`: Paso actual
- `pending`: Paso pendiente

### 🔔 Componentes de Notificación

#### Alert
```tsx
import { Alert } from '@imj_media/ui'

<Alert
  type="info"
  title="Información"
  description="Este es un mensaje informativo"
  closable={true}
  onClose={() => handleClose()}
/>
```

#### Toast
```tsx
import { Toast } from '@imj_media/ui'

<Toast
  type="success"
  title="Éxito"
  description="Operación completada"
  duration={5000}
  position="top-right"
/>
```

#### Tooltip
```tsx
import { Tooltip } from '@imj_media/ui'

<Tooltip
  content="Información adicional"
  position="top"
  alignment="center"
  color="blue"
>
  <Button>Hover me</Button>
</Tooltip>
```

### 🎭 Componentes de Layout

#### Cards
```tsx
import { Cards } from '@imj_media/ui'

<Cards>
  <Cards.Header>
    <Cards.Title>Título de la Tarjeta</Cards.Title>
    <Cards.Subtitle>Subtítulo opcional</Cards.Subtitle>
  </Cards.Header>
  <Cards.Body>
    Contenido de la tarjeta
  </Cards.Body>
  <Cards.Footer>
    <Button>Acción</Button>
  </Cards.Footer>
</Cards>
```

#### Separator
```tsx
import { Separator } from '@imj_media/ui'

<Separator orientation="horizontal" />
<Separator orientation="vertical" />
```

#### Tag
```tsx
import { Tag } from '@imj_media/ui'

<Tag
  color="blue"
  size="md"
  closable={true}
  onClose={() => handleClose()}
>
  Etiqueta
</Tag>
```

### 🎨 Componentes de Iconos y Emojis

#### Icon
```tsx
import { Icon } from '@imj_media/ui'

<Icon
  name="star"
  variant="fill"
  size="lg"
  color="yellow"
/>
```

**Variantes disponibles:**
- `outline`: Iconos con contorno
- `fill`: Iconos rellenos

#### Emoji
```tsx
import { Emoji } from '@imj_media/ui'

<Emoji name="smile" size="lg" />
```

### 🎬 Componentes Especiales

#### StoryBox
```tsx
import { StoryBox } from '@imj_media/ui'

<StoryBox
  title="Historia del Usuario"
  description="Como usuario, quiero..."
  priority="high"
  status="in-progress"
/>
```

#### Filters
```tsx
import { Filters } from '@imj_media/ui'

<Filters
  filters={[
    { key: 'status', label: 'Estado', type: 'select' },
    { key: 'priority', label: 'Prioridad', type: 'radio' }
  ]}
  onFilterChange={handleFilterChange}
/>
```

## 🎨 Sistema de Colores

El paquete incluye un sistema de colores completo con variables CSS personalizables:

```css
:root {
  --ui-color-blue-50: #ebeef9;
  --ui-color-blue-500: #3658c1;
  --ui-color-blue-900: #172551;
  
  --ui-color-green-50: #f0f9f0;
  --ui-color-green-500: #039b59;
  --ui-color-green-900: #014125;
  
  --ui-color-red-50: #f9eae9;
  --ui-color-red-500: #c62e1f;
  --ui-color-red-900: #53130d;
  
  --ui-color-orange-50: #fcf3e9;
  --ui-color-orange-500: #dc8921;
  --ui-color-orange-900: #5c3a0e;
  
  --ui-color-yellow-50: #fcfbec;
  --ui-color-yellow-500: #e1d63d;
  --ui-color-yellow-900: #5f5a1a;
  
  --ui-color-neutral-50: #f0f0f0;
  --ui-color-neutral-500: #6b6b6b;
  --ui-color-neutral-900: #2d2d2d;
}
```

## 🛠️ Utilidades

### Función `cn()`
Utilidad para combinar clases CSS de manera inteligente:

```tsx
import { cn } from '@imj_media/ui'

const className = cn(
  'base-class',
  condition && 'conditional-class',
  'another-class'
)
```

## 📱 Responsive Design

Todos los componentes están diseñados para ser completamente responsivos:

- **Breakpoints**: xs, sm, md, lg, xl, 2xl
- **Mobile First**: Diseño optimizado para dispositivos móviles
- **Adaptive Layouts**: Componentes que se adaptan automáticamente

## ♿ Accesibilidad

Los componentes siguen las mejores prácticas de accesibilidad:

- **ARIA Labels**: Etiquetas descriptivas para lectores de pantalla
- **Keyboard Navigation**: Navegación completa por teclado
- **Focus Management**: Manejo inteligente del foco
- **Screen Reader Support**: Compatibilidad con lectores de pantalla

## 🎨 Personalización

### Variables CSS
Puedes personalizar el tema modificando las variables CSS:

```css
:root {
  --ui-color-blue-500: #your-custom-blue;
  --ui-color-green-500: #your-custom-green;
}
```

### Tailwind CSS
Todos los componentes utilizan Tailwind CSS y pueden ser personalizados a través de tu configuración:

```js
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'custom-blue': '#1234567',
      }
    }
  }
}
```

## 📚 Storybook

Para ver todos los componentes en acción y explorar sus variantes:

```bash
npm run storybook
```

Storybook incluye:
- **Documentación interactiva** de todos los componentes
- **Controles en tiempo real** para probar diferentes props
- **Ejemplos de uso** y mejores prácticas
- **Testing visual** de componentes

## 🔧 Scripts Disponibles

```json
{
  "scripts": {
    "build": "vite build",
    "dev": "vite build --watch",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,scss,md}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,scss,md}\""
  }
}
```

## 📦 Dependencias

### Peer Dependencies
- `react`: ^18.0.0
- `react-dom`: ^18.0.0

### Dependencies Principales
- `class-variance-authority`: Sistema de variantes de componentes
- `clsx`: Utilidad para combinar clases CSS
- `tailwind-merge`: Fusión inteligente de clases Tailwind
- `tailwind-variants`: Sistema de variantes tipadas

## 🚀 Roadmap

- [ ] Componente de Tabla avanzada
- [ ] Componente de Gráficos
- [ ] Componente de Calendario
- [ ] Componente de Drag & Drop
- [ ] Componente de Rich Text Editor
- [ ] Temas oscuros/claros
- [ ] Internacionalización (i18n)

## 🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

## 📄 Licencia

Este proyecto está bajo la Licencia ISC. Ver el archivo `LICENSE` para más detalles.

## 👥 Autores

- **Oscar Rubio - IMJ** - *Desarrollo inicial* - [oscar.rubio@imjmedia.com.mx](mailto:oscar.rubio@imjmedia.com.mx)

## 🙏 Agradecimientos

- [Tailwind CSS](https://tailwindcss.com/) por el sistema de diseño
- [React](https://reactjs.org/) por el framework
- [TypeScript](https://www.typescriptlang.org/) por el tipado estático
- [Storybook](https://storybook.js.org/) por la documentación interactiva

---

**¿Necesitas ayuda?** Abre un issue en el repositorio o contacta al equipo de desarrollo.