@dev-tcloud/tcloud-ui 6.15.0 → 6.18.0

package/docs/tcloud-ui-filters.md

@@ -0,0 +1,337 @@
+# Filters
+
+## Características
+- Componente standalone para filtragem dinâmica de dados em listas e tabelas.
+- Suporta múltiplos tipos de filtros: texto, número, select, booleano, data, datetime.
+- Busca em propriedades aninhadas usando notação de ponto (ex: `product.name`).
+- Suporte a arrays com notação `[]` (ex: `list[].description`, `subitem[].list[].description`).
+- Filtros com operadores de condição: `equal`, `gte` (>=), `lte` (<=), `lt` (<), `gt` (>), `notEqual`.
+- Suporte a filtros de intervalo de datas (`start`/`stop`) com opções rápidas (7 dias, 15 dias, etc).
+- Normalização de busca: ignora maiúsculas, minúsculas e acentos (configurável).
+- Submissão automática de filtros ao alterar valores ou via botão (configurável).
+- Detecção automática de layout (classic ou modern).
+- Eventos: `result`, `onFilter`, `onChange`, `onSubmit`.
+
+## Instalação
+```ts
+import { TCloudUiFiltersComponent } from 'projects/tcloud-ui/src/public-api';
+import { TCDataFilters, TCFiltersType, TCCondition } from 'projects/tcloud-ui/src/public-api';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [TCloudUiFiltersComponent],
+  template: `
+    <tcloud-ui-filters 
+      [data]="items" 
+      [filters]="filterConfig"
+      (result)="filteredResult = $event">
+    </tcloud-ui-filters>
+  `
+})
+export class ExampleComponent {
+  items: any[] = [...];
+  filterConfig: TCDataFilters[] = [...];
+  filteredResult: any[] = [];
+}
+```
+
+## Propriedades (API)
+### Inputs
+| Nome | Tipo | Descrição | Valor Default |
+| --- | --- | --- | --- |
+| data | any[] | Array de dados a serem filtrados. | undefined |
+| filters | TCDataFilters[] | Array de configurações de filtros. | undefined |
+| submitText | string | Texto do botão de submit. | 'Filtrar' |
+| btnSubmitClass | string | Classe CSS do botão de submit. | 'tc-btn-primary' |
+| useOnChangeSubmit | boolean | Se true, filtra automaticamente ao alterar qualquer input. | true |
+| useButtonSubmit | boolean | Se true, exibe botão de submit e não filtra automaticamente. | false |
+| useNormalizeCaseSensitive | boolean | Se true, ignora maiúsculas, minúsculas e acentos na busca. | true |
+| useRangeDate | boolean | Se true, ativa suporte a filtros de intervalo de datas. | true |
+| useFilterAccept | boolean | Se true, valida filtros de aceitação.  | false |
+| border | boolean | Se true, exibe borda no container de filtros. | true |
+
+### Outputs
+| Nome | Tipo de Evento | Descrição |
+| --- | --- | --- |
+| result | EventEmitter<any[]> | Emite array de dados filtrados atualizado. |
+| onFilter | EventEmitter<any> | Emite ao aplicar filtro. Retorna configuração de filtro. |
+| onChange | EventEmitter<any> | Emite ao alterar valor de input. |
+| onSubmit | EventEmitter<TCDataFilters[]> | Emite ao submeter filtros com configuração final. |
+
+## Interface TCDataFilters
+```ts
+{
+  description: string;              // Rótulo do filtro
+  searchIn: string;                 // Caminho da propriedade (dot notation, aceita [])
+  type?: TCFiltersType;             // Tipo de filtro (default: text)
+  width?: string;                   // Largura (ex: '20%', '200px')
+  placeholder?: string;             // Placeholder do input
+  notIn?: boolean;                  // Se true, inverte a busca (NOT IN)
+  condition?: TCCondition;          // Operador: equal, gte, lte, lt, gt, notEqual
+  id?: string;                      // ID único (obrigatório para 'start'/'stop' em datas)
+  value?: any;                      // Valor selecionado
+  searchText?: any;                 // Texto de busca (internal)
+  accept?: boolean;                 // Flag de aceitação
+  data?: TCDataOptions[];           // Opções para select
+  defaultValuePeriodStartStop?: string; // Valor padrão para intervalo (7-days, 30-days, etc)
+  useOptionsDateTime?: boolean;     // Se true, exibe atalhos de tempo
+}
+```
+
+## Tipos de Filtro (TCFiltersType)
+- **text**: Input de texto (busca parcial)
+- **number**: Input numérico com operador de condição
+- **select**: Select com opções predefinidas
+- **boolean**: Checkbox (true/false)
+- **hidden**: Campo oculto
+- **date-local**: Data no formato local (DD/MM/YYYY)
+- **datetime-local**: Data e hora (DD/MM/YYYY HH:mm)
+- **date**: Usando input type="date" do browser
+- **datetime**: Usando input type="datetime" do browser
+
+## Operadores de Condição (TCCondition)
+- **equal**: Igualdade (=)
+- **gte**: Maior ou igual (>=)
+- **lte**: Menor ou igual (<=)
+- **gt**: Maior que (>)
+- **lt**: Menor que (<)
+- **notEqual**: Diferente (!=)
+
+## Exemplos de Uso
+### Uso Básico - Filtro de Texto Simples
+```ts
+export class ExampleComponent {
+  items = [
+    { id: 1, name: 'João', city: 'São Paulo' },
+    { id: 2, name: 'Maria', city: 'Rio de Janeiro' }
+  ];
+
+  filters: TCDataFilters[] = [
+    { description: 'Nome', searchIn: 'name', placeholder: 'Digite o nome', width: '50%' },
+    { description: 'Cidade', searchIn: 'city', placeholder: 'Digite a cidade', width: '50%' }
+  ];
+
+  result: any[] = [];
+}
+```
+
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  (result)="result = $event">
+</tcloud-ui-filters>
+
+<table>
+  <tr *ngFor="let item of result">
+    <td>{{ item.id }}</td>
+    <td>{{ item.name }}</td>
+    <td>{{ item.city }}</td>
+  </tr>
+</table>
+```
+
+### Com Filtro Select
+```ts
+filters: TCDataFilters[] = [
+  { 
+    description: 'Status', 
+    searchIn: 'status', 
+    type: TCFiltersType.select,
+    width: '30%',
+    data: [
+      { description: 'Ativo', value: 'active' },
+      { description: 'Inativo', value: 'inactive' },
+      { description: 'Pendente', value: 'pending' }
+    ]
+  }
+];
+```
+
+### Com Filtro Booleano
+```ts
+filters: TCDataFilters[] = [
+  { 
+    description: 'Exibir apenas ativos', 
+    searchIn: 'active', 
+    type: TCFiltersType.boolean,
+    width: '20%'
+  }
+];
+```
+
+### Com Filtro Numérico e Condições
+```ts
+filters: TCDataFilters[] = [
+  { 
+    description: 'Valor maior ou igual',
+    searchIn: 'price',
+    type: TCFiltersType.number,
+    condition: TCCondition.gte,
+    placeholder: 'Mínimo',
+    width: '20%'
+  },
+  { 
+    description: 'Valor menor ou igual',
+    searchIn: 'price',
+    type: TCFiltersType.number,
+    condition: TCCondition.lte,
+    placeholder: 'Máximo',
+    width: '20%'
+  }
+];
+```
+
+### Com Busca em Propriedades Aninhadas
+```ts
+items = [
+  {
+    id: 1,
+    name: 'Produto A',
+    product: { category: 'Eletrônicos', brand: 'LG' }
+  },
+  {
+    id: 2,
+    name: 'Produto B',
+    product: { category: 'Móveis', brand: 'Ikea' }
+  }
+];
+
+filters: TCDataFilters[] = [
+  { description: 'Categoria', searchIn: 'product.category', width: '30%' },
+  { description: 'Marca', searchIn: 'product.brand', width: '30%' }
+];
+```
+
+## Uso Avançado
+### Com Busca em Arrays Aninhados
+```ts
+items = [
+  {
+    id: 1,
+    name: 'Item 1',
+    tags: ['importante', 'urgente'],
+    details: [
+      { type: 'email', value: 'test@example.com' },
+      { type: 'phone', value: '123456' }
+    ]
+  }
+];
+
+filters: TCDataFilters[] = [
+  { description: 'Tags', searchIn: 'tags[]', width: '30%' },
+  { description: 'Detalhes', searchIn: 'details[].value', width: '30%' }
+];
+```
+
+### Com Filtro de Intervalo de Datas
+```ts
+filters: TCDataFilters[] = [
+  { 
+    description: 'Data Inicial',
+    id: 'start',
+    searchIn: 'createdDate',
+    type: TCFiltersType.browserdate,
+    condition: TCCondition.gte,
+    width: '25%',
+    useOptionsDateTime: true
+  },
+  { 
+    description: 'Data Final',
+    id: 'stop',
+    searchIn: 'createdDate',
+    type: TCFiltersType.browserdatetime,
+    condition: TCCondition.lte,
+    width: '25%'
+  }
+];
+```
+
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  [useRangeDate]="true"
+  (result)="result = $event">
+</tcloud-ui-filters>
+```
+
+### Submissão Manual com Botão
+```ts
+filters: TCDataFilters[] = [...];
+
+// Desativa submit automático
+useOnChangeSubmit = false;
+useButtonSubmit = true;
+```
+
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  [useOnChangeSubmit]="false"
+  [useButtonSubmit]="true"
+  submitText="Buscar"
+  (result)="result = $event">
+</tcloud-ui-filters>
+```
+
+### Com Eventos
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  (result)="result = $event"
+  (onFilter)="onFilterChange($event)"
+  (onChange)="onValueChange($event)"
+  (onSubmit)="onSubmitFilters($event)">
+</tcloud-ui-filters>
+```
+
+Componente:
+```ts
+export class ExampleComponent {
+  onFilterChange(event: any) {
+    console.log('Filtro aplicado:', event);
+  }
+
+  onValueChange(event: any) {
+    console.log('Valor alterado:', event);
+  }
+
+  onSubmitFilters(filters: TCDataFilters[]) {
+    console.log('Filtros submetidos:', filters);
+  }
+}
+```
+
+### Filtro com Negação (NOT IN)
+```ts
+filters: TCDataFilters[] = [
+  { 
+    description: 'Excluir Nome',
+    searchIn: 'name',
+    notIn: true,  // Busca inversa
+    width: '30%'
+  }
+];
+```
+
+### Sem Normalização de Busca
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  [useNormalizeCaseSensitive]="false">
+</tcloud-ui-filters>
+```
+
+### Sem Borda
+```html
+<tcloud-ui-filters 
+  [data]="items" 
+  [filters]="filters"
+  [border]="false">
+</tcloud-ui-filters>
+```