@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-modal.md

@@ -0,0 +1,196 @@
+# Modal
+
+## Características
+
+- Modal standalone com animação de entrada/saída configurável por posição, e bloqueio de scroll do `body` enquanto aberto.
+- Suporte a posições de âncora (`top`, `right`, `left`, `bottom`) e tamanhos predefinidos via `window` ou controle fino via `maxWidth`.
+- Modo confirmação opcional: exige que o usuário digite um texto específico antes de habilitar a ação — com suporte à desabilitação do campo de texto (`confirmInput: false`).
+- Estado de carregamento controlável via `loading`, que desabilita as ações do footer enquanto uma operação assíncrona está em curso.
+- Estrutura modular baseada em três sub-componentes de composição: `tcloud-ui-modal-header`, `tcloud-ui-modal-body` e `tcloud-ui-modal-footer`.
+- Suporte a two-way binding via `[(open)]` para controle declarativo da visibilidade.
+
+## Instalação
+
+Importe os componentes necessários no componente standalone consumidor:
+
+```ts
+import {
+  TCloudUiModalComponent,
+  TCloudUiModalHeaderComponent,
+  TCloudUiModalBodyComponent,
+  TCloudUiModalFooterComponent
+} from 'tcloud-ui';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [
+    TCloudUiModalComponent,
+    TCloudUiModalHeaderComponent,
+    TCloudUiModalBodyComponent,
+    TCloudUiModalFooterComponent
+  ],
+  template: `...`
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+### `tcloud-ui-modal` — Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|---|---|---|---|
+| `open` | `boolean` | Controla a visibilidade do modal. Suporta two-way binding via `[(open)]`. | `false` |
+| `loading` | `boolean` | Coloca o modal em estado de carregamento, desabilitando as ações do footer. | `false` |
+| `autoClose` | `boolean` | Fecha o modal automaticamente após uma ação confirmada ou cancelada. | `true` |
+| `confirm` | `boolean` | Ativa o modo confirmação no footer, exibindo campo de digitação e botões de confirmar/cancelar. | `false` |
+| `confirmText` | `string` | Texto que o usuário deve digitar para habilitar a confirmação (utilizado quando `confirm: true`). | `'Confirmo'` |
+| `confirmInput` | `boolean` | Quando `false`, omite o campo de texto no modo confirmação e permite confirmar diretamente. | `true` |
+| `maxWidth` | `number` | Largura máxima do modal em pixels. Ignorado se `window` for utilizado. | `500` |
+| `window` | `'small' \| 'medium' \| 'large' \| 'big' \| 'full'` | Define a largura por tamanho semântico: 300 / 500 / 900 / 1100 / 1400 px. Tem precedência sobre `maxWidth`. | — |
+| `position` | `'top' \| 'right' \| 'left' \| 'bottom'` | Define a âncora de entrada/saída da animação e o layout do modal. | `'top'` |
+| `sticky` | `boolean` | Mantém o modal em modo fixo (útil para side panels com scroll interno). | `false` |
+| `title` | `any` | Título exibido no topo do modal (alternativa a usar `tcloud-ui-modal-header`). | — |
+
+### `tcloud-ui-modal` — Outputs
+
+| Nome | Tipo de Evento | Descrição |
+|---|---|---|
+| `openChange` | `EventEmitter<boolean>` | Emite o novo estado ao fechar, viabilizando two-way binding com `[(open)]`. |
+| `toConfirm` | `EventEmitter<boolean>` | Emite `true` quando o usuário confirma a ação no modo confirmação. |
+| `toCancel` | `EventEmitter<boolean>` | Emite `false` quando o usuário cancela no modo confirmação. |
+| `toAction` | `EventEmitter<'confirmed' \| 'cancel' \| 'close'>` | Emite a ação resultante após qualquer interação de fechamento do modal. |
+
+---
+
+### `tcloud-ui-modal-header` — Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|---|---|---|---|
+| `title` | `any` | Texto do cabeçalho do modal. | — |
+| `mode` | `'colorless' \| 'info' \| 'success' \| 'danger' \| 'warning'` | Define a variação visual do cabeçalho e propaga o modo ao footer via serviço interno. | `'info'` |
+
+---
+
+### `tcloud-ui-modal-footer` — Inputs
+
+| Nome | Tipo | Descrição | Valor Default |
+|---|---|---|---|
+| `actions` | `boolean` | Controla a exibição dos botões de ação no footer. | `true` |
+| `btnCloseText` | `string` | Texto do botão de fechar (exibido quando não está em modo confirmação). | `'Fechar'` |
+| `btnCancelText` | `string` | Texto do botão de cancelar (exibido no modo confirmação). | `'Cancelar'` |
+| `btnConfirmText` | `string` | Texto do botão de confirmar (exibido no modo confirmação). | `'Confirmar'` |
+
+---
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<!-- app.component.html -->
+<tcloud-ui-modal [(open)]="isOpen" [window]="'big'">
+  <tcloud-ui-modal-header title="Título do Modal" mode="colorless"></tcloud-ui-modal-header>
+  <tcloud-ui-modal-body>
+    <p>Conteúdo do modal aqui.</p>
+  </tcloud-ui-modal-body>
+  <tcloud-ui-modal-footer></tcloud-ui-modal-footer>
+</tcloud-ui-modal>
+
+<button type="button" (click)="isOpen = !isOpen">Abrir Modal</button>
+```
+
+```ts
+// app.component.ts
+export class AppComponent {
+  isOpen = false;
+}
+```
+
+---
+
+### Uso Avançado
+
+#### Side panel lateral com scroll e modo sticky
+
+```html
+<tcloud-ui-modal [(open)]="openRight" [window]="'small'" [position]="'right'" [sticky]="true">
+  <tcloud-ui-modal-header title="Painel Lateral" mode="colorless"></tcloud-ui-modal-header>
+  <tcloud-ui-modal-body>
+    <table>
+      <tr *ngFor="let item of items">
+        <td>{{ item.name }}</td>
+      </tr>
+    </table>
+  </tcloud-ui-modal-body>
+  <tcloud-ui-modal-footer></tcloud-ui-modal-footer>
+</tcloud-ui-modal>
+
+<button type="button" (click)="openRight = !openRight">Abrir lateral direita</button>
+```
+
+#### Modal de confirmação com digitação obrigatória
+
+```html
+<tcloud-ui-modal
+  [(open)]="openConfirm"
+  [confirm]="true"
+  confirmText="EXCLUIR"
+  (toAction)="onAction($event)">
+  <tcloud-ui-modal-header title="Atenção" mode="warning"></tcloud-ui-modal-header>
+  <tcloud-ui-modal-body>
+    Digite <strong>EXCLUIR</strong> para confirmar a exclusão permanente do registro.
+  </tcloud-ui-modal-body>
+  <tcloud-ui-modal-footer></tcloud-ui-modal-footer>
+</tcloud-ui-modal>
+```
+
+```ts
+onAction(action: 'confirmed' | 'cancel' | 'close') {
+  if (action === 'confirmed') {
+    // executar exclusão
+  }
+}
+```
+
+#### Modal de confirmação sem campo de texto
+
+```html
+<tcloud-ui-modal
+  [(open)]="openConfirmSimple"
+  [confirm]="true"
+  [confirmInput]="false"
+  (toAction)="onAction($event)">
+  <tcloud-ui-modal-header title="Confirmar ação" mode="danger"></tcloud-ui-modal-header>
+  <tcloud-ui-modal-body>Deseja realmente executar esta ação?</tcloud-ui-modal-body>
+  <tcloud-ui-modal-footer></tcloud-ui-modal-footer>
+</tcloud-ui-modal>
+```
+
+#### Modal com estado de carregamento
+
+```html
+<tcloud-ui-modal [(open)]="isOpen" [loading]="isSaving">
+  <tcloud-ui-modal-header title="Salvar" mode="info"></tcloud-ui-modal-header>
+  <tcloud-ui-modal-body>
+    Processando sua solicitação...
+  </tcloud-ui-modal-body>
+  <tcloud-ui-modal-footer></tcloud-ui-modal-footer>
+</tcloud-ui-modal>
+```
+
+```ts
+export class AppComponent {
+  isOpen = false;
+  isSaving = false;
+
+  save() {
+    this.isSaving = true;
+    this.myService.save().subscribe(() => {
+      this.isSaving = false;
+      this.isOpen = false;
+    });
+  }
+}
+```

