@dev-tcloud/tcloud-ui 6.19.2 → 6.20.0

package/docs/tcloud-ui-dialog.md

@@ -0,0 +1,167 @@
+# TCloud UI Dialog
+
+Componente standalone de diálogo de confirmação criado dinamicamente via `TCloudUiDialogService`, com suporte a mensagem HTML, estado de carregamento, confirmação por texto digitado e encadeamento fluente (`onConfirm` / `onCancel`).
+
+## Características
+
+- Abertura imperativa com `ComponentFactoryResolver` e `ViewContainerRef` raiz definido pelo consumidor
+- Título, mensagem (`innerHTML`), textos de botões e rótulos via `TCloudUiDialogModel` e i18n padrão
+- Modo de confirmação por palavra (`TCloudUiDialogTextConfirmationEnum`) com validação case-insensitive
+- Indicador de carregamento (`tc-rev-small-loading`) quando `data.loading` é verdadeiro
+- Tecla Escape e botão fechar disparam fluxo de cancelamento; animação de entrada/saída (`fade`)
+- `BehaviorSubject` `events` notifica ciclo de vida (`open` / `close`); após `close` o serviço destrói a instância do componente
+
+## Instalação
+
+O componente e o serviço estão no `TCloudUiModule` (o serviço também está em `providedIn: 'root'`).
+
+```typescript
+import { TCloudUiModule, TCloudUiDialogService } from 'projects/tcloud-ui/src/public-api';
+
+@NgModule({
+  imports: [TCloudUiModule],
+})
+export class AppModule {}
+```
+
+Uso standalone (apenas o componente, sem abrir via serviço — cenário raro, pois o fluxo previsto é via serviço):
+
+```typescript
+import { TCloudUiDialogComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiDialogComponent],
+})
+export class ExampleComponent {}
+```
+
+## Propriedades (API)
+
+O seletor `tcloud-ui-dialog` não expõe `@Input()` nem `@Output()` para templates externos: a configuração ocorre pelo retorno de `TCloudUiDialogService.open()` e pela mutação de `data` na instância retornada.
+
+### Parâmetros de `TCloudUiDialogService.open(_data?)`
+
+Valores passados em `_data` são mesclados com padrões do serviço (incluindo chaves i18n). O serviço instancia `TCloudUiDialogModel` internamente.
+
+| Campo | Tipo | Descrição | Valor padrão (comportamento do serviço) |
+|-------|------|-----------|----------------------------------------|
+| `title` | `string` | Título do cabeçalho | Tradução de `dialogConfirmation.default_title` ou *Atenção* |
+| `message` | `string` | Corpo do diálogo (HTML) | Tradução de `dialogConfirmation.default_message` |
+| `loading` | `boolean` | Exibe loading e bloqueia ações enquanto verdadeiro | `undefined` / herdado do objeto |
+| `disable` | `boolean` | Desabilita botões, fechar e Escape | `undefined` / herdado |
+| `disableClickOutside` | `boolean` | Comportamento do clique no backdrop: quando **falso** ou indefinido, o clique é ignorado; quando **verdadeiro** e `disable` é falso, o clique chama `close(true)` (mesmo fluxo que cancelar) | `undefined` / herdado |
+| `inputConfirmationText` | `TCloudUiDialogTextConfirmationEnum` | Palavra esperada no campo de confirmação (mapeada para texto i18n) | `confirm` |
+| `buttonConfirmText` | `string` | Armazenado em `TCloudUiDialogModel`; o template atual do diálogo exibe no botão principal o valor de `textConfirmation` com `titlecase`, não este campo | Opcional |
+| `buttonCancelText` | `string` | Rótulo do botão cancelar | Tradução de `dialogConfirmation.cancel` se omitido |
+
+### `TCloudUiDialogTextConfirmationEnum`
+
+| Valor | Uso |
+|-------|-----|
+| `continue` | Palavra de confirmação associada à tradução `dialogConfirmation.continue` |
+| `remove` | Idem `dialogConfirmation.remove` |
+| `confirm` | Idem `dialogConfirmation.confirm` (padrão do serviço) |
+
+### `TCloudUiDialogEventsEnum`
+
+Emitido em `events` da instância do componente: `open` (valor inicial) e `close` ao finalizar animação de fechamento.
+
+### `TCloudUiDialogStatusEnum`
+
+Valores `success`, `error`, `info`, `warning` exportados no pacote para uso alinhado a fluxos de UI; o componente de diálogo atual não aplica esse enum no template.
+
+### API pública da instância (`TCloudUiDialogComponent`)
+
+| Membro | Tipo | Descrição |
+|--------|------|-----------|
+| `data` | `TCloudUiDialogModel` | Modelo exibido; pode ser mutado após abrir (ex.: `dialog.data.loading = true`) |
+| `textConfirmation` | `string` | Palavra efetiva de confirmação (definida pelo serviço com base no enum e i18n) |
+| `inputConfirmationControl` | `FormControl` | Controle do campo de confirmação; `Validators.required`; desabilitado quando `disable` ou `loading` |
+| `events` | `BehaviorSubject<TCloudUiDialogEventsEnum>` | Ciclo de vida; completa após `close` |
+| `animation` | `string` | Estado da animação (`visible` / `hide`) |
+| `close(emitCancel?)` | `void` | Inicia fechamento; `emitCancel === true` (padrão) invoca callback de `onCancel`; `false` apenas encerra sem disparar cancelamento |
+| `confirm()` | `void` | Valida texto de confirmação (se habilitado) e chama callback de `onConfirm` |
+| `onConfirm(fn)` | `TCloudUiDialogComponent` | Registra callback recebendo a instância do diálogo; encadeável |
+| `onCancel(fn)` | `TCloudUiDialogComponent` | Registra callback de cancelamento; encadeável |
+
+### Configuração obrigatória do serviço
+
+| Método | Descrição |
+|--------|-----------|
+| `setRootViewContainerRef(ref: ViewContainerRef)` | Define o container onde o host do diálogo será inserido (tipicamente `ViewChild` template em `#dialogRoot`) |
+
+## Exemplos de uso
+
+### Uso básico
+
+Template com âncora para o diálogo e botão para abrir:
+
+```html
+<ng-container #dialogRoot></ng-container>
+<button type="button" (click)="open()">Abrir diálogo</button>
+```
+
+```typescript
+import { AfterViewInit, Component, ViewChild, ViewContainerRef } from '@angular/core';
+import {
+  TCloudUiDialogService,
+  TCloudUiDialogTextConfirmationEnum,
+} from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent implements AfterViewInit {
+  @ViewChild('dialogRoot', { read: ViewContainerRef }) dialogRoot!: ViewContainerRef;
+
+  constructor(private readonly dialog: TCloudUiDialogService) {}
+
+  ngAfterViewInit(): void {
+    this.dialog.setRootViewContainerRef(this.dialogRoot);
+  }
+
+  open(): void {
+    this.dialog
+      .open({
+        title: 'Confirmar operação',
+        message: '<p>Deseja prosseguir?</p>',
+        inputConfirmationText: TCloudUiDialogTextConfirmationEnum.confirm,
+      })
+      .onConfirm((d) => d.close(false))
+      .onCancel(() => {});
+  }
+}
+```
+
+### Uso avançado
+
+Padrão da página de demonstração: confirmação com palavra `remove`, bloqueio de clique externo até confirmar texto, fluxo assíncrono com `loading` e fechamento sem callback de cancelamento após sucesso.
+
+```typescript
+openDialogWarning(): void {
+  this.tCloudUiDialogService
+    .open({
+      title: 'Teste title',
+      message: 'Teste message',
+      disableClickOutside: true,
+      inputConfirmationText: TCloudUiDialogTextConfirmationEnum.remove,
+      buttonConfirmText: 'Teste confirm',
+      buttonCancelText: 'Teste cancel',
+    })
+    .onConfirm((dialog) => {
+      dialog.data.loading = true;
+      setTimeout(() => dialog.close(false), 3000);
+    })
+    .onCancel(() => {
+      alert('Cancelado');
+    });
+}
+```
+
+Notas de comportamento:
+
+- `dialog.close(false)` após operações bem-sucedidas evita executar o handler registrado em `onCancel`.
+- Enquanto `data.loading` ou `data.disable` é verdadeiro, Escape não fecha o diálogo e os botões permanecem desabilitados.
+- Com campo de confirmação ativo, o valor digitado deve coincidir com `textConfirmation` (comparação sem diferenciar maiúsculas/minúsculas).

