AC Components 🚀

Librería de componentes premium para React, diseñada para ser altamente flexible, robusta y fácil de usar por desarrolladores de todos los niveles. Incluye validaciones integradas, manejo de formularios y una estética moderna.

📦 Instalación

Para instalar la librería en tu proyecto, ejecuta:

npm install ac-react-ui

🚀 Uso Básico

No necesitas importar el CSS por separado, ¡ya viene incluido en la librería!

import {
  Input, Select, DateRange, Button,
  Modal, Table, ToastContainer, toast,
  Tooltip, Tabs, Accordion, AccordionItem,
  Sidebar, Carousel,
} from 'ac-react-ui';

function App() {
  return (
    <div>
      <Input label="Nombre" placeholder="Escribe tu nombre" required />
      <Button scheme="primary">Enviar</Button>
    </div>
  );
}

🎨 Componentes

1. Input (Entradas de Texto)

Entrada de texto avanzada con soporte para validación en tiempo real, prefijos, sufijos y estados de error/advertencia.

Ejemplo de Uso

import { Input } from 'ac-react-ui';

<Input 
  label="Usuario" 
  placeholder="Escribe tu nombre de usuario" 
  required 
  prefix={<span>👤</span>}
  variant="outlined"
  color="#6366f1"
/>

API de Input

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | name | Nombre único para el campo y validación | string | - | | label | Etiqueta que aparece arriba del input | string | - | | showLabel | Muestra u oculta la etiqueta | boolean | true | | placeholder | Texto de ayuda dentro del campo | string | 'Escribe algo...' | | showPlaceholder | Muestra u oculta el placeholder | boolean | true | | type | Tipo de input (text, password, number, email, etc.) | string | 'text' | | value | Valor controlado del input | string \| number | - | | defaultValue | Valor inicial (modo no controlado) | string \| number | '' | | width | Ancho del componente (px, %, etc) | string \| number | '100%' | | height | Alto del campo de entrada | string \| number | - | | size | Tamaño del componente | 'small' \| 'medium' \| 'large' | 'medium' | | variant | Estilo visual del input | 'outlined' \| 'filled' \| 'underlined' \| 'borderless' | 'outlined' | | color | Color principal (foco y acento) | string | '#6366f1' | | minLength | Cantidad mínima de caracteres | number | - | | maxLength | Cantidad máxima de caracteres | number | - | | textOnly | Bloquea todo lo que no sea letras | boolean | false | | allowSpecialChars| Permite o bloquea caracteres especiales | boolean | true | | allowedChars | Regex o cadena de caracteres permitidos | string | - | | showCounter | Muestra contador de caracteres | boolean | false | | prefix | Elemento o icono al inicio | ReactNode | - | | suffix | Elemento o icono al final | ReactNode | - | | status | Estado visual del campo | 'default' \| 'error' \| 'warning' | 'default' | | errorMessage | Mensaje de error personalizado | string | - | | required | Campo obligatorio | boolean | false | | disabled | Deshabilita el input | boolean | false | | readOnly | Pone el campo en modo lectura | boolean | false | | autoComplete | Atributo autocomplete de HTML | string | - |

2. Select (Selector Premium)

Selector personalizable que soporta búsqueda, selección múltiple y limpieza de datos.

Ejemplo de Uso

import { Select } from 'ac-react-ui';

const options = [
  { value: 'react', label: 'React' },
  { value: 'vue', label: 'Vue' }
];

<Select 
  label="Framework Favorito" 
  options={options} 
  searchable 
  multiple 
  placeholder="Selecciona uno o varios" 
/>

API de Select

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | name | Nombre del campo | string | - | | label | Etiqueta del selector | string | - | | showLabel | Muestra u oculta la etiqueta | boolean | true | | options | Lista de opciones | {value, label}[] | [] | | value | Valor seleccionado (controlado) | any \| any[] | - | | defaultValue | Valor inicial | any \| any[] | - | | placeholder | Texto cuando no hay selección | string | 'Seleccionar...' | | searchable | Habilita búsqueda interna | boolean | false | | searchPlaceholder| Placeholder del buscador | string | 'Buscar...' | | multiple | Permite selección múltiple | boolean | false | | clearable | Permite limpiar la selección | boolean | false | | width | Ancho total | string \| number | '100%' | | height | Alto del selector | string \| number | - | | maxDropdownHeight| Alto máximo del menú desplegable | number | - | | color | Color de realce y foco | string | '#6366f1' | | noResultsText | Texto cuando no hay coincidencias | string | 'Sin resultados' |

