@po-ui/ng-components 21.22.0 → 21.23.0

package/lib/components/po-field/index.d.ts

@@ -24,6 +24,13 @@ export * from './po-decimal/po-decimal.component';
 export * from './po-email/po-email.component';
 export * from './po-input/po-input.component';
 export * from './po-input/po-mask';
+export * from './po-search-ai/po-search-ai.component';
+export * from './po-search-ai/po-search-ai.module';
+export * from './po-search-ai/po-search-ai.service';
+export * from './po-search-ai/po-search-ai-odata-filter';
+export * from './po-search-ai/interfaces/po-search-ai-column.interface';
+export * from './po-search-ai/interfaces/po-search-ai.interface';
+export * from './po-search-ai/interfaces/po-search-ai-literals.interface';
 export * from './po-login/po-login.component';
 export * from './po-lookup/interfaces/po-lookup-column.interface';
 export * from './po-lookup/interfaces/po-lookup-filter.interface';

package/lib/components/po-field/po-field.module.d.ts

@@ -2,8 +2,7 @@
  * @description
  *
  * Módulo dos componentes: po-checkbox, po-checkbox-group, po-combo, po-datepicker, po-datetimepicker, po-datepicker-range, po-email, po-input,
- * po-lookup, po-number, po-multiselect, po-password, po-radio-group, po-select, po-switch, po-textarea, po-upload
- * e po-url.
+ * po-lookup, po-number, po-multiselect, po-password, po-radio-group, po-select, po-switch, po-textarea, po-upload, po-url e po-search-ai.
  *
  * > Não esqueça de importar o módulo `FormsModule` para usar os componentes de formulários e caso esteja trabalhando com
  * > formulários reativos, importe o módulo `ReactiveFormsModule`, ambos nativos do Angular.

package/lib/components/po-field/po-search-ai/interfaces/po-search-ai-column.interface.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface que define os metadados de uma coluna/campo enviados ao endpoint de IA
+ * para contextualizar a interpretação da busca em linguagem natural.
+ *
+ * Esses metadados ajudam o provedor de IA a mapear os termos digitados pelo usuário
+ * para as propriedades reais dos dados e a gerar um filtro (por exemplo, OData) coerente.
+ */
+export interface PoSearchAiColumn {
+    /** Nome da propriedade do campo (ex: `name`, `age`, `city`). */
+    property: string;
+    /** Rótulo legível exibido ao usuário (ex: `Nome`, `Idade`, `Cidade`). */
+    label: string;
+    /**
+     * Tipo do campo, utilizado pela IA para gerar comparações adequadas.
+     *
+     * Valores comuns: `string`, `number`, `date`, `currency`, `boolean`.
+     *
+     * @default `string`
+     */
+    type?: string;
+}
+/**
+ * @docsPrivate
+ *
+ * Formato de entrada aceito por `extractColumnsMetadata`: superconjunto de `PoSearchAiColumn`
+ * que inclui campos de controle de visibilidade usados por consumidores como o `po-table`.
+ */
+export interface PoSearchAiColumnInput {
+    property?: string;
+    label?: string;
+    type?: string;
+    /** Quando `true`, a coluna é excluída dos metadados enviados à IA. Padrão: `false`. */
+    searchAiIgnore?: boolean;
+    visible?: boolean;
+}

package/lib/components/po-field/po-search-ai/interfaces/po-search-ai-literals-default.interface.d.ts

@@ -0,0 +1,7 @@
+import { PoSearchAiLiterals } from './po-search-ai-literals.interface';
+export declare const poSearchAiLiteralsDefault: {
+    en: PoSearchAiLiterals;
+    es: PoSearchAiLiterals;
+    pt: PoSearchAiLiterals;
+    ru: PoSearchAiLiterals;
+};

package/lib/components/po-field/po-search-ai/interfaces/po-search-ai-literals.interface.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface para definição das literais usadas no `po-search-ai`.
+ */
+export interface PoSearchAiLiterals {
+    /** Texto de acessibilidade do botão de limpar o campo. */
+    clean?: string;
+    /** Mensagem exibida quando a busca com IA falha. */
+    errorMessage?: string;
+}

