@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/confirm-dialog/README.md

@@ -0,0 +1,105 @@
+# ConfirmDialog
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Serviço para exibir diálogos de confirmação modais de forma programática. Utilizado via `ConfirmDialogService.confirm()` — não é instanciado diretamente no template.
+
+## Quando usar
+
+- Confirmar ações destrutivas como exclusão ou arquivamento de registros
+- Solicitar confirmação explícita antes de operações irreversíveis
+- Exibir alertas que requerem reconhecimento do usuário (sem botão de cancelar)
+
+## Quando não usar
+
+- Mensagens de feedback simples sem necessidade de confirmação — use [`Alert`](../alert/README.md) ou notificações inline
+- Fluxos com formulários complexos — use [`Dialog`](../dialog/README.md) com `DialogService`
+
+## Instalação
+
+```typescript
+import { ConfirmDialogService } from '@seniorsistemas/angular-components/confirm-dialog';
+import { DialogService } from '@seniorsistemas/angular-components/dialog';
+
+@Component({
+  standalone: true,
+  providers: [ConfirmDialogService, DialogService],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```typescript
+// No componente — injete o serviço e chame confirm()
+constructor(private confirmDialogService: ConfirmDialogService) {}
+
+openConfirm() {
+  this.confirmDialogService.confirm({
+    header: 'Remover item?',
+    message: 'Esta ação não pode ser desfeita.',
+    acceptLabel: 'Remover',
+    rejectLabel: 'Cancelar',
+    accept: () => this.delete(),
+    reject: () => console.log('cancelado'),
+  });
+}
+```
+
+## API
+
+### Tipos
+
+```typescript
+type ConfirmDialog = {
+  header: string;        // Título do diálogo (obrigatório)
+  message: string;       // Mensagem exibida no corpo (obrigatório)
+  acceptLabel: string;   // Label do botão de confirmar (obrigatório)
+  accept: VoidFunction;  // Callback ao confirmar (obrigatório)
+  rejectLabel?: string;  // Label do botão de cancelar (opcional)
+  reject?: VoidFunction; // Callback ao cancelar ou fechar (opcional)
+}
+```
+
+### ConfirmDialogService
+
+| Método | Parâmetros | Descrição |
+|--------|-----------|-----------|
+| `confirm` | `confirmDialog: ConfirmDialog` | Abre o diálogo de confirmação modal |
+
+## Exemplos
+
+### Confirmação de exclusão
+
+```typescript
+this.confirmDialogService.confirm({
+  header: 'Remover este item?',
+  message: 'Uma vez removido, o item não poderá ser restaurado.',
+  acceptLabel: 'Remover',
+  rejectLabel: 'Cancelar',
+  accept: () => { this.lastAction = 'Confirmado: item removido'; },
+  reject: () => { this.lastAction = 'Cancelado'; },
+});
+```
+
+### Alerta sem botão de cancelar
+
+```typescript
+this.confirmDialogService.confirm({
+  header: 'Atividade concluída',
+  message: 'Salvamos esta atividade em seu repositório.',
+  acceptLabel: 'Entendi',
+  accept: () => { this.lastAction = 'Usuário confirmou'; },
+});
+```
+
+## Acessibilidade
+
+- O diálogo é aberto em uma janela modal com backdrop que bloqueia interação com o conteúdo de fundo
+- O foco é capturado dentro do diálogo enquanto estiver aberto
+- Fechar via Escape chama o callback `reject` quando definido
+
+## Componentes relacionados
+
+- [`Dialog`](../dialog/README.md) — quando precisar de formulários ou conteúdo customizado na modal
+- [`Alert`](../alert/README.md) — para mensagens de feedback inline sem confirmação

package/content-generator/README.md

@@ -0,0 +1,111 @@
+# ContentGenerator
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de área de texto com geração de conteúdo por inteligência artificial integrada. Permite ao usuário digitar livremente ou solicitar geração de texto via IA através de um diálogo de contexto, com suporte opcional a reconhecimento de voz.
+
+## Quando usar
+
+- Campos de texto longos onde a IA pode auxiliar na redação (descrições, observações, resumos)
+- Formulários com campos de conteúdo aberto onde a geração assistida melhora a produtividade
+- Campos com contexto específico onde um `prompt` customizado direciona a IA
+
+## Quando não usar
+
+- Campos de texto simples sem necessidade de IA — use [`TextArea`](../text-area/README.md)
+- Campos de entrada curtos (nome, código) — use um input simples
+- O seletor `s-text-area-ia` está descontinuado (remoção na v20.0.0) — use `s-content-generator`
+
+## Instalação
+
+```typescript
+import { ContentGeneratorModule } from '@seniorsistemas/angular-components/content-generator';
+
+@Component({ standalone: true, imports: [ContentGeneratorModule] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-content-generator
+  formControlName="descricao"
+  label="Descrição"
+  [rows]="6"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | — | — | Label exibido acima da área de texto |
+| `placeholder` | `string` | `''` | — | Texto de placeholder quando a área está vazia |
+| `prompt` | `string` | — | — | Instrução enviada à IA para direcionar o conteúdo gerado |
+| `rows` | `number` | `10` | — | Número de linhas visíveis da área de texto |
+| `cols` | `number` | `10` | — | Número de colunas da área de texto |
+| `readonly` | `boolean` | `false` | — | Torna a área de texto somente leitura |
+| `speechRecognition` | `boolean` | `false` | — | Habilita o botão de reconhecimento de voz |
+| `keepContext` | `boolean` | `false` | — | Mantém o contexto do diálogo de IA entre aberturas |
+| `speechRecognitionPlaceholder` | `string` | `''` | — | Placeholder exibido durante o reconhecimento de voz |
+| `maxLength` | `number \| null` | `null` | — | Limite máximo de caracteres (`null` = sem limite) |
+| `id` | `string` | `ContentGenerator_{n}` | — | Identificador único do componente no DOM |
+| `textAreaStyle` | `Partial<CSSStyleDeclaration>` | `{}` | — | Estilos CSS inline aplicados à área de texto interna |
+
+## Exemplos
+
+### Com prompt customizado
+
+```html
+<form [formGroup]="form">
+  <s-content-generator
+    formControlName="descricao"
+    label="Descrição do produto"
+    placeholder="Descreva o produto ou use a IA para gerar..."
+    [rows]="6"
+    prompt="Gere uma descrição focada em benefícios para o cliente, em tom profissional."
+  ></s-content-generator>
+</form>
+```
+
+### Com reconhecimento de voz
+
+```html
+<form [formGroup]="form">
+  <s-content-generator
+    formControlName="observacoes"
+    label="Observações"
+    placeholder="Digite ou dite suas observações..."
+    [rows]="5"
+    [speechRecognition]="true"
+    speechRecognitionPlaceholder="Ouvindo... fale agora"
+  ></s-content-generator>
+</form>
+```
+
+### Com limite de caracteres
+
+```html
+<form [formGroup]="form">
+  <s-content-generator
+    formControlName="resumo"
+    label="Resumo executivo"
+    placeholder="Máximo de 500 caracteres..."
+    [maxLength]="500"
+    [rows]="5"
+  ></s-content-generator>
+</form>
+```
+
+## Acessibilidade
+
+- Implementa `ControlValueAccessor` — compatível com `formControlName`, `formControl` e `ngModel`
+- O botão de IA e o botão de voz possuem labels acessíveis
+- O diálogo de contexto da IA é navegável por teclado
+
+## Componentes relacionados
+
+- [`TextArea`](../text-area/README.md) — área de texto simples sem IA
+- [`SpeechRecognition`](../speech-recognition/README.md) — reconhecimento de voz standalone

package/control-errors/README.md

@@ -0,0 +1,92 @@
+# ControlErrors
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente que exibe as mensagens de erro de validação associadas a um controle de formulário. Observa as mudanças de estado do controle e renderiza as mensagens mapeadas quando o campo está `dirty` e inválido.
+
+## Quando usar
+
+- Exibir mensagens de erro de validação abaixo de campos de formulário de forma padronizada
+- Substituir lógica manual de `*ngIf` para erros por um padrão consistente
+- Campos com múltiplas regras de validação simultâneas
+
+## Quando não usar
+
+- Mensagens de erro globais de formulário — use um componente de alerta
+- Validações assíncronas que retornam mensagens da API — adapte usando o mapa `errorMessages`
+
+## Instalação
+
+```typescript
+import { ControlErrorsModule } from '@seniorsistemas/angular-components/control-errors';
+
+@Component({ standalone: true, imports: [ControlErrorsModule] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<input type="email" formControlName="email" />
+<s-control-errors
+  [control]="form.get('email')"
+  [errorMessages]="{ required: 'E-mail obrigatório', email: 'E-mail inválido' }"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `control` | `AbstractControl \| NgModel` | — | Sim | Controle do formulário cujos erros serão exibidos |
+| `errorMessages` | `Record<string, string>` | `{}` | — | Mapa de chave de erro para mensagem de texto |
+| `id` | `string` | `s-control-errors-{n}` | — | Identificador único do componente |
+| `form` | `any` | — | — | Referência ao formulário pai para validações customizadas |
+
+## Exemplos
+
+### Campo de e-mail com validação
+
+```html
+<form [formGroup]="form">
+  <label>E-mail *</label>
+  <input type="email" formControlName="email" (blur)="form.get('email')?.markAsDirty()" />
+  <s-control-errors
+    [control]="form.get('email')"
+    [errorMessages]="{ required: 'E-mail é obrigatório.', email: 'Informe um e-mail válido.' }"
+  ></s-control-errors>
+</form>
+```
+
+### Campo de senha com múltiplas regras
+
+```html
+<s-control-errors
+  [control]="form.get('password')"
+  [errorMessages]="{
+    required: 'Senha é obrigatória.',
+    minlength: 'A senha deve ter no mínimo 8 caracteres.',
+    pattern: 'A senha deve conter ao menos uma letra maiúscula e um número.'
+  }"
+></s-control-errors>
+```
+
+### Formulário com submissão e marcação de campos
+
+```typescript
+onSubmit() {
+  Object.values(this.form.controls).forEach(c => c.markAsDirty());
+  this.form.updateValueAndValidity();
+}
+```
+
+## Acessibilidade
+
+- As mensagens de erro são renderizadas no DOM com IDs únicos para possível associação via `aria-describedby`
+- As mensagens só aparecem após interação do usuário (`dirty`), evitando erros prematuros ao carregar a página
+
+## Componentes relacionados
+
+- [`Alert`](../alert/README.md) — mensagens de feedback inline não vinculadas a um controle

package/country-phone-picker/README.md

@@ -0,0 +1,121 @@
+# CountryPhonePicker
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de seleção de país com DDI e campo de telefone com máscara dinâmica. Exibe uma lista de países com bandeiras, aplica automaticamente a máscara de formatação conforme o país selecionado e emite os dados via Angular Forms.
+
+## Quando usar
+
+- Formulários internacionais que aceitam números de telefone de diferentes países
+- Cadastros onde o DDI precisa ser capturado junto ao número
+- Formulários regionalizados onde apenas um subconjunto de países é relevante
+
+## Quando não usar
+
+- Formulários exclusivamente nacionais sem necessidade de seleção de país — use um campo de texto com máscara
+- Quando o DDI é fixo e não precisa ser selecionado pelo usuário
+
+## Instalação
+
+```typescript
+import { CountryPhonePickerModule } from '@seniorsistemas/angular-components/country-phone-picker';
+
+@Component({ standalone: true, imports: [CountryPhonePickerModule] })
+export class MeuComponent {}
+```
+
+> **Atenção:** É necessário adicionar os estilos de bandeiras no `angular.json`:
+> ```json
+> "styles": ["node_modules/flag-icons/css/flag-icons.min.css"]
+> ```
+
+## Uso básico
+
+```html
+<s-country-phone-picker formControlName="telefone" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `countries` | `string[]` | `[]` | — | Lista de códigos ISO 3166-1 alpha-2 exibidos no dropdown. Vazio = todos os países |
+| `ordination` | `Ordination` | `Ordination.NO` | — | Critério de ordenação da lista de países |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `selected` | `EventEmitter<CountryPhoneData>` | Emitido ao selecionar um país no dropdown |
+| `focusLost` | `EventEmitter<PhoneSelectionData \| null>` | Emitido quando o campo de telefone perde o foco |
+
+### Tipos
+
+```typescript
+enum Ordination {
+  NO = 'no',   // Sem ordenação (ordem padrão)
+  AZ = 'az',   // Ordem alfabética A-Z
+  ZA = 'za',   // Ordem alfabética Z-A
+}
+
+interface CountryPhoneData {
+  id: string;              // Código ISO do país (ex: 'br')
+  ddi: string;             // Código DDI (ex: '+55')
+  mask: string | string[]; // Máscara(s) de formatação
+}
+
+interface PhoneSelectionData {
+  id: string;       // Código ISO do país selecionado
+  ddi: string;      // Código DDI
+  value: string;    // Número formatado com máscara
+  rawValue: string; // Número sem formatação
+}
+```
+
+## Exemplos
+
+### Lista filtrada para países específicos
+
+```html
+<s-country-phone-picker
+  formControlName="telefone"
+  [countries]="['br', 'us', 'ar', 'co', 'py', 'uy', 'cl', 'pe']"
+  (selected)="onPaisSelecionado($event)"
+  (focusLost)="onFocusLost($event)"
+></s-country-phone-picker>
+```
+
+### Lista ordenada alfabeticamente
+
+```html
+<s-country-phone-picker
+  formControlName="telefone"
+  [ordination]="'az'"
+></s-country-phone-picker>
+```
+
+### Reagindo à seleção de país
+
+```typescript
+onPaisSelecionado(country: CountryPhoneData) {
+  console.log('País selecionado:', country.id, 'DDI:', country.ddi);
+}
+
+onFocusLost(data: PhoneSelectionData | null) {
+  if (data) {
+    console.log('Número formatado:', data.value);
+  }
+}
+```
+
+## Acessibilidade
+
+- Navegação por teclado no dropdown: `Enter`/`Espaço` abre/confirma, `Escape` fecha, `ArrowUp`/`ArrowDown` navega entre países
+- O dropdown fecha ao clicar fora do componente
+- Implementa `ControlValueAccessor` — compatível com `formControlName`, `formControl` e `ngModel`
+
+## Componentes relacionados
+
+- [`Mask`](../mask/README.md) — diretiva de máscara aplicada internamente ao campo de telefone

package/currency/README.md

@@ -0,0 +1,90 @@
+# Currency
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Serviço para obter o símbolo de uma moeda formatado de acordo com o locale ativo da aplicação, utilizando a API nativa `Intl.NumberFormat` do browser.
+
+## Quando usar
+
+- Exibir o símbolo da moeda dinamicamente ao lado de valores monetários
+- Construir campos de entrada com prefixo de moeda que se adapta ao locale do usuário
+- Obter o símbolo compacto (ex: `R$`, `$`, `€`) para exibição em interfaces
+
+## Quando não usar
+
+- Formatação completa de valores monetários — use o `CurrencyPipe` do Angular ou o pipe `Numeric` da biblioteca
+- Validação de entradas monetárias — use validators de formulário
+
+## Instalação
+
+```typescript
+import { CurrencyService } from '@seniorsistemas/angular-components/currency';
+
+@Component({ standalone: true })
+export class MeuComponent {
+  private readonly currencyService = inject(CurrencyService);
+}
+```
+
+O serviço é `providedIn: 'root'` e não requer módulo adicional. Requer que `LocaleModule.forRoot()` esteja configurado na aplicação.
+
+## Uso básico
+
+```typescript
+const symbol = this.currencyService.getCurrencySymbol({ currency: 'BRL' }); // 'R$'
+const symbol = this.currencyService.getCurrencySymbol({ currency: 'USD' }); // 'US$' ou '$'
+const symbol = this.currencyService.getCurrencySymbol({ currency: 'EUR' }); // '€'
+```
+
+## API
+
+### CurrencyService
+
+| Método | Parâmetros | Retorno | Descrição |
+|--------|-----------|---------|-----------|
+| `getCurrencySymbol` | `{ currency: Currency }` | `string` | Retorna o símbolo da moeda formatado para o locale ativo |
+
+### Tipos
+
+```typescript
+// Currency é um union type de todos os códigos ISO 4217 suportados
+type Currency = 'BRL' | 'USD' | 'EUR' | 'GBP' | 'JPY' | 'ARS' | 'CLP' | 'MXN' | /* ... */;
+```
+
+## Exemplos
+
+### Exibindo símbolo em um campo de entrada
+
+```typescript
+@Component({
+  template: `
+    <div class="input-group">
+      <span class="prefix">{{ currencySymbol }}</span>
+      <input type="number" formControlName="valor" />
+    </div>
+  `
+})
+export class ValorComponent {
+  private readonly currencyService = inject(CurrencyService);
+  readonly currencySymbol = this.currencyService.getCurrencySymbol({ currency: 'BRL' });
+}
+```
+
+### Múltiplas moedas
+
+```typescript
+const moedas: Currency[] = ['BRL', 'USD', 'EUR', 'GBP', 'JPY'];
+const simbolos = moedas.map(code => ({
+  code,
+  symbol: this.currencyService.getCurrencySymbol({ currency: code }),
+}));
+// [{ code: 'BRL', symbol: 'R$' }, { code: 'USD', symbol: 'US$' }, ...]
+```
+
+## Acessibilidade
+
+- O símbolo retornado é uma string de texto simples, compatível com leitores de tela quando usado em elementos HTML com contexto adequado
+
+## Componentes relacionados
+
+- [`Locale`](../locale/README.md) — serviço de localização que define o locale usado na formatação

package/custom-fields/README.md

@@ -0,0 +1,142 @@
+# CustomFields
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente que carrega e renderiza campos customizados dinamicamente a partir da API de customização de campos da plataforma Senior. Realiza chamadas HTTP para obter a configuração dos campos, gera o formulário reativamente e implementa `ControlValueAccessor` e `Validator` para integração completa com formulários Angular.
+
+## Quando usar
+
+- Telas que precisam exibir campos customizados configurados pelo cliente na plataforma Senior
+- Formulários de entidades que suportam extensão via campo customizável
+- Quando os campos são definidos dinamicamente em runtime via API
+
+## Quando não usar
+
+- Formulários com campos fixos conhecidos em tempo de compilação — use [`DynamicForm`](../dynamic-form/README.md) diretamente
+- Ambientes sem conexão com a API da plataforma Senior — o componente depende de autenticação e endpoints externos
+
+## Instalação
+
+```typescript
+import { CustomFieldsModule } from '@seniorsistemas/angular-components/custom-fields';
+
+@Component({ standalone: true, imports: [CustomFieldsModule] })
+export class MeuComponent {}
+```
+
+Requer `LocaleModule.forRoot()` e `TranslateModule.forRoot()` configurados na aplicação.
+
+## Uso básico
+
+```html
+<form [formGroup]="form">
+  <s-custom-fields
+    formControlName="camposCustomizados"
+    domain="plataforma"
+    service="servico"
+    entity="entidade"
+  />
+</form>
+```
+
+```typescript
+this.form = new FormGroup({
+  camposCustomizados: new FormControl(null),
+});
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `domain` | `string` | — | Sim | Domínio para buscar os campos na API |
+| `service` | `string` | — | Sim | Nome do serviço para identificar os campos |
+| `entity` | `string` | — | Sim | Nome da entidade para a qual os campos são carregados |
+| `entityObject` | `CustomFieldsResponse` | — | — | Dados pré-carregados para evitar chamada extra à API |
+| `invalidErrorLabel` | `string` | `''` | — | Mensagem de erro para campos com valor inválido |
+| `customFieldsEndpoint` | `string` | `'platform/field_customization/queries/getEntity'` | — | Endpoint para buscar a configuração dos campos |
+| `fileLocationEndpoint` | `string` | `'platform/field_customization/actions/requestUpload'` | — | Endpoint para upload de arquivos em campos blob |
+| `requestAccessEndpoint` | `string` | `'platform/field_customization/actions/requestAccess'` | — | Endpoint para acesso a arquivos já enviados |
+| `requiredErrorMessage` | `string` | `''` | — | Mensagem de erro para campos obrigatórios não preenchidos |
+| `displayTimeInfoSign` | `number` | `0` | — | Tempo em ms após o qual o info-sign de campos data é exibido |
+| `showFileUploadDate` | `boolean` | `false` | — | Exibe data de upload nos campos do tipo arquivo |
+| `ready$` | `BehaviorSubject<boolean> \| null` | `null` | — | Observable que sinaliza quando iniciar o carregamento dos campos |
+| `disableFields` | `boolean` | — | — | Quando `true`, todos os campos são desabilitados |
+
+### Tipos
+
+```typescript
+enum CustomFieldType {
+  String = 'String',
+  Boolean = 'Boolean',
+  Integer = 'Integer',
+  Double = 'Double',
+  Date = 'Date',
+  DateTime = 'DateTime',
+  LocalDateTime = 'LocalDateTime',
+  Time = 'Time',
+  Money = 'Money',
+  Blob = 'Blob',
+  Binary = 'Binary',
+  Any = 'Any',
+  Enum = 'Enum',
+}
+
+interface CustomFieldsResponse {
+  entity_: {
+    active: boolean;
+    fields: FieldFromAPI[];
+  };
+}
+```
+
+## Exemplos
+
+### Uso básico com formulário reativo
+
+```html
+<form [formGroup]="form">
+  <s-custom-fields
+    formControlName="camposCustomizados"
+    domain="plataforma"
+    service="servico"
+    entity="entidade"
+    requiredErrorMessage="Campo obrigatório"
+  />
+</form>
+```
+
+### Com dados pré-carregados
+
+```html
+<s-custom-fields
+  formControlName="camposCustomizados"
+  domain="plataforma"
+  service="servico"
+  entity="entidade"
+  [entityObject]="dadosPreCarregados"
+/>
+```
+
+### Desabilitando campos
+
+```html
+<s-custom-fields
+  formControlName="camposCustomizados"
+  domain="plataforma"
+  service="servico"
+  entity="entidade"
+  [disableFields]="modoSomenteLeitura"
+/>
+```
+
+## Acessibilidade
+
+- Os campos renderizados são os mesmos do `DynamicForm`, que segue as práticas de acessibilidade dos componentes internos
+- Labels e tooltips dos campos são configurados via API de customização da plataforma
+
+## Componentes relacionados
+
+- [`DynamicForm`](../dynamic-form/README.md) — formulário dinâmico base usado internamente