package/docs/tcloud-ui-monthname.md

@@ -0,0 +1,123 @@
+# MonthNamePipe
+
+O pipe `monthname` converte uma string no formato `yyyy-MM` para o nome do mês correspondente em português brasileiro. Utiliza um array interno com os 12 meses do ano para realizar a tradução do número do mês para seu nome por extenso.
+
+## Características
+
+- Conversão de formato `yyyy-MM` para nome do mês em português (Janeiro a Dezembro)
+- Parsing da string pelo separador `-` para extrair o mês
+- Retorna string vazia para valores vazios ou formatos inválidos
+- Validação: exige exatamente duas partes separadas por `-`
+- Pipe standalone
+
+## Instalação
+
+Importe o pipe diretamente no módulo ou componente standalone:
+
+```typescript
+import { MonthNamePipe } from 'tcloud-ui';
+```
+
+## API
+
+### Sintaxe do Pipe
+
+```
+{{ valor | monthname }}
+```
+
+### Parâmetros
+
+Este pipe não recebe parâmetros adicionais.
+
+### Entrada e Saída
+
+| Entrada      | Saída        |
+|--------------|--------------|
+| `'2026-01'`  | `'Janeiro'`  |
+| `'2026-03'`  | `'Março'`    |
+| `'2026-06'`  | `'Junho'`    |
+| `'2026-12'`  | `'Dezembro'` |
+| `''`         | `''`         |
+
+### Meses Disponíveis
+
+| Número | Nome       |
+|--------|------------|
+| 01     | Janeiro    |
+| 02     | Fevereiro  |
+| 03     | Março      |
+| 04     | Abril      |
+| 05     | Maio       |
+| 06     | Junho      |
+| 07     | Julho      |
+| 08     | Agosto     |
+| 09     | Setembro   |
+| 10     | Outubro    |
+| 11     | Novembro   |
+| 12     | Dezembro   |
+
+## Exemplos de Uso
+
+### Básico — Exibição do nome do mês
+
+```html
+<p>{{ '2026-03' | monthname }}</p>
+<!-- Resultado: Março -->
+
+<p>{{ '2026-12' | monthname }}</p>
+<!-- Resultado: Dezembro -->
+```
+
+```typescript
+import { MonthNamePipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [MonthNamePipe],
+  template: `
+    <p>{{ competencia | monthname }}</p>
+  `
+})
+export class ExemploBasicoComponent {
+  competencia = '2026-03';
+}
+```
+
+### Avançado — Listagem de competências
+
+```html
+<table class="table">
+  <thead>
+    <tr>
+      <th>Competência</th>
+      <th>Mês</th>
+      <th>Valor</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr *ngFor="let item of competencias">
+      <td>{{ item.periodo }}</td>
+      <td>{{ item.periodo | monthname }}</td>
+      <td>{{ item.valor | currency:'BRL' }}</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```typescript
+import { MonthNamePipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule, MonthNamePipe],
+  template: `...`
+})
+export class ExemploAvancadoComponent {
+  competencias = [
+    { periodo: '2026-01', valor: 1500.00 },
+    { periodo: '2026-02', valor: 2300.50 },
+    { periodo: '2026-03', valor: 1800.75 }
+  ];
+}
+```

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

@@ -0,0 +1,290 @@
+# Multi Input
+
+## Características
+- Componente standalone para entrada de múltiplos valores em formato de tags/labels.
+- Input com botão de adicionar (+) para inserir novos itens à lista.
+- Cada item exibido com botão de remoção (x).
+- Suporte a ngModel (two-way binding) via ControlValueAccessor.
+- Validação com `required` via NG_VALIDATORS: exige ao menos um item na lista.
+- Suporte a estados: `disabled` e `loading`.
+- Largura máxima configurável para labels.
+- Modo `showInput`: oculta o input de entrada, exibindo apenas os itens.
+- Emite alterações via evento `tcChange`.
+
+## Instalação
+```ts
+import { TCloudUiMultiInputComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiMultiInputComponent],
+  template: `
+    <tcloud-ui-multi-input 
+      [tcList]="items"
+      (tcChange)="onItemsChanged($event)">
+    </tcloud-ui-multi-input>
+  `
+})
+export class ExampleComponent {
+  items = [{ value: 'Item 1' }, { value: 'Item 2' }];
+
+  onItemsChanged(event: any[]) {
+    console.log('Itens atualizados:', event);
+  }
+}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| tcList | { value: any }[] | Array de objetos com propriedade `value` representando os itens. | undefined |
+| placeholder | string | Texto exibido no input quando vazio. | '' |
+| disabled | boolean | Se true, desabilita input e botões. | false |
+| loading | boolean | Se true, desabilita input e botões (estado de carregamento). | false |
+| required | string | Se definido, habilita validação de pelo menos um item na lista. | undefined |
+| maxWidthLabel | string | Largura máxima de cada label (ex: '95px', '120px'). | undefined |
+| showInput | boolean | Se true, oculta o input de entrada e exibe apenas os itens existentes. | false |
+| ngModel | { value: any }[] | Array de itens para two-way binding. | undefined |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| tcChange | EventEmitter<any[]> | Emite o array de itens atualizado ao adicionar ou remover. |
+| onChange | EventEmitter<any> | Emite alterações internas. |
+
+## Exemplos de Uso
+### Uso Básico - Modo Simples
+```ts
+export class ExampleComponent {
+  items = [
+    { value: 'Texto 1' },
+    { value: 'Texto 2' },
+    { value: 'Texto 3' }
+  ];
+
+  onItemsChanged(event: any[]) {
+    console.log('Itens:', event);
+  }
+}
+```
+
+```html
+<tcloud-ui-multi-input 
+  [tcList]="items"
+  (tcChange)="onItemsChanged($event)"
+  [placeholder]="'Digite um valor'">
+</tcloud-ui-multi-input>
+
+<pre>{{ items | json }}</pre>
+```
+
+### Com Largura Máxima de Label
+```html
+<tcloud-ui-multi-input 
+  [tcList]="items"
+  (tcChange)="onItemsChanged($event)"
+  [maxWidthLabel]="'95px'"
+  [placeholder]="'Selecione um item'">
+</tcloud-ui-multi-input>
+```
+
+### Com Validação Required (ngModel)
+```html
+<form #formulario="ngForm">
+  <tcloud-ui-multi-input 
+    name="tags"
+    [(ngModel)]="selectedItems"
+    required>
+  </tcloud-ui-multi-input>
+
+  <p *ngIf="formulario.invalid">
+    É necessário ao menos um item.
+  </p>
+
+  <button [disabled]="formulario.invalid">Salvar</button>
+</form>
+```
+
+Componente:
+```ts
+export class FormComponent {
+  selectedItems: { value: any }[] | undefined;
+}
+```
+
+### Modo Somente Leitura (showInput)
+```html
+<!-- Exibe apenas os itens, sem input para adicionar novos -->
+<tcloud-ui-multi-input 
+  [tcList]="items"
+  [showInput]="true"
+  (tcChange)="onItemsChanged($event)"
+  [maxWidthLabel]="'95px'">
+</tcloud-ui-multi-input>
+```
+
+### Desabilitado
+```html
+<tcloud-ui-multi-input 
+  [tcList]="items"
+  [disabled]="true"
+  [placeholder]="'Input desabilitado'">
+</tcloud-ui-multi-input>
+```
+
+## Uso Avançado
+### Com ngModel e Formulário Reativo
+```ts
+export class FormComponent {
+  tags: { value: string }[] = [];
+
+  addTag(tag: string) {
+    this.tags.push({ value: tag });
+  }
+
+  removeAllTags() {
+    this.tags = [];
+  }
+}
+```
+
+```html
+<form #form="ngForm">
+  <div>
+    <label>Tags do Produto:</label>
+    <tcloud-ui-multi-input 
+      name="productTags"
+      [(ngModel)]="tags"
+      required
+      [placeholder]="'Adicionar tag...'">
+    </tcloud-ui-multi-input>
+  </div>
+
+  <p *ngIf="tags && tags.length > 0">
+    Total de tags: {{ tags.length }}
+  </p>
+
+  <button type="button" (click)="removeAllTags()">Limpar</button>
+  <button type="submit" [disabled]="form.invalid">Salvar</button>
+</form>
+```
+
+### Lista de Emails
+```ts
+export class EmailListComponent {
+  emails: { value: string }[] = [
+    { value: 'admin@example.com' },
+    { value: 'user@example.com' }
+  ];
+
+  onEmailsChanged(updatedEmails: any[]) {
+    console.log('Emails atualizados:', updatedEmails);
+  }
+}
+```
+
+```html
+<div>
+  <label>Destinatários:</label>
+  <tcloud-ui-multi-input 
+    [tcList]="emails"
+    (tcChange)="onEmailsChanged($event)"
+    [placeholder]="'Digite um email...'"
+    [maxWidthLabel]="'200px'">
+  </tcloud-ui-multi-input>
+</div>
+```
+
+### Com Estado de Loading
+```ts
+export class LoadingComponent {
+  items: { value: string }[] = [];
+  isLoading: boolean = false;
+
+  loadItems() {
+    this.isLoading = true;
+    // Simular carregamento
+    setTimeout(() => {
+      this.items = [
+        { value: 'Item carregado 1' },
+        { value: 'Item carregado 2' }
+      ];
+      this.isLoading = false;
+    }, 2000);
+  }
+}
+```
+
+```html
+<tcloud-ui-multi-input 
+  [tcList]="items"
+  [loading]="isLoading"
+  [placeholder]="'Carregando...'">
+</tcloud-ui-multi-input>
+
+<button (click)="loadItems()" [disabled]="isLoading">Carregar Itens</button>
+```
+
+### Controle Dinâmico com Dados Externos
+```ts
+export class DynamicComponent {
+  tags: { value: string }[] = [];
+  suggestions = ['Angular', 'React', 'Vue', 'Svelte', 'Next.js'];
+
+  addSuggestion(suggestion: string) {
+    if (!this.tags.find(t => t.value === suggestion)) {
+      this.tags.push({ value: suggestion });
+    }
+  }
+
+  onTagsChanged(event: any[]) {
+    this.tags = event;
+  }
+}
+```
+
+```html
+<div>
+  <label>Tecnologias:</label>
+  <tcloud-ui-multi-input 
+    [tcList]="tags"
+    (tcChange)="onTagsChanged($event)"
+    [placeholder]="'Adicionar tecnologia...'"
+    [maxWidthLabel]="'120px'">
+  </tcloud-ui-multi-input>
+
+  <div class="suggestions">
+    <p>Sugestões:</p>
+    <button 
+      *ngFor="let s of suggestions" 
+      (click)="addSuggestion(s)"
+      type="button">
+      {{ s }}
+    </button>
+  </div>
+</div>
+```
+
+## Estrutura de Dados
+Os itens devem seguir o formato:
+```ts
+interface IMultiInputItem {
+  value: any; // Valor exibido e armazenado
+}
+```
+
+Exemplo:
+```ts
+const items = [
+  { value: 'Tag 1' },
+  { value: 'Tag 2' },
+  { value: 'Tag 3' }
+];
+```
+
+## Validação
+- Quando `required` é definido, o componente valida se há ao menos um item na lista.
+- A validação é integrada com Angular Forms via `NG_VALIDATORS`.
+- O controle é marcado como inválido quando a lista está vazia e `required` está ativo.