AvanzaCast/packages/ui-components/QUICK_REFERENCE.md

🚀 Avanza UI - Referencia Rápida de Componentes

📋 Índice de Componentes

Formularios

• Button - Botones con múltiples variantes
• Input - Campos de texto
• Textarea - Área de texto
• Select - Selector dropdown
• Checkbox - Casillas de verificación
• Radio - Botones de radio
• Switch - Toggle switch

Layout

• Card - Tarjetas con secciones
• Tabs - Pestañas

Feedback

• Alert - Mensajes de alerta
• Spinner - Indicador de carga
• Tooltip - Tooltips

Display

• Avatar - Avatares con status
• Badge - Insignias

Overlay

• Modal - Modales
• Dropdown - Menús desplegables

---

Button

<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

<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

<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

<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

<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

<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

<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

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

---

Tabs

<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

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

---

Spinner

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

---

Tooltip

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

---

Avatar

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

---

Badge

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

---

Modal

<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

<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

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

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

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

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