@seniorsistemas/angular-components 19.0.4 → 19.0.6

package/dynamic-form/dynamic-form/form-field/configurations/fields/button-field.d.ts

@@ -1,11 +1,34 @@
 import { ButtonComponent } from '@seniorsistemas/angular-components/button';
 import { FieldConfig } from './field';
 type ExtractedButtonProperties = Partial<Pick<ButtonComponent, 'priority' | 'iconClass' | 'disabled' | 'auxiliary' | 'caret' | 'iconColor' | 'badge' | 'animation' | 'slide' | 'menuOptions' | 'baseZIndex' | 'styleClass' | 'rightIconClass' | 'tooltipPosition' | 'size' | 'type'>>;
+/**
+ * Configuração para campo do tipo botão dentro do DynamicForm.
+ *
+ * Renderiza um botão (`s-button`) diretamente como um campo do formulário.
+ * Útil para ações contextuais associadas ao formulário, como buscar dados, limpar campos
+ * ou acionar funcionalidades sem submeter o formulário.
+ *
+ * As propriedades visuais e comportamentais (priority, iconClass, menuOptions, etc.)
+ * são herdadas diretamente de `ButtonComponent`.
+ */
 export interface ButtonFieldConfig extends FieldConfig, ExtractedButtonProperties {
+    /** Tipo do campo: sempre `'button'`. */
     type: 'button';
+    /**
+     * Callback chamado quando o botão é clicado.
+     */
     onClick?: (event?: any) => any;
+    /**
+     * Quando `true`, o botão ocupa toda a largura da célula/coluna do formulário.
+     */
     fullWidth?: boolean;
+    /**
+     * Callback chamado quando o mouse entra na área do botão.
+     */
     mouseEnter?: (button: ButtonFieldConfig) => void;
+    /**
+     * Callback chamado quando o mouse sai da área do botão.
+     */
     mouseLeave?: (button: ButtonFieldConfig) => void;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/calendar-field.d.ts

@@ -1,25 +1,91 @@
 import { CalendarLocaleOptions } from '@seniorsistemas/angular-components/locale';
 import { FieldConfig } from './field';
+/**
+ * Configuração para campos de data e hora.
+ *
+ * Quatro variantes disponíveis:
+ * - `'date'` — apenas data (dia/mês/ano)
+ * - `'time'` — apenas hora (hora:minuto[:segundo])
+ * - `'dateTime'` — data com horário com timezone (UTC)
+ * - `'localDateTime'` — data com horário sem timezone (local da máquina)
+ *
+ * Suporta restrições de intervalo, modo de visualização (dia/mês/ano), seleção múltipla
+ * e localização de labels do calendário.
+ */
 export interface CalendarFieldConfig extends FieldConfig {
+    /**
+     * `'date'` — campo de data apenas.
+     * `'time'` — campo de hora apenas.
+     * `'dateTime'` — data e hora com timezone UTC.
+     * `'localDateTime'` — data e hora sem timezone (local).
+     */
     type: 'dateTime' | 'localDateTime' | 'time' | 'date';
+    /**
+     * Modo de visualização inicial do calendário.
+     * `'date'` — grade de dias (padrão).
+     * `'month'` — selector de mês.
+     * `'year'` — seletor de ano.
+     */
     view?: 'date' | 'month' | 'year';
+    /**
+     * Data mínima selecionável. Datas anteriores serão desabilitadas no calendário.
+     */
     minDate?: Date;
+    /**
+     * Data máxima selecionável. Datas posteriores serão desabilitadas no calendário.
+     */
     maxDate?: Date;
+    /**
+     * Data exibida inicialmente ao abrir o calendário quando nenhuma data está selecionada.
+     */
     defaultDate?: Date;
+    /**
+     * Elemento DOM ao qual o painel do calendário será anexado.
+     * Use `'body'` para evitar problemas de overflow em containers com `overflow: hidden`.
+     */
     appendTo?: string;
+    /**
+     * Quando `true`, o calendário abre automaticamente ao focar o campo.
+     * @default true
+     */
     showOnFocus?: boolean;
+    /**
+     * Opções de localização do calendário (nomes de dias da semana, meses, etc.).
+     * Se omitido, usa o locale padrão da aplicação.
+     */
     calendarLocaleOptions?: CalendarLocaleOptions;
+    /** Callback chamado quando o campo perde o foco. */
     onBlur?: (event: Event) => void;
+    /** Callback chamado quando o campo recebe foco. */
     onFocus?: (event: Event) => void;
+    /** Callback chamado quando o usuário seleciona uma data. */
     onSelect?: (event: any) => void;
+    /** Callback chamado quando o usuário digita manualmente no campo. */
     onInput?: (event: any) => void;
+    /** Callback chamado quando o painel do calendário é fechado. */
     onClose?: (event: any) => void;
+    /** Callback chamado quando o usuário clica no botão "Hoje". */
     onTodayClick?: (event: any) => void;
+    /** Callback chamado quando o usuário clica no botão "Limpar". */
     onClearClick?: (event: any) => void;
+    /** Callback chamado quando o mês visualizado muda. */
     onMonthChange?: (event: any) => void;
+    /** Callback chamado quando o ano visualizado muda. */
     onYearChange?: (event: any) => void;
+    /**
+     * Modo de seleção de datas.
+     * `'single'` — seleção de uma data (padrão).
+     * `'multiple'` — seleção de múltiplas datas incompatíveis.
+     */
     selectionMode?: 'single' | 'multiple';
+    /**
+     * Separador exibido entre as datas de início e fim quando `selectionMode = 'range'`.
+     * @default ' - '
+     */
     rangeSeparator?: string;
+    /**
+     * Quando `true`, exibe o seletor de segundos no modo de hora.
+     */
     showSeconds?: boolean;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/checkbox-field.d.ts

@@ -1,7 +1,22 @@
 import { CheckboxListData } from '@seniorsistemas/angular-components/checkbox-list';
 import { FieldConfig } from './field';
+/**
+ * Configuração para campo de múltipla escolha com checkboxes.
+ *
+ * Renderiza uma lista de checkboxes com suporte a agrupamento hierárquico via `CheckboxListData`.
+ * O valor do campo será um array com os valores dos itens selecionados.
+ *
+ * Use quando o usuário pode selecionar zero ou mais opções de uma lista finita.
+ * Para seleção única, prefira `type: 'radioButton'` ou `type: 'enum'`.
+ */
 export interface CheckboxFieldConfig extends FieldConfig {
+    /** Tipo do campo: sempre `'checkbox'`. */
     type: 'checkbox';
+    /**
+     * Dados que definem os itens e a estrutura hierárquica dos checkboxes.
+     * Importado de `@seniorsistemas/angular-components/checkbox-list`.
+     * Cada item possui `label`, `value` e opcionalmente `children` com sub-itens.
+     */
     data: CheckboxListData;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/chips-field.d.ts

@@ -1,14 +1,44 @@
 import { FieldConfig } from './field';
+/**
+ * Configuração para campo de entrada de múltiplas tags (chips).
+ *
+ * Permite que o usuário insira vários valores de texto livres, visualizados como chips/tags.
+ * Cada valor é adicionado ao pressionar Enter (ou o separador configurado).
+ * O valor do campo é um array de strings.
+ *
+ * Use para e-mails, palavras-chave, códigos ou qualquer lista de valores livres.
+ */
 export interface ChipsFieldConfig extends FieldConfig {
+    /** Tipo do campo: sempre `'chips'`. */
     type: 'chips';
+    /**
+     * Expressão regular que filtra os caracteres aceitos em cada chip.
+     * @example /[a-zA-Z0-9]/ para aceitar apenas alfanuméricos
+     */
     keyFilter?: RegExp;
+    /**
+     * Caractere separador para adicionar novos chips além do Enter.
+     * @example ',' para adicionar chip ao digitar vírgula
+     */
     separator?: string;
+    /**
+     * Quando `true`, exibe um botão de copiar todos os chips para a área de transferência.
+     */
     showCopyButton?: boolean;
+    /** Callback chamado quando um novo chip é adicionado. */
     onAdd?: (event: any) => void;
+    /** Callback chamado quando um chip é removido. */
     onRemove?: (event: any) => void;
+    /** Callback chamado quando o usuário clica em um chip existente. */
     onChipClick?: (event: any) => void;
+    /** Callback chamado quando o campo recebe foco. */
     onFocus?: (event: any) => void;
+    /** Callback chamado quando o campo perde o foco. */
     onBlur?: (event: any) => void;
+    /**
+     * Callback chamado quando o usuário copia o conteúdo dos chips.
+     * Recebe o texto combinado de todos os chips.
+     */
     onCopy?: (content: string) => void;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/content-generator-field.d.ts

@@ -1,19 +1,64 @@
 import { FieldConfig } from './field';
+/**
+ * Configuração para campo de área de texto com geração de conteúdo via IA.
+ *
+ * Combina um textarea completo com recursos de:
+ * - Geração automática de texto por IA via prompt
+ * - Reconhecimento de voz (speech-to-text)
+ * - Contexto persistente entre gerações (`keepContext`)
+ *
+ * Use `type: 'contentGenerator'` para novas implementações.
+ * O tipo `'textAreaIA'` está depreciado e será removido na v20.
+ */
 export interface ContentGeneratorFieldConfig extends FieldConfig {
     /**
-     * @deprecated O tipo 'textAreaIA' será removido na versão v20.
-     * Utilize 'contentGenerator' em seu lugar.
+     * `'contentGenerator'` — tipo atual recomendado.
+     * `'textAreaIA'` — **@deprecated** Será removido na v20, use `'contentGenerator'`.
      */
     type: 'contentGenerator' | 'textAreaIA';
+    /**
+     * Número de colunas de texto do textarea.
+     */
     cols?: number;
+    /**
+     * Número de linhas visíveis do textarea.
+     */
     rows?: number;
+    /**
+     * Filtro de teclas aceitas. Aceita regex ou string.
+     */
     keyFilter?: any;
+    /**
+     * Estilos CSS inline aplicados diretamente no elemento textarea.
+     */
     style?: Partial<CSSStyleDeclaration>;
+    /**
+     * Prompt inicial enviado à IA para gerar conteúdo.
+     * Define a instrução base para o assistente de geração de texto.
+     * @example 'Gere um e-mail formal de boas-vindas para o cliente'
+     */
     prompt?: string;
+    /**
+     * Função que retorna `true` quando o campo deve estar em modo somente-leitura.
+     */
     readonly?: () => boolean;
+    /**
+     * Quando `true`, ativa o botão de reconhecimento de voz (speech-to-text).
+     * O conteúdo falado é convertido em texto e inserido no campo.
+     */
     speechRecognition?: boolean;
+    /**
+     * Quando `true`, o contexto das gerações anteriores é mantido ao gerar novo conteúdo.
+     * Permite que a IA considere o histórico da conversa na próxima geração.
+     */
     keepContext: boolean;
+    /**
+     * Texto de placeholder exibido na área de reconhecimento de voz enquanto o microfone está ativo.
+     */
     speechRecognitionPlaceholder: string;
+    /**
+     * Número máximo de caracteres permitidos no campo.
+     */
     maxLength?: number;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/country-phone-picker-field.d.ts

@@ -1,10 +1,36 @@
 import { CountryPhoneData, Ordination, PhoneSelectionData } from '@seniorsistemas/angular-components/country-phone-picker';
 import { FieldConfig } from './field';
+/**
+ * Configuração para campo de seleção de país com entrada de número de telefone.
+ *
+ * Combina um dropdown de seleção de país (com bandeira e código DDI) com um campo de telefone
+ * que aplica automaticamente a máscara de cada país selecionado.
+ *
+ * O valor do campo é do tipo `PhoneSelectionData`, contendo o país e o número.
+ */
 export interface CountryPhonePickerConfig extends FieldConfig {
+    /** Tipo do campo: sempre `'countryPhonePicker'`. */
     type: 'countryPhonePicker';
+    /**
+     * Lista de códigos de países disponíveis no dropdown.
+     * Use códigos ISO 3166-1 alpha-2 em maiúsculas.
+     * @example ['BR', 'US', 'AR', 'DE']
+     */
     countries: string[];
+    /**
+     * Critério de ordenação dos países no dropdown.
+     * Importado de `@seniorsistemas/angular-components/country-phone-picker`.
+     */
     ordination: Ordination;
+    /**
+     * Callback obrigatório chamado quando o país é selecionado.
+     * Recebe os dados do país escolhido (nome, DDI, código).
+     */
     onSelected: (data: CountryPhoneData) => void;
+    /**
+     * Callback chamado quando o campo de telefone perde o foco.
+     * Recebe os dados completos da seleção (país + número), ou `null` se vazio.
+     */
     onFocusLost?: (data: PhoneSelectionData | null) => void;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/currency-field.d.ts

@@ -1,11 +1,28 @@
 import { Currency } from '@seniorsistemas/angular-components/currency';
 import { NumberFieldConfig } from './number-field';
 /**
- * @deprecated should use BigNumberField instead
+ * Configuração para campo monetário com símbolo de moeda.
+ *
+ * @deprecated Use `BignumberFieldConfig` com `type: 'number'` ou `'double'` em combinação com
+ * `leftAddon` ou `rightAddon` para exibir o símbolo monetário. Esta interface será removida
+ * em versão futura.
+ *
+ * Estende `NumberFieldConfig` omitindo `alignTo`, `leftAddon` e `rightAddon`.
  */
 export interface CurrencyFieldConfig extends Omit<NumberFieldConfig, 'type' | 'alignTo' | 'leftAddon' | 'rightAddon'> {
+    /** Tipo do campo: sempre `'money'`. */
     type: 'money';
+    /**
+     * Alinhamento do texto dentro do campo.
+     * `'left'` — alinhado à esquerda.
+     * `'right'` — alinhado à direita (comum em campos monetários).
+     */
     alignTo?: 'left' | 'right';
+    /**
+     * Função que retorna o objeto de moeda a ser exibido junto ao valor.
+     * Inclui símbolo, código e formatação.
+     * @example () => ({ symbol: 'R$', code: 'BRL' })
+     */
     currency?: () => Currency;
 }
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/field.d.ts

@@ -1,13 +1,57 @@
+/**
+ * Configuração base compartilhada por **todos** os tipos de campo do DynamicForm.
+ *
+ * Toda interface específica de campo (ex: TextFieldConfig, SelectFieldConfig) estende esta interface.
+ * As propriedades aqui definidas estão disponíveis em qualquer campo do formulário.
+ */
 export interface FieldConfig {
+    /**
+     * Tipo do campo. Deve ser um dos valores registrados em `FieldTypeMap`.
+     * Exemplos: `'string'`, `'enum'`, `'date'`, `'lookup'`, `'boolean'`, etc.
+     * Para tipos opcionais (ex: `'editor'`), o provider correspondente deve ser registrado no `AppConfig` ou `AppModule`.
+     */
     type: FieldType;
+    /**
+     * Função que retorna se o campo é obrigatório dinamicamente.
+     * Use uma função para que a obrigatoriedade possa mudar em resposta ao estado do formulário.
+     * @example () => this.model.ativo === true
+     */
     required?: () => boolean;
+    /**
+     * ID HTML do elemento de input gerado. Útil para testes automatizados e acessibilidade.
+     */
     id?: string;
+    /**
+     * Nome do campo no modelo de dados. Deve corresponder à chave da propriedade no objeto de dados do formulário.
+     * @example 'nomeCompleto'
+     */
     name: string;
+    /**
+     * Rótulo exibido acima ou ao lado do campo no formulário.
+     * Se omitido, o campo é exibido sem label.
+     */
     label?: string;
+    /**
+     * Ícone de informação exibido ao lado do campo. Aceita classes de ícone (ex: `'ph ph-info'`).
+     */
     infoSign?: string;
+    /**
+     * Texto do tooltip exibido ao passar o mouse sobre o campo ou sobre o infoSign.
+     */
     tooltip?: string;
+    /**
+     * Texto de placeholder exibido enquanto o campo estiver vazio.
+     */
     placeholder?: string;
+    /**
+     * Tempo em milissegundos para exibir automaticamente o infoSign quando o campo está focado.
+     * Útil para orientar o usuário após um curto intervalo de inatividade.
+     */
     displayTimeInfoSign?: number;
+    /**
+     * Quando `true`, o infoSign usa a referência do input focado como âncora do tooltip.
+     * Útil para garantir que o tooltip apareça próximo ao campo correto em layouts complexos.
+     */
     useInfoSignFocusedInputRef?: boolean;
 }
 export interface FieldTypeMap {

package/dynamic-form/dynamic-form/form-field/configurations/fields/lookup-field.d.ts

@@ -1,53 +1,161 @@
 import { Observable } from 'rxjs';
-import { FieldConfig } from './field';
+import { LookupSearchRequest } from '../../../components/lookup/models/lookup-api.model';
+import { DynamicType, FieldConfig } from './field';
+/**
+ * Dados retornados pelo Observable de pesquisa avançada do Lookup.
+ */
 export interface SearchObservable {
+    /** Array de registros retornados da pesquisa. */
     gridData: any[];
+    /** Número total de registros encontrados (para paginação). */
     totalRecords: number;
+    /** Label customizada para exibir o total de registros encontrados. */
     searchTotalRecordsLabel?: string;
 }
+/**
+ * Configuração para campo de pesquisa avançada (Lookup).
+ *
+ * Exibe um input com autocompletar e botão de pesquisa que abre um diálogo com grid de resultados.
+ * Suporta seleção simples ou múltipla, filtros padrão, ações CRUD na seleção e configuração
+ * dinâmica das colunas da grade.
+ *
+ * Requer dois Observables:
+ * - `suggestionsObservable`: para sugestões no autocompletar
+ * - `searchObservable`: para a grade de resultados do diálogo
+ */
 export interface LookupFieldConfig extends FieldConfig {
+    /** Tipo do campo: sempre `'lookup'`. */
     type: 'lookup';
+    /**
+     * Valor padrão pré-selecionado ao inicializar o formulário.
+     */
     defaultValue?: any;
+    /**
+     * Quando `true`, permite selecionar múltiplos registros exibidos como tags.
+     */
     multiple?: boolean;
+    /**
+     * Quando `true`, exibe o botão de pesquisa avançada que abre o diálogo com a grade.
+     */
     showSearch?: boolean;
-    searchFields: any[];
-    searchGridFields: any[];
+    /**
+     * Colunas de filtro exibidas no diálogo de pesquisa avançada.
+     * Cada item define o campo de filtro disponível para o usuário.
+     */
+    searchFields: DynamicType[];
+    /**
+     * Colunas exibidas na grade de resultados do diálogo de pesquisa.
+     * Cada item define uma coluna com header e campo de dados.
+     */
+    searchGridFields: DynamicType[];
+    /**
+     * Observable que emite sugestões para o autocompletar do input do lookup.
+     * Deve emitir um array de objetos com a propriedade `lookupDisplayField`.
+     */
     suggestionsObservable: Observable<any[]>;
+    /**
+     * Observable que emite os dados da grade do diálogo de pesquisa avançada.
+     * Deve emitir um objeto `SearchObservable` com `gridData` e `totalRecords`.
+     *
+     * Estrutura de `SearchObservable`: `{ gridData: any[]; totalRecords: number; searchTotalRecordsLabel?: string; }`
+     * @typeImport import { SearchObservable } from '@seniorsistemas/angular-components/dynamic-form';
+     */
     searchObservable: Observable<SearchObservable>;
+    /**
+     * Nome da propriedade única do objeto que identifica cada registro.
+     * @example 'id'
+     */
     dataKey: string;
+    /**
+     * Nome da propriedade do objeto de resultado a ser exibida no input e nas tags.
+     * @example 'nome'
+     */
     lookupDisplayField: string;
+    /** Título do diálogo de pesquisa avançada. */
     searchTitle?: string;
+    /** Mensagem exibida quando a pesquisa não retorna resultados. */
     searchEmptyTitle?: string;
+    /** Label do campo de filtro no diálogo. */
     filterLabel?: string;
+    /** Título do campo de filtro no diálogo. */
     filterTitle?: string;
+    /** Label do botão de limpar filtros. */
     clearLabel?: string;
+    /** Label do botão de cancelar e fechar o diálogo. */
     cancelLabel?: string;
+    /** Label do botão de confirmar a seleção no diálogo. */
     selectLabel?: string;
+    /** Mensagem exibida quando nenhum registro é encontrado na grade. */
     emptyMessage?: string;
+    /** Label para um registro (singular). @example 'registro' */
     recordLabel?: string;
+    /** Label para múltiplos registros (plural). @example 'registros' */
     recordsLabel?: string;
+    /** Label exibida quando o campo está vazio e sem seleção. */
     emptyFieldLabel?: string;
+    /**
+     * Elemento DOM ao qual o painel de sugestões será anexado.
+     * Use `'body'` para evitar problemas com `overflow: hidden`.
+     */
     appendTo?: string;
+    /**
+     * Quando `true`, o usuário só pode selecionar valores da lista de sugestões;
+     * texto livre é descartado ao perder o foco.
+     */
     autocompleteForceSelection?: boolean;
     maxlength?: number | null;
     showAddOption?: boolean;
+    /** Quando `true`, exibe o botão de editar o registro selecionado. */
     showEditOption?: boolean;
+    /** Quando `true`, exibe o botão de remover registros selecionados. */
     showRemoveOption?: boolean;
+    /**
+     * Lista de colunas que não podem ser ordenadas na grade do diálogo.
+     * @example ['descricao', 'createdAt']
+     */
     sortableColumnsDisabled?: string[];
+    /**
+     * Filtros padrão aplicados automaticamente à pesquisa.
+     * Cada item define um campo e um valor fixo ou dinâmico (função).
+     *
+     * Estrutura de `DefaultFilter`: `{ field: string; value: string | (() => string); }`
+     * @typeImport import { DefaultFilter } from '@seniorsistemas/angular-components/dynamic-form';
+     */
     defaultFilter?: DefaultFilter[];
+    /**
+     * Callback chamado quando o usuário digita para buscar sugestões.
+     * Deve atualizar o `suggestionsObservable` com os resultados da busca.
+     */
     onLookupRequest: (query: string) => void;
-    onSearchRequest: (event: any) => void;
+    /**
+     * Callback chamado quando o usuário realiza uma pesquisa no diálogo avançado.
+     * Deve atualizar o `searchObservable` com os resultados paginados.
+     *
+     * Estrutura de `LookupSearchRequest`: `{ filterData: Record<string, any>; first: number; rows: number; }`
+     * @typeImport import { LookupSearchRequest } from '@seniorsistemas/angular-components/dynamic-form';
+     */
+    onSearchRequest: (event: LookupSearchRequest) => void;
+    /** Callback chamado quando o usuário seleciona um registro. */
     onSelect?: (event: any) => void;
+    /** Callback chamado quando o usuário remove um registro selecionado (modo múltiplo). */
     onUnselect?: (event: any) => void;
+    /** Callback chamado quando o usuário limpa todos os registros selecionados. */
     onClear?: (event: any) => void;
+    /** Callback chamado quando o campo perde o foco. */
     onBlur?: (event: FocusEvent) => void;
+    /** Callback chamado quando o usuário clica no botão de adicionar novo registro. */
     onAdd?: () => void;
+    /** Callback chamado quando o usuário clica no botão de editar. Recebe o item selecionado. */
     onEdit?: (selectedItem: unknown) => void;
+    /** Callback chamado quando o usuário clica no botão de remover. Recebe os itens selecionados. */
     onRemove?: (selectedItems: unknown[]) => void;
+    /** Callback chamado quando o usuário clica no botão de limpar do campo (X). */
     onClearButtonClick?: () => void;
 }
 export type DefaultFilter = {
+    /** Nome do campo a ser filtrado. */
     field: string;
+    /** Valor do filtro. Pode ser uma string estática ou função que retorna o valor dinamicamente. */
     value: string | (() => string);
 };
 declare module './field' {

package/dynamic-form/dynamic-form/form-field/configurations/fields/number-field.d.ts

@@ -4,25 +4,64 @@ import { AddonConfig } from '../../addon-config';
 import { FieldConfig } from './field';
 type stringFn = () => string | string;
 /**
- * @deprecated Should use BignumberFieldConfig instead
+ * Configuração para campos numéricos inteiros ou de número legado.
+ *
+ * @deprecated Use `BignumberFieldConfig` com `type: 'number'` ou `'double'` para novas
+ * implementações. Esta interface está mantida por compatibilidade retro-ativa.
+ *
+ * - `'integer'` — campo de número inteiro.
+ * - `'legacyNumber'` — campo numérico legado (comportamento antigo).
  */
 export interface NumberFieldConfig extends FieldConfig {
+    /**
+     * `'integer'` — campo numérico inteiro.
+     * `'legacyNumber'` — campo numérico legado.
+     */
     type: 'integer' | 'legacyNumber';
     /**
-     * @deprecated `numberLocaleOptions` should not be used. It is not needed anymore and should be removed if possible.
+     * Opções de localização numérica.
+     * @deprecated Não é mais necessário. Remova se presente.
      */
     numberLocaleOptions?: NumberLocaleOptions;
+    /**
+     * Controla o autocomplete nativo do browser.
+     */
     browserAutocomplete?: boolean;
+    /**
+     * Número total de dígitos aceitos. Pode ser função para controle dinâmico.
+     */
     precision?: Function | number;
+    /**
+     * Número de casas decimais. Pode ser função para controle dinâmico.
+     */
     scale?: (() => number) | number;
+    /**
+     * Alinhamento do texto no campo.
+     */
     alignTo?: NumberAlignmentOption;
+    /**
+     * Máscara de entrada. Pode ser string estática ou função.
+     */
     mask?: stringFn | string;
+    /**
+     * Addon exibido à esquerda do campo.
+     */
     leftAddon?: AddonConfig;
+    /**
+     * Addon exibido à direita do campo.
+     */
     rightAddon?: AddonConfig;
+    /**
+     * Quando `true`, usa o componente de número localizado.
+     */
     localizedNumber?: boolean;
+    /** Callback chamado quando o campo perde o foco. */
     onBlur?: (event: Event) => void;
+    /** Callback chamado quando o campo recebe foco. */
     onFocus?: (event: Event) => void;
-    onComplete?: (event: FocusEvent) => void;
+    /** Callback chamado quando a máscara é completamente preenchida. */
+    onComplete?: (event: Event) => void;
+    /** Callback chamado a cada alteração no valor do input. */
     onInput?: (event: Event) => void;
 }
 declare module './field' {