@praxisui/table 8.0.0-beta.2 → 8.0.0-beta.21

package/docs/dynamic-filter-payload-contract.md

@@ -0,0 +1,331 @@
+---
+title: "Dynamic Filter Payload Contract"
+slug: "dynamic-filter-payload-contract"
+description: "Contrato operacional do payload do filtro dinamico, cobrindo eventos do PraxisFilter, envio ao backend e normalizacao aplicada pelo metadata-starter."
+doc_type: "reference"
+document_kind: "host-guide"
+component: "table"
+category: "integration"
+audience:
+  - "host"
+  - "frontend"
+  - "backend"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "payload"
+  - "GenericFilterDTO"
+  - "metadata-starter"
+  - "http"
+order: 27
+icon: "send"
+toc: true
+sidebar: true
+search_boost: 1.2
+reading_time: 18
+estimated_setup_time: 40
+version: "1.0"
+related_docs:
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-fields-inline-components-guide"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "table-overview"
+keywords:
+  - "submit"
+  - "change"
+  - "GenericFilterDTO"
+  - "POST /filter"
+source_of_truth:
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.spec.ts"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceQueryController.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java"
+  - "../praxis-metadata-starter/docs/examples/filter-dto.md"
+  - "../praxis-metadata-starter/docs/guides/FILTROS-E-PAGINACAO.md"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Payload Contract
+
+## Objetivo
+
+Formalizar como o payload do filtro dinâmico nasce na UI, como deve ser enviado pelo host e como o `praxis-metadata-starter` o trata antes de construir a consulta.
+
+Nota de trilha:
+
+- `table` documenta o payload da feature
+- `dynamic-fields` documenta o shape que cada inline coloca no formulario antes do envio
+
+## Pré-requisitos
+
+- Conhecimento básico do `PraxisFilter` e dos endpoints resource-oriented de filtro.
+- DTO de filtro backend implementando `GenericFilterDTO`.
+- Entendimento mínimo de `controlType`, `@Filterable` e operações de range.
+
+## Quando usar
+
+Use este documento para:
+
+- implementar integração host -> backend sem adivinhação;
+- revisar shape do payload emitido por `change` e `submit`;
+- alinhar frontend e backend sobre o que é aceito como filtro válido;
+- depurar `400 FILTER_PAYLOAD_INVALID`.
+
+## Contrato funcional
+
+O runtime do filtro expõe dois eventos principais:
+
+- `change`: mudanças incrementais do formulário;
+- `submit`: snapshot que normalmente deve ser enviado ao backend.
+
+Além disso, existem eventos auxiliares como `clear`, `tagsChange`, `selectedFieldIdsChange`, `metaChanged` e `schemaStatusChange`, mas eles não substituem o payload principal do filtro.
+
+O fluxo oficial do payload é o seguinte.
+
+```mermaid
+sequenceDiagram
+  participant UI as PraxisFilter
+  participant Host
+  participant Controller as AbstractResourceQueryController
+  participant Advice as FilterRequestBodyAdvice
+  participant Normalizer as RangePayloadNormalizer
+  participant DTO as GenericFilterDTO
+  participant Builder as GenericSpecificationsBuilder
+
+  UI->>Host: submit or change payload
+  Host->>Controller: POST /filter
+  Controller->>Advice: intercept request body
+  Advice->>Normalizer: normalize ranges and aliases
+  Normalizer->>DTO: canonical payload
+  DTO->>Builder: typed filter ready for specification
+  Builder-->>Controller: query/specification pronta ou erro
+  Controller-->>Host: result payload or 400 FILTER_PAYLOAD_INVALID
+```
+
+## O que o host realmente envia
+
+O host deve serializar o DTO produzido pela UI como JSON e enviá-lo para o controller correspondente.
+
+Superfícies padrão do starter:
+
+- `POST /filter`
+- `POST /filter/cursor`
+- `POST /locate`
+- `POST /options/filter`
+
+O shape exato depende do seu `FilterDTO`, mas o princípio é o mesmo: cada propriedade enviada deve corresponder a um campo filtrável do backend.
+
+## Pipeline do payload
+
+### 1. Runtime Angular
+
+O `PraxisFilter` agrega o estado do formulário e emite objetos do tipo `Record<string, any>`.
+
+Aspectos relevantes do runtime:
+
+- ranges vazios não devem sobreviver à serialização;
+- estado avançado e preferências visuais podem ser persistidos localmente;
+- aliases inline e metadata overrides influenciam a UI, mas não devem gerar um contrato HTTP arbitrário.
+
+### 2. Envio HTTP
+
+O host é responsável por:
+
+- observar `submit` ou `change`;
+- aplicar debounce/estratégia de busca adequada;
+- enviar o JSON ao endpoint correto;
+- não inventar transformações fora do contrato do backend.
+
+### 3. Interceptação no backend
+
+No `praxis-metadata-starter`, o request body passa por `FilterRequestBodyAdvice` antes da desserialização final.
+
+Esse ponto é central para a doc:
+
+- o payload não é consumido “como veio”;
+- ranges podem ser canonicalizados;
+- payload inválido já pode falhar nessa etapa.
+
+### 4. Normalização de ranges
+
+`RangePayloadNormalizer` converte payloads canônicos para o formato de lista esperado pelos DTOs tipados.
+
+Isso inclui:
+
+- arrays canônicos;
+- objetos canônicos;
+- nomes de bound reconhecidos pela plataforma para domínios como data, numérico e monetário.
+
+### 5. Construção da consulta
+
+Depois da normalização, `GenericSpecificationsBuilder` monta a predicate com base em `@Filterable`.
+
+Para o frontend, a consequência prática é simples:
+
+- a UI pode ser rica;
+- o contrato final precisa continuar mapeável para `GenericFilterDTO`.
+
+## Exemplo de payload enviado pela UI
+
+```json
+{
+  "name": "Alice",
+  "departmentId": 10,
+  "salaryRange": {
+    "minPrice": 6500,
+    "maxPrice": 15000,
+    "currency": "BRL"
+  },
+  "admissionPeriod": {
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  },
+  "status": [
+    "ACTIVE",
+    "PENDING"
+  ]
+}
+```
+
+## Entity Lookup em coleções
+
+Quando um filtro usa `entityLookup` com `multiple=true`, o `PraxisFilter` não deve persistir nem emitir a coleção rica do runtime como contrato HTTP final. A tabela agora reaproveita o helper canônico de `@praxisui/core` e respeita o mesmo `payloadMode` já usado pelo `dynamic-form`.
+
+Regras:
+
+- `multiple=true` sem `payloadMode` explícito envia `ids`
+- `multiple=true` com `payloadMode: "entityRefs"` envia `[{ id, type }]`
+- o `entityType` padrão vem de `optionSource.entityKey` quando a linha ainda não trouxer `type`
+
+Exemplo com `ids`:
+
+```json
+{
+  "supplierIds": ["sup_1", "sup_2"]
+}
+```
+
+Exemplo com `entityRefs`:
+
+```json
+{
+  "suppliers": [
+    { "id": "sup_1", "type": "supplier" },
+    { "id": "sup_2", "type": "legacy-supplier" }
+  ]
+}
+```
+
+Diretriz:
+
+- hosts não devem criar um serializer paralelo para filtros de entidade em tabela;
+- `PraxisFilter` já deve emitir o payload canônico pronto para envio ao backend.
+
+## Como o starter trata esse payload
+
+Para campos simples:
+
+- valores seguem diretamente para o `FilterDTO`.
+
+Para ranges:
+
+- o backend pode converter o objeto em lista canônica;
+- chaves auxiliares consumidas pelo normalizador são removidas do payload final desserializado;
+- listas com limites inválidos ou conflitantes retornam erro.
+
+Exemplo de canonicalização:
+
+```json
+{
+  "salaryRange": [6500, 15000],
+  "admissionPeriod": ["2026-03-01", "2026-03-31"]
+}
+```
+
+## Regras práticas para o frontend
+
+1. Envie apenas propriedades semanticamente preenchidas.
+   Não envie objetos vazios, listas com três posições ou placeholders neutros.
+
+2. Prefira objeto canônico ou lista canônica para ranges.
+   Não envie payload escalar para operações Java de range.
+
+3. Não serialize metadata de UI junto com o DTO.
+   `label`, `tooltip`, `clearButton` e `inlineAutoSize` são contrato de renderização, não de busca.
+
+4. Use nomes canônicos nos contratos novos.
+   Para numérico genérico, prefira `{ min, max }`; para monetário, `{ minPrice, maxPrice }`; para datas, `{ startDate, endDate }`.
+
+5. Considere `change` e `submit` como contrato de integração, não como detalhe interno.
+
+## Query Context na Orquestração de Página
+
+Quando o filtro dinâmico participar de um `praxis-dynamic-page`, o contrato recomendado entre widgets não é mais gravar diretamente `filterCriteria` em cada consumidor.
+
+O caminho canônico passa a ser:
+
+- `praxis-filter` emite `requestSearch` com o DTO filtrado
+- a página escreve esse payload em `page.state`
+- a página ou o builder propagam um `queryContext` para widgets de dados
+
+Exemplo recomendado:
+
+```json
+{
+  "queryContext": {
+    "filters": {
+      "departmentId": 10,
+      "status": "ACTIVE"
+    },
+    "sort": ["nome,asc"],
+    "page": {
+      "index": 0,
+      "size": 25
+    }
+  }
+}
+```
+
+Diretriz de compatibilidade:
+
+- `filterCriteria` continua válido em componentes que ainda publicam esse contrato
+- para novo authoring, recipes e bindings, prefira `queryContext`
+- a semântica mínima garantida hoje é `queryContext.filters`; `sort`, `limit` e `page` devem ser consumidos apenas por widgets que já declararam suporte a esses campos
+
+## Payloads que devem ser evitados
+
+Exemplos inválidos ou indesejáveis:
+
+```json
+{ "salaryRange": 1500 }
+```
+
+```json
+{ "salaryRange": [10, 20, 30] }
+```
+
+```json
+{ "admissionPeriod": { "startDate": null, "endDate": null } }
+```
+
+```json
+{ "salaryRange": { "from": 10, "minPrice": 20 } }
+```
+
+O último caso é especialmente perigoso porque pode configurar fonte conflitante para o mesmo bound.
+
+## Como documentar esta feature daqui para frente
+
+Toda documentação de filtro dinâmico precisa citar explicitamente:
+
+- qual evento gera o payload;
+- qual endpoint o recebe;
+- como o `FilterRequestBodyAdvice` o intercepta;
+- como `RangePayloadNormalizer` o canonicaliza;
+- quais falhas devolvem `400`.
+
+Sem isso, a doc tende a ficar “bonita na UI” e incompleta na integração real.

