@etus/ui 0.1.1 → 0.1.2

package/src/components/data-display/Carousel/README.md

@@ -1,711 +0,0 @@
-# Carousel
-
-## Visão Geral
-
-O Carousel e um componente de exibicao de dados que permite navegar por uma sequencia de itens (slides) de forma horizontal ou vertical. Construido sobre o Embla Carousel, oferece uma experiencia fluida com suporte a gestos touch, navegacao por teclado e APIs programaticas.
-
-### Classificacao Atomica
-- **Categoria**: Organisms
-- **Subcategoria**: Data Display / Navigation
-
-### Casos de Uso Comuns
-- Galeria de imagens de produtos
-- Slides de apresentacao
-- Carrossel de testimonials
-- Listagem horizontal de cards
-- Onboarding flows
-- Banner rotativo de promocoes
-- Preview de arquivos
-
-### Relacao com Outros Componentes
-- **ImageGallery**: Usa Carousel internamente
-- **Card**: Items frequentemente sao Cards
-- **Button**: Controles de navegacao
-- **Lightbox**: Pode ser ativado a partir de carousel
-
-## Design Specs
-
-### Componentes do Sistema
-
-1. **Carousel**: Container principal com provider de contexto
-2. **CarouselContent**: Container dos slides
-3. **CarouselItem**: Slide individual
-4. **CarouselPrevious**: Botao de navegacao anterior
-5. **CarouselNext**: Botao de navegacao proximo
-
-### Orientacoes
-
-| Orientacao | Eixo | Navegacao |
-|------------|------|-----------|
-| `horizontal` | X | ArrowLeft / ArrowRight |
-| `vertical` | Y | ArrowUp / ArrowDown |
-
-### Variantes de Botao
-
-Os botoes usam o componente Button com variantes:
-
-- **variant**: `outline` (padrao)
-- **size**: `icon` (padrao)
-
-### Estados
-
-- **Default**: Slide ativo visivel
-- **Can Scroll Prev**: Botao anterior habilitado
-- **Can Scroll Next**: Botao proximo habilitado
-- **Disabled**: Botao desabilitado quando nao pode navegar
-
-### Tokens de Design
-
-#### Cores
-- Botoes: Herdam do Button component
-- Background: Transparente
-
-#### Espacamento
-- Item Padding: `pl-4` (horizontal) ou `pt-4` (vertical)
-- Content Margin: `-ml-4` (horizontal) ou `-mt-4` (vertical)
-- Button Size: `size-8`
-- Button Position: `-left-12` / `-right-12` ou `-top-12` / `-bottom-12`
-
-#### Tipografia
-- Botoes usam sr-only para texto
-
-#### Bordas e Arredondamento
-- Botoes: `rounded-full`
-
-#### Motion e Transicoes
-- Transicoes gerenciadas pelo Embla Carousel
-- Suporte a drag/swipe
-
-### Consideracoes de Responsividade
-
-- **Mobile**: Gestos touch funcionam nativamente
-- **Tablet**: Pode mostrar multiplos slides
-- **Desktop**: Navegacao por botoes e teclado
-- **Basis**: Use `basis-1/2`, `basis-1/3` para multiplos slides visiveis
-
-## API
-
-### Carousel
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direcao do carousel |
-| `opts` | `CarouselOptions` | - | Opcoes do Embla Carousel |
-| `plugins` | `CarouselPlugin` | - | Plugins do Embla |
-| `setApi` | `(api: CarouselApi) => void` | - | Callback para acessar API |
-| `className` | `string` | `""` | Classes Tailwind |
-
-### CarouselOptions (Embla)
-
-| Opcao | Tipo | Padrao | Descricao |
-|-------|------|--------|-----------|
-| `loop` | `boolean` | `false` | Loop infinito |
-| `align` | `"start" \| "center" \| "end"` | `"start"` | Alinhamento dos slides |
-| `dragFree` | `boolean` | `false` | Arraste livre sem snap |
-| `containScroll` | `"trimSnaps" \| "keepSnaps" \| false` | - | Comportamento de scroll |
-| `slidesToScroll` | `number \| "auto"` | `1` | Slides por navegacao |
-
-### CarouselContent
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `""` | Classes Tailwind |
-
-### CarouselItem
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `""` | Classes Tailwind |
-
-### CarouselPrevious / CarouselNext
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `variant` | `ButtonVariant` | `"outline"` | Variante do botao |
-| `size` | `ButtonSize` | `"icon"` | Tamanho do botao |
-| `className` | `string` | `""` | Classes Tailwind |
-
-### Hook: useCarousel
-
-```typescript
-function useCarousel(): {
-  carouselRef: RefObject<HTMLDivElement>
-  api: EmblaCarouselType | undefined
-  opts: CarouselOptions | undefined
-  orientation: "horizontal" | "vertical"
-  scrollPrev: () => void
-  scrollNext: () => void
-  canScrollPrev: boolean
-  canScrollNext: boolean
-}
-```
-
-Deve ser usado dentro de `Carousel`.
-
-### Interfaces TypeScript
-
-```typescript
-import type { UseEmblaCarouselType } from "embla-carousel-react"
-
-// API do Carousel
-type CarouselApi = UseEmblaCarouselType[1]
-
-// Opcoes do Embla
-type CarouselOptions = Parameters<typeof useEmblaCarousel>[0]
-
-// Plugins do Embla
-type CarouselPlugin = Parameters<typeof useEmblaCarousel>[1]
-
-// Props do Carousel
-interface CarouselProps extends React.ComponentProps<"div"> {
-  opts?: CarouselOptions
-  plugins?: CarouselPlugin
-  orientation?: "horizontal" | "vertical"
-  setApi?: (api: CarouselApi) => void
-}
-
-// Context
-interface CarouselContextProps extends CarouselProps {
-  carouselRef: ReturnType<typeof useEmblaCarousel>[0]
-  api: ReturnType<typeof useEmblaCarousel>[1]
-  scrollPrev: () => void
-  scrollNext: () => void
-  canScrollPrev: boolean
-  canScrollNext: boolean
-}
-```
-
-### Comparacao com Referencias
-
-| Feature | ETUS | Embla | Swiper | React Slick |
-|---------|------|-------|--------|-------------|
-| Bundle Size | ~15KB | ~15KB | ~140KB | ~45KB |
-| Touch/Swipe | Sim | Sim | Sim | Sim |
-| Loop | Sim | Sim | Sim | Sim |
-| Autoplay | Plugin | Plugin | Nativo | Nativo |
-| Lazy Load | Plugin | Plugin | Nativo | Nativo |
-| TypeScript | Sim | Sim | Sim | Parcial |
-| SSR | Sim | Sim | Sim | Sim |
-
-## Acessibilidade (A11y)
-
-### Atributos ARIA
-
-O componente implementa:
-
-- `role="region"` no container
-- `aria-roledescription="carousel"` no container
-- `role="group"` em cada slide
-- `aria-roledescription="slide"` em cada slide
-- `aria-label` nos botoes de navegacao
-
-### Navegacao por Teclado
-
-| Tecla | Acao |
-|-------|------|
-| `ArrowLeft` | Slide anterior (horizontal) |
-| `ArrowRight` | Proximo slide (horizontal) |
-| `ArrowUp` | Slide anterior (vertical) |
-| `ArrowDown` | Proximo slide (vertical) |
-| `Tab` | Navega para elementos focaveis dentro dos slides |
-
-### Contraste e Legibilidade
-
-- Botoes com contraste adequado
-- Indicadores visiveis de navegacao
-- Estados disabled claramente visiveis
-
-### Tecnologias Assistivas
-
-- Screen readers anunciam "carousel" e "slide X of Y"
-- Botoes Previous/Next tem labels descritivos
-- Conteudo dos slides e lido normalmente
-
-### Conformidade WCAG
-
-- **1.3.1** Info e Relacionamentos: Estrutura semantica correta
-- **2.1.1** Teclado: Totalmente navegavel por teclado
-- **2.4.3** Ordem de foco: Ordem logica
-- **4.1.2** Nome, Funcao, Valor: Roles e labels corretos
-
-## Exemplos
-
-### Uso Basico
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from '@etus/ui'
-
-function BasicCarousel() {
-  return (
-    <Carousel className="w-full max-w-xs">
-      <CarouselContent>
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 1</div>
-        </CarouselItem>
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 2</div>
-        </CarouselItem>
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 3</div>
-        </CarouselItem>
-      </CarouselContent>
-      <CarouselPrevious />
-      <CarouselNext />
-    </Carousel>
-  )
-}
-```
-
-### Multiplos Slides Visiveis
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from '@etus/ui'
-import { Card, CardContent } from '@etus/ui'
-
-function MultiSlideCarousel() {
-  return (
-    <Carousel className="w-full">
-      <CarouselContent className="-ml-2 md:-ml-4">
-        {Array.from({ length: 5 }).map((_, index) => (
-          <CarouselItem
-            key={index}
-            className="pl-2 md:pl-4 basis-1/2 md:basis-1/3 lg:basis-1/4"
-          >
-            <Card>
-              <CardContent className="flex aspect-square items-center justify-center p-6">
-                <span className="text-3xl font-semibold">{index + 1}</span>
-              </CardContent>
-            </Card>
-          </CarouselItem>
-        ))}
-      </CarouselContent>
-      <CarouselPrevious />
-      <CarouselNext />
-    </Carousel>
-  )
-}
-```
-
-### Loop Infinito
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from '@etus/ui'
-
-function LoopCarousel() {
-  return (
-    <Carousel
-      opts={{
-        loop: true,
-      }}
-      className="w-full max-w-sm"
-    >
-      <CarouselContent>
-        {images.map((src, index) => (
-          <CarouselItem key={index}>
-            <img
-              src={src}
-              alt={`Slide ${index + 1}`}
-              className="w-full aspect-video object-cover rounded-lg"
-            />
-          </CarouselItem>
-        ))}
-      </CarouselContent>
-      <CarouselPrevious />
-      <CarouselNext />
-    </Carousel>
-  )
-}
-```
-
-### Vertical
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from '@etus/ui'
-
-function VerticalCarousel() {
-  return (
-    <Carousel
-      orientation="vertical"
-      className="w-full max-w-xs"
-    >
-      <CarouselContent className="h-[200px]">
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 1</div>
-        </CarouselItem>
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 2</div>
-        </CarouselItem>
-        <CarouselItem>
-          <div className="p-6 bg-muted rounded-lg">Slide 3</div>
-        </CarouselItem>
-      </CarouselContent>
-      <CarouselPrevious />
-      <CarouselNext />
-    </Carousel>
-  )
-}
-```
-
-### Com Autoplay (Plugin)
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem
-} from '@etus/ui'
-import Autoplay from 'embla-carousel-autoplay'
-
-function AutoplayCarousel() {
-  return (
-    <Carousel
-      plugins={[
-        Autoplay({
-          delay: 3000,
-          stopOnInteraction: true,
-        }),
-      ]}
-      className="w-full max-w-lg"
-    >
-      <CarouselContent>
-        {slides.map((slide, index) => (
-          <CarouselItem key={index}>
-            <div className="p-6 bg-primary text-primary-foreground rounded-lg">
-              {slide.title}
-            </div>
-          </CarouselItem>
-        ))}
-      </CarouselContent>
-    </Carousel>
-  )
-}
-```
-
-### Acessando a API
-
-```tsx
-import { useState, useEffect } from 'react'
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  type CarouselApi
-} from '@etus/ui'
-
-function CarouselWithAPI() {
-  const [api, setApi] = useState<CarouselApi>()
-  const [current, setCurrent] = useState(0)
-  const [count, setCount] = useState(0)
-
-  useEffect(() => {
-    if (!api) return
-
-    setCount(api.scrollSnapList().length)
-    setCurrent(api.selectedScrollSnap() + 1)
-
-    api.on('select', () => {
-      setCurrent(api.selectedScrollSnap() + 1)
-    })
-  }, [api])
-
-  return (
-    <div>
-      <Carousel setApi={setApi}>
-        <CarouselContent>
-          {items.map((item, index) => (
-            <CarouselItem key={index}>{item}</CarouselItem>
-          ))}
-        </CarouselContent>
-      </Carousel>
-      <p className="text-center text-sm text-muted-foreground mt-2">
-        Slide {current} of {count}
-      </p>
-    </div>
-  )
-}
-```
-
-### Galeria de Produtos
-
-```tsx
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from '@etus/ui'
-import { Card, CardContent, CardFooter } from '@etus/ui'
-import { Button } from '@etus/ui'
-
-function ProductCarousel({ products }) {
-  return (
-    <Carousel className="w-full">
-      <CarouselContent>
-        {products.map((product) => (
-          <CarouselItem
-            key={product.id}
-            className="md:basis-1/2 lg:basis-1/3"
-          >
-            <Card>
-              <CardContent className="p-0">
-                <img
-                  src={product.image}
-                  alt={product.name}
-                  className="w-full aspect-square object-cover"
-                />
-              </CardContent>
-              <CardFooter className="flex-col items-start gap-2 p-4">
-                <h3 className="font-semibold">{product.name}</h3>
-                <p className="text-lg font-bold">
-                  R$ {product.price.toFixed(2)}
-                </p>
-                <Button className="w-full">Adicionar ao carrinho</Button>
-              </CardFooter>
-            </Card>
-          </CarouselItem>
-        ))}
-      </CarouselContent>
-      <CarouselPrevious className="-left-4" />
-      <CarouselNext className="-right-4" />
-    </Carousel>
-  )
-}
-```
-
-### Thumbnails Sync
-
-```tsx
-import { useState, useCallback } from 'react'
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  type CarouselApi
-} from '@etus/ui'
-
-function ThumbnailCarousel({ images }) {
-  const [mainApi, setMainApi] = useState<CarouselApi>()
-  const [thumbApi, setThumbApi] = useState<CarouselApi>()
-  const [selected, setSelected] = useState(0)
-
-  const onSelect = useCallback(() => {
-    if (!mainApi || !thumbApi) return
-    setSelected(mainApi.selectedScrollSnap())
-    thumbApi.scrollTo(mainApi.selectedScrollSnap())
-  }, [mainApi, thumbApi])
-
-  return (
-    <div className="space-y-4">
-      <Carousel setApi={setMainApi} onSelect={onSelect}>
-        <CarouselContent>
-          {images.map((src, index) => (
-            <CarouselItem key={index}>
-              <img
-                src={src}
-                alt={`Image ${index + 1}`}
-                className="w-full aspect-video object-cover rounded-lg"
-              />
-            </CarouselItem>
-          ))}
-        </CarouselContent>
-      </Carousel>
-
-      <Carousel setApi={setThumbApi}>
-        <CarouselContent className="-ml-2">
-          {images.map((src, index) => (
-            <CarouselItem
-              key={index}
-              className="basis-1/4 pl-2 cursor-pointer"
-              onClick={() => mainApi?.scrollTo(index)}
-            >
-              <img
-                src={src}
-                alt=""
-                className={cn(
-                  "aspect-video object-cover rounded border-2",
-                  selected === index
-                    ? "border-primary"
-                    : "border-transparent"
-                )}
-              />
-            </CarouselItem>
-          ))}
-        </CarouselContent>
-      </Carousel>
-    </div>
-  )
-}
-```
-
-## Testes
-
-### Estrategias de Teste
-
-#### Testes Unitarios
-- Renderizacao dos slides
-- Navegacao prev/next
-- Estados disabled dos botoes
-
-#### Testes de Integracao
-- Swipe gestures (simulados)
-- Keyboard navigation
-- API callbacks
-
-#### Testes de Acessibilidade
-- ARIA roles e labels
-- Keyboard navigation
-- Screen reader announcements
-
-### Exemplos de Codigo
-
-```typescript
-import { describe, it, expect, vi } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import {
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext
-} from './Carousel'
-
-describe('Carousel', () => {
-  it('renders slides', () => {
-    render(
-      <Carousel>
-        <CarouselContent>
-          <CarouselItem>Slide 1</CarouselItem>
-          <CarouselItem>Slide 2</CarouselItem>
-        </CarouselContent>
-      </Carousel>
-    )
-
-    expect(screen.getByText('Slide 1')).toBeInTheDocument()
-    expect(screen.getByText('Slide 2')).toBeInTheDocument()
-  })
-
-  it('has carousel role', () => {
-    render(
-      <Carousel>
-        <CarouselContent>
-          <CarouselItem>Slide</CarouselItem>
-        </CarouselContent>
-      </Carousel>
-    )
-
-    expect(screen.getByRole('region')).toHaveAttribute(
-      'aria-roledescription',
-      'carousel'
-    )
-  })
-
-  it('has slide role on items', () => {
-    render(
-      <Carousel>
-        <CarouselContent>
-          <CarouselItem>Slide</CarouselItem>
-        </CarouselContent>
-      </Carousel>
-    )
-
-    expect(screen.getByRole('group')).toHaveAttribute(
-      'aria-roledescription',
-      'slide'
-    )
-  })
-
-  it('navigates with keyboard', async () => {
-    const user = userEvent.setup()
-
-    render(
-      <Carousel>
-        <CarouselContent>
-          <CarouselItem>Slide 1</CarouselItem>
-          <CarouselItem>Slide 2</CarouselItem>
-        </CarouselContent>
-        <CarouselPrevious />
-        <CarouselNext />
-      </Carousel>
-    )
-
-    const carousel = screen.getByRole('region')
-    carousel.focus()
-
-    await user.keyboard('{ArrowRight}')
-    // Assert slide changed
-  })
-
-  it('disables prev button at start', () => {
-    render(
-      <Carousel>
-        <CarouselContent>
-          <CarouselItem>Slide 1</CarouselItem>
-          <CarouselItem>Slide 2</CarouselItem>
-        </CarouselContent>
-        <CarouselPrevious />
-        <CarouselNext />
-      </Carousel>
-    )
-
-    expect(screen.getByLabelText('Previous slide')).toBeDisabled()
-  })
-
-  it('calls setApi with carousel API', () => {
-    const setApi = vi.fn()
-
-    render(
-      <Carousel setApi={setApi}>
-        <CarouselContent>
-          <CarouselItem>Slide</CarouselItem>
-        </CarouselContent>
-      </Carousel>
-    )
-
-    expect(setApi).toHaveBeenCalled()
-  })
-})
-```
-
----
-
-## Roadmap / Features Futuras
-
-- Construido sobre Embla Carousel para performance
-- Context API para compartilhar estado entre componentes
-- Suporta plugins do Embla (Autoplay, etc.)
-- Keyboard events capturados no container
-- `data-slot` para identificacao de partes
-- Botoes usam componente Button existente
-
-## Referências
-
-- [Embla Carousel](https://www.embla-carousel.com/)
-- [Shadcn UI Carousel](https://ui.shadcn.com/docs/components/carousel)
-- [WAI-ARIA Carousel Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/)
-- [Inclusive Components: A Content Slider](https://inclusive-components.design/a-content-slider/)

package/src/components/data-display/Carousel/index.ts

@@ -1 +0,0 @@
-export * from './Carousel'