package/lib/components/po-field/po-search-ai/interfaces/po-search-ai.interface.d.ts

@@ -0,0 +1,109 @@
+import { PoSearchAiColumn } from './po-search-ai-column.interface';
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Enum que define os tipos de resposta suportados pelo endpoint de IA.
+ *
+ */
+export declare enum PoSearchAiResponseType {
+    /** Resposta contendo um filtro estruturado (ex: OData). */
+    filter = "filter",
+    /** Resposta conversacional em linguagem natural. */
+    chat = "chat",
+    /** Payload genérico definido pelo consumidor. */
+    custom = "custom"
+}
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface que define o payload enviado ao endpoint de IA configurado via `p-url`.
+ *
+ * O componente é **agnóstico ao provedor de IA**: o backend (proxy) recebe este payload,
+ * encaminha para a LLM e retorna um `PoSearchAiResponse`.
+ */
+export interface PoSearchAiRequest {
+    /** Texto em linguagem natural digitado pelo usuário. */
+    query: string;
+    /** Metadados dos campos disponíveis para a busca (ver `PoSearchAiColumn`). */
+    columns: Array<PoSearchAiColumn>;
+}
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface que define a resposta esperada do endpoint de IA configurado via `p-url`.
+ */
+export interface PoSearchAiResponse {
+    /**
+     * Tipo da resposta retornada pela IA.
+     *
+     * Quando omitido, o componente infere `'filter'` se `filter` estiver presente,
+     * caso contrário assume `'custom'`.
+     *
+     * @default `'filter'`
+     */
+    type?: PoSearchAiResponseType;
+    /**
+     * Filtro gerado pela IA, normalmente no padrão OData
+     * (ex: `age gt 30 and city eq 'São Paulo'`).
+     *
+     * Utilizado quando `type` é `'filter'`.
+     */
+    filter?: string;
+    /** Descrição legível, em linguagem natural, da resposta. */
+    description?: string;
+    /**
+     * Nível de confiança da interpretação da IA, em um intervalo de `0.0` a `1.0`.
+     *
+     * Utilizado em conjunto com `p-min-confidence` para decidir se o resultado é confiável.
+     */
+    confidence?: number;
+    /**
+     * Payload genérico da resposta da IA (mensagem de chat, ações, dados customizados, etc.).
+     *
+     * Utilizado quando `type` é `'chat'` ou `'custom'`.
+     */
+    data?: Record<string, any>;
+}
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface que define o objeto emitido pelos eventos `p-result` e `p-low-confidence`.
+ */
+export interface PoSearchAiResult {
+    /** Texto original digitado pelo usuário. */
+    query: string;
+    /** Tipo da resposta retornada pela IA. */
+    type: PoSearchAiResponseType;
+    /** Filtro retornado pela IA (ex: filtro OData). Presente quando `type` é `'filter'`. */
+    filter?: string;
+    /** Descrição legível da resposta. */
+    description?: string;
+    /** Nível de confiança da interpretação (`0.0` a `1.0`). */
+    confidence?: number;
+    /** Payload genérico da resposta (chat, ações, dados customizados, etc.). */
+    data?: Record<string, any>;
+}
+/**
+ * @usedBy PoSearchAiComponent
+ *
+ * @description
+ *
+ * Interface que define o objeto emitido pelo evento `p-error` quando a chamada à
+ * API de IA falha (erro HTTP, timeout, resposta inválida, etc.).
+ */
+export interface PoSearchAiError {
+    /** Texto original digitado pelo usuário. */
+    query: string;
+    /** Código HTTP do erro (ex: `500`, `408` para timeout). */
+    statusCode: number;
+    /** Mensagem de erro. */
+    message: string;
+}

package/lib/components/po-field/po-search-ai/po-search-ai-base.component.d.ts

