@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-topology.md

@@ -0,0 +1,232 @@
+# Topology Pipes
+
+O conjunto de pipes `topology` fornece quatro pipes independentes para tradução de valores de topologia de infraestrutura TOTVS Cloud: status de servidores, regiões de datacenter, tipos de ambiente e produtos. Cada pipe realiza a conversão de chaves internas para nomes legíveis em português.
+
+## Características
+
+- Quatro pipes especializados: `topologyStatus`, `topologyRegion`, `topologyEnvironment` e `topologyProduct`
+- Tradução de chaves de infraestrutura para nomes legíveis
+- Comparação case-insensitive no pipe de status
+- Suporte a subproduto no pipe de produto (ex: Protheus como Smart ERP via `origin`)
+- Retorna o valor original quando não encontra correspondência (exceto `topologyEnvironment` que retorna "Ambiente Indefinido")
+- Todos os pipes são standalone
+
+## Instalação
+
+Importe os pipes diretamente no módulo ou componente standalone:
+
+```typescript
+import {
+  TopologyStatusPipe,
+  TopologyRegionPipe,
+  TopologyEnvironmentPipe,
+  TopologyProductPipe
+} from 'tcloud-ui';
+```
+
+---
+
+## TopologyStatusPipe
+
+### Sintaxe
+
+```
+{{ valor | topologyStatus }}
+```
+
+### Mapa de Status
+
+| Chave         | Valor             |
+|---------------|-------------------|
+| `ok` / `done` | Disponível        |
+| `error`       | Indisponível      |
+| `deleting`    | Apagando...       |
+| `stopped`     | Desligado         |
+| `new`         | Em criação        |
+| `dr_new`      | Configurando DR   |
+| `dr_done`     | DR configurado    |
+| `maintenance` | Em manutenção     |
+| `migrating`   | Migrando          |
+
+---
+
+## TopologyRegionPipe
+
+### Sintaxe
+
+```
+{{ valor | topologyRegion }}
+```
+
+### Mapa de Regiões
+
+| Chave    | Valor  |
+|----------|--------|
+| `zone_1` | TESP01 |
+| `zone_2` | TESP02 |
+| `tesp03` | TESP03 |
+| `tesp04` | TESP04 |
+| `tesp05` | TESP05 |
+| `tece01` | TECE01 |
+| `tesp06` | TESP06 |
+
+---
+
+## TopologyEnvironmentPipe
+
+### Sintaxe
+
+```
+{{ valor | topologyEnvironment }}
+```
+
+### Mapa de Ambientes
+
+| Chave          | Valor                |
+|----------------|----------------------|
+| `production`   | Produção             |
+| `qa`           | Qualidade            |
+| `development`  | Desenvolvimento      |
+| `troubleshoot` | Troubleshoot         |
+| `audit`        | Auditoria            |
+| `historical`   | Histórico            |
+| *(outros)*     | Ambiente Indefinido  |
+
+---
+
+## TopologyProductPipe
+
+### Sintaxe
+
+```
+{{ valor | topologyProduct }}
+{{ valor | topologyProduct:origin }}
+```
+
+### Parâmetros
+
+| Parâmetro | Tipo     | Obrigatório | Descrição                                                           |
+|-----------|----------|-------------|----------------------------------------------------------------------|
+| `origin`  | `string` | Não         | Origem do produto. Quando `'smarterp'` e valor `'protheus'`, retorna "Smart ERP" |
+
+### Mapa de Produtos
+
+| Chave             | Valor             |
+|-------------------|-------------------|
+| `2c`              | Carol Connect     |
+| `bioenergia`      | Bioenergia        |
+| `consinco`        | Consinco          |
+| `datasul`         | Datasul           |
+| `fluig`           | Fluig             |
+| `iaas`            | IaaS              |
+| `license_server`  | License Server    |
+| `logix`           | Logix             |
+| `paas`            | Outros            |
+| `pep`             | PEP               |
+| `protheus`        | Protheus          |
+| `pvi`             | PVI               |
+| `rm`              | RM                |
+| `rms`             | RMS               |
+| `sfa`             | SFA               |
+| `sisjuri`         | Sisjuri           |
+| `smarterp`        | Smart ERP         |
+| `smartrm`         | RM                |
+| `smartrm_cluster` | Smart RM Cluster  |
+| `smartrm_control` | Smart RM Control  |
+| `taf`             | TAF               |
+| `totvsagro`       | TOTVS Agro        |
+| `totvsmoda`       | TOTVS Moda        |
+| `treports`        | TReports          |
+| `tss`             | TSS               |
+| `winthor`         | Winthor           |
+
+---
+
+## Exemplos de Uso
+
+### Básico — Tradução de status e ambiente
+
+```html
+<p>{{ 'ok' | topologyStatus }}</p>
+<!-- Resultado: Disponível -->
+
+<p>{{ 'production' | topologyEnvironment }}</p>
+<!-- Resultado: Produção -->
+```
+
+```typescript
+import { TopologyStatusPipe, TopologyEnvironmentPipe } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TopologyStatusPipe, TopologyEnvironmentPipe],
+  template: `
+    <span>{{ servidor.status | topologyStatus }}</span>
+    <span>{{ servidor.ambiente | topologyEnvironment }}</span>
+  `
+})
+export class ExemploBasicoComponent {
+  servidor = { status: 'ok', ambiente: 'production' };
+}
+```
+
+### Avançado — Listagem de servidores com todos os pipes
+
+```html
+<table class="table">
+  <thead>
+    <tr>
+      <th>Produto</th>
+      <th>Ambiente</th>
+      <th>Região</th>
+      <th>Status</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr *ngFor="let srv of servidores">
+      <td>{{ srv.produto | topologyProduct }}</td>
+      <td>{{ srv.ambiente | topologyEnvironment }}</td>
+      <td>{{ srv.regiao | topologyRegion }}</td>
+      <td>{{ srv.status | topologyStatus }}</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```typescript
+import {
+  TopologyStatusPipe,
+  TopologyRegionPipe,
+  TopologyEnvironmentPipe,
+  TopologyProductPipe
+} from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [
+    CommonModule,
+    TopologyStatusPipe,
+    TopologyRegionPipe,
+    TopologyEnvironmentPipe,
+    TopologyProductPipe
+  ],
+  template: `...`
+})
+export class ExemploAvancadoComponent {
+  servidores = [
+    { produto: 'protheus', ambiente: 'production', regiao: 'zone_1', status: 'ok' },
+    { produto: 'rm', ambiente: 'qa', regiao: 'tesp03', status: 'maintenance' },
+    { produto: 'datasul', ambiente: 'development', regiao: 'tece01', status: 'new' }
+  ];
+}
+```
+
+### Avançado — Produto com origin (Smart ERP)
+
+```html
+<p>{{ 'protheus' | topologyProduct:'smarterp' }}</p>
+<!-- Resultado: Smart ERP -->
+
+<p>{{ 'protheus' | topologyProduct }}</p>
+<!-- Resultado: Protheus -->
+```

package/docs/tcloud-ui-upload-area.md

@@ -0,0 +1,195 @@
+# TCloudUiUploadArea
+
+Componente de área de upload com suporte a drag-and-drop, pré-visualização de imagens, reordenação por arraste e validação de arquivos.
+
+---
+
+## Seletor
+
+```html
+<tcloud-ui-upload-area></tcloud-ui-upload-area>
+```
+
+---
+
+## Inputs
+
+| Nome | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `maxFiles` | `number \| undefined` | `undefined` | Número máximo de arquivos permitidos. Se `undefined`, não há limite. |
+| `acceptedFileTypes` | `AcceptedFileType[] \| undefined` | `undefined` | Lista de tipos MIME aceitos. Se `undefined`, todos os tipos são aceitos. Utiliza o enum `AcceptedFileType`. |
+| `imageDimensions` | `ImageDimensions \| undefined` | `undefined` | Dimensões permitidas para imagens (largura x altura em pixels). Se `strict: true`, valida exatamente; caso contrário, aceita até as dimensões informadas. |
+| `showProgress` | `boolean` | `false` | Exibe barra de progresso animada durante o carregamento dos arquivos. |
+| `preloadedImages` | `PreloadedImage[] \| string[]` | — | Imagens pré-carregadas para modo de edição. Aceita array de URLs (strings) ou objetos `PreloadedImage` com `url`, `key` e `order`. As imagens são baixadas e convertidas em `File`. |
+
+---
+
+## Outputs
+
+| Nome | Tipo emitido | Descrição |
+|------|-------------|-----------|
+| `onChange` | `ImageItem[]` | Evento centralizado emitido sempre que houver mudança (adição, remoção ou reordenação). |
+| `filesSelected` | `File[]` | Emitido quando novos arquivos são selecionados ou arrastados. |
+| `imagesReordered` | `string[]` | Emitido após reordenação das imagens (array de previews atualizado). |
+| `imagesRemoved` | `string[]` | Emitido após remoção de uma imagem (array de previews atualizado). |
+| `onError` | `string` | Emitido quando ocorre um erro ou aviso (tipo rejeitado, limite atingido, dimensões inválidas). |
+| `onProgress` | `number` | Emitido durante o carregamento, informando o progresso de 0 a 100. |
+
+---
+
+## Enums
+
+### AcceptedFileType
+
+```typescript
+enum AcceptedFileType {
+  // Imagens
+  JPEG = 'image/jpeg',
+  JPG  = 'image/jpg',
+  PNG  = 'image/png',
+  GIF  = 'image/gif',
+  WEBP = 'image/webp',
+  SVG  = 'image/svg+xml',
+  BMP  = 'image/bmp',
+  ICO  = 'image/x-icon',
+
+  // Vídeos
+  MP4  = 'video/mp4',
+  WEBM = 'video/webm',
+  OGG  = 'video/ogg',
+  AVI  = 'video/x-msvideo',
+  MOV  = 'video/quicktime',
+  WMV  = 'video/x-ms-wmv',
+  FLV  = 'video/x-flv',
+  MKV  = 'video/x-matroska'
+}
+```
+
+---
+
+## Interfaces
+
+### PreloadedImage
+
+```typescript
+interface PreloadedImage {
+  url: string;
+  key?: string;
+  order?: number;
+}
+```
+
+### ImageDimensions
+
+```typescript
+interface ImageDimensions {
+  width: number;
+  height: number;
+  strict?: boolean; // true = exato, false = máximo
+}
+```
+
+### ImageItem
+
+```typescript
+interface ImageItem {
+  name: string;       // Nome original do arquivo
+  new_name: string;   // Nome gerado aleatoriamente
+  order: number;      // Posição na lista (1-based)
+  preview?: string;   // Data URL ou URL para preview
+  file: File;         // Objeto File do arquivo
+}
+```
+
+---
+
+## Exemplos de Uso
+
+### Básico
+
+```html
+<tcloud-ui-upload-area
+  (onChange)="onImagesChange($event)"
+></tcloud-ui-upload-area>
+```
+
+### Com limite de arquivos e tipos aceitos
+
+```html
+<tcloud-ui-upload-area
+  [maxFiles]="5"
+  [acceptedFileTypes]="acceptedTypes"
+  (onChange)="onImagesChange($event)"
+  (onError)="onError($event)"
+></tcloud-ui-upload-area>
+```
+
+```typescript
+import { AcceptedFileType } from 'tcloud-ui';
+
+acceptedTypes = [
+  AcceptedFileType.JPEG,
+  AcceptedFileType.PNG,
+  AcceptedFileType.WEBP
+];
+```
+
+### Com barra de progresso e validação de dimensões
+
+```html
+<tcloud-ui-upload-area
+  [maxFiles]="10"
+  [showProgress]="true"
+  [imageDimensions]="{ width: 1920, height: 1080 }"
+  (onChange)="onImagesChange($event)"
+  (onError)="onError($event)"
+  (onProgress)="onProgress($event)"
+></tcloud-ui-upload-area>
+```
+
+### Com imagens pré-carregadas (modo edição)
+
+```html
+<tcloud-ui-upload-area
+  [preloadedImages]="existingImages"
+  (onChange)="onImagesChange($event)"
+></tcloud-ui-upload-area>
+```
+
+```typescript
+// Usando array de strings (URLs)
+existingImages = [
+  'https://example.com/img1.jpg',
+  'https://example.com/img2.jpg'
+];
+
+// Ou usando objetos PreloadedImage
+existingImages: PreloadedImage[] = [
+  { url: 'https://example.com/img1.jpg', key: 'img1', order: 1 },
+  { url: 'https://example.com/img2.jpg', key: 'img2', order: 2 }
+];
+```
+
+---
+
+## Funcionalidades
+
+- **Drag and Drop**: Arraste arquivos do sistema para a área de upload.
+- **Clique para selecionar**: Clique na área para abrir o seletor de arquivos.
+- **Pré-visualização**: Exibe thumbnails das imagens selecionadas.
+- **Reordenação**: Arraste e solte as imagens para alterar a ordem.
+- **Remoção**: Botão "×" para remover imagens individualmente.
+- **Validação de tipos**: Filtra arquivos por tipo MIME usando o enum `AcceptedFileType`.
+- **Validação de dimensões**: Valida largura e altura das imagens (exata ou máxima).
+- **Limite de arquivos**: Controla o número máximo de arquivos.
+- **Barra de progresso**: Exibe progresso animado durante o carregamento com efeito shimmer.
+- **Imagens pré-carregadas**: Suporte a modo edição com imagens existentes (baixa URLs e converte para `File`).
+- **Tratamento de erros**: Detecta imagens que falharam ao carregar e exibe placeholder de erro.
+
+---
+
+## Importação
+
+```typescript
+import { TCloudUiUploadAreaComponent, AcceptedFileType, PreloadedImage, ImageDimensions, ImageItem } from 'tcloud-ui';
+```

package/docs/tcloud-ui-welcome.md

@@ -0,0 +1,112 @@
+# TCloudUiWelcome
+
+O componente `tcloud-ui-welcome` exibe uma seção de boas-vindas com imagem opcional, título, descrição e área de conteúdo projetado via `ng-content`. É ideal para páginas iniciais, estados vazios ou telas introdutórias. O título e a descrição são renderizados via `innerHTML`, permitindo uso de HTML. Quando uma imagem é fornecida, o layout se divide em colunas (4/8); sem imagem, o conteúdo ocupa a largura total (12 colunas).
+
+## Características
+
+- Layout responsivo com grid de colunas (imagem 4 cols + conteúdo 8 cols, ou conteúdo 12 cols sem imagem)
+- Imagem opcional com tamanho configurável (`small`, `normal`, `big`)
+- Título e descrição com suporte a HTML (`innerHTML`)
+- Tamanho de fonte da descrição configurável (`small`, `normal`, `big`)
+- Projeção de conteúdo via `ng-content` para botões ou ações customizadas
+- Componente standalone
+
+## Instalação
+
+Importe o componente diretamente no módulo ou componente standalone:
+
+```typescript
+import { TCloudUiWelcomeComponent } from 'tcloud-ui';
+```
+
+## Propriedades
+
+### Inputs
+
+| Propriedade   | Tipo                              | Padrão     | Descrição                                                                          |
+|---------------|-----------------------------------|------------|-------------------------------------------------------------------------------------|
+| `imgSrc`      | `string`                          | `''`       | URL da imagem exibida ao lado do conteúdo. Quando vazio, o conteúdo ocupa 12 colunas |
+| `title`       | `string`                          | `''`       | Título da seção de boas-vindas. Aceita HTML via `innerHTML`                         |
+| `description` | `string`                          | `''`       | Texto descritivo abaixo do título. Aceita HTML via `innerHTML`                      |
+| `size`        | `'small' \| 'normal' \| 'big'`   | `'small'`  | Define o tamanho da imagem                                                          |
+| `font`        | `'small' \| 'normal' \| 'big'`   | `'normal'` | Define o tamanho da fonte da descrição                                              |
+| `mirrored`    | `boolean`                         | `false`    | Espelha o layout (inverte a posição da imagem e do conteúdo)                        |
+
+### Outputs
+
+Este componente não possui outputs.
+
+## Exemplos de Uso
+
+### Básico — Boas-vindas com imagem e botão de ação
+
+```html
+<tcloud-ui-welcome
+  [imgSrc]="'https://example.com/welcome.svg'"
+  [title]="'Bem-vindo ao Sistema'"
+  [description]="'Comece criando seu primeiro registro.'">
+  <button class="tc-btn tc-btn-primary" type="button">
+    Criar Registro
+  </button>
+</tcloud-ui-welcome>
+```
+
+```typescript
+import { TCloudUiWelcomeComponent } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiWelcomeComponent],
+  template: `...`
+})
+export class ExemploBasicoComponent {}
+```
+
+### Avançado — Descrição com HTML e múltiplas ações
+
+```html
+<tcloud-ui-welcome
+  [imgSrc]="'https://tcloud.totvs.com.br/assets/img/commercial-event-art.svg'"
+  [title]="'Bem vindo a Janela de Manutenções Programadas'"
+  [description]="descricaoHTML"
+  [size]="'big'"
+  [font]="'big'">
+  <button class="tc-btn tc-btn-primary" type="button" (click)="criarAgendamento()">
+    Criar Agendamentos
+  </button>
+</tcloud-ui-welcome>
+```
+
+```typescript
+import { TCloudUiWelcomeComponent } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiWelcomeComponent],
+  template: `...`
+})
+export class ExemploAvancadoComponent {
+  descricaoHTML = `
+    <p>Aqui você pode criar agendamentos, utilizando as ações disponíveis no catálogo de ações do seu ambiente.</p>
+    <p>Se você precisa agendar uma ação solicitada por alguma manutenção programada pela TOTVS,
+    acesse o menu lateral: "Janela de Manutenção" - "Agendamentos Pendentes"</p>
+  `;
+
+  criarAgendamento() {
+    console.log('Abrindo formulário de agendamento');
+  }
+}
+```
+
+### Avançado — Sem imagem, apenas texto centralizado
+
+```html
+<tcloud-ui-welcome
+  [title]="'Nenhum dado disponível'"
+  [description]="'Utilize o botão abaixo para importar seus dados.'"
+  [font]="'small'">
+  <button class="tc-btn tc-btn-outline-primary" type="button">
+    Importar Dados
+  </button>
+</tcloud-ui-welcome>
+```

package/docs/tcloud-ui-wizard-steps.md

@@ -0,0 +1,103 @@
+# Wizard Steps
+
+Componente de wizard/stepper que exibe uma sequência de etapas com suporte a direções horizontal e vertical. Cada etapa pode ter estados de concluído, atual e próximo, com animação de barra de progresso e clique opcional nas etapas.
+
+## Características
+
+- Layout horizontal e vertical
+- Estados visuais: concluído (com ícone de check), atual (destacado) e próximo
+- Barra de progresso animada entre as etapas concluídas
+- Suporte a clique nas etapas já concluídas (quando habilitado)
+- Descrição opcional por etapa
+
+## Instalação
+
+```typescript
+import { TCloudUiModule } from 'tcloud-ui';
+```
+
+Adicione `TCloudUiModule` aos imports do seu componente/módulo.
+
+## Propriedades (API)
+
+### Inputs
+
+| Nome           | Tipo                           | Descrição                                      | Valor Default    |
+|----------------|--------------------------------|-------------------------------------------------|------------------|
+| steps          | `WizardStep[]`                 | Lista de etapas do wizard (obrigatório)         | —                |
+| currentStep    | `number`                       | Índice da etapa atual (base 0)                  | `0`              |
+| direction      | `'horizontal' \| 'vertical'`  | Direção do layout do wizard                     | `'horizontal'`   |
+| stepClickable  | `boolean`                      | Permite clicar em etapas concluídas/atuais      | `false`          |
+
+### Outputs
+
+| Nome         | Tipo de Evento                           | Descrição                                          |
+|--------------|------------------------------------------|----------------------------------------------------|
+| onStepClick  | `{ step: WizardStep, index: number }`    | Emitido ao clicar em uma etapa (quando habilitado) |
+
+### Tipo WizardStep
+
+```typescript
+type WizardStep = {
+  title: string;
+  description?: string;
+  completed?: boolean;
+}
+```
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<tcloud-ui-wizard-steps
+  [steps]="steps"
+  [currentStep]="1">
+</tcloud-ui-wizard-steps>
+```
+
+```typescript
+steps: WizardStep[] = [
+  { title: 'Dados pessoais', description: 'Informações do usuário' },
+  { title: 'Endereço', description: 'Localização e CEP' },
+  { title: 'Pagamento', description: 'Forma de pagamento' },
+  { title: 'Confirmação', description: 'Revisão e envio' }
+];
+```
+
+### Uso Avançado — Steps clicáveis com controle de etapa
+
+```html
+<tcloud-ui-wizard-steps
+  [steps]="steps"
+  [currentStep]="currentStep"
+  [stepClickable]="true"
+  (onStepClick)="onStepClicked($event)">
+</tcloud-ui-wizard-steps>
+```
+
+```typescript
+currentStep = 2;
+
+steps: WizardStep[] = [
+  { title: 'Dados pessoais', completed: true },
+  { title: 'Endereço', completed: true },
+  { title: 'Pagamento' },
+  { title: 'Confirmação' }
+];
+
+onStepClicked(event: { step: WizardStep, index: number }) {
+  console.log('Etapa clicada:', event);
+  this.currentStep = event.index + 1;
+}
+```
+
+### Layout Vertical
+
+```html
+<tcloud-ui-wizard-steps
+  [steps]="steps"
+  [currentStep]="currentStep"
+  direction="vertical">
+</tcloud-ui-wizard-steps>
+```