Fork: Código fonte extraído de @senior-hcm-service-tower/hst-lookup e mantido independentemente para o contexto ERP.

ERP Service Tower Senior - Lookup

Componente desenvolvido para uso em telas customizadas e BPMs pelo time de serviços customizados ERP da Senior Sistemas.

Requisitos

• Angular: 18.0.1
• primeflex: 3.3.1
• primeicons: 7.0.0
• primeng: 17.18.9

Instalação

npm install @senior-erp-service-tower/hst-lookup

Visão Geral

O componente hst-lookup é um campo de busca com dialog modal contendo uma tabela paginada com lazy loading. Implementa ControlValueAccessor, permitindo uso com formControlName e ngModel. Ao clicar no campo, um modal é aberto com uma tabela para busca e seleção de registros.

Parâmetros de Entrada (@Input)

| Input | Tipo | Valor Padrão | Descrição | | --- | --- | --- | --- | | config | SearchConfigModel | undefined | Configuração obrigatória do lookup (serviço, colunas, pattern) | | label | string | '' | Label exibida acima do campo | | title | string | 'Selecionar valor para o campo' | Título do modal de busca | | placeHolder | string | 'Clique para buscar' | Placeholder do campo | | errorsMessage | object | undefined | Dicionário customizado de mensagens de erro | | disabled | boolean | false | Desabilita o campo (exibe apenas o valor selecionado) | | showIcon | boolean | true | Exibe ícone de busca (lupa) no campo | | args | object | {} | Parâmetros adicionais enviados ao serviço de busca |

Modelos Exportados

SearchConfigModel

Interface principal de configuração do lookup.

export interface SearchConfigModel {
  filterType: FilterType[];     // Colunas exibidas na tabela de busca
  patternField: string;         // Pattern para exibir o valor selecionado no campo
  service: ServiceSearch<any>;  // Serviço que implementa a busca
  initialValue?: any;           // Valor inicial (objeto completo)
}

| Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | filterType | FilterType[] | Sim | Define as colunas da tabela no modal | | patternField | string | Sim | Template para exibição do valor selecionado. Use ${campo} para referenciar propriedades do objeto | | service | ServiceSearch | Sim | Serviço que implementa a interface ServiceSearch | | initialValue | any | Não | Objeto inicial para pré-seleção |

FilterType

Interface que define cada coluna da tabela de busca.

export interface FilterType {
  label: string;  // Título da coluna (header)
  field: string;  // Nome do campo no objeto de dados
}

ServiceSearch

Interface que o serviço de busca deve implementar.

export interface ServiceSearch<T> {
  find(
    top: number,
    skip: number,
    filter: string,
    args?: Record<string, string>
  ): Observable<ResultListInterface<T>>;
}

| Parâmetro | Tipo | Descrição | | --- | --- | --- | | top | number | Quantidade de registros por página | | skip | number | Offset para paginação | | filter | string | Texto digitado pelo usuário para filtro | | args | Record<string, string> | Parâmetros adicionais opcionais (recebidos do Input args) |

ResultListInterface

Interface do retorno esperado pelo serviço de busca.

export interface ResultListInterface<T> {
  size?: number;  // Total de registros
  result: T[];    // Lista de resultados da página atual
}

Sistema de Dicionário de Erros

O lookup possui o mesmo sistema de dicionário de erros do hst-input:

const errors = {
  default: 'Valor inválido!',
  required: 'Campo obrigatório!',
  minlength: 'Tamanho inválido!',
  cpf: 'CPF inválido!',
  cnpj: 'CNPJ inválido!',
  email: 'E-mail inválido!'
};

Personalize com o input errorsMessage:

<hst-lookup
  formControlName="colaborador"
  [config]="config"
  [errorsMessage]="{ required: 'Selecione um colaborador' }">
</hst-lookup>

Exemplo Completo

1. Criar o modelo de dados

export interface ColaboradorModel {
  matricula: number;
  nome: string;
  cargo: string;
}

2. Implementar o serviço de busca

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';
import { ServiceSearch, ResultListInterface } from '@senior-erp-service-tower/hst-lookup';
import { ColaboradorModel } from './colaborador.model';

@Injectable({ providedIn: 'root' })
export class ColaboradorService implements ServiceSearch<ColaboradorModel> {

  private readonly url = 'https://api.exemplo.com/colaboradores';

  constructor(private http: HttpClient) {}

  find(
    top: number,
    skip: number,
    filter: string,
    args?: Record<string, string>
  ): Observable<ResultListInterface<ColaboradorModel>> {
    const params: any = { top, skip };
    if (filter) params.filter = filter;
    if (args?.filial) params.filial = args.filial;

    return this.http.get<ResultListInterface<ColaboradorModel>>(this.url, { params });
  }
}

3. Configurar e utilizar o componente

import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { LookupComponent, SearchConfigModel, FilterType } from '@senior-erp-service-tower/hst-lookup';
import { ColaboradorService } from './colaborador.service';

@Component({
  selector: 'app-formulario',
  standalone: true,
  imports: [LookupComponent, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <hst-lookup
        formControlName="colaborador"
        label="Colaborador"
        title="Buscar Colaborador"
        placeHolder="Clique para buscar o colaborador"
        [config]="buscaColabConfig"
        [args]="{ filial: '01' }">
      </hst-lookup>
    </form>
  `
})
export class FormularioComponent {
  form: FormGroup;
  buscaColabConfig: SearchConfigModel;

  constructor(
    private fb: FormBuilder,
    private colaboradorService: ColaboradorService
  ) {
    this.form = this.fb.group({
      colaborador: [null, Validators.required]
    });

    this.buscaColabConfig = {
      filterType: [
        { label: 'Matrícula', field: 'matricula' } as FilterType,
        { label: 'Nome', field: 'nome' } as FilterType,
        { label: 'Cargo', field: 'cargo' } as FilterType
      ],
      patternField: '${matricula} - ${nome}',
      service: this.colaboradorService
    };
  }
}

Exemplo com Valor Inicial

Para pré-selecionar um valor ao carregar o componente:

this.buscaColabConfig = {
  filterType: [
    { label: 'Matrícula', field: 'matricula' },
    { label: 'Nome', field: 'nome' }
  ],
  patternField: '${matricula} - ${nome}',
  service: this.colaboradorService,
  initialValue: { matricula: 12345, nome: 'João da Silva' }
};

Ou via FormControl:

this.form.get('colaborador')?.setValue({ matricula: 12345, nome: 'João da Silva' });

Comportamento do Modal

1. Ao clicar no campo, o modal é aberto com uma tabela paginada
2. O usuário pode digitar um filtro e pressionar Enter ou clicar no botão de busca
3. A tabela exibe os resultados com paginação (10 registros por página)
4. Ao clicar em uma linha, o objeto é selecionado e o modal fecha
5. O valor exibido no campo segue o patternField configurado

Indicador de Campo Obrigatório

Se o FormControl possuir o validador Validators.required, um asterisco vermelho (*) será exibido automaticamente antes da label.