@@ -0,0 +1,229 @@
+import { AbstractControl } from '@angular/forms';
+import { OnDestroy } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { PoInputGeneric } from '../po-input-generic/po-input-generic';
+import { PoSearchAiColumn } from './interfaces/po-search-ai-column.interface';
+import { PoSearchAiLiterals } from './interfaces/po-search-ai-literals.interface';
+import { PoSearchAiError, PoSearchAiResult } from './interfaces/po-search-ai.interface';
+import { PoSearchAiService } from './po-search-ai.service';
+/**
+ * @description
+ *
+ * O `po-search-ai` é um componente de **busca em linguagem natural** baseado em input.
+ * Ele permite que o usuário digite uma consulta em texto livre (por exemplo,
+ * *"clientes de SP com saldo acima de R$ 500"*) e a converte, através de um provedor de IA,
+ * em um filtro estruturado (normalmente OData) que pode ser aplicado por outro componente,
+ * como o [`po-table`](/documentation/po-table).
+ *
+ * > **Componente experimental:** o `po-search-ai` está em fase experimental. Sua API
+ * > (propriedades, eventos e contrato com o backend) pode sofrer alterações
+ * > entre versões. Utilize com cautela em ambientes de produção.
+ *
+ * O componente é **agnóstico ao provedor de IA**. Toda a comunicação ocorre através do
+ * endpoint informado em `p-url`, que recebe `{ query, columns }` e deve retornar
+ * `{ filter, description, confidence }`. Isso garante que nenhuma chave de IA seja
+ * exposta no client-side — a integração com a LLM é responsabilidade do backend (proxy).
+ *
+ * Por herdar de `po-input`, o componente suporta as propriedades comuns de formulário
+ * (label, help, helper, required, disabled, readonly, size, clean, loading, etc.) e
+ * integra-se a formulários `template-driven` e `reactive`.
+ *
+ * #### Endpoint de IA (backend)
+ *
+ * O componente **não conversa diretamente com a LLM**. Você deve disponibilizar um endpoint
+ * próprio (proxy) e informá-lo em `p-url`.
+ * É nesse backend que devem ficar a chave de acesso da IA e as regras usadas para montar
+ * o prompt. Essas informações nunca devem ficar expostas no client-side
+ *
+ * O contrato é simples. O componente faz um `POST` enviando:
+ *
+ * ```json
+ * {
+ *   "query": "funcionários de São Paulo com salário acima de 5000",
+ *   "columns": [
+ *     { "property": "name", "label": "Nome", "type": "string" },
+ *     { "property": "city", "label": "Cidade", "type": "string" },
+ *     { "property": "salary", "label": "Salário", "type": "number" }
+ *   ]
+ * }
+ * ```
+ *
+ * E o endpoint deve responder com:
+ *
+ * ```json
+ * {
+ *   "filter": "city eq 'São Paulo' and salary gt 5000",
+ *   "description": "Funcionários de São Paulo com salário acima de 5000",
+ *   "confidence": 0.92
+ * }
+ * ```
+ *
+ * Onde `filter` é o filtro estruturado gerado pela IA (normalmente OData), `description` é um
+ * resumo legível e `confidence` (`0.0` a `1.0`) indica o quão confiável foi a interpretação —
+ * comparado com `p-min-confidence` para decidir entre os eventos `p-result` e `p-low-confidence`.
+ *
+ * > **Exemplo de implementação:** o PO UI mantém um backend de referência, open source, que recebe
+ * > esse contrato e o encaminha para um provedor de IA (Groq/Gemini).
+ * > - Endpoint público: [`/v1/ai/filter`](https://po-sample-api.onrender.com/api#/ai)
+ * > - Código-fonte: [po-sample-api/src/ai/ai.service.ts](https://github.com/po-ui/po-sample-api/blob/main/src/ai/ai.service.ts)
+ *
+ * #### Estados de comportamento
+ *
+ * - **Idle:** aguardando a digitação da consulta.
+ * - **Loading:** consulta em andamento (ícone de carregamento ativo).
+ * - **Aplicado:** após uma resposta bem-sucedida, exibe um feedback persistente de
+ *   "filtro aplicado via IA" enquanto a consulta estiver ativa, com opção de limpeza rápida.
+ * - **Baixa confiança:** quando `confidence` for menor que `p-min-confidence`, emite
+ *   `p-low-confidence` e não aplica o filtro automaticamente.
+ * - **Erro:** quando a chamada falha, emite `p-error`.
+ *
+ * #### Tokens customizáveis
+ *
+ * É possível alterar o estilo do componente usando os seguintes tokens (CSS):
+ *
+ * > Para maiores informações, acesse o guia [Personalizando o Tema Padrão com Tokens CSS](https://po-ui.io/guides/theme-customization).
+ *
+ * | Propriedade                   | Descrição                                                       | Valor Padrão                       |
+ * |-------------------------------|-----------------------------------------------------------------|------------------------------------|
+ * | **Default**                   |                                                                 |                                    |
+ * | `--font-family`               | Família tipográfica do campo                                    | `var(--font-family-theme)`         |
+ * | `--font-size`                 | Tamanho da fonte do campo                                       | `var(--font-size)`                 |
+ * | `--text-color`                | Cor do texto digitado                                           | `var(--color-neutral-dark-90)`     |
+ * | `--text-color-placeholder`    | Cor do texto do placeholder                                     | `var(--color-neutral-light-30)`    |
+ * | `--color`                     | Cor da borda do campo                                           | `var(--color-neutral-dark-70)`     |
+ * | `--background`                | Cor de fundo do campo                                           | `var(--color-neutral-light-05)`    |
+ * | `--border-radius`             | Raio da borda do campo                                          | `var(--border-radius-md)`          |
+ * | **Ícones e divisória**        |                                                                 |                                    |
+ * | `--color-icon-read`           | Cor do ícone de busca por IA                                    | `var(--color-neutral-dark-70)`     |
+ * | `--color-divider`             | Cor da divisória vertical entre o campo e o botão de busca      | `var(--color-neutral-mid-40)`      |
+ * | `--color-icon-processing`     | Cor do ícone exibido enquanto a consulta está sendo processada  | `var(--color-action-default)`      |
+ * | **Hover**                     |                                                                 |                                    |
+ * | `--color-hover`               | Cor da borda no estado hover                                    | `var(--color-brand-01-dark)`       |
+ * | `--background-hover`          | Cor de fundo no estado hover                                    | `var(--color-brand-01-lightest)`   |
+ * | **Focused**                   |                                                                 |                                    |
+ * | `--color-focused`             | Cor da borda no estado de foco                                  | `var(--color-action-default)`      |
+ * | `--outline-color-focused`     | Cor do outline no estado de foco                                | `var(--color-action-focus)`        |
+ * | **Disabled**                  |                                                                 |                                    |
+ * | `--color-disabled`            | Cor da borda no estado desabilitado                             | `var(--color-neutral-light-30)`    |
+ * | `--background-disabled`       | Cor de fundo no estado desabilitado                             | `var(--color-neutral-light-20)`    |
+ */
+export declare abstract class PoSearchAiBaseComponent extends PoInputGeneric implements OnDestroy {
+    protected aiErrorMessage: string;
+    protected aiLoading: boolean;
+    protected aiSubscription: Subscription;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Evento disparado quando o filtro aplicado via IA é limpo, seja pela ação do usuário
+     * ou programaticamente. Não emite valor.
+     */
+    clearEvent: import("@angular/core").OutputEmitterRef<void>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Metadados das colunas/campos disponíveis para a busca por IA. Essas informações são
+     * enviadas ao endpoint configurado em `p-url` para que a IA mapeie os termos digitados
+     * para as propriedades reais dos dados.
+     *
+     * @default `[]`
+     */
+    columns: import("@angular/core").InputSignal<PoSearchAiColumn[]>;
+    protected readonly effectiveLiterals: import("@angular/core").Signal<any>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Evento disparado quando a chamada à API de IA falha (erro HTTP, timeout, etc.).
+     * Emite um objeto `PoSearchAiError`.
+     */
+    error: import("@angular/core").OutputEmitterRef<PoSearchAiError>;
+    private readonly language;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Objeto com os literais usados no componente. Permite sobrescrever as mensagens padrão
+     * para internacionalização ou customização.
+     */
+    literals: import("@angular/core").InputSignal<PoSearchAiLiterals>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Evento disparado quando a confiança da resposta da IA é menor que `p-min-confidence`.
+     * Emite um objeto `PoSearchAiResult`, permitindo ao desenvolvedor decidir o que fazer
+     * (ex: confirmar com o usuário antes de aplicar o filtro).
+     */
+    lowConfidence: import("@angular/core").OutputEmitterRef<PoSearchAiResult>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Nível mínimo de confiança (`0.0` a `1.0`) para que o resultado da IA seja considerado
+     * confiável. Quando a confiança retornada for menor, o evento `p-low-confidence` é
+     * emitido em vez de `p-result`.
+     *
+     * @default `0.5`
+     */
+    minConfidence: import("@angular/core").InputSignalWithTransform<number, number>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Evento disparado quando a IA retorna um resultado com confiança maior ou igual a
+     * `p-min-confidence`. Emite um objeto `PoSearchAiResult`.
+     *
+     * O campo `type` do resultado indica como o consumidor deve interpretar a resposta:
+     *
+     * - **`filter`** _(padrão)_: a IA retornou um filtro estruturado (ex: OData). Use `result.filter`
+     *   para aplicar a consulta à fonte de dados — por exemplo, passando para um `po-table` via `p-filter`.
+     *
+     * - **`chat`**: a IA retornou uma resposta conversacional. Use `result.data` para exibir a mensagem
+     *   ao usuário, por exemplo em um painel lateral ou tooltip.
+     *
+     * - **`custom`**: a IA retornou um payload genérico definido pelo backend. Use `result.data` para
+     *   executar qualquer ação específica da aplicação (ex: navegação, abertura de modal, acionamento de comando).
+     */
+    result: import("@angular/core").OutputEmitterRef<PoSearchAiResult>;
+    protected searchAiService: PoSearchAiService;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Tempo máximo de espera (em milissegundos) pela resposta da IA antes de abortar a
+     * requisição e emitir `p-error` com `statusCode 408`.
+     *
+     * @default `10000`
+     */
+    timeout: import("@angular/core").InputSignalWithTransform<number, number>;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Endpoint (proxy) responsável por encaminhar a consulta para o provedor de IA.
+     * Recebe `{ query, columns }` via `POST` e deve retornar `{ filter, description, confidence }`.
+     *
+     * > A integração com a LLM e a guarda de chaves devem ocorrer **no backend**, nunca no client-side.
+     */
+    url: import("@angular/core").InputSignal<string>;
+    constructor();
+    abstract clearSearch(): void;
+    abstract search(): void;
+    getErrorPattern(): string;
+    extraValidation(_c: AbstractControl): {
+        [key: string]: any;
+    };
+    hasValue(): boolean;
+    ngOnDestroy(): void;
+}