3. DateRange (Selector de Fechas)

Calendario interactivo para selección de rangos de fechas con soporte para límites de tiempo.

Ejemplo de Uso

import { DateRange } from 'ac-react-ui';

const [range, setRange] = useState({ start: null, end: null });

<DateRange 
  label="Periodo de Reporte"
  value={range}
  onChange={(val) => setRange(val)}
  allowPastDates={false}
  color="#6366f1"
/>

API de DateRange

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | name | Nombre del campo | string | - | | label | Etiqueta del selector | string | - | | showLabel | Muestra u oculta la etiqueta | boolean | true | | value | Rango seleccionado {start, end} | object | - | | defaultValue | Rango inicial | object | - | | placeholder | Texto sin selección | string | 'Seleccionar rango' | | width | Ancho total | string \| number | '100%' | | height | Alto del campo de texto | string \| number | - | | color | Color del rango y botones | string | '#6366f1' | | rangeColor | Color específico del rango | string | - | | allowFutureDates | Permite fechas futuras | boolean | true | | allowPastDates | Permite fechas pasadas | boolean | true | | minDate | Fecha mínima permitida | Date | - | | maxDate | Fecha máxima permitida | Date | - | | locale | Idioma del calendario | 'es' \| 'en' | 'es' | | formatDate | Función para formatear la fecha | function | - |

4. Modal (Ventanas Emergentes)

Modales elegantes con tipos predefinidos (info, success, error) y contenido personalizado.

Ejemplo de Uso

import { Modal } from 'ac-react-ui';

const [isOpen, setIsOpen] = useState(false);

<Modal 
  isOpen={isOpen} 
  onClose={() => setIsOpen(false)} 
  type="success"
  title="Operación Exitosa"
>
  <p>Los datos han sido guardados correctamente.</p>
</Modal>

API de Modal

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | isOpen | Controla la visibilidad | boolean | false | | title | Título del modal | string | 'Aviso' | | type | Tipo predefinido | 'info' \| 'success' \| 'error' \| 'custom' | 'info' | | maxWidth | Ancho máximo (en px) | number | 500 | | color | Color del tema / icono | string | - | | overlayColor | Color del fondo detrás del modal (rgba/hex) | string | 'rgba(0,0,0,0.5)' | | blur | Nivel de desenfoque del fondo | string | number | '4px' | | showCloseButton | Muestra la X de cerrar | boolean | true | | closeOnOverlay | Cierra al pulsar fuera | boolean | true | | closeOnEscape | Cierra al pulsar Escape | boolean | true | | icon | Icono personalizado | ReactNode | - | | footer | Pie del modal personalizado | ReactNode | - | | onClose | Callback al cerrar | function | - |

5. Table (Grid de Datos Avanzado)

Potente grid de datos con ordenamiento lógico, filtrado por columna y búsqueda global.

Ejemplo de Uso

import { Table } from 'ac-react-ui';

const columns = [
  { key: 'id', header: 'ID', width: 60 },
  { key: 'nombre', header: 'Nombre', sortable: true, filterable: true },
  { key: 'rol', header: 'Rol', filterable: true }
];

<Table 
  columns={columns} 
  data={miArregloDeDatos} 
  pagination 
  searchable 
  color="#4f46e5"
/>

