AvanzaCast/packages/ui-components/README.md

# Avanza UI

Sistema de componentes UI independiente para AvanzaCast - Sin dependencias de Tailwind CSS

## 🎯 Componentes Disponibles

### Componentes Básicos
- ✅ **Button** - Botones con múltiples variantes y tamaños
- ✅ **Card** - Tarjetas con header, body y footer
- ✅ **Input** - Campos de entrada con validación
- ✅ **Badge** - Insignias y etiquetas
- ✅ **Avatar** - Avatares con soporte de imágenes e iniciales
- ✅ **Spinner** - Indicadores de carga

### Componentes de Feedback
- ✅ **Alert** - Mensajes de alerta (success, warning, danger, info)
- ✅ **Tooltip** - Tooltips posicionables
- ✅ **Modal** - Modales con header, body y footer

### Componentes de Navegación
- ✅ **Dropdown** - Menús desplegables con items y dividers

## 📦 Instalación

```bash
# Desde el workspace (monorepo)
npm install avanza-ui@file:../ui-components

# O crear link simbólico
cd packages/ui-components
npm link
cd ../tu-proyecto
npm link avanza-ui
```

## 🚀 Uso Rápido

```tsx
import {
  Button,
  Card,
  CardHeader,
  CardBody,
  Input,
  Alert,
  Avatar,
  Badge,
  Spinner,
  Modal,
  ModalHeader,
  ModalBody,
  ModalFooter,
  Dropdown,
  DropdownItem,
  Tooltip
} from 'avanza-ui';

// Importar estilos globales
import 'avanza-ui/dist/index.css';

function App() {
  const [isModalOpen, setIsModalOpen] = React.useState(false);

  return (
    <div>
      {/* Alert */}
      <Alert variant="success" title="¡Éxito!" message="Operación completada" closable />

      {/* Card con componentes */}
      <Card>
        <CardHeader>
          <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
            <Avatar src="/avatar.jpg" size="md" status="online" />
            <div>
              <h3>Usuario</h3>
              <Badge variant="primary">Premium</Badge>
            </div>
          </div>
        </CardHeader>
        <CardBody>
          <Input
            label="Email"
            type="email"
            placeholder="tu@email.com"
            helperText="Ingresa tu correo electrónico"
          />
          
          <Tooltip content="Haz clic para enviar" position="top">
            <Button variant="primary" fullWidth>
              Enviar
            </Button>
          </Tooltip>
        </CardBody>
      </Card>

      {/* Dropdown */}
      <Dropdown trigger={<Button variant="secondary">Opciones</Button>}>
        <DropdownItem icon={<span>👤</span>}>Mi Perfil</DropdownItem>
        <DropdownItem icon={<span>⚙️</span>}>Configuración</DropdownItem>
        <DropdownDivider />
        <DropdownItem danger icon={<span>🚪</span>}>Cerrar Sesión</DropdownItem>
      </Dropdown>

      {/* Modal */}
      <Button onClick={() => setIsModalOpen(true)}>Abrir Modal</Button>
      <Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)} size="md">
        <ModalHeader title="Título del Modal" onClose={() => setIsModalOpen(false)} />
        <ModalBody>
          <p>Contenido del modal</p>
        </ModalBody>
        <ModalFooter>
          <Button variant="secondary" onClick={() => setIsModalOpen(false)}>
            Cancelar
          </Button>
          <Button variant="primary">Aceptar</Button>
        </ModalFooter>
      </Modal>

      {/* Spinner */}
      {loading && <Spinner size="lg" variant="primary" />}
    </div>
  );
}
```

## 🎨 Personalización de Temas

```tsx
// Cambiar tema programáticamente
document.documentElement.setAttribute('data-theme', 'dark'); // o 'light'

// Personalizar variables CSS
const customStyles = `
  :root {
    --au-primary-600: #your-color;
    --au-spacing-4: 1.5rem;
  }
`;
```

## 📖 API de Componentes

### Button

```tsx
<Button
  variant="primary" // 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'ghost' | 'link'
  size="md" // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  fullWidth={false}
  loading={false}
  disabled={false}
  leftIcon={<Icon />}
  rightIcon={<Icon />}
  onClick={() => {}}
>
  Texto del Botón
</Button>
```

### Avatar

```tsx
<Avatar
  src="/avatar.jpg"
  alt="Usuario"
  size="md" // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  initials="AB"
  status="online" // 'online' | 'offline' | 'busy' | 'away'
/>
```

### Badge

```tsx
<Badge
  variant="primary" // 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'
  size="md" // 'sm' | 'md' | 'lg'
  dot={false}
>
  Texto
</Badge>
```

### Alert

```tsx
<Alert
  variant="success" // 'success' | 'warning' | 'danger' | 'info'
  title="Título"
  message="Mensaje"
  closable={true}
  onClose={() => {}}
/>
```

## 🎯 Variables CSS Disponibles

### Colores
- `--au-primary-*` (50-950)
- `--au-gray-*` (50-950)
- `--au-success-*`
- `--au-warning-*`
- `--au-danger-*`
- `--au-info-*`

### Espaciado
- `--au-spacing-0` a `--au-spacing-24`

### Tipografía
- `--au-text-xs` a `--au-text-4xl`
- `--au-font-normal`, `--au-font-medium`, `--au-font-semibold`, `--au-font-bold`

### Bordes
- `--au-radius-none` a `--au-radius-full`

### Sombras
- `--au-shadow-sm` a `--au-shadow-xl`

## 🛠️ Utilidades

```tsx
import { cn, debounce, throttle, generateId } from 'avanza-ui';

// Combinar clases
const className = cn('base-class', condition && 'conditional-class');

// Debounce
const debouncedFn = debounce((value) => console.log(value), 300);

// Throttle
const throttledFn = throttle(() => console.log('scroll'), 100);

// Generar ID único
const id = generateId('component'); // 'component-a1b2c3d4'
```

## 📄 Licencia

MIT

---

**Avanza UI** v1.0.0 - Sistema de componentes para AvanzaCast