@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-currency.md

@@ -0,0 +1,271 @@
+# Currency
+
+A diretiva **Currency** formata automaticamente valores monetários em Reais (R$) em um campo de entrada. Ela implementa `ControlValueAccessor`, permitindo integração transparente com `ngModel` e formulários reativos do Angular.
+
+## Características
+
+- **Formatação automática de moeda**: Exibe valores no formato `R$ 1.234,56`
+- **Máscara de entrada**: Remove caracteres não numéricos e aplica formatação em tempo real
+- **Compatível com ngModel**: Funciona perfeitamente com two-way data binding
+- **Compatível com Reactive Forms**: Implementa `ControlValueAccessor`
+- **Alinhamento à direita**: Posiciona o texto monetário à direita automaticamente
+- **Cursor inteligente**: Posiciona o cursor ao final do valor quando o input recebe foco
+- **Conversão segura**: Converte valores para número quando emitidos através de `onChange`
+
+## Instalação
+
+```typescript
+import { TCloudUiModule } from 'projects/tcloud-ui/src/public-api';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  imports: [TCloudUiModule, FormsModule],
+  // ... resto da configuração
+})
+export class MyComponent {}
+```
+
+## Propriedades (API)
+
+### Seletor
+
+| Seletor | Descrição |
+|---------|-----------|
+| `[TCcurrency]` | Atributo aplicado em um elemento `<input>` para ativar a formatação de moeda |
+
+### Implementação de ControlValueAccessor
+
+A diretiva implementa as seguintes interfaces obrigatórias de `ControlValueAccessor`:
+
+| Método | Assinatura | Descrição |
+|--------|-----------|-----------|
+| `writeValue(value: any)` | Escreve o valor formatado no elemento | Formata e exibe o valor com máscara de moeda |
+| `registerOnChange(fn: any)` | Registra callback de mudança | Chamado quando o usuário modifica o valor |
+| `registerOnTouched(fn: any)` | Registra callback de toque | Chamado quando o usuário interage com o input |
+
+### Listeners do Host
+
+| Evento | Descrição |
+|--------|-----------|
+| `@HostListener('focus')` | Posiciona o cursor ao final do valor |
+| `@HostListener('input')` | Formata o valor conforme o usuário digita |
+
+## Comportamento
+
+### Formatação
+
+Os valores são exibidos no formato brasileiro de moeda:
+- Separador de milhares: `.` (ponto)
+- Separador decimal: `,` (vírgula)
+- Símbolo monetário: `R$ `
+
+**Exemplos:**
+- `100` → `R$ 0,00`
+- `1000` → `R$ 10,00`
+- `100050` → `R$ 1.000,50`
+- `1234567` → `R$ 12.345,67`
+
+### Entrada de Dados
+
+A diretiva automaticamente:
+1. Remove caracteres não numéricos
+2. Aplica formatação de moeda
+3. Emite o valor numérico puro via `onChange`
+
+## Exemplos de Uso
+
+### Uso Básico com ngModel
+
+Implementação simples com two-way binding:
+
+```typescript
+@Component({
+  selector: 'app-currency-basic',
+  imports: [CommonModule, FormsModule, TCloudUiModule],
+  template: `
+    <div>
+      <label>Valor:</label>
+      <input 
+        TCcurrency 
+        [(ngModel)]="valor" 
+        class="tc-form-control"
+        placeholder="0,00"
+      >
+      <p>Valor armazenado: {{ valor }}</p>
+    </div>
+  `
+})
+export class CurrencyBasicComponent {
+  valor: number = 0;
+}
+```
+
+### Uso com Formulário Reativo
+
+Integração com Reactive Forms:
+
+```typescript
+@Component({
+  selector: 'app-currency-reactive',
+  imports: [CommonModule, ReactiveFormsModule, TCloudUiModule],
+  template: `
+    <form [formGroup]="form">
+      <div>
+        <label>Valor da Venda:</label>
+        <input 
+          TCcurrency 
+          formControlName="saleValue"
+          class="tc-form-control"
+        >
+        <small *ngIf="form.get('saleValue')?.invalid">
+          Valor inválido
+        </small>
+      </div>
+
+      <button 
+        (click)="submitForm()"
+        class="tc-btn tc-btn-primary"
+      >
+        Enviar
+      </button>
+    </form>
+  `
+})
+export class CurrencyReactiveComponent {
+  form: FormGroup;
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      saleValue: [0, [Validators.required, Validators.min(0)]]
+    });
+  }
+
+  submitForm() {
+    if (this.form.valid) {
+      console.log('Valor enviado:', this.form.get('saleValue')?.value);
+    }
+  }
+}
+```
+
+### Uso Avançado com Validação de Range
+
+Diretiva aplicada com validação de valor mínimo e máximo:
+
+```typescript
+@Component({
+  selector: 'app-currency-advanced',
+  imports: [CommonModule, ReactiveFormsModule, TCloudUiModule],
+  template: `
+    <form [formGroup]="form">
+      <div class="form-group">
+        <label>Preço do Produto (R$ 0,01 - R$ 999.999,99):</label>
+        <input 
+          TCcurrency 
+          formControlName="price"
+          class="tc-form-control"
+          (blur)="validatePrice()"
+        >
+
+        <div *ngIf="priceOutOfRange" class="error-message">
+          Preço deve estar entre R$ 0,01 e R$ 999.999,99
+        </div>
+      </div>
+
+      <div class="form-group">
+        <label>Desconto (R$ 0,00 - máximo 50% do preço):</label>
+        <input 
+          TCcurrency 
+          formControlName="discount"
+          class="tc-form-control"
+          (blur)="validateDiscount()"
+        >
+
+        <div *ngIf="discountOutOfRange" class="error-message">
+          Desconto inválido
+        </div>
+      </div>
+
+      <div class="summary">
+        <p>Preço: {{ form.get('price')?.value | currency }}</p>
+        <p>Desconto: -{{ form.get('discount')?.value | currency }}</p>
+        <p><strong>Total: {{ calculateTotal() | currency }}</strong></p>
+      </div>
+
+      <button 
+        (click)="save()"
+        [disabled]="form.invalid"
+        class="tc-btn tc-btn-primary"
+      >
+        Salvar Produto
+      </button>
+    </form>
+  `,
+  styles: [`
+    .error-message {
+      color: #d32f2f;
+      font-size: 12px;
+      margin-top: 4px;
+    }
+    .summary {
+      background: #f5f5f5;
+      padding: 12px;
+      border-radius: 4px;
+      margin: 16px 0;
+    }
+  `]
+})
+export class CurrencyAdvancedComponent {
+  form: FormGroup;
+  priceOutOfRange: boolean = false;
+  discountOutOfRange: boolean = false;
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      price: [0, [Validators.required, Validators.min(0.01)]],
+      discount: [0, [Validators.required, Validators.min(0)]]
+    });
+  }
+
+  validatePrice() {
+    const price = this.form.get('price')?.value;
+    this.priceOutOfRange = price < 0.01 || price > 999999.99;
+  }
+
+  validateDiscount() {
+    const price = this.form.get('price')?.value;
+    const discount = this.form.get('discount')?.value;
+    const maxDiscount = price * 0.5;
+    this.discountOutOfRange = discount < 0 || discount > maxDiscount;
+  }
+
+  calculateTotal(): number {
+    const price = this.form.get('price')?.value || 0;
+    const discount = this.form.get('discount')?.value || 0;
+    return price - discount;
+  }
+
+  save() {
+    if (this.form.valid) {
+      const data = {
+        price: this.form.get('price')?.value,
+        discount: this.form.get('discount')?.value,
+        total: this.calculateTotal()
+      };
+      console.log('Produto salvo:', data);
+    }
+  }
+}
+```
+
+## Notas de Implementação
+
+- A diretiva é **standalone** e pode ser usada diretamente em componentes standalone
+- Trabalha especificamente com a moeda **Real Brasileiro (R$)**
+- O valor armazenado internamente é sempre um **número decimal** (ex: `100.50`)
+- A exibição sempre será formatada como **`R$ 1.234,56`** (formato brasileiro)
+- A diretiva implementa `ControlValueAccessor`, permitindo uso com `ngModel`, `formControl` e `formControlName`
+- O input é automaticamente configurado com `type="text"` e `text-align="right"`
+- Quando o input recebe foco, o cursor é posicionado ao final do valor
+- Valores inválidos ou vazios são tratados como `0`
+- A diretiva não valida se o valor é negativo; use `Validators.min()` do Reactive Forms para isso