package/docs/tcloud-ui-progress-status-bar.md

@@ -0,0 +1,92 @@
+# Progress Status Bar
+
+## Características
+- Componente standalone para exibir progresso com gradiente por faixa de status.
+- Permite definir múltiplas faixas (`start` e `end`) para trocar automaticamente a cor.
+- Suporte aos status de gradiente: `info`, `danger`, `success` e `alert`.
+- Quando o valor atual ultrapassa a última faixa, mantém o gradiente da última configuração.
+
+## Instalação
+```ts
+import { TCloudUiProgressStatusBarComponent } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiProgressStatusBarComponent],
+  template: `
+    <tcloud-ui-progress-status-bar
+      [currentValue]="42"
+      [progressStatusConfig]="statusConfig">
+    </tcloud-ui-progress-status-bar>
+  `
+})
+export class ExampleComponent {
+  statusConfig = [
+    { start: 0, end: 25, gradientStatus: 'info' },
+    { start: 26, end: 60, gradientStatus: 'alert' },
+    { start: 61, end: 85, gradientStatus: 'danger' },
+    { start: 86, end: 100, gradientStatus: 'success' }
+  ];
+}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| currentValue | number | Valor percentual atual da barra. | obrigatório |
+| progressStatusConfig | ProgressStatusConfig[] | Lista de faixas para definir gradiente por intervalo. | obrigatório |
+
+### Tipo ProgressStatusConfig
+| Nome | Tipo | Descrição |
+| --- | --- | --- |
+| start | number | Valor inicial da faixa (inclusivo). |
+| end | number | Valor final da faixa (inclusivo). |
+| gradientStatus | ProgressStatusBarGradientStatus | Tipo de gradiente aplicado para a faixa. |
+
+### Enum ProgressStatusBarGradientStatus
+- `info`
+- `danger`
+- `success`
+- `alert`
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| (não possui) | - | Componente não emite eventos. |
+
+## Exemplos de Uso
+### Uso Básico
+```html
+<tcloud-ui-progress-status-bar
+  [currentValue]="42"
+  [progressStatusConfig]="statusConfig">
+</tcloud-ui-progress-status-bar>
+```
+
+### Exemplo com faixas operacionais
+```ts
+statusConfig = [
+  { start: 0, end: 40, gradientStatus: 'success' },
+  { start: 41, end: 75, gradientStatus: 'info' },
+  { start: 76, end: 90, gradientStatus: 'alert' },
+  { start: 91, end: 100, gradientStatus: 'danger' }
+];
+```
+
+```html
+<tcloud-ui-progress-status-bar
+  [currentValue]="82"
+  [progressStatusConfig]="statusConfig">
+</tcloud-ui-progress-status-bar>
+```
+
+### Valor acima da última faixa
+```html
+<!-- Usa o gradiente da última faixa configurada -->
+<tcloud-ui-progress-status-bar
+  [currentValue]="120"
+  [progressStatusConfig]="statusConfig">
+</tcloud-ui-progress-status-bar>
+```