@dev-tcloud/tcloud-ui 6.24.0 → 6.25.0-beta.2

package/docs/tcloud-ui-carousel.md

@@ -0,0 +1,159 @@
+# TCloudUiCarousel
+
+O componente `tcloud-ui-carousel` exibe conteúdos em formato de carrossel horizontal, com suporte a imagens ou qualquer conteúdo projetado via `ng-content`. Ele foi pensado para banners, cards e blocos visuais simples, mantendo navegação, paginação, autoplay e efeitos configuráveis por atributos.
+
+## Características
+
+- Projeção de conteúdo via `ng-content`
+- Cada item projetado ocupa 100% da largura disponível do carrossel
+- Navegação por setas sobre a imagem
+- Paginação por indicadores sobre a imagem
+- Autoplay configurável
+- Suporte a efeito `slide` e `fade`
+- Loop opcional
+- Scroll snap opcional
+- Componente standalone
+
+## Instalação
+
+Importe o componente diretamente em componentes standalone:
+
+```typescript
+import { TCloudUiCarouselComponent } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiCarouselComponent],
+  template: `...`
+})
+export class ExemploCarouselComponent {}
+```
+
+Ou utilize pelo `TCloudUiModule`, quando a aplicação já importar o módulo completo da biblioteca.
+
+## Uso Básico
+
+```html
+<tcloud-ui-carousel>
+  <img src="assets/banner-1.png" alt="Banner 1">
+  <img src="assets/banner-2.png" alt="Banner 2">
+  <img src="assets/banner-3.png" alt="Banner 3">
+</tcloud-ui-carousel>
+```
+
+## Uso com Configurações
+
+```html
+<tcloud-ui-carousel
+  autoplay-delay="8000"
+  autoplay-disable-on-interaction="false"
+  effect="fade"
+  loop="true"
+  pagination="true"
+  pagination-clickable="true"
+  navigation="true"
+  speed="1000">
+  <img src="assets/banner-1.png" alt="Banner 1">
+  <img src="assets/banner-2.png" alt="Banner 2">
+</tcloud-ui-carousel>
+```
+
+## Controlando a Largura Externamente
+
+O carrossel ocupa `100%` da largura do container pai. Para exibir em tamanho menor, controle o wrapper externo:
+
+```html
+<div class="carousel-wrapper">
+  <tcloud-ui-carousel pagination="true" navigation="true">
+    <img src="assets/banner-1.png" alt="Banner 1">
+    <img src="assets/banner-2.png" alt="Banner 2">
+  </tcloud-ui-carousel>
+</div>
+```
+
+```scss
+.carousel-wrapper {
+  width: 80%;
+  max-width: 900px;
+  margin: 0 auto;
+}
+```
+
+## Propriedades
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Descrição |
+|-------------|------|--------|-----------|
+| `ariaLabel` | `string` | `'Carrossel'` | Texto acessível usado para identificar a região do carrossel para leitores de tela. |
+| `controlsPosition` | `'inside' \| 'outside'` | `'inside'` | Define a posição dos botões. Atualmente o uso principal é `inside`, com setas sobre o conteúdo. |
+| `gap` | `string` | `'0'` | Espaçamento horizontal entre slides. Aceita qualquer valor CSS válido, como `'0'`, `'8px'` ou `'var(--size-16)'`. |
+| `hideScrollbar` | `boolean` | `true` | Oculta a scrollbar horizontal do carrossel. |
+| `scrollBehavior` | `ScrollBehavior` | `'smooth'` | Comportamento nativo do scroll. Aceita `'smooth'`, `'auto'` ou `'instant'`, conforme suporte do navegador. |
+| `snap` | `boolean` | `true` | Faz o scroll encaixar no início de cada slide. Evita que o carrossel pare entre dois slides no efeito `slide`. |
+| `autoplay-delay` | `number` | `0` | Tempo em milissegundos entre as trocas automáticas de slide. Use `0` para desativar autoplay. |
+| `autoplay-disable-on-interaction` | `boolean` | `true` | Define se o autoplay deve parar quando o usuário interagir com setas ou paginação. |
+| `effect` | `'slide' \| 'fade'` | `'slide'` | Tipo de transição visual entre slides. |
+| `loop` | `boolean` | `false` | Permite navegação circular entre os slides. Ao avançar no último, volta para o primeiro. |
+| `pagination` | `boolean` | `false` | Exibe os indicadores de paginação sobre a imagem. |
+| `pagination-clickable` | `boolean` | `true` | Permite clicar nos indicadores para navegar diretamente para um slide. |
+| `navigation` | `boolean` | `true` | Exibe os botões de navegação anterior e próximo sobre a imagem. |
+| `speed` | `number` | `300` | Duração da animação em milissegundos. Afeta a animação customizada de slide e a transição de opacidade no `fade`. |
+
+### Outputs
+
+| Output | Tipo | Descrição |
+|--------|------|-----------|
+| `activeIndexChange` | `EventEmitter<number>` | Emitido quando o slide ativo muda. Retorna o índice do slide, começando em `0`. |
+
+## Exemplos
+
+### Com Slide, Paginação e Setas
+
+```html
+<tcloud-ui-carousel
+  effect="slide"
+  pagination="true"
+  navigation="true"
+  loop="true">
+  <img src="assets/banner-1.png" alt="Banner 1">
+  <img src="assets/banner-2.png" alt="Banner 2">
+</tcloud-ui-carousel>
+```
+
+### Com Fade e Autoplay
+
+```html
+<tcloud-ui-carousel
+  effect="fade"
+  autoplay-delay="5000"
+  autoplay-disable-on-interaction="false"
+  speed="1000"
+  pagination="true">
+  <img src="assets/banner-1.png" alt="Banner 1">
+  <img src="assets/banner-2.png" alt="Banner 2">
+</tcloud-ui-carousel>
+```
+
+### Com Cards
+
+```html
+<tcloud-ui-carousel pagination="true" navigation="true">
+  <article class="card">
+    <h3>Plano Basic</h3>
+    <p>Conteúdo do primeiro slide.</p>
+  </article>
+
+  <article class="card">
+    <h3>Plano Prime</h3>
+    <p>Conteúdo do segundo slide.</p>
+  </article>
+</tcloud-ui-carousel>
+```
+
+## Observações
+
+- Para imagens externas, prefira URLs públicas e estáveis. URLs assinadas com expiração podem fazer o carrossel parecer vazio quando vencerem.
+- Para reduzir a largura visual, use um container externo em vez de alterar estilos internos do componente.
+- No modo `fade`, os slides são sobrepostos e alternados por opacidade.
+- No modo `slide`, o carrossel usa scroll horizontal com suporte a snap.