@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-input-container.md

@@ -0,0 +1,520 @@
+# Input Container
+
+## Características
+
+O componente `tcloud-ui-input-container` é um wrapper visual que envolve inputs, checkboxes, radios e outros elementos de formulário, fornecendo um label customizável com posicionamento flexível. Ideal para criar layouts de formulário consistentes e acessíveis.
+
+## Instalação
+
+Para utilizar o componente Input Container, 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-input-container label="Nome" labelPosition="top">
+      <input type="text" placeholder="Digite seu nome">
+    </tcloud-ui-input-container>
+  `
+})
+export class ExampleComponent {}
+```
+
+Ou importe diretamente o componente:
+
+```typescript
+import { TCloudUiInputContainerComponent } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiInputContainerComponent],
+  template: `...`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|------|------|-----------|---------------|
+| `label` | `string` | Texto do label exibido com o input | `''` (vazio) |
+| `inputId` | `string` | ID do input para associação com label via atributo `for` | `''` |
+| `labelPosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | Posição do label em relação ao input | `'top'` |
+| `required` | `boolean` | Exibe asterisco vermelho indicando campo obrigatório | `false` |
+| `fullWidth` | `boolean` | Faz o container ocupar 100% da largura disponível | `false` |
+
+## Características Técnicas
+
+- **Flexbox Layout**: Utiliza flexbox para posicionamento flexível do label
+- **ng-content**: Aceita qualquer elemento HTML como conteúdo
+- **Label Acessível**: Suporta associação com input via atributo `for` quando `inputId` é fornecido
+- **Indicador Obrigatório**: Asterisco customizável para campos requeridos
+- **Responsive**: Adapta-se a diferentes tamanhos de viewport
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-basic-input-container',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <tcloud-ui-input-container 
+      label="Nome"
+      inputId="name-input"
+      labelPosition="top">
+      <input id="name-input" type="text" placeholder="Digite seu nome">
+    </tcloud-ui-input-container>
+
+    <tcloud-ui-input-container 
+      label="Email"
+      inputId="email-input"
+      labelPosition="top"
+      [required]="true">
+      <input id="email-input" type="email" placeholder="Digite seu email">
+    </tcloud-ui-input-container>
+  `
+})
+export class BasicInputContainerComponent {}
+```
+
+### Posições do Label
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-label-positions',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <div class="position-examples">
+      <!-- Label Acima (TOP) -->
+      <tcloud-ui-input-container 
+        label="Acima"
+        labelPosition="top">
+        <input type="text" placeholder="Label no topo">
+      </tcloud-ui-input-container>
+
+      <!-- Label à Direita (RIGHT) -->
+      <tcloud-ui-input-container 
+        label="Direita"
+        labelPosition="right">
+        <input type="text" placeholder="Label à direita">
+      </tcloud-ui-input-container>
+
+      <!-- Label Abaixo (BOTTOM) -->
+      <tcloud-ui-input-container 
+        label="Abaixo"
+        labelPosition="bottom">
+        <input type="text" placeholder="Label abaixo">
+      </tcloud-ui-input-container>
+
+      <!-- Label à Esquerda (LEFT) -->
+      <tcloud-ui-input-container 
+        label="Esquerda"
+        labelPosition="left">
+        <input type="text" placeholder="Label à esquerda">
+      </tcloud-ui-input-container>
+    </div>
+  `,
+  styles: [`
+    .position-examples {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      gap: 2rem;
+    }
+  `]
+})
+export class LabelPositionsComponent {}
+```
+
+### Com Checkboxes
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-checkbox-container',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <div class="checkbox-group">
+      <tcloud-ui-input-container 
+        label="Concordo com os termos"
+        labelPosition="left">
+        <input type="checkbox" id="terms">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Receber notificações"
+        labelPosition="left">
+        <input type="checkbox" id="notifications">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Ativar autenticação 2FA"
+        labelPosition="left"
+        [required]="true">
+        <input type="checkbox" id="2fa">
+      </tcloud-ui-input-container>
+    </div>
+  `,
+  styles: [`
+    .checkbox-group {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+  `]
+})
+export class CheckboxContainerComponent {}
+```
+
+### Com Radio Buttons
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-radio-container',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <div class="radio-group">
+      <tcloud-ui-input-container 
+        label="Opção 1"
+        labelPosition="left">
+        <input type="radio" name="options" id="option1" value="opt1">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Opção 2"
+        labelPosition="left">
+        <input type="radio" name="options" id="option2" value="opt2">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Opção 3"
+        labelPosition="left">
+        <input type="radio" name="options" id="option3" value="opt3">
+      </tcloud-ui-input-container>
+    </div>
+  `,
+  styles: [`
+    .radio-group {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+  `]
+})
+export class RadioContainerComponent {}
+```
+
+### Campos Obrigatórios
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-required-fields',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <form class="form-group">
+      <tcloud-ui-input-container 
+        label="Nome Completo"
+        inputId="full-name"
+        labelPosition="top"
+        [required]="true">
+        <input 
+          id="full-name" 
+          type="text" 
+          placeholder="Digite seu nome completo"
+          [(ngModel)]="formData.fullName"
+          (ngModelChange)="validateField('fullName')">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Email"
+        inputId="email"
+        labelPosition="top"
+        [required]="true">
+        <input 
+          id="email" 
+          type="email" 
+          placeholder="Digite seu email"
+          [(ngModel)]="formData.email"
+          (ngModelChange)="validateField('email')">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Telefone"
+        inputId="phone"
+        labelPosition="top">
+        <input 
+          id="phone" 
+          type="tel" 
+          placeholder="Digite seu telefone">
+      </tcloud-ui-input-container>
+
+      <button (click)="submitForm()">Enviar</button>
+    </form>
+  `,
+  styles: [`
+    .form-group {
+      display: flex;
+      flex-direction: column;
+      gap: 1.5rem;
+      max-width: 500px;
+    }
+
+    button {
+      padding: 0.75rem 1.5rem;
+      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 RequiredFieldsComponent {
+  formData = {
+    fullName: '',
+    email: '',
+    phone: ''
+  };
+
+  validateField(fieldName: string): void {
+    console.log(`Validando campo: ${fieldName}`);
+  }
+
+  submitForm(): void {
+    console.log('Form data:', this.formData);
+  }
+}
+```
+
+### Largura Completa
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+
+@Component({
+  selector: 'app-full-width-form',
+  standalone: true,
+  imports: [TCloudUiModule],
+  template: `
+    <form class="form-container">
+      <tcloud-ui-input-container 
+        label="Nome"
+        inputId="name"
+        labelPosition="top"
+        [fullWidth]="true">
+        <input id="name" type="text" placeholder="Seu nome">
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Descri​ção"
+        inputId="description"
+        labelPosition="top"
+        [fullWidth]="true">
+        <textarea id="description" placeholder="Descreva..."></textarea>
+      </tcloud-ui-input-container>
+
+      <tcloud-ui-input-container 
+        label="Qual é sua experiência?"
+        labelPosition="top"
+        [fullWidth]="true">
+        <select>
+          <option>Iniciante</option>
+          <option>Intermediário</option>
+          <option>Avançado</option>
+        </select>
+      </tcloud-ui-input-container>
+    </form>
+  `,
+  styles: [`
+    .form-container {
+      display: flex;
+      flex-direction: column;
+      gap: 1.5rem;
+    }
+
+    input, textarea, select {
+      width: 100%;
+      padding: 0.75rem;
+      border: 1px solid var(--c-neutral-300);
+      border-radius: var(--bor-radius-4);
+      font-family: var(--f-family);
+    }
+  `]
+})
+export class FullWidthFormComponent {}
+```
+
+### Form Complexo com Layout
+
+```typescript
+import { Component } from '@angular/core';
+import { TCloudUiModule } from '@tcloud-ui/lib';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-complex-form',
+  standalone: true,
+  imports: [CommonModule, TCloudUiModule],
+  template: `
+    <form class="complex-form">
+      <section class="form-section">
+        <h3>Informações Pessoais</h3>
+        
+        <div class="form-row">
+          <tcloud-ui-input-container 
+            label="Primeiro Nome"
+            labelPosition="top"
+            [fullWidth]="true">
+            <input type="text" placeholder="João">
+          </tcloud-ui-input-container>
+
+          <tcloud-ui-input-container 
+            label="Último Nome"
+            labelPosition="top"
+            [fullWidth]="true">
+            <input type="text" placeholder="Silva">
+          </tcloud-ui-input-container>
+        </div>
+
+        <tcloud-ui-input-container 
+          label="Email"
+          inputId="email"
+          labelPosition="top"
+          [required]="true"
+          [fullWidth]="true">
+          <input id="email" type="email" placeholder="seu@email.com">
+        </tcloud-ui-input-container>
+      </section>
+
+      <section class="form-section">
+        <h3>Preferências</h3>
+
+        <tcloud-ui-input-container 
+          label="Receber newsletter"
+          labelPosition="left">
+          <input type="checkbox">
+        </tcloud-ui-input-container>
+
+        <tcloud-ui-input-container 
+          label="Receber notificações por email"
+          labelPosition="left">
+          <input type="checkbox" checked>
+        </tcloud-ui-input-container>
+      </section>
+    </form>
+  `,
+  styles: [`
+    .complex-form {
+      max-width: 600px;
+      padding: 2rem;
+      border: 1px solid var(--c-neutral-200);
+      border-radius: var(--bor-radius-8);
+    }
+
+    .form-section {
+      margin-bottom: 2rem;
+    }
+
+    .form-section h3 {
+      margin: 0 0 1rem 0;
+      font-size: var(--f-size-18);
+      font-weight: var(--f-weight-700);
+      color: var(--c-neutral-900);
+    }
+
+    .form-row {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 1rem;
+      margin-bottom: 1.5rem;
+    }
+
+    @media (max-width: 600px) {
+      .form-row {
+        grid-template-columns: 1fr;
+      }
+    }
+
+    input, textarea, select {
+      width: 100%;
+      padding: 0.75rem;
+      border: 1px solid var(--c-neutral-300);
+      border-radius: var(--bor-radius-4);
+      font-family: var(--f-family);
+    }
+
+    tcloud-ui-input-container {
+      margin-bottom: 1.5rem;
+    }
+  `]
+})
+export class ComplexFormComponent {}
+```
+
+## Boas Práticas
+
+1. **Sempre use inputId**: Quando possível, forneça o atributo `inputId` para melhor acessibilidade
+2. **Posição apropriada**: Escolha a posição do label baseado no contexto:
+   - `top`: Padrão para inputs texto (email, senha, etc.)
+   - `left`: Ideal para checkboxes e radio buttons
+   - `right`: Menos comum, use com cuidado
+   - `bottom`: Raro, evite usar
+
+3. **Marque campos obrigatórios**: Use `required="true"` para indicar visualmente campos obrigatórios
+4. **Use fullWidth com moderação**: Ideal em formulários verticais mas pode quebrar layouts horizontais
+
+## Acessibilidade
+
+- O componente suporta o atributo `for` no label quando `inputId` é fornecido
+- Labels descritivos melhoram a usabilidade e acessibilidade
+- Asterisco para campos obrigatórios melhora a compreensão
+
+## Responsividade
+
+O componente é totalmente responsivo e se adapta a diferentes tamanhos de tela através do Flexbox.
+
+## Compatibilidade
+
+- **Angular**: 16+
+- **Browsers**: Todos os navegadores modernos
+- **CSS Variables**: Utiliza variáveis CSS do sistema de design
+
+## Suporte
+
+Para reportar problemas, sugestões ou criar pull requests, visite o repositório oficial do projeto.