API de Table

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | columns | Configuración de columnas | ColumnDef[] | [] | | data | Arreglo de datos | object[] | [] | | width | Ancho total | string \| number | '100%' | | height | Alto máximo del área de datos | string \| number | - | | color | Color de acento y paginación | string | '#4f46e5' | | pagination | Habilita paginación | boolean | true | | pageSize | Filas por página iniciales | number | 10 | | pageSizeOptions | Opciones de tamaño de página | number[] | [5, 10, 20, 50] | | searchable | Muestra buscador global | boolean | true | | searchPlaceholder| Placeholder del buscador | string | 'Buscar...' | | emptyMessage | Mensaje si no hay datos | string | 'No hay datos para mostrar' | | rowKey | Propiedad que actúa como ID único | string | - | | striped | Filas con colores alternos | boolean | true | | hoverable | Efecto hover en filas | boolean | true | | onRowClick | Callback al pulsar una fila | function(row) | - |

6. Button (Botones)

Botones con variantes visuales, tamaños, iconos, estado de carga y colores personalizados.

Ejemplo de Uso

import { Button } from 'ac-react-ui';

<Button scheme="primary" iconLeft={<span>👍</span>}>
  Primario
</Button>
<Button scheme="secondary" variant="outlined">
  Secundario
</Button>
<Button color="#22c55e" loading>
  Guardando...
</Button>

API de Button

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | scheme | Esquema de color | 'primary' \| 'secondary' | 'primary' | | variant | Variante visual | 'contained' \| 'outlined' \| 'text' | 'contained' | | size | Tamaño del botón | 'small' \| 'medium' \| 'large' | 'medium' | | color | Color principal | string | '#6366f1' | | disabled | Deshabilita el botón | boolean | false | | loading | Muestra spinner de carga | boolean | false | | fullWidth | Ancho completo | boolean | false | | iconLeft | Icono a la izquierda | ReactNode | - | | iconRight | Icono a la derecha | ReactNode | - | | type | Tipo de botón HTML | 'button' \| 'submit' \| 'reset' | 'button' | | width | Ancho personalizado | string \| number | - | | height | Alto personalizado | string \| number | - | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

7. Toast / Notificación

Notificaciones emergentes con tipos predefinidos, posiciones configurables y auto-dismiss con barra de progreso.

Ejemplo de Uso

import { ToastContainer, toast } from 'ac-react-ui';

// Agrega ToastContainer una vez en tu layout
function Layout() {
  return (
    <ToastContainer
      position="top-right"
      showProgress
      maxToasts={5}
    />
  );
}

// Dispara toasts desde cualquier parte
toast.success('Operación exitosa');
toast.error('Ocurrió un error');
toast.info('Nueva actualización disponible');
toast.warning('Revisa los datos');
toast.custom({ title: 'Aviso', message: 'Mensaje personalizado', duration: 0 });

API de ToastContainer

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | position | Posición en pantalla | 'top-right' \| 'top-left' \| 'top-center' \| 'bottom-right' \| 'bottom-left' \| 'bottom-center' | 'top-right' | | maxToasts | Máximo de toasts visibles | number | 5 | | width | Ancho del contenedor | string \| number | - | | showProgress | Muestra barra de progreso | boolean | true | | textColor | Color del texto del toast | string | - | | bgColor | Color de fondo del toast | string | - |

API de toast

| Método | Descripción | |--------|-------------| | toast.success(msg, opts?) | Toast de éxito | | toast.error(msg, opts?) | Toast de error | | toast.info(msg, opts?) | Toast informativo | | toast.warning(msg, opts?) | Toast de advertencia | | toast.custom({ type?, title?, message?, duration?, icon? }) | Toast personalizado |

Opciones comunes: { title, duration, icon, color }. Con duration: 0 el toast no se cierra solo.

8. Tooltip

Tooltips con posiciones configurables, activación por hover o click, y contenido multimedia.

Ejemplo de Uso

import { Tooltip } from 'ac-react-ui';

<Tooltip content="Texto de ayuda" position="top">
  <span>Pasa el mouse</span>
</Tooltip>

<Tooltip
  content={<div><strong>Imagen</strong><img src="foto.jpg" /></div>}
  trigger="click"
  position="bottom"
>
  <button>Click para ver</button>
</Tooltip>

