@dev-tcloud/tcloud-ui 6.15.0 → 6.18.0

package/docs/tcloud-ui-message.md

@@ -0,0 +1,539 @@
+# Message
+
+## Características
+
+O componente `tcloud-ui-message` é um componente de mensagem de feedback que exibe notificações ao usuário em quatro tipos diferentes: sucesso, erro, informação e aviso. Cada tipo possui ícone e paleta de cores específicos para comunicar claramente o tipo de mensagem.
+
+## Instalação
+
+Para utilizar o componente Message, 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-message 
+      message="Operação concluída com sucesso!"
+      type="success">
+    </tcloud-ui-message>
+  `
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente:
+
+```typescript
+import { TCloudUiMessageComponent } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiMessageComponent],
+  template: `...`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `message` | `string` | Texto da mensagem a ser exibida | `''` (vazio) |
+| `type` | `'success' \| 'error' \| 'info' \| 'warning'` | Tipo da mensagem que determina estilo e ícone | `'info'` |
+
+## Tipos de Mensagem
+
+### Success (Sucesso)
+- **Ícone**: ✓ Check
+- **Cor de Fundo**: Verde claro (`var(--c-success-300)`)
+- **Cor do Texto**: Verde (`var(--c-success-500)`)
+- **Uso**: Confirmar ações bem-sucedidas
+
+### Error (Erro)
+- **Ícone**: ✕ Times
+- **Cor de Fundo**: Vermelho claro (`var(--c-danger-300)`)
+- **Cor do Texto**: Vermelho (`var(--c-danger-500)`)
+- **Uso**: Indicar erros e problemas
+
+### Info (Informação)
+- **Ícone**: ⓘ Info Circle
+- **Cor de Fundo**: Azul claro (`var(--c-info-300)`)
+- **Cor do Texto**: Azul (`var(--c-info-500)`)
+- **Uso**: Exibir informações gerais
+
+### Warning (Aviso)
+- **Ícone**: ⚠ Exclamation Triangle
+- **Cor de Fundo**: Laranja claro (`var(--c-alert-300)`)
+- **Cor do Texto**: Laranja (`var(--c-alert-500)`)
+- **Uso**: Alertar o usuário sobre ações importantes
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-basic-message',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-message 
+      message="Ação realizada com sucesso!"
+      type="success">
+    </tcloud-ui-message>
+
+    <tcloud-ui-message 
+      message="Ocorreu um erro ao processar"
+      type="error">
+    </tcloud-ui-message>
+
+    <tcloud-ui-message 
+      message="Esta é uma mensagem informativa"
+      type="info">
+    </tcloud-ui-message>
+
+    <tcloud-ui-message 
+      message="Tenha cuidado ao prosseguir"
+      type="warning">
+    </tcloud-ui-message>
+  `
+})
+export class BasicMessageComponent {}
+```
+
+### Mensagens Dinâmicas
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-dynamic-message',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="message-demo">
+      <button (click)="showSuccess()">Mostrar Sucesso</button>
+      <button (click)="showError()">Mostrar Erro</button>
+      <button (click)="showWarning()">Mostrar Aviso</button>
+      <button (click)="clear()">Limpar</button>
+
+      @if (currentMessage()) {
+        <tcloud-ui-message 
+          [message]="currentMessage()"
+          [type]="currentType()">
+        </tcloud-ui-message>
+      }
+    </div>
+  `,
+  styles: [`
+    .message-demo {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+
+    button {
+      padding: 0.5rem 1rem;
+      background: var(--c-primary-500);
+      color: white;
+      border: none;
+      border-radius: var(--bor-radius-4);
+      cursor: pointer;
+      font-weight: 600;
+    }
+
+    button:hover {
+      background: var(--c-primary-600);
+    }
+  `]
+})
+export class DynamicMessageComponent {
+  currentMessage = signal<string>('');
+  currentType = signal<'success' | 'error' | 'info' | 'warning'>('info');
+
+  showSuccess() {
+    this.currentMessage.set('Operação concluída com sucesso!');
+    this.currentType.set('success');
+  }
+
+  showError() {
+    this.currentMessage.set('Ocorreu um erro ao processar sua solicitação');
+    this.currentType.set('error');
+  }
+
+  showWarning() {
+    this.currentMessage.set('Altere a senha para aumentar a segurança');
+    this.currentType.set('warning');
+  }
+
+  clear() {
+    this.currentMessage.set('');
+  }
+}
+```
+
+### Validação de Formulário
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-form-validation-message',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule, FormsModule],
+  template: `
+    <div class="form">
+      <input
+        type="email"
+        [(ngModel)]="email"
+        (blur)="validateEmail()"
+        placeholder="Digite seu email"
+        class="input"
+      />
+
+      @if (emailError()) {
+        <tcloud-ui-message 
+          [message]="emailError()"
+          type="error">
+        </tcloud-ui-message>
+      } @else if (emailValid()) {
+        <tcloud-ui-message 
+          message="Email válido!"
+          type="success">
+        </tcloud-ui-message>
+      }
+
+      <input
+        type="password"
+        [(ngModel)]="password"
+        (change)="validatePassword()"
+        placeholder="Senha"
+        class="input"
+      />
+
+      @if (passwordMessage()) {
+        <tcloud-ui-message 
+          [message]="passwordMessage()"
+          [type]="passwordStrength() > 2 ? 'success' : 'warning'">
+        </tcloud-ui-message>
+      }
+    </div>
+  `,
+  styles: [`
+    .form {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+      max-width: 400px;
+    }
+
+    .input {
+      padding: 0.75rem;
+      border: 1px solid var(--c-neutral-300);
+      border-radius: var(--bor-radius-4);
+      font-size: 1rem;
+    }
+
+    .input:focus {
+      outline: none;
+      border-color: var(--c-primary-500);
+    }
+  `]
+})
+export class FormValidationMessageComponent {
+  email = signal<string>('');
+  password = signal<string>('');
+  emailError = signal<string>('');
+  emailValid = signal<boolean>(false);
+  passwordMessage = signal<string>('');
+  passwordStrength = signal<number>(0);
+
+  validateEmail() {
+    const email = this.email();
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+    if (!email) {
+      this.emailError.set('Email é obrigatório');
+      this.emailValid.set(false);
+    } else if (!emailRegex.test(email)) {
+      this.emailError.set('Email inválido');
+      this.emailValid.set(false);
+    } else {
+      this.emailError.set('');
+      this.emailValid.set(true);
+    }
+  }
+
+  validatePassword() {
+    const pwd = this.password();
+    let strength = 0;
+    let message = '';
+
+    if (pwd.length < 8) {
+      message = '❌ Muito curta (minuto 8 caracteres)';
+    } else {
+      strength++;
+      if (/[A-Z]/.test(pwd)) strength++;
+      if (/[0-9]/.test(pwd)) strength++;
+      if (/[^A-Za-z0-9]/.test(pwd)) strength++;
+
+      const messages = [
+        'Senha fraca',
+        'Senha regular',
+        'Senha boa',
+        'Senha forte'
+      ];
+      message = messages[strength - 1] || 'Senha muito forte';
+    }
+
+    this.passwordStrength.set(strength);
+    this.passwordMessage.set(message);
+  }
+}
+```
+
+### Notificações de Status
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-status-notification',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="status-container">
+      <h3>Status das Operações</h3>
+
+      @for (operation of operations(); track operation.id) {
+        <div class="operation">
+          <span>{{ operation.name }}</span>
+          <tcloud-ui-message 
+            [message]="operation.message"
+            [type]="operation.type">
+          </tcloud-ui-message>
+        </div>
+      }
+    </div>
+  `,
+  styles: [`
+    .status-container {
+      max-width: 500px;
+    }
+
+    .operation {
+      display: grid;
+      grid-template-columns: 200px 1fr;
+      align-items: center;
+      gap: 1rem;
+      margin-bottom: 1rem;
+      padding-bottom: 1rem;
+      border-bottom: 1px solid var(--c-neutral-200);
+    }
+
+    span {
+      font-weight: 600;
+      color: var(--c-neutral-700);
+    }
+  `]
+})
+export class StatusNotificationComponent {
+  operations = signal([
+    { id: 1, name: 'Download', message: 'Arquivo baixado com sucesso', type: 'success' as const },
+    { id: 2, name: 'Upload', message: 'Erro ao fazer upload do arquivo', type: 'error' as const },
+    { id: 3, name: 'Sincronização', message: 'Sincronizando dados...', type: 'info' as const },
+    { id: 4, name: 'Atualização', message: 'Atualização importante disponível', type: 'warning' as const }
+  ]);
+}
+```
+
+### Mensagens com Ações
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-message-with-action',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="message-container">
+      @if (sessionExpiring()) {
+        <div class="message-wrapper">
+          <tcloud-ui-message 
+            message="Sua sessão expirará em 2 minutos. Deseja continuar?"
+            type="warning">
+          </tcloud-ui-message>
+          <div class="actions">
+            <button (click)="continueSession()" class="btn-primary">
+              Continuar
+            </button>
+            <button (click)="logout()" class="btn-secondary">
+              Sair
+            </button>
+          </div>
+        </div>
+      }
+
+      @if (deleteConfirm()) {
+        <div class="message-wrapper">
+          <tcloud-ui-message 
+            message="Tem certeza que deseja deletar este item? Esta ação é irreversível."
+            type="error">
+          </tcloud-ui-message>
+          <div class="actions">
+            <button (click)="confirmDelete()" class="btn-danger">
+              Deletar
+            </button>
+            <button (click)="cancelDelete()" class="btn-secondary">
+              Cancelar
+            </button>
+          </div>
+        </div>
+      }
+    </div>
+  `,
+  styles: [`
+    .message-wrapper {
+      padding: 1.5rem;
+      border: 1px solid var(--c-neutral-300);
+      border-radius: var(--bor-radius-8);
+      background: white;
+      margin-bottom: 1rem;
+    }
+
+    .actions {
+      display: flex;
+      gap: 1rem;
+      margin-top: 1rem;
+    }
+
+    button {
+      padding: 0.5rem 1rem;
+      border: none;
+      border-radius: var(--bor-radius-4);
+      cursor: pointer;
+      font-weight: 600;
+      transition: background 200ms;
+    }
+
+    .btn-primary {
+      background: var(--c-primary-500);
+      color: white;
+    }
+
+    .btn-primary:hover {
+      background: var(--c-primary-600);
+    }
+
+    .btn-danger {
+      background: var(--c-danger-500);
+      color: white;
+    }
+
+    .btn-danger:hover {
+      background: var(--c-danger-600);
+    }
+
+    .btn-secondary {
+      background: var(--c-neutral-200);
+      color: var(--c-neutral-700);
+    }
+
+    .btn-secondary:hover {
+      background: var(--c-neutral-300);
+    }
+  `]
+})
+export class MessageWithActionComponent {
+  sessionExpiring = signal(false);
+  deleteConfirm = signal(false);
+
+  continueSession() {
+    this.sessionExpiring.set(false);
+  }
+
+  logout() {
+    console.log('Logout...');
+  }
+
+  confirmDelete() {
+    console.log('Item deletado');
+    this.deleteConfirm.set(false);
+  }
+
+  cancelDelete() {
+    this.deleteConfirm.set(false);
+  }
+}
+```
+
+## Estilos Padrão
+
+- **Padding**: 0.75rem vertical, 1rem horizontal
+- **Border Radius**: 6px
+- **Font Size**: 14px
+- **Margin Vertical**: 8px
+- **Display**: Flex com align-items center
+- **Gap entre ícone e texto**: 0.5rem
+- **Ícone Font Size**: 16px
+
+## Comportamentos
+
+- O componente só renderiza se `message` não estiver vazio
+- Usa `ChangeDetectionStrategy.OnPush` para melhor performance
+- Suporta renderização condicional com `*ngIf`
+- Ícones vêm da biblioteca FontAwesome (classes fas)
+
+## Casos de Uso
+
+- Feedback de ações do usuário
+- Validação de formulários
+- Notificações de sistema
+- Erros de conexão
+- Avisos de segurança
+- Confirmação de ações
+- Status de operações
+- Mensagens de sucesso
+- Alertas de atualização
+- Feedback de upload/download
+
+## Performance
+
+- Usa `ChangeDetectionStrategy.OnPush` para renderização otimizada
+- Renderização condicional com `*ngIf` evita elementos desnecessários
+- Suporta signals para reatividade eficiente
+
+## Acessibilidade
+
+- Ícones semânticos indicam tipo de mensagem
+- Cores seguem padrão de contraste adequado
+- Texto descreve claramente a mensagem
+- Suporta leitura de tela com `role="alert"` (recomendado adicionar)
+
+## Dicas de Customização
+
+1. **Auto-fechar**: Kombine com `setTimeout` para auto-fechar após 3-5 segundos
+2. **Animação**: Adicione transição CSS para efeito fade in/out
+3. **Múltiplas**: Empilhe vários componentes para exibir múltiplas mensagens
+4. **Personalizado**: Use com `<ng-content>` para conteúdo customizado