package/docs/tcloud-ui-data-list.md

@@ -0,0 +1,91 @@
+# Data List
+
+## Características
+- Dropdown com busca e suporte a loading, disabled e abertura programática.
+- Integração com `ngModel` (ControlValueAccessor) e eventos de abertura/fechamento e mudança de valor.
+- Opções podem ser declaradas via conteúdo (`tcloud-ui-data-list-option`) ou via `listItems` (array de objetos `{ value, description, disabled? }`).
+- Ajuste automático de posicionamento (abre para cima se faltar espaço) e input opcional (`showInput`).
+
+## Instalação
+```ts
+import { TCloudUiDataListComponent } from 'projects/tcloud-ui/src/public-api';
+import { TCloudUiDataListOptionComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDataListComponent, TCloudUiDataListOptionComponent],
+  template: `<tcloud-ui-data-list></tcloud-ui-data-list>`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| placeholder | string | Placeholder exibido quando nada está selecionado. | '' |
+| disabled | boolean | Desabilita interação. | false |
+| loading | boolean | Exibe estado de carregamento e bloqueia interação. | false |
+| showInput | boolean | Exibe input (bordas/área de clique). | true |
+| search | boolean | Habilita campo de busca interno. | true |
+| listItems | ISelectOptions[] | Lista de opções alternativa ao conteúdo projetado. | [] |
+| open | boolean | Abre/fecha programaticamente o menu. | false |
+| border | boolean | Controla exibição da borda do input. | true |
+| ngModel | any | Valor selecionado (two-way). | '' |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| onInputChange | EventEmitter<ISelectOptions> | Emite a descrição/valor ao digitar ou alterar internamente. |
+| onChange | EventEmitter<ISelectOptions> | Emite quando o valor é alterado. |
+| onOpened | EventEmitter<any> | Emite ao abrir o menu. |
+| onClosed | EventEmitter<any> | Emite ao fechar o menu. |
+| ngModelChange | EventEmitter<any> | Suporte ao two-way binding de `ngModel`. |
+
+## Exemplos de Uso
+### Uso Básico com opções inline
+```html
+<tcloud-ui-data-list placeholder="Opções" [(ngModel)]="selected">
+  <tcloud-ui-data-list-option [value]="''"></tcloud-ui-data-list-option>
+  <tcloud-ui-data-list-option value="a">Opção A</tcloud-ui-data-list-option>
+  <tcloud-ui-data-list-option value="b" [disabled]="true">Opção B</tcloud-ui-data-list-option>
+  <tcloud-ui-data-list-option value="c">Opção C</tcloud-ui-data-list-option>
+</tcloud-ui-data-list>
+
+<pre>selected: {{ selected }}</pre>
+```
+
+### Uso com lista dinâmica, loading e eventos
+```html
+<tcloud-ui-data-list
+  [placeholder]="'Tamanho do Disco'"
+  [listItems]="diskOptions"
+  [loading]="loading"
+  (onChange)="handleChange($event)"
+  (onInputChange)="handleInput($event)"
+  [(ngModel)]="diskSize">
+</tcloud-ui-data-list>
+
+<button type="button" (click)="loading = true">Simular loading</button>
+```
+
+### Abrir programaticamente e ocultar input
+```html
+<tcloud-ui-data-list
+  [open]="openMenu"
+  [showInput]="false"
+  [listItems]="items"
+  [(ngModel)]="value">
+</tcloud-ui-data-list>
+<button type="button" (click)="openMenu = !openMenu">Toggle open</button>
+```
+
+## Tipos auxiliares
+```ts
+export interface ISelectOptions {
+  description: any;
+  value: any;
+  disabled?: boolean;
+}
+```

package/docs/tcloud-ui-datebr.md

@@ -0,0 +1,139 @@
+# DateBRPipe
+
+O pipe `datebr` formata uma string numérica em formato de data brasileira (`dd/MM/yyyy`). A formatação é progressiva — aplica a máscara de acordo com a quantidade de dígitos informados, inserindo as barras (`/`) automaticamente. Remove barras existentes antes de processar, permitindo uso tanto com valores brutos quanto pré-formatados. Retorna string vazia quando o valor é nulo ou undefined.
+
+## Características
+
+- Formatação progressiva conforme quantidade de dígitos (1 a 8+)
+- Inserção automática de barras (`/`) como separadores
+- Remoção de barras existentes antes do processamento
+- Suporte a strings com 1 a 8 dígitos:
+  - 1 dígito: `#`
+  - 2 dígitos: `##/`
+  - 3 dígitos: `##/#`
+  - 4 dígitos: `##/##`
+  - 5 dígitos: `##/##/#`
+  - 6 dígitos: `##/##/##`
+  - 7 dígitos: `##/##/###`
+  - 8 dígitos: `##/##/####`
+- Retorna string vazia para valores falsy
+- Retorna valor original se a string excede 10 caracteres
+- Pipe standalone
+
+## Instalação
+
+Importe o pipe diretamente no módulo ou componente standalone:
+
+```typescript
+import { DateBRPipe } from 'tcloud-ui';
+```
+
+## API
+
+### Sintaxe do Pipe
+
+```
+{{ valor | datebr }}
+```
+
+### Parâmetros
+
+Este pipe não recebe parâmetros adicionais.
+
+### Entrada e Saída
+
+| Entrada        | Saída          |
+|----------------|----------------|
+| `'04032026'`   | `'04/03/2026'` |
+| `'040326'`     | `'04/03/26'`   |
+| `'0403'`       | `'04/03'`      |
+| `'04'`         | `'04/'`        |
+| `'04/03/2026'` | `'04/03/2026'` |
+| `null`         | `''`           |
+
+## Exemplos de Uso
+
+### Básico — Formatação de data completa
+
+```html
+<p>{{ '04032026' | datebr }}</p>
+<!-- Resultado: 04/03/2026 -->
+
+<p>{{ '0403' | datebr }}</p>
+<!-- Resultado: 04/03 -->
+```
+
+```typescript
+import { DateBRPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [DateBRPipe],
+  template: `
+    <p>{{ data | datebr }}</p>
+  `
+})
+export class ExemploBasicoComponent {
+  data = '04032026';
+}
+```
+
+### Avançado — Máscara em tempo real em input
+
+```html
+<input type="text" [value]="dataDigitada | datebr" (input)="onInput($event)" placeholder="dd/MM/yyyy">
+```
+
+```typescript
+import { DateBRPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [DateBRPipe],
+  template: `...`
+})
+export class ExemploAvancadoComponent {
+  dataDigitada = '';
+
+  onInput(event: Event) {
+    const input = event.target as HTMLInputElement;
+    this.dataDigitada = input.value.replace(/\//g, '');
+  }
+}
+```
+
+### Avançado — Exibição em tabela
+
+```html
+<table class="table">
+  <thead>
+    <tr>
+      <th>Evento</th>
+      <th>Data</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr *ngFor="let item of eventos">
+      <td>{{ item.nome }}</td>
+      <td>{{ item.data | datebr }}</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```typescript
+import { DateBRPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule, DateBRPipe],
+  template: `...`
+})
+export class ExemploTabelaComponent {
+  eventos = [
+    { nome: 'Deploy Produção', data: '04032026' },
+    { nome: 'Sprint Review', data: '15032026' },
+    { nome: 'Retrospectiva', data: '20032026' }
+  ];
+}
+```

package/docs/tcloud-ui-datepicker-time.md

@@ -0,0 +1,191 @@
+# Datepicker Time
+
+## Características
+- Componente standalone que combina seleção de data com hora e minutos.
+- Integração com `TCloudUiDatepickerComponent` para seleção de datas.
+- Seletores dropdown para hora (00-23) e minutos (00-59).
+- Suporte a intervalo de datas com `minDate` e `maxDate`.
+- Opção de atalhos de tempo rápido: 7 dias, 15 dias, 30 dias, mês atual, ano atual.
+- Integração com ngModel (two-way binding) via ControlValueAccessor.
+- Emite eventos em mudanças: `onChange`, `ngModelChange` e `eventChange`.
+- Validação automática de datas.
+
+## Instalação
+```ts
+import { TCloudUiDatepickerTimeComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiDatepickerTimeComponent],
+  template: `<tcloud-ui-datepicker-time [(ngModel)]="dateTimeValue"></tcloud-ui-datepicker-time>`
+})
+export class ExampleComponent {
+  dateTimeValue: Date = new Date();
+}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| minDate | string | Data mínima permitida no formato DD/MM/YYYY. | '' |
+| maxDate | string | Data máxima permitida no formato DD/MM/YYYY. | '' |
+| useOptionsDateTime | boolean | Se true, exibe dropdown com opções rápidas de data (7 dias, 15 dias, etc). | false |
+| ngModel | Date | Data e hora selecionada (two-way binding). | undefined |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| onChange | EventEmitter<Date> | Emite quando data ou hora é alterada. |
+| ngModelChange | EventEmitter<Date> | Emite mudança do ngModel para two-way binding. |
+| eventChange | EventEmitter<any> | Emite o elemento nativo ao alterar data/hora. |
+
+## Exemplos de Uso
+### Uso Básico
+```html
+<tcloud-ui-datepicker-time [(ngModel)]="dateTimeValue"></tcloud-ui-datepicker-time>
+
+<p>Data/Hora selecionada: {{ dateTimeValue }}</p>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  dateTimeValue: Date = new Date();
+}
+```
+
+### Com Intervalo de Datas
+```html
+<tcloud-ui-datepicker-time 
+  [minDate]="'01/01/2024'"
+  [maxDate]="'31/12/2024'"
+  [(ngModel)]="dateTimeValue">
+</tcloud-ui-datepicker-time>
+```
+
+### Modo Input com Intervalo
+```html
+<tcloud-ui-datepicker-time 
+  [minDate]="'15/03/2024'"
+  [maxDate]="'15/04/2024'"
+  [(ngModel)]="dateTime">
+</tcloud-ui-datepicker-time>
+
+<p>Valor: {{ dateTime | date:'dd/MM/yyyy HH:mm' }}</p>
+```
+
+## Uso Avançado
+### Com Opções de Tempo Rápido
+Quando `useOptionsDateTime="true"`, o componente exibe um dropdown com atalhos:
+- **7 dias**: últimos 7 dias
+- **15 dias**: últimos 15 dias
+- **30 dias**: últimos 30 dias
+- **Mês atual até agora**: de 1º do mês até a data atual
+- **Ano atual até agora**: de 1º de janeiro até a data atual
+
+```html
+<tcloud-ui-datepicker-time 
+  [useOptionsDateTime]="true"
+  [(ngModel)]="dateTimeValue">
+</tcloud-ui-datepicker-time>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  dateTimeValue: Date = new Date();
+}
+```
+
+### Com Eventos
+```html
+<tcloud-ui-datepicker-time 
+  [(ngModel)]="dateTimeValue"
+  (onChange)="onDateTimeChanged($event)"
+  (eventChange)="onEventChange($event)">
+</tcloud-ui-datepicker-time>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  dateTimeValue: Date = new Date();
+
+  onDateTimeChanged(newDateTime: Date) {
+    console.log('Nova data/hora:', newDateTime);
+    // Realizar ações quando data/hora mudar
+  }
+
+  onEventChange(element: any) {
+    console.log('Elemento nativo:', element);
+  }
+}
+```
+
+### Combinação: Intervalo + Opções Rápidas
+```html
+<tcloud-ui-datepicker-time 
+  [minDate]="'01/01/2024'"
+  [maxDate]="'31/12/2024'"
+  [useOptionsDateTime]="true"
+  [(ngModel)]="filtroData">
+</tcloud-ui-datepicker-time>
+
+<p>Filtro: {{ filtroData | date:'dd/MM/yyyy HH:mm' }}</p>
+```
+
+Componente:
+```ts
+export class FiltroComponent {
+  filtroData: Date = new Date();
+}
+```
+
+### Em Formulário com Validação
+```html
+<form #form="ngForm">
+  <div>
+    <label>Data/Hora:</label>
+    <tcloud-ui-datepicker-time 
+      name="dataHora"
+      [(ngModel)]="dataHora"
+      (onChange)="validarData()">
+    </tcloud-ui-datepicker-time>
+  </div>
+  <p *ngIf="erroData" class="error">{{ erroData }}</p>
+</form>
+```
+
+Componente:
+```ts
+export class FormularioComponent {
+  dataHora: Date = new Date();
+  erroData: string = '';
+
+  validarData() {
+    if (this.dataHora) {
+      this.erroData = '';
+    } else {
+      this.erroData = 'Selecione uma data/hora válida.';
+    }
+  }
+}
+```
+
+### Inicializar com Valor Específico
+```ts
+export class ExampleComponent implements OnInit {
+  dateTimeValue: Date;
+
+  ngOnInit() {
+    // Inicializar com data específica
+    this.dateTimeValue = new Date(2024, 0, 15, 14, 30); // 15/01/2024 às 14:30
+  }
+}
+```
+
+```html
+<tcloud-ui-datepicker-time [(ngModel)]="dateTimeValue"></tcloud-ui-datepicker-time>
+```