API de Tooltip

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | content | Contenido del tooltip (texto, imagen, video) | ReactNode | - | | position | Posición | 'top' \| 'bottom' \| 'left' \| 'right' | 'top' | | trigger | Modo de activación | 'hover' \| 'click' | 'hover' | | delay | Delay en ms para mostrar | number | 200 | | hideDelay | Delay en ms para ocultar | number | 100 | | maxWidth | Ancho máximo del tooltip | number | 280 | | width | Ancho personalizado | string \| number | - | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

9. Tabs (Pestañas)

Navegación por pestañas con tres variantes visuales, iconos y tabs deshabilitados.

Ejemplo de Uso

import { Tabs } from 'ac-react-ui';

const tabs = [
  { key: 'perfil', label: 'Perfil', content: <div>Contenido del perfil</div> },
  { key: 'ajustes', label: 'Ajustes', icon: <span>⚙️</span>, content: <div>Ajustes</div> },
];

<Tabs tabs={tabs} variant="pills" color="#6366f1" />

API de Tabs

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | tabs | Array de tabs con { key, label, icon?, disabled?, content } | TabDef[] | [] | | activeKey | Tab activo (controlado) | string | - | | defaultActiveKey | Tab inicial (no controlado) | string | primer tab | | onChange | Callback al cambiar de tab | function | - | | variant | Variante visual | 'underlined' \| 'pills' \| 'boxed' | 'underlined' | | color | Color del tab activo | string | '#6366f1' | | width | Ancho del contenedor | string \| number | - | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

10. Accordion (Acordeón)

Acordeones expandibles con soporte para apertura múltiple, iconos, items deshabilitados y anidados.

Ejemplo de Uso

import { Accordion, AccordionItem } from 'ac-react-ui';

<Accordion multiple defaultActiveKeys={['1']}>
  <AccordionItem itemKey="1" title="¿Qué es?" icon={<span>📦</span>}>
    Es una librería de componentes React.
  </AccordionItem>
  <AccordionItem itemKey="2" title="¿Cómo se usa?" disabled>
    Este está deshabilitado.
  </AccordionItem>
  <AccordionItem itemKey="3" title="Anidado">
    <Accordion>
      <AccordionItem itemKey="3a" title="Sub-item">Contenido anidado</AccordionItem>
    </Accordion>
  </AccordionItem>
</Accordion>

API de Accordion

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | multiple | Permite múltiples items abiertos | boolean | false | | defaultActiveKeys | Keys inicialmente abiertos | string[] | [] | | activeKeys | Keys abiertos (controlado) | string[] | - | | onChange | Callback al cambiar items abiertos | function | - | | width | Ancho del contenedor | string \| number | - | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

API de AccordionItem

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | title | Título del item | ReactNode | - | | icon | Icono del item | ReactNode | - | | itemKey | Key único del item | string | - | | disabled | Item deshabilitado | boolean | false |

11. Sidebar (Panel Lateral)

Panel lateral con dos modos: drawer (superposición vía portal) y persistent (en línea para layouts fijos). Soporta navegación con accordion, colapso a iconos, enlace activo e integración con React Router.

Ejemplo de Uso

import { Sidebar } from 'ac-react-ui';

const [open, setOpen] = useState(false);
const [collapsed, setCollapsed] = useState(false);

const navItems = [
  { key: 'home', label: 'Inicio', icon: <span>🏠</span>, onClick: () => {} },
  {
    key: 'users', label: 'Usuarios', icon: <span>👥</span>,
    children: [
      { key: 'list', label: 'Listado', onClick: () => {} },
      { key: 'roles', label: 'Roles', onClick: () => {}, disabled: true },
    ],
  },
];

// Modo drawer
<Sidebar isOpen={open} onClose={() => setOpen(false)} position="left" title="Menú">
  <p>Contenido del sidebar</p>
</Sidebar>

// Modo persistente con navegación y colapso
<div style={{ display: 'flex' }}>
  <Sidebar
    type="persistent"
    collapsible
    collapsed={collapsed}
    onCollapse={setCollapsed}
    width={250}
    title="Mi App"
    items={navItems}
  />
  <main style={{ flex: 1 }}>Contenido principal</main>
</div>