package/lib/components/po-field/po-search-ai/po-search-ai-odata-filter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @docsPrivate
+ *
+ * Este arquivo implementa um motor independente para interpretar filtros no formato OData v4 e aplicá-los sobre listas de objetos JavaScript.
+ * Na prática, ele permite que o po-search-ai receba uma condição de filtro em texto, como “nome contém Henrique" ou “idade maior que 18”, e transforme isso em uma função capaz de filtrar os dados localmente.
+ * A principal vantagem é que essa lógica não depende do Angular nem de outro framework. Com isso, o mesmo motor pode ser reutilizado por diferentes consumidores do po-search-ai, mantendo o comportamento de filtro padronizado.
+ * O arquivo suporta os principais recursos necessários para filtros simples e intermediários, como comparações, operadores lógicos, funções de texto, valores booleanos, nulos, números, datas e campos aninhados.
+ * Também há um cuidado para evitar que filtros inválidos quebrem a aplicação. Quando o filtro está vazio ou não pode ser interpretado, o motor apenas mantém a lista original, sem aplicar nenhuma filtragem.
+ * Em resumo, este arquivo centraliza a interpretação e execução dos filtros, reduzindo dependências externas e tornando o comportamento mais previsível, reutilizável e fácil de manter.
+ *
+ * Operadores suportados:
+ * - Comparação: eq, ne, gt, ge, lt, le
+ * - Lógicos: and, or, not, parênteses
+ * - Funções de string: contains, startswith, endswith
+ * - Funções de transformação: tolower, toupper
+ * - Literais: string ('...'), número, true, false, null, data ISO (yyyy-MM-dd)
+ */
+/**
+ * Compila uma string de filtro OData v4 em um predicado JavaScript reutilizável.
+ *
+ * Operadores suportados: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not`,
+ * `contains`, `startswith`, `endswith`, `tolower`, `toupper`.
+ *
+ * Em caso de filtro inválido ou vazio, retorna `() => true` (sem filtragem).
+ *
+ * @param filter String de filtro OData (ex: `"city eq 'SP' and salary gt 5000"`).
+ */
+export declare function poSearchAiCompileFilter(filter: string): (item: Record<string, unknown>) => boolean;
+/**
+ * Filtra um array de itens aplicando uma string de filtro OData v4.
+ *
+ * Utiliza `poSearchAiCompileFilter` internamente. Em caso de filtro inválido
+ * ou array vazio, retorna o array original sem modificação.
+ *
+ * @param items Array de itens a filtrar.
+ * @param filter String de filtro OData.
+ */
+export declare function poSearchAiFilterItems<T extends Record<string, unknown>>(items: Array<T>, filter: string): Array<T>;