package/docs/dynamic-filter-range-filters-guide.md

@@ -0,0 +1,289 @@
+---
+title: "Dynamic Filter Range Filters Guide"
+slug: "dynamic-filter-range-filters-guide"
+description: "Guia avancado de ranges no filtro dinamico, cobrindo variantes inline, shapes aceitos no payload, normalizacao backend e semantica das operacoes."
+doc_type: "reference"
+document_kind: "host-guide"
+component: "table"
+category: "data-crud"
+audience:
+  - "host"
+  - "frontend"
+  - "backend"
+  - "architect"
+level: "enterprise"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "range"
+  - "date-range"
+  - "time-range"
+  - "price-range"
+  - "dynamic-filter"
+order: 28
+icon: "swap_horiz"
+toc: true
+sidebar: true
+search_boost: 1.25
+reading_time: 20
+estimated_setup_time: 45
+version: "1.0"
+related_docs:
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-fields-inline-components-guide"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-fields-inline-filter-catalog"
+  - "table-overview"
+keywords:
+  - "BETWEEN"
+  - "BETWEEN_EXCLUSIVE"
+  - "OUTSIDE_RANGE"
+  - "minPrice"
+  - "startDate"
+source_of_truth:
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.spec.ts"
+  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
+  - "projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/extension/CustomOpenApiResolver.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangeBoundAliasRegistry.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/specification/GenericSpecificationsBuilder.java"
+  - "../praxis-metadata-starter/docs/examples/filter-dto.md"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Range Filters Guide
+
+## Objetivo
+
+Documentar com precisão enterprise como funcionam os filtros de faixa no ecossistema Praxis, da escolha do `controlType` até a predicate final aplicada no backend.
+
+Nota de trilha:
+
+- este guia cobre a semantica de range da feature
+- a implementacao dos inline range components fica na suite especializada de `praxis-dynamic-fields`
+
+## Pré-requisitos
+
+- Familiaridade com `PraxisFilter`, `dynamic-fields` e `GenericFilterDTO`.
+- Conhecimento básico de `priceRange`, `rangeSlider`, `dateRange` e `timeRange`.
+- Backend configurado com `@Filterable` para operações de range.
+
+## Quando usar
+
+Use este guia quando precisar:
+
+- modelar filtros monetários, numéricos, de data ou de hora;
+- entender como a UI envia ranges;
+- decidir entre formatos canônicos de payload;
+- explicar por que `BETWEEN_EXCLUSIVE` e `OUTSIDE_RANGE` não se comportam como `BETWEEN`.
+
+## Tipos de range cobertos
+
+No runtime Angular, os cenários principais são:
+
+- `rangeSlider` / `inlineRange`
+- `priceRange` / `inlineCurrencyRange`
+- `dateRange` / `inlineDateRange`
+- `timeRange` / `inlineTimeRange`
+
+Além disso, controles especializados como `inlineRating`, `inlineDistanceRadius` e `inlineScorePriority` também reutilizam semântica de faixa.
+
+## Como a UI resolve ranges
+
+### Toolbar compacta
+
+O `PraxisFilter` converte `controlType` genérico em variante inline por padrão quando existe equivalente dedicado. As flags abaixo funcionam como opt-out:
+
+- `useInlineRangeVariant`
+- `useInlineDateRangeVariant`
+- `useInlineTimeRangeVariant`
+
+Para monetário, `priceRange` já aponta para a experiência compacta específica do filtro.
+
+### Filter settings
+
+`filter-settings.component.ts` participa da história porque ele controla:
+
+- quais tipos aparecem como opção no editor;
+- como o host promove um campo para a toolbar compacta.
+
+### Regra de UX importante
+
+Range vazio não deve virar critério ativo.
+
+Esse comportamento precisa aparecer na doc porque já existe proteção no runtime e em teste para ignorar objeto vazio no `advanced change payload`.
+
+## Shapes aceitos no payload
+
+### Lista canônica
+
+Para operações não exclusivas, o backend aceita:
+
+- `[min]`
+- `[min, max]`
+- `[null, max]`
+
+Exemplo:
+
+```json
+{
+  "salaryRange": [6500, 15000]
+}
+```
+
+### Objeto canônico
+
+Também são aceitos objetos descritivos, especialmente úteis para clareza na UI e no host:
+
+```json
+{
+  "salaryRange": {
+    "minPrice": 6500,
+    "maxPrice": 15000,
+    "currency": "BRL"
+  }
+}
+```
+
+```json
+{
+  "scoreRange": {
+    "min": 10,
+    "max": 20
+  }
+}
+```
+
+```json
+{
+  "admissionPeriod": {
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  }
+}
+```
+
+## Bounds aceitos pelo backend
+
+O `RangeBoundAliasRegistry` reconhece nomes de bounds publicados pela plataforma para clareza por domínio.
+
+Exemplos relevantes:
+
+- datas: `startDate`, `fromDate`, `start`, `from`, `endDate`, `toDate`, `end`, `to`
+- monetário: `minPrice`, `valorMin`, `min`, `from`, `start`, `maxPrice`, `valorMax`, `max`, `to`, `end`
+
+Regra editorial:
+
+- use nomes canônicos em novos contratos: `{ min, max }`, `{ minPrice, maxPrice }` ou `{ startDate, endDate }`.
+
+## Operações suportadas
+
+### `BETWEEN`
+
+Semântica:
+
+- com dois limites: intervalo inclusivo;
+- com um limite inferior: `>=`;
+- com um limite superior: `<=`.
+
+### `BETWEEN_EXCLUSIVE`
+
+Semântica:
+
+- exige exatamente dois limites não nulos;
+- aplica `>` no lower bound e `<` no upper bound.
+
+Consequência prática:
+
+- não aceite payload parcial;
+- não documente `[null, max]` nem `[min]` para essa operação.
+
+### `NOT_BETWEEN`
+
+Semântica:
+
+- com dois limites: negação do intervalo;
+- com limite único: transforma a operação em comparação simples oposta.
+
+### `OUTSIDE_RANGE`
+
+Semântica:
+
+- com dois limites: `< lower OR > upper`;
+- com limite único: segue comparação unilateral fora da faixa.
+
+## Regras de normalização que precisam estar na doc
+
+1. Payload escalar é inválido.
+
+```json
+{ "salaryRange": 1500 }
+```
+
+Não há flag canônica no starter para preservar payload escalar em operações de range.
+
+2. Bounds invertidos podem ser normalizados.
+
+Se o usuário enviar `min > max`, o normalizador pode fazer swap para preservar semântica consistente.
+
+3. Upper-only deve preservar nulidade explícita do lower.
+
+```json
+{ "salaryRange": [null, 15000] }
+```
+
+4. Objeto sem bound efetivo é inválido.
+
+```json
+{ "salaryRange": { "minPrice": null, "maxPrice": null } }
+```
+
+5. Fontes conflitantes para o mesmo range devem falhar.
+
+Não misture duas origens diferentes para o mesmo campo.
+
+## Regras por domínio
+
+### Numérico genérico
+
+Use `rangeSlider` quando o intervalo for numérico puro e houver benefício em slider/preset.
+
+### Monetário
+
+Use `priceRange` ou `inlineCurrencyRange` quando precisar:
+
+- máscara monetária;
+- formatação por locale;
+- resumo de faixa monetária;
+- combinação de slider e inputs numéricos.
+
+### Data
+
+Use `dateRange` ou `inlineDateRange` quando o campo representar período calendárico.
+
+No backend, `LocalDate` exige atenção especial: algumas predicates trabalham com início do dia e início do próximo dia para manter semântica correta.
+
+### Hora
+
+Use `timeRange` ou `inlineTimeRange` quando a busca depender de faixa horária pura, sem necessidade de data.
+
+## O que documentar para hosts
+
+Em qualquer doc host-facing de range, explique sempre:
+
+- qual `controlType` foi adotado;
+- se o host manteve o padrão inline ou aplicou opt-out explícito;
+- qual payload o host deve enviar;
+- qual operação backend está associada;
+- quais formatos inválidos geram `400`.
+
+## Boas práticas finais
+
+1. Prefira objeto canônico na documentação funcional e lista canônica na explicação de normalização.
+2. Não publique payload escalar como exemplo de operação de range.
+3. Relacione sempre a UI de range com a operação `@Filterable` correspondente.
+4. Documente claramente diferença entre `BETWEEN`, `BETWEEN_EXCLUSIVE`, `NOT_BETWEEN` e `OUTSIDE_RANGE`.
+5. Em casos críticos, cite explicitamente que o `praxis-metadata-starter` é quem canonicaliza o range antes da specification.