API de Sidebar

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | type | Modo del sidebar | 'drawer' \| 'persistent' | 'drawer' | | isOpen | Controla apertura/cierre (drawer) | boolean | false | | onClose | Callback al cerrar (drawer) | function | - | | position | Lado de aparición (drawer) | 'left' \| 'right' | 'left' | | overlay | Muestra overlay oscuro (drawer) | boolean | true | | closeOnOverlay | Cierra al hacer clic fuera | boolean | true | | closeOnEscape | Cierra con tecla Escape | boolean | true | | collapsible | Permite colapsar a iconos (persistent) | boolean | false | | collapsed | Estado colapsado (controlado) | boolean | - | | defaultCollapsed | Estado colapsado inicial | boolean | false | | collapsedWidth | Ancho cuando está colapsado | string \| number | 60 | | onCollapse | Callback al colapsar/expandir | function | - | | width | Ancho del sidebar | string \| number | 280 | | height | Alto del sidebar | string \| number | - | | title | Título en el header | string | - | | items | Items de navegación (soporta children para accordion) | ItemDef[] | - | | linkComponent | Componente para links (NavLink de React Router) | element | 'a' | | activePath | Path activo para resaltar item | string | location.pathname | | onItemClick | Callback al hacer clic en un item | function(item) | - | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

Estructura de ItemDef

| Propiedad | Tipo | Descripción | |-----------|------|-------------| | key | string | Identificador único | | label | string | Texto mostrado | | icon | ReactNode | Icono (SVG, emoji, etc.) | | path | string | Ruta de navegación (con linkComponent) | | onClick | function(item) | Callback al hacer clic | | children | ItemDef[] | Sub-items que se muestran como accordion | | disabled | boolean | Deshabilita el item |

12. Carousel (Carrusel)

Carrusel de imágenes con flechas, indicadores, auto-play, loop infinito y títulos descriptivos.

Ejemplo de Uso

import { Carousel } from 'ac-react-ui';

const slides = [
  { image: '/foto1.jpg', title: 'Montañas', description: 'Paisaje increíble' },
  { image: '/foto2.jpg', title: 'Lago', description: 'Atardecer en el lago' },
];

<Carousel
  slides={slides}
  height={400}
  autoPlay
  interval={3000}
  captionPosition="bottom"
/>

API de Carousel

| Propiedad | Descripción | Tipo | Por defecto | |-----------|-------------|------|-------------| | slides | Array de slides { image, title?, description? } | Slide[] | [] | | showArrows | Muestra flechas de navegación | boolean | true | | showDots | Muestra puntitos indicadores | boolean | true | | captionPosition | Posición del título/descripción | 'bottom' \| 'top' \| 'center' \| 'hidden' | 'bottom' | | autoPlay | Reproducción automática | boolean | false | | interval | Intervalo en ms entre slides | number | 3000 | | loop | Navegación infinita | boolean | true | | height | Alto del carrusel | string \| number | 400 | | width | Ancho del carrusel | string \| number | '100%' | | textColor | Color del texto | string | - | | bgColor | Color de fondo | string | - |

🛡️ Validación Global

La librería incluye un hook para acceder al estado de validación global, ideal para bloquear botones de "Enviar" si hay errores.

import { useValidationStore } from 'ac-react-ui';

function MiFormulario() {
  const { errors, isValid } = useValidationStore();
  
  return (
    <button disabled={!isValid}>
      Enviar ({Object.keys(errors).length} errores)
    </button>
  );
}

🔔 Toast Store

La librería incluye un store de Zustand para manejar notificaciones toast de forma global.

import { toast, useToastStore } from 'ac-react-ui';

// Disparar toasts desde cualquier lugar
toast.success('Operación exitosa');
toast.error('Error al guardar');

// Acceder al estado de toasts
function MyComponent() {
  const toasts = useToastStore(s => s.toasts);
  return <div>{toasts.length} notificaciones activas</div>;
}

✨ Características Especiales

• Validaciones Inteligentes: Soporta validaciones complejas que se disparan al escribir o al enviar el formulario.
• Inyección Automática: No requiere configuración de CSS adicional.
• Personalización Total: Soporte universal para className, style, width y height.
• Accesibilidad: Diseñado siguiendo estándares de usabilidad modernos.