# 🚀 Avanza UI - Referencia Rápida de Componentes

## 📋 Índice de Componentes

### Formularios
- [Button](#button) - Botones con múltiples variantes
- [Input](#input) - Campos de texto
- [Textarea](#textarea) - Área de texto
- [Select](#select) - Selector dropdown
- [Checkbox](#checkbox) - Casillas de verificación
- [Radio](#radio) - Botones de radio
- [Switch](#switch) - Toggle switch

### Layout
- [Card](#card) - Tarjetas con secciones
- [Tabs](#tabs) - Pestañas

### Feedback
- [Alert](#alert) - Mensajes de alerta
- [Spinner](#spinner) - Indicador de carga
- [Tooltip](#tooltip) - Tooltips

### Display
- [Avatar](#avatar) - Avatares con status
- [Badge](#badge) - Insignias

### Overlay
- [Modal](#modal) - Modales
- [Dropdown](#dropdown) - Menús desplegables

---

## 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={() => {}}
>
  Click me
</Button>
```

---

## Input

```tsx
<Input
  label="Email"
  type="email" // 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search'
  placeholder="you@example.com"
  size="md" // 'sm' | 'md' | 'lg'
  error={false}
  errorMessage="Error message"
  success={false}
  helperText="Helper text"
  leftIcon={<Icon />}
  rightIcon={<Icon />}
  fullWidth={true}
  required={false}
  disabled={false}
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>
```

---

## Textarea

```tsx
<Textarea
  label="Description"
  placeholder="Enter description..."
  rows={4}
  maxLength={500}
  showCharacterCount={true}
  resize="vertical" // 'none' | 'vertical' | 'horizontal' | 'both'
  error={false}
  errorMessage="Error"
  helperText="Helper text"
  fullWidth={true}
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>
```

---

## Select

```tsx
<Select
  label="Country"
  placeholder="Select country"
  options={[
    { label: 'Mexico', value: 'mx' },
    { label: 'Spain', value: 'es', disabled: true }
  ]}
  size="md" // 'sm' | 'md' | 'lg'
  error={false}
  errorMessage="Error"
  helperText="Helper"
  fullWidth={true}
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>
```

---

## Checkbox

```tsx
<Checkbox
  label="Accept terms"
  variant="primary" // 'primary' | 'success' | 'warning' | 'danger' | 'info'
  size="md" // 'sm' | 'md' | 'lg'
  checked={isChecked}
  defaultChecked={false}
  disabled={false}
  onChange={(e) => setIsChecked(e.target.checked)}
/>
```

---

## Radio

```tsx
<Radio
  label="Option 1"
  name="options"
  value="option1"
  variant="primary" // 'primary' | 'success' | 'warning' | 'danger' | 'info'
  size="md" // 'sm' | 'md' | 'lg'
  checked={selected === 'option1'}
  onChange={(e) => setSelected(e.target.value)}
/>
```

---

## Switch

```tsx
<Switch
  label="Dark mode"
  variant="primary" // 'primary' | 'success' | 'warning' | 'danger' | 'info'
  size="md" // 'sm' | 'md' | 'lg'
  checked={isDark}
  onChange={(e) => setIsDark(e.target.checked)}
/>
```

---

## Card

```tsx
<Card padding="md" hoverable={true} onClick={() => {}}>
  <CardHeader>
    <h3>Title</h3>
  </CardHeader>
  <CardBody>
    Content here
  </CardBody>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>
```

---

## Tabs

```tsx
<Tabs
  variant="default" // 'default' | 'pills' | 'boxed'
  orientation="horizontal" // 'horizontal' | 'vertical'
  tabs={[
    {
      id: 'tab1',
      label: 'Tab 1',
      icon: <Icon />,
      disabled: false,
      content: <div>Content 1</div>
    },
    {
      id: 'tab2',
      label: 'Tab 2',
      content: <div>Content 2</div>
    }
  ]}
  activeTab={activeTab}
  onTabChange={(id) => setActiveTab(id)}
/>
```

---

## Alert

```tsx
<Alert
  variant="success" // 'success' | 'warning' | 'danger' | 'info'
  title="Success!"
  message="Operation completed successfully"
  icon={<CustomIcon />}
  closable={true}
  onClose={() => {}}
/>
```

---

## Spinner

```tsx
<Spinner
  size="md" // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  variant="primary" // 'primary' | 'secondary' | 'white'
/>
```

---

## Tooltip

```tsx
<Tooltip
  content="Tooltip text"
  position="top" // 'top' | 'bottom' | 'left' | 'right'
>
  <Button>Hover me</Button>
</Tooltip>
```

---

## Avatar

```tsx
<Avatar
  src="/avatar.jpg"
  alt="User name"
  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}
>
  New
</Badge>
```

---

## Modal

```tsx
<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  size="md" // 'sm' | 'md' | 'lg' | 'xl' | 'fullScreen'
  closeOnOverlayClick={true}
  closeOnEscape={true}
>
  <ModalHeader 
    title="Modal Title"
    onClose={() => setIsOpen(false)}
    showCloseButton={true}
  />
  <ModalBody>
    Modal content
  </ModalBody>
  <ModalFooter>
    <Button variant="secondary" onClick={() => setIsOpen(false)}>Cancel</Button>
    <Button variant="primary">Confirm</Button>
  </ModalFooter>
</Modal>
```

---

## Dropdown

```tsx
<Dropdown
  trigger={<Button>Options</Button>}
  align="right" // 'left' | 'right' | 'center'
>
  <DropdownHeader>Header</DropdownHeader>
  <DropdownItem icon={<Icon />} onClick={() => {}}>
    Action 1
  </DropdownItem>
  <DropdownDivider />
  <DropdownItem danger onClick={() => {}}>
    Delete
  </DropdownItem>
</Dropdown>
```

---

## 🎨 Variables CSS Comunes

```css
/* Colores */
--au-primary-600: #4f46e5;
--au-success-600: #16a34a;
--au-danger-600: #dc2626;
--au-warning-600: #d97706;
--au-info-600: #2563eb;

/* Espaciado */
--au-spacing-2: 0.5rem;   /* 8px */
--au-spacing-4: 1rem;      /* 16px */
--au-spacing-6: 1.5rem;    /* 24px */

/* Bordes */
--au-radius-sm: 0.25rem;
--au-radius-md: 0.5rem;
--au-radius-lg: 0.75rem;

/* Sombras */
--au-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--au-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
```

---

## 🛠️ Utilidades

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

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

// Debounce
const handleSearch = debounce((query) => search(query), 300);

// Throttle
const handleScroll = throttle(() => onScroll(), 100);

// Generar ID
const id = generateId('input'); // 'input-abc123'
```

---

## 🎯 Cambiar Tema

```tsx
// Dark mode
document.documentElement.setAttribute('data-theme', 'dark');

// Light mode
document.documentElement.setAttribute('data-theme', 'light');

// En React
const [theme, setTheme] = useState('light');

useEffect(() => {
  document.documentElement.setAttribute('data-theme', theme);
}, [theme]);
```

---

## 📦 Importación

```tsx
// Importar estilos (solo una vez en main.tsx)
import 'avanza-ui/dist/index.css';

// Importar componentes
import {
  Button, Input, Select, Checkbox,
  Card, Tabs, Modal, Alert
} from 'avanza-ui';

// Importar tipos
import type { ButtonProps, SelectOption } from 'avanza-ui';

// Importar utilidades
import { cn, debounce } from 'avanza-ui';
```

---

**Avanza UI v1.0.0** - Referencia Rápida  
*Actualizado: 11 de Noviembre, 2025*