package/lib/components/po-field/po-search-ai/po-search-ai-utils.d.ts

@@ -0,0 +1,12 @@
+import { PoSearchAiColumn, PoSearchAiColumnInput } from './interfaces/po-search-ai-column.interface';
+/**
+ * @docsPrivate
+ *
+ * Extrai e normaliza os metadados das colunas para envio à IA,
+ * descartando colunas sem `property`, invisíveis ou marcadas com `searchAiIgnore`.
+ *
+ * Função utilitária pura, reutilizada pelo `PoSearchAiService` e pelo `PoTableComponent`.
+ *
+ * @param columns Lista de colunas no formato bruto do componente consumidor.
+ */
+export declare function extractSearchAiColumns(columns: Array<PoSearchAiColumnInput>): Array<PoSearchAiColumn>;

package/lib/components/po-field/po-search-ai/po-search-ai.component.d.ts

@@ -0,0 +1,58 @@
+import { ElementRef, OnChanges, SimpleChanges } from '@angular/core';
+import { PoButtonComponent } from '../../po-button/po-button.component';
+import { PoSearchAiBaseComponent } from './po-search-ai-base.component';
+/**
+ * @docsExtends PoSearchAiBaseComponent
+ *
+ * @example
+ *
+ * <example name="po-search-ai-basic" title="PO AI Search Basic">
+ *  <file name="sample-po-search-ai-basic/sample-po-search-ai-basic.component.html"> </file>
+ *  <file name="sample-po-search-ai-basic/sample-po-search-ai-basic.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-search-ai-labs" title="PO AI Search Labs">
+ *  <file name="sample-po-search-ai-labs/sample-po-search-ai-labs.component.html"> </file>
+ *  <file name="sample-po-search-ai-labs/sample-po-search-ai-labs.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-search-ai-result" title="PO AI Search - Result">
+ *  <file name="sample-po-search-ai-result/sample-po-search-ai-result.component.html"> </file>
+ *  <file name="sample-po-search-ai-result/sample-po-search-ai-result.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-search-ai-filter" title="PO AI Search - Filter">
+ *  <file name="sample-po-search-ai-filter/sample-po-search-ai-filter.component.html"> </file>
+ *  <file name="sample-po-search-ai-filter/sample-po-search-ai-filter.component.ts"> </file>
+ * </example>
+ */
+export declare class PoSearchAiComponent extends PoSearchAiBaseComponent implements OnChanges {
+    inp: ElementRef;
+    iconSearchAiEl: PoButtonComponent;
+    id: string;
+    constructor();
+    ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Envia a consulta atual (valor do campo) para o endpoint de IA configurado em `p-url`.
+     *
+     * Caso a consulta esteja vazia ou `p-url` não esteja definido, nada é feito.
+     * O resultado é emitido via `p-result` (ou `p-low-confidence` quando a confiança for baixa)
+     * e falhas são emitidas via `p-error`.
+     */
+    search(): void;
+    clearAndFocus(): void;
+    handleCleanKeydown(event: KeyboardEvent): void;
+    /**
+     * Limpa o filtro aplicado via IA, esvazia o campo e emite o evento `p-clear`.
+     */
+    clearSearch(): void;
+    /**
+     * Manipula a tecla pressionada no campo: dispara a busca ao pressionar `Enter`.
+     *
+     * @param event Evento de teclado.
+     */
+    onSearchKeydown(event: KeyboardEvent): void;
+    private finishProcessing;
+    private handleResponse;
+    private handleError;
+}

