@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-skeleton-loading.md

@@ -0,0 +1,394 @@
+# Skeleton Loading
+
+## Características
+
+O componente `tcloud-ui-skeleton-loading` é um componente de carregamento que exibe um placeholder animado (shimmer effect) enquanto o conteúdo está sendo carregado. É ideal para melhorar a experiência do usuário durante operações assíncronas, fornecendo feedback visual de que algo está acontecendo.
+
+## Instalação
+
+Para utilizar o componente Skeleton Loading, importe o módulo `TCloudUiModule`:
+
+```typescript
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-skeleton-loading></tcloud-ui-skeleton-loading>
+  `
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente:
+
+```typescript
+import { TCloudUiSkeletonLoadingComponent } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiSkeletonLoadingComponent],
+  template: `...`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `width` | `string` | Largura do placeholder em unidades CSS | `'10rem'` |
+| `height` | `string` | Altura do placeholder em unidades CSS | `'1.25rem'` |
+| `borderRadius` | `string` | Raio de borda do placeholder em unidades CSS | `'0.3rem'` |
+
+## Características Técnicas
+
+- **Animação**: Shimmer gradient que se move horizontalmente
+- **Duração**: 2 segundos por ciclo
+- **Loop**: Infinito e contínuo
+- **Gradiente**: Linear 90 graus da esquerda para direita
+- **Responsividade**: Suporta unidades CSS relativas (rem, em, %) e absolutas (px)
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-basic-skeleton',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <!-- Placeholder padrão -->
+    <tcloud-ui-skeleton-loading></tcloud-ui-skeleton-loading>
+
+    <!-- Placeholder grande para títulos -->
+    <tcloud-ui-skeleton-loading 
+      [width]="'15rem'" 
+      [height]="'2rem'">
+    </tcloud-ui-skeleton-loading>
+
+    <!-- Placeholder pequeno para texto -->
+    <tcloud-ui-skeleton-loading 
+      [width]="'20rem'" 
+      [height]="'0.75rem'">
+    </tcloud-ui-skeleton-loading>
+  `
+})
+export class BasicSkeletonComponent {}
+```
+
+### Carregamento de Dados
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-data-loading-skeleton',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="container">
+      @if (loading()) {
+        <div class="skeleton-wrapper">
+          <tcloud-ui-skeleton-loading 
+            [width]="'100%'" 
+            [height]="'2rem'">
+          </tcloud-ui-skeleton-loading>
+          <tcloud-ui-skeleton-loading 
+            [width]="'100%'" 
+            [height]="'1rem'"
+            class="mt-2">
+          </tcloud-ui-skeleton-loading>
+          <tcloud-ui-skeleton-loading 
+            [width]="'80%'" 
+            [height]="'1rem'"
+            class="mt-2">
+          </tcloud-ui-skeleton-loading>
+        </div>
+      } @else {
+        <h2>{{ title() }}</h2>
+        <p>{{ description() }}</p>
+      }
+    </div>
+  `,
+  styles: [`
+    .container {
+      padding: 1rem;
+    }
+
+    .skeleton-wrapper {
+      display: flex;
+      flex-direction: column;
+      gap: 0.75rem;
+    }
+
+    .mt-2 {
+      margin-top: 0.5rem;
+    }
+
+    h2 {
+      margin: 0 0 0.5rem 0;
+    }
+
+    p {
+      margin: 0;
+      color: #666;
+    }
+  `]
+})
+export class DataLoadingSkeletonComponent {
+  loading = signal<boolean>(true);
+  title = signal<string>('Título do Conteúdo');
+  description = signal<string>('Descrição detalhada sobre o conteúdo carregado');
+
+  constructor() {
+    setTimeout(() => {
+      this.loading.set(false);
+    }, 3000);
+  }
+}
+```
+
+### Layout com Múltiplos Placeholders
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-card-skeleton',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="card">
+      @if (loading()) {
+        <div class="card-skeleton">
+          <tcloud-ui-skeleton-loading 
+            [width]="'100%'" 
+            [height]="'12rem'"
+            [borderRadius]="'0.5rem'">
+          </tcloud-ui-skeleton-loading>
+          
+          <div class="card-content">
+            <tcloud-ui-skeleton-loading 
+              [width]="'80%'" 
+              [height]="'1.5rem'">
+            </tcloud-ui-skeleton-loading>
+            
+            <tcloud-ui-skeleton-loading 
+              [width]="'100%'" 
+              [height]="'1rem'"
+              class="mt-1">
+            </tcloud-ui-skeleton-loading>
+            
+            <tcloud-ui-skeleton-loading 
+              [width]="'90%'" 
+              [height]="'1rem'"
+              class="mt-1">
+            </tcloud-ui-skeleton-loading>
+          </div>
+        </div>
+      } @else {
+        <img [src]="imageUrl()" alt="Card image" class="card-image">
+        <div class="card-content">
+          <h3>{{ cardTitle() }}</h3>
+          <p>{{ cardDescription() }}</p>
+        </div>
+      }
+    </div>
+  `,
+  styles: [`
+    .card {
+      border: 1px solid #e0e0e0;
+      border-radius: 0.5rem;
+      overflow: hidden;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    .card-skeleton {
+      padding: 1rem;
+    }
+
+    .card-image {
+      width: 100%;
+      height: 12rem;
+      object-fit: cover;
+    }
+
+    .card-content {
+      padding: 1rem;
+    }
+
+    .card-content h3 {
+      margin: 0 0 0.5rem 0;
+      font-size: 1.25rem;
+    }
+
+    .card-content p {
+      margin: 0;
+      color: #666;
+      font-size: 0.875rem;
+    }
+
+    .mt-1 {
+      margin-top: 0.5rem;
+    }
+  `]
+})
+export class CardSkeletonComponent {
+  loading = signal<boolean>(true);
+  imageUrl = signal<string>('https://via.placeholder.com/300x150');
+  cardTitle = signal<string>('Título do Card');
+  cardDescription = signal<string>('Descrição breve do conteúdo do card que será exibida aqui.');
+
+  constructor() {
+    setTimeout(() => {
+      this.loading.set(false);
+    }, 2000);
+  }
+}
+```
+
+### Variações de Tamanho
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-skeleton-variants',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <div class="variants-container">
+      <div class="variant">
+        <h4>Pequeno (Texto)</h4>
+        <tcloud-ui-skeleton-loading 
+          [width]="'10rem'" 
+          [height]="'0.75rem'">
+        </tcloud-ui-skeleton-loading>
+      </div>
+
+      <div class="variant">
+        <h4>Médio (Padrão)</h4>
+        <tcloud-ui-skeleton-loading 
+          [width]="'15rem'" 
+          [height]="'1.25rem'">
+        </tcloud-ui-skeleton-loading>
+      </div>
+
+      <div class="variant">
+        <h4>Grande (Título)</h4>
+        <tcloud-ui-skeleton-loading 
+          [width]="'20rem'" 
+          [height]="'2rem'">
+        </tcloud-ui-skeleton-loading>
+      </div>
+
+      <div class="variant">
+        <h4>Cheio (100%)</h4>
+        <tcloud-ui-skeleton-loading 
+          [width]="'100%'" 
+          [height]="'3rem'">
+        </tcloud-ui-skeleton-loading>
+      </div>
+
+      <div class="variant">
+        <h4>Arredondado</h4>
+        <tcloud-ui-skeleton-loading 
+          [width]="'8rem'" 
+          [height]="'8rem'"
+          [borderRadius]="'50%'">
+        </tcloud-ui-skeleton-loading>
+      </div>
+    </div>
+  `,
+  styles: [`
+    .variants-container {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+      gap: 2rem;
+      padding: 1rem;
+    }
+
+    .variant {
+      border: 1px solid #e0e0e0;
+      padding: 1rem;
+      border-radius: 0.5rem;
+    }
+
+    .variant h4 {
+      margin: 0 0 1rem 0;
+      font-size: 0.875rem;
+      font-weight: 600;
+      color: #333;
+    }
+
+    tcloud-ui-skeleton-loading {
+      display: block;
+    }
+  `]
+})
+export class SkeletonVariantsComponent {}
+```
+
+## Boas Práticas
+
+1. **Use em operações assíncronas**: Exiba o skeleton loading enquanto dados estão sendo carregados de uma API
+2. **Combine com estrutura real**: Mantenha o layout do skeleton similar ao conteúdo real que será exibido
+3. **Tempo apropriado**: Não use por muito tempo; idealmente 2-5 segundos é o esperado
+4. **Acessibilidade**: Considere adicionar um `aria-label` para leitores de tela
+5. **Dimensões realistas**: Use dimensões que correspondem ao conteúdo que será carregado
+
+## Casos de Uso
+
+- Carregamento de listas e tabelas
+- Carregamento de cards e imagens
+- Carregamento de conteúdo de detalhes
+- Simulação de estrutura durante requisições HTTP
+- Feedback visual em operações que levam tempo
+
+## Performance
+
+O componente Skeleton Loading é otimizado para performance:
+- Utiliza animação CSS pura (não JavaScript)
+- Renderização eficiente sem reflows desnecessários
+- Suporta múltiplas instâncias sem impacto significativo
+
+## Responsividade
+
+O componente funciona com qualquer unidade CSS, facilitando layouts responsivos:
+
+```typescript
+// Em desktop
+<tcloud-ui-skeleton-loading [width]="'100%'" [height]="'2rem'"></tcloud-ui-skeleton-loading>
+
+// Em mobile - ajuste via CSS media queries ou propriedades dinâmicas
+<tcloud-ui-skeleton-loading 
+  [width]="isMobile() ? '100%' : '50%'" 
+  [height]="'1.5rem'">
+</tcloud-ui-skeleton-loading>
+```
+
+## Compatibilidade
+
+- **Angular**: 16+
+- **Browsers**: Todos os navegadores modernos que suportam CSS Grid e Flexbox
+- **CSS Variables**: Utiliza variáveis CSS customizáveis
+
+## Suporte
+
+Para reportar problemas, sugestões ou criar pull requests, visite o repositório oficial do projeto.

package/docs/tcloud-ui-slide-toggle.md

@@ -0,0 +1,210 @@
+# Slide Toggle
+
+## Características
+
+A diretiva `tcloudUiSlideToggle` transforma um `<input type="checkbox">` em um toggle switch estilizado. Aplica automaticamente a classe CSS `tcloud-ui-slide-toggle` ao elemento host, transformando a aparência padrão do checkbox em um controle de alternância visual com animação suave de transição.
+
+## Instalação
+
+Para utilizar a diretiva Slide Toggle, importe o módulo `TCloudUiModule`:
+
+```typescript
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `<input type="checkbox" tcloudUiSlideToggle />`
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente a diretiva:
+
+```typescript
+import { TCloudUiSlideToggleDirective } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiSlideToggleDirective],
+  template: `<input type="checkbox" tcloudUiSlideToggle />`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| (nativo) `disabled` | `boolean` | Desabilita o toggle, alterando cursor e estilo visual | `false` |
+| (nativo) `checked` | `boolean` | Estado inicial do toggle | `false` |
+
+### Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|------|----------------|-----------|
+| (nativo) `change` | `Event` | Evento nativo disparado quando o estado do checkbox muda |
+
+### Selector
+
+```
+input[type="checkbox"][tcloudUiSlideToggle]
+```
+
+A diretiva só é aplicável a elementos `<input type="checkbox">` que possuam o atributo `tcloudUiSlideToggle`.
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-basic-toggle',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <input type="checkbox" tcloudUiSlideToggle />
+  `
+})
+export class BasicToggleComponent {}
+```
+
+### Com Two-Way Binding (ngModel)
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-bound-toggle',
+  standalone: true,
+  imports: [TCloudUiModule, FormsModule],
+  template: `
+    <label>
+      <input type="checkbox" tcloudUiSlideToggle [(ngModel)]="isActive" />
+      {{ isActive ? 'Ativo' : 'Inativo' }}
+    </label>
+  `
+})
+export class BoundToggleComponent {
+  isActive = false;
+}
+```
+
+### Estado Desabilitado
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-disabled-toggle',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <div>
+      <p>Desabilitado (off):</p>
+      <input type="checkbox" tcloudUiSlideToggle [disabled]="true" />
+    </div>
+
+    <div>
+      <p>Desabilitado (on):</p>
+      <input type="checkbox" tcloudUiSlideToggle [disabled]="true" [checked]="true" />
+    </div>
+  `
+})
+export class DisabledToggleComponent {}
+```
+
+### Em Formulário Reativo
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { FormBuilder, FormGroup, ReactiveFormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-reactive-toggle',
+  standalone: true,
+  imports: [TCloudUiModule, ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form">
+      <label>
+        Notificações por e-mail
+        <input type="checkbox" tcloudUiSlideToggle formControlName="emailNotifications" />
+      </label>
+
+      <label>
+        Modo escuro
+        <input type="checkbox" tcloudUiSlideToggle formControlName="darkMode" />
+      </label>
+    </form>
+
+    <pre>{{ form.value | json }}</pre>
+  `
+})
+export class ReactiveToggleComponent implements OnInit {
+  form!: FormGroup;
+
+  constructor(private fb: FormBuilder) {}
+
+  ngOnInit(): void {
+    this.form = this.fb.group({
+      emailNotifications: [true],
+      darkMode: [false]
+    });
+  }
+}
+```
+
+### Uso com Evento de Mudança
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-event-toggle',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <input 
+      type="checkbox" 
+      tcloudUiSlideToggle 
+      (change)="onToggleChange($event)" 
+    />
+    <p>Último estado: {{ lastState }}</p>
+  `
+})
+export class EventToggleComponent {
+  lastState: string = 'N/A';
+
+  onToggleChange(event: Event): void {
+    const checked = (event.target as HTMLInputElement).checked;
+    this.lastState = checked ? 'Ligado' : 'Desligado';
+    console.log('Toggle alterado para:', this.lastState);
+  }
+}
+```
+
+## Comportamento Visual
+
+- **Off**: Fundo cinza (`--c-neutral-300`) com indicador circular branco à esquerda
+- **On**: Fundo na cor primária (`--c-primary-500`) com indicador circular branco à direita
+- **Disabled**: Fundo cinza com cursor `not-allowed`
+- **Transição**: Animação suave de 0.2s ao alternar estados
+
+## Compatibilidade
+
+- **Angular**: 16+
+- **Browsers**: Todos os navegadores modernos
+- **Formulários**: Compatível com `ngModel`, `FormControl` e formulários reativos