diff --git a/projects/ui/src/lib/components/po-search/po-search-base.component.ts b/projects/ui/src/lib/components/po-search/po-search-base.component.ts index 2ec1f4d76d..3d4b303386 100644 --- a/projects/ui/src/lib/components/po-search/po-search-base.component.ts +++ b/projects/ui/src/lib/components/po-search/po-search-base.component.ts @@ -3,19 +3,100 @@ import { PoFilterMode } from './po-search-filter-mode.enum'; import { Directive, EventEmitter, Input, Output } from '@angular/core'; import { convertToBoolean } from '../../utils/util'; +/** + * @description + * + * O componente search, também conhecido como barra de pesquisa, é utilizado para ajudar os usuários a localizar um determinado conteúdo + * + * Normalmente localizado no canto superior direito, junto com o ícone de lupa, uma vez que este ícone é amplamente reconhecido. + * + * Portanto, é de extrema importância que, ao utilizar este componente, as pessoas responsáveis por seu desenvolvimento considerem os seguintes critérios. + * + * #### Boas práticas + * + * Foram estruturados os padrões de usabilidade para auxiliar na utilização do componente e garantir uma boa experiência aos usuários. Por isso, é muito importante que ao utilizar este componente, as pessoas que o projetarem devem levar em consideração os seguintes critérios: + * - Utilize labels para apresentar resultados que estão sendo exibidos e apresente os resultados mais relevantes primeiro. + * - Exiba uma mensagem clara quando não forem encontrados resultados para busca e sempre que possível ofereça outras sugestões de busca. + * - Mantenha o texto original no campo de input, que facilita a ação do usuário caso queira fazer uma nova busca com alguma modificação na pesquisa. + * - Caso seja possível detectar um erro de digitação, mostre os resultados para a palavra "corrigida", isso evita a frustração de não obter resultados e não força o usuário a realizar uma nova busca. + * - Quando apropriado, destaque os termos da busca nos resultados. + * - A entrada do campo de pesquisa deve caber em uma linha. Não use entradas de pesquisa de várias linhas. + * - Recomenda-se ter apenas uma pesquisa por página. Se você precisar de várias pesquisas, rotule-as claramente para indicar sua finalidade. + * - Se possível, forneça sugestões de pesquisa, seja em um helptext ou sugestão de pesquisa que é um autocomplete. Isso ajuda os usuários a encontrar o que estão procurando, especialmente se os itens pesquisáveis forem complexos. + * + * #### Acessibilidade tratada no componente + * + * Algumas diretrizes de acessibilidade já são tratadas no componente, internamente, e não podem ser alteradas pelo proprietário do conteúdo. São elas: + * + * - Permitir a interação via teclado (2.1.1: Keyboard (A)); + * - Alteração entre os estados precisa ser indicada por mais de um elemento além da cor (1.4.1: Use of Color); + */ @Directive() export class PoSearchBaseComponent { + /** + * @optional + * + * @description + * + * Desabilita o po-search e não permite que o usuário interaja com o mesmo. + * + * @default `false` + */ @Input({ alias: 'p-disabled', transform: convertToBoolean }) disabled?: boolean; + /** + * @optional + * + * @description + * + * Exibe um ícone de carregamento à esquerda do label do botão. + * + * @default `false` + */ @Input('p-loading') loading: boolean; + /** + * @optional + * + * @description + * + * Lista de itens que serão utilizados para pesquisa + */ @Input('p-items') items: Array = []; + /** + * @optional + * + * @description + * + * Deve ser informado o nome da propriedade do objeto que será utilizado para a conversão dos itens apresentados na lista do componente (p-items), esta propriedade será responsável pelo texto de apresentação de cada item da lista. + */ @Input('p-filter-keys') filterKeys: Array = []; + /** + * @optional + * + * @description + * + * Define o modo de pesquisa utilizado no campo de busca, quando habilitado. Valores definidos no enum: PoFilterMode + */ @Input('p-filter-type') filterType: PoFilterMode = PoFilterMode.startsWith; + /** + * @optional + * + * @description + * + * Pode ser informada uma função que será disparada quando houver alterações no input. + */ @Output('p-filtered-items-change') filteredItemsChange = new EventEmitter>(); + /** + * @optional + * + * @description + * + * Pode ser informada uma função que será disparada quando houver alterações nos filtros. + */ @Output('p-filter') filter: EventEmitter = new EventEmitter(); } diff --git a/projects/ui/src/lib/components/po-search/po-search.component.html b/projects/ui/src/lib/components/po-search/po-search.component.html index 820e59b23e..a3cfb03e47 100644 --- a/projects/ui/src/lib/components/po-search/po-search.component.html +++ b/projects/ui/src/lib/components/po-search/po-search.component.html @@ -1,4 +1,4 @@ -