package/lib/components/po-field/po-search-ai/po-search-ai.module.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @description
+ * Módulo do componente `po-search-ai`.
+ *
+ * Pode ser importado de forma independente por qualquer módulo que precise renderizar
+ * o campo de busca por IA.
+ */
+export declare class PoSearchAiModule {
+}

package/lib/components/po-field/po-search-ai/po-search-ai.service.d.ts

@@ -0,0 +1,34 @@
+import { HttpClient, HttpHeaders } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { PoSearchAiColumn, PoSearchAiColumnInput } from './interfaces/po-search-ai-column.interface';
+import { PoSearchAiResponse } from './interfaces/po-search-ai.interface';
+/**
+ * @docsPrivate
+ *
+ * Serviço responsável por enviar a consulta em linguagem natural para o endpoint de IA
+ * configurado no `PoSearchAiComponent` e tratar a resposta/erros.
+ *
+ * O serviço é agnóstico ao provedor de IA: ele apenas faz o `POST` do payload
+ * (`{ query, columns }`) e padroniza o tratamento de timeout e falhas.
+ */
+export declare class PoSearchAiService {
+    private readonly http;
+    readonly headers: HttpHeaders;
+    constructor(http: HttpClient);
+    /**
+     * Envia a consulta para o endpoint de IA.
+     *
+     * @param url Endpoint configurado em `p-url`.
+     * @param query Texto em linguagem natural digitado pelo usuário.
+     * @param columns Metadados das colunas/campos disponíveis para a busca.
+     * @param timeoutMs Tempo máximo de espera (ms) antes de abortar a requisição.
+     */
+    sendQuery(url: string, query: string, columns: Array<PoSearchAiColumn>, timeoutMs?: number): Observable<PoSearchAiResponse>;
+    /**
+     * Extrai e normaliza os metadados das colunas para envio à IA,
+     * descartando colunas sem `property` ou marcadas para serem ignoradas.
+     *
+     * @param columns Lista de colunas no formato bruto do componente consumidor.
+     */
+    extractColumnsMetadata(columns: Array<PoSearchAiColumnInput>): Array<PoSearchAiColumn>;
+}

