componentes / carousel

Carousel

Slides con flechas, indicadores, teclado, autoplay opcional y loop.

Cómo usar

Cada hijo es un slide. Es una `region` con `aria-roledescription="carousel"`; los slides son `group`s y los que no se ven quedan ocultos para tecnologías de apoyo y sin foco. ←/→/Home/End navegan. El `autoplay` se pausa con el ratón y el foco y nunca corre con `prefers-reduced-motion`. `index` puede ser controlado; `slidesPerView` muestra varios slides a la vez.

preview

Carousel.tsx

import { Carousel } from "vaiperui";
 
<Carousel aria-label="Slides destacados" loop autoplay={4000}>
  <img src="/photos/1.jpg" alt="One" />
  <img src="/photos/2.jpg" alt="Two" />
  <img src="/photos/3.jpg" alt="Three" />
</Carousel>

Varios a la vez

preview

a-la-vez.tsx

<Carousel aria-label="..." slidesPerView={2}>...</Carousel>

Autoplay y loop

Se pausa con ratón y foco; no corre con prefers-reduced-motion.

preview

autoplay.tsx

<Carousel aria-label="..." loop autoplay={3000}>...</Carousel>

Controlado

preview

controlado.tsx

const [index, setIndex] = useState(0);
 
<Carousel aria-label="..." index={index} onIndexChange={setIndex}>...</Carousel>

Colores

preview

colores.tsx

<Carousel variantColor="primary" ...>
<Carousel variantColor="success" ...>
<Carousel variantColor="warning" ...>
<Carousel variantColor="danger" ...>

Color personalizado

preview

color-personalizado.tsx

<Carousel customColor="#db2777" ...>

Props

Prop	Valores	Predeterminado	Descripción
children	ReactNode	—	Un slide por hijo
aria-label	string	—	Nombre accesible del carrusel
index / defaultIndex	number	0	Primer slide visible controlado / inicial
onIndexChange	(index: number) => void	ninguno	Llamado cuando cambia la posición
slidesPerView	number	1	Slides visibles a la vez
loop	boolean	false	Volver del final al inicio
autoplay	boolean \| number	false	Avanza cada N ms (true = 5000). Se pausa con ratón/foco
showArrows / showDots	boolean	true	Mostrar las flechas / indicadores
previousLabel / nextLabel	string	Previous slide / Next slide	Nombres accesibles de las flechas
dotLabel	(index) => string	Go to slide N	Nombre accesible de cada indicador
slideLabel	(index, total) => string	N of total	Nombre accesible de cada slide
variantColor	primary \| success \| warning \| danger	primary	Color de acento (botón play, progreso, indicadores)
customColor	string \| { light, dark }	ninguno	Cualquier color CSS (o un par por tema). Reemplaza a variantColor
size	sm \| md \| lg	md	Tamaño de los controles y del texto
radius	none \| sm \| md \| lg \| full	lg	Redondeo de las esquinas
animation	none \| smooth \| fast \| bounce	smooth	Transición de los controles

Accesibilidad

La raíz es una `<section>` con `aria-roledescription="carousel"` y el `aria-label` que pasas.
Cada slide es un `role="group"` con `aria-roledescription="slide"` y un nombre de `slideLabel` (por defecto `1 of 5`).
Los slides fuera de vista quedan `aria-hidden` e `inert`, así que su contenido no se lee ni se enfoca.
Las flechas son botones nombrados por `previousLabel` / `nextLabel` (deshabilitadas en los extremos salvo con `loop`), y los puntos son botones nombrados por `dotLabel` con `aria-current="true"` en el actual.
El autoplay se pausa mientras el puntero está sobre el carrusel o el foco está dentro, y no corre con `prefers-reduced-motion: reduce`; la transición entre slides también se elimina.
El área de slides es `aria-live="off"` mientras corre el autoplay y `polite` en otro caso, así que los cambios manuales se anuncian.

Teclado

Tecla	Acción
ArrowLeft / ArrowRight	Slide anterior / siguiente (da la vuelta con `loop`)
Home / End	Primer / último slide
Tab	Recorre flechas, puntos y contenido enfocable de los slides visibles

Ten en cuenta

El autoplay no tiene botón de pausa; hover o foco lo pausan. Prefiere sin autoplay, o un intervalo largo, para contenido que hay que leer.
El texto alternativo de las imágenes y las etiquetas (`aria-label`, `slideLabel`, `dotLabel`, flechas) en el idioma de la página son responsabilidad de tu app.