package/lib/components/po-table/index.d.ts

@@ -6,6 +6,7 @@ export * from './interfaces/po-table-boolean.interface';
 export * from './interfaces/po-table-column.interface';
 export * from './interfaces/po-table-column-sort.interface';
 export * from './interfaces/po-table-literals.interface';
+export * from './interfaces/po-table-search-ai-field.interface';
 export * from './po-table-column-icon/po-table-column-icon.interface';
 export * from './po-table-column-label/po-table-column-label.interface';
 export * from './po-table-detail/po-table-detail-column.interface';

package/lib/components/po-table/interfaces/po-table-column.interface.d.ts

@@ -299,4 +299,18 @@ export interface PoTableColumn {
      * Caso a coluna possua um `type` diferente de `string`, a máscara será ignorada.
      */
     mask?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Quando `true`, exclui a coluna dos metadados enviados ao endpoint de IA configurado
+     * em `p-search-ai-field`, independentemente de estar visível na tabela.
+     *
+     * Útil para ocultar colunas de controle interno (IDs, flags técnicos, etc.) da
+     * interpretação da linguagem natural.
+     *
+     * @default `false`
+     */
+    searchAiIgnore?: boolean;
 }

package/lib/components/po-table/interfaces/po-table-literals.interface.d.ts

@@ -38,4 +38,6 @@ export interface PoTableLiterals {
     deleteSuccessful?: string;
     /** Texto de notificação de erro na requisição Delete */
     deleteApiError?: string;
+    /** Texto exibido como placeholder padrão no campo de busca por IA (`p-search-ai-field`) quando nenhum `placeholder` é informado. */
+    searchAiPlaceholder?: string;
 }