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

package/docs/dynamic-filter-backend-contract-cheatsheet.md

@@ -0,0 +1,167 @@
+---
+title: "Dynamic Filter Backend Contract Cheatsheet"
+slug: "dynamic-filter-backend-contract-cheatsheet"
+description: "Cheatsheet canônico do contrato backend do filtro dinamico, resumindo endpoints, formas de payload, ranges, erros e configuracoes do metadata-starter relevantes para hosts."
+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"
+  - "backend"
+  - "cheatsheet"
+  - "metadata-starter"
+  - "payload"
+order: 33
+icon: "rule_folder"
+toc: true
+sidebar: true
+search_boost: 1.18
+reading_time: 14
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-fields-inline-filter-runtime-contract"
+  - "dynamic-filter-troubleshooting-guide"
+keywords:
+  - "POST /filter"
+  - "POST /filter/cursor"
+  - "FILTER_PAYLOAD_INVALID"
+source_of_truth:
+  - "../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/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/rest/exceptionhandler/GlobalExceptionHandler.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 Backend Contract Cheatsheet
+
+## Objetivo
+
+Resumir, em formato operacional, o que um host precisa saber sobre o contrato backend do filtro dinâmico.
+
+## Pré-requisitos
+
+- Conhecimento básico de `GenericFilterDTO`.
+- Leitura do contrato de payload e do guia de ranges.
+
+## Quando usar
+
+Use este documento como referência rápida em implementação, revisão de payload e troubleshooting.
+
+## Endpoints principais
+
+- `POST /filter`
+- `POST /filter/cursor`
+- `POST /locate`
+- `POST /options/filter`
+
+Todos pertencem à superfície resource-oriented padrão de `AbstractResourceQueryController`.
+
+## Pipeline backend
+
+1. request body chega ao controller;
+2. `FilterRequestBodyAdvice` intercepta o body;
+3. `RangePayloadNormalizer` canonicaliza ranges;
+4. Jackson desserializa no `GenericFilterDTO`;
+5. `GenericSpecificationsBuilder` monta a consulta;
+6. erros retornam `400` quando houver violação de payload.
+
+```mermaid
+sequenceDiagram
+  participant Host
+  participant Controller as AbstractResourceQueryController
+  participant Advice as FilterRequestBodyAdvice
+  participant Normalizer as RangePayloadNormalizer
+  participant DTO as GenericFilterDTO
+  participant Builder as GenericSpecificationsBuilder
+
+  Host->>Controller: POST /filter
+  Controller->>Advice: intercept request body
+  Advice->>Normalizer: canonicalize ranges
+  Normalizer->>DTO: canonical payload ready
+  DTO->>Builder: build specification
+  Builder-->>Controller: query result or FILTER_PAYLOAD_INVALID
+  Controller-->>Host: response payload or HTTP 400
+```
+
+## Shapes aceitos para range
+
+### Lista canônica
+
+- `[min]`
+- `[min, max]`
+- `[null, max]`
+
+### Objeto canônico
+
+- monetário: `{ minPrice, maxPrice, currency? }`
+- data: `{ startDate, endDate }`
+- numérico genérico: `{ min, max }`
+
+## Formatos inválidos por padrão
+
+- escalar puro: `1500`
+- lista com 3 valores
+- objeto sem nenhum limite efetivo
+- fontes conflitantes para o mesmo bound
+
+## Operações de range relevantes
+
+- `BETWEEN`
+- `BETWEEN_EXCLUSIVE`
+- `NOT_BETWEEN`
+- `OUTSIDE_RANGE`
+
+Resumo:
+
+- `BETWEEN`: inclusivo e aceita bound parcial;
+- `BETWEEN_EXCLUSIVE`: exige dois bounds e usa exclusão;
+- `NOT_BETWEEN`: nega o intervalo;
+- `OUTSIDE_RANGE`: fora da faixa.
+
+## Código de erro relevante
+
+Para payload inválido de filtro:
+
+- HTTP `400`
+- `errors[].properties.code = FILTER_PAYLOAD_INVALID`
+
+## Regras práticas para hosts
+
+1. Envie DTO limpo, sem metadata de UI.
+2. Prefira objeto ou lista canônica para range.
+3. Não envie payload escalar para operações de range.
+4. Não dependa de aliases alternativos como estilo principal.
+5. Compare sempre a operação backend com o shape enviado.
+
+## Exemplo curto
+
+```json
+{
+  "salaryRange": {
+    "minPrice": 6500,
+    "maxPrice": 15000
+  },
+  "status": ["ACTIVE", "PENDING"]
+}
+```
+
+Resultado esperado:
+
+- `salaryRange` pode ser normalizado para `[6500,15000]`;
+- `status` segue como lista para operação compatível;
+- payload inválido resulta em `400`.

package/docs/dynamic-filter-editor-settings-guide.md

@@ -0,0 +1,229 @@
+---
+title: "Dynamic Filter Editor Settings Guide"
+slug: "dynamic-filter-editor-settings-guide"
+description: "Guia detalhado do editor de configuracoes do filtro dinamico, cobrindo campos always visible, metadata overrides, variantes inline, painel avancado e governanca operacional."
+doc_type: "reference"
+document_kind: "host-guide"
+component: "table"
+category: "components"
+audience:
+  - "host"
+  - "frontend"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "filter-settings"
+  - "always-visible"
+  - "metadata-overrides"
+  - "editor"
+order: 30
+icon: "settings_suggest"
+toc: true
+sidebar: true
+search_boost: 1.15
+reading_time: 22
+estimated_setup_time: 40
+version: "1.0"
+related_docs:
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-inline-filter-catalog"
+  - "dynamic-fields-inline-components-guide"
+  - "table-overview"
+keywords:
+  - "advancedOpenMode"
+  - "advancedClearButtonsEnabled"
+  - "alwaysVisibleFieldMetadataOverrides"
+  - "useInlineDateRangeVariant"
+source_of_truth:
+  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
+  - "projects/praxis-table/src/lib/services/filter-config.service.ts"
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Editor Settings Guide
+
+## Objetivo
+
+Documentar o papel do editor/configurador do filtro dinâmico como camada de governança da feature, e não apenas como tela auxiliar.
+
+## Pré-requisitos
+
+- Conhecimento de `advancedFilters.settings`.
+- Entendimento básico de `controlType` inline e toolbar compacta.
+- Familiaridade com a diferença entre metadata original e overrides do host.
+
+## Quando usar
+
+Use este guia para:
+
+- padronizar o editor do filtro em ambientes enterprise;
+- explicar como o host altera a UX sem alterar o DTO original;
+- decidir quais flags inline ativar;
+- documentar a política de always visible fields.
+
+## Papel do editor
+
+O `filter-settings` não é cosmético. Ele governa:
+
+- quais campos ficam sempre visíveis;
+- quais campos podem ser escolhidos pelo usuário;
+- quais variantes inline são permitidas;
+- como o painel avançado abre;
+- como clear buttons e métricas operam.
+
+Em termos arquiteturais, ele é o ponto onde a experiência do filtro deixa de ser “schema puro” e passa a ser “schema + política do produto”.
+
+## Grupos principais de configuração
+
+### Always visible
+
+Campos centrais:
+
+- `alwaysVisibleFields`
+- `alwaysVisibleFieldMetadataOverrides`
+- `selectedFieldIds`
+
+Use esse grupo para controlar a barra compacta principal.
+
+### Operação
+
+Campos centrais:
+
+- `changeDebounceMs`
+- `allowSaveTags`
+- `showAdvanced`
+- `mode`
+
+Esse grupo controla como o filtro reage, não só como ele parece.
+
+### Variantes inline
+
+Flags principais:
+
+- `useInlineSearchableSelectVariant`
+- `useInlineRangeVariant`
+- `useInlineDateVariant`
+- `useInlineDateRangeVariant`
+- `useInlineTimeVariant`
+- `useInlineTimeRangeVariant`
+- `useInlineTreeSelectVariant`
+
+Essas flags são decisivas para a documentação porque vários `controlType` agora migram para a experiência compacta por padrão, e o host usa essas chaves como opt-out explícito quando precisa preservar o renderer tradicional.
+
+### Painel avançado
+
+Campos centrais:
+
+- `overlayVariant`
+- `overlayBackdrop`
+- `advancedOpenMode`
+- `advancedClearButtonsEnabled`
+
+Esse grupo define a experiência do formulário avançado e precisa ser documentado junto com a jornada de uso.
+
+## Always visible fields em profundidade
+
+### O que são
+
+São os campos “pinned” do filtro, exibidos antes da grade ampliada e antes dos campos opcionais escolhidos pelo usuário.
+
+### Quando usar
+
+Escolha campos que tenham:
+
+- alta frequência de uso;
+- leitura rápida;
+- valor decisório forte;
+- compatibilidade com layout compacto.
+
+### Quando evitar
+
+Evite promover para always visible campos que:
+
+- tenham interação longa e pouco frequente;
+- dependam de catálogos remotos lentos;
+- exijam overlay complexo para valor baixo de uso;
+- prejudiquem a leitura do conjunto da barra.
+
+## Metadata overrides
+
+`alwaysVisibleFieldMetadataOverrides` existe para ajustes controlados sobre campos fixados.
+
+Use quando o campo precisar:
+
+- label mais curta;
+- outro `controlType`;
+- clear button diferente;
+- largura e auto-size específicos;
+- hints e aria labels adequados ao modo compacto.
+
+Não use para:
+
+- reinventar o contrato do DTO;
+- alterar o significado semântico do campo;
+- criar divergência editorial entre barra compacta e formulário avançado sem documentação.
+
+## Política de variantes inline
+
+### Regra recomendada
+
+Inline é o padrão do `praxis-filter` quando existe equivalente dedicado para a barra compacta.
+
+Sugestão prática:
+
+- mantenha `useInlineRangeVariant` e `useInlineDateVariant` no padrão inline;
+- mantenha `useInlineDateRangeVariant` no padrão inline e faça opt-out apenas quando o host precisar do renderer dedicado por densidade ou fluxo operacional;
+- mantenha `useInlineTimeVariant` e `useInlineTimeRangeVariant` no padrão inline, validando densidade e clareza de rótulo no host real;
+- mantenha `useInlineSearchableSelectVariant` no padrão inline, mas faça opt-out se o endpoint, paginação ou volume remoto exigirem o renderer dedicado;
+- mantenha `useInlineTreeSelectVariant` no padrão inline para seleção hierárquica compacta e faça opt-out quando o fluxo depender da leitura expandida do componente dedicado.
+
+## Advanced open mode
+
+`advancedOpenMode` define se o filtro avançado abre em:
+
+- `modal`
+- `drawer`
+
+Regra recomendada:
+
+- `modal` quando o contexto exige foco e baixa simultaneidade;
+- `drawer` quando a tabela precisa continuar visível e comparável durante o refinamento do filtro.
+
+## Clear buttons avançados
+
+`advancedClearButtonsEnabled` não é detalhe cosmético. Ele interfere na velocidade de limpeza do formulário e na previsibilidade da UX.
+
+Recomendação:
+
+- mantenha `true` por padrão em ambientes enterprise;
+- desabilite apenas quando houver conflito com um design de formulário altamente controlado.
+
+## Sinais operacionais importantes
+
+O editor também conversa com preocupações de operação:
+
+- `logLevel`
+- `enablePerformanceMetrics`
+
+Esses campos ajudam a transformar o filtro em feature observável em vez de caixa-preta.
+
+## Erros editoriais comuns
+
+1. Ativar todas as variantes inline ao mesmo tempo.
+2. Tratar `alwaysVisibleFieldMetadataOverrides` como escape hatch permanente.
+3. Criar toolbar compacta mais complexa que o formulário avançado.
+4. Não documentar por que certos campos foram fixados e outros não.
+5. Ignorar diferenças de layout entre desktop, tablet e mobile.
+
+## Recomendação de governança
+
+Para documentação extensa e sustentável:
+
+1. registre a política de always visible por produto;
+2. documente quais flags inline estão aprovadas;
+3. trate overrides como exceção auditável;
+4. mantenha catálogo visual e settings guide sincronizados.

package/docs/dynamic-filter-host-integration-guide.md

@@ -0,0 +1,217 @@
+---
+title: "Dynamic Filter Host Integration Guide"
+slug: "dynamic-filter-host-integration-guide"
+description: "Guia operacional para integrar o filtro dinamico em hosts Praxis, cobrindo bindings da tabela, persistencia, eventos, settings e envio do DTO ao backend."
+doc_type: "guide"
+document_kind: "host-guide"
+component: "table"
+category: "integration"
+audience:
+  - "host"
+  - "frontend"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "host"
+  - "praxis-table"
+  - "integration"
+  - "settings"
+order: 29
+icon: "integration_instructions"
+toc: true
+sidebar: true
+search_boost: 1.15
+reading_time: 18
+estimated_setup_time: 45
+version: "1.0"
+related_docs:
+  - "table-overview"
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-editor-settings-guide"
+  - "dynamic-inline-filter-catalog"
+keywords:
+  - "alwaysVisibleFields"
+  - "selectedFieldIds"
+  - "allowSaveTags"
+  - "changeDebounceMs"
+source_of_truth:
+  - "projects/praxis-table/src/lib/praxis-table.html"
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "projects/praxis-table/src/lib/services/filter-config.service.ts"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Host Integration Guide
+
+## Objetivo
+
+Mostrar como um host integra o filtro dinâmico no contexto real da `table`, incluindo bindings de configuração, eventos emitidos, persistência local e envio do payload ao backend.
+
+## Pré-requisitos
+
+- Conhecimento básico de `TableConfig` e `@praxisui/table`.
+- Backend já expondo schema e endpoint de filtro.
+- Entendimento prévio do contrato de payload e de ranges.
+
+## Quando usar
+
+Use este guia para:
+
+- plugar o filtro em uma tabela nova;
+- padronizar configuração de `advancedFilters.settings`;
+- decidir quais campos ficam sempre visíveis;
+- alinhar debounce, tags e comportamento do painel avançado.
+
+## Integração mínima
+
+No runtime da tabela, o `praxis-filter` já é montado pela própria `praxis-table`.
+
+O host normalmente atua via `config.behavior.filtering.advancedFilters.settings`, alimentando bindings como:
+
+- `alwaysVisibleFields`
+- `alwaysVisibleFieldMetadataOverrides`
+- `selectedFieldIds`
+- `allowSaveTags`
+- `changeDebounceMs`
+- `showFilterSettings`
+
+O template da tabela também encaminha:
+
+- `resourcePath`
+- `filterId`
+- `formId`
+- `persistenceKey`
+- `fieldMetadata`
+- `enableCustomization` (opt-in; default canônico `false`)
+
+O host deve pensar a integração na ordem abaixo.
+
+```mermaid
+flowchart TD
+  config["Load TableConfig"] --> bindings["Resolve bindings and effective data mode"]
+  bindings --> render["praxis-table mounts praxis-filter when advanced filtering is enabled"]
+  render --> schema["PraxisFilter uses provided fieldMetadata or resolves schema via /schemas/filtered"]
+  schema --> settings["Apply advancedFilters.settings and persisted filter state"]
+  settings --> events["Observe submit/change/clear/tags/meta events"]
+  events --> backend["Send DTO to /filter or /filter/cursor"]
+```
+
+## Fluxo de integração recomendado
+
+### 1. Definir o DTO e o schema do filtro
+
+O host precisa garantir que a fonte de metadata do filtro e o backend estejam alinhados.
+
+Sem isso, o runtime até renderiza o formulário, mas o payload não será previsível.
+
+### 2. Configurar `advancedFilters.settings`
+
+Essas chaves são as mais importantes na prática:
+
+- `alwaysVisibleFields`: fixa campos prioritários na barra do filtro;
+- `alwaysVisibleFieldMetadataOverrides`: permite ajustar label, `controlType`, clear button e outros detalhes para campos sempre visíveis;
+- `selectedFieldIds`: controla os extras escolhidos pelo usuário;
+- `allowSaveTags`: habilita tags persistidas/visíveis;
+- `changeDebounceMs`: regula a cadência de emissão de `change` e `submit`.
+
+### 3. Definir política do painel avançado
+
+Os principais knobs são:
+
+- `advancedOpenMode`: `modal` ou `drawer`;
+- `advancedClearButtonsEnabled`: liga ou desliga clear buttons nos campos do formulário avançado;
+- `showFilterSettings`: normalmente atrelado a `enableCustomization` quando o host opta por expor customização runtime.
+
+### 4. Observar os eventos corretos
+
+Os eventos principais para integração são:
+
+- `submit`: use para busca explícita;
+- `change`: use para filtros reativos com debounce;
+- `clear`: reseta o estado do filtro;
+- `tagsChange`: sincroniza chips persistidos/salvos;
+- `selectedFieldIdsChange`: acompanha customização de campos visíveis;
+- `metaChanged` e `schemaStatusChange`: importantes para observabilidade e reconciliação de schema.
+
+## Exemplo mental de integração
+
+O fluxo típico é:
+
+1. host carrega `TableConfig`;
+2. `praxis-table` resolve o metadata do filtro;
+3. `praxis-filter` renderiza toolbar compacta e/ou formulário avançado;
+4. usuário altera valores;
+5. host observa `submit` ou `change`;
+6. host envia DTO para `/filter` ou `/filter/cursor`.
+
+## Persistência local
+
+O runtime já persiste dois grupos de informação:
+
+- estado operacional do filtro em `filter-dto:<key>`;
+- preferências/configuração em `filter-config:<key>`.
+
+Isso tem duas implicações:
+
+1. a doc do host precisa deixar claro o papel do `persistenceKey`;
+2. o reset de preferências precisa considerar DTO e config, não só um deles.
+
+## Estratégia de UX recomendada
+
+### Campos sempre visíveis
+
+Use `alwaysVisibleFields` apenas para filtros de alta frequência e leitura rápida:
+
+- status;
+- período principal;
+- faixa monetária;
+- texto livre;
+- owner/departamento em operações recorrentes.
+
+### Metadata overrides
+
+Use `alwaysVisibleFieldMetadataOverrides` quando o mesmo campo precisar:
+
+- de label mais curta;
+- de `controlType` inline canônico;
+- de `clearButton` diferente;
+- de `inlineAutoSize` próprio.
+
+### Debounce
+
+Regra prática:
+
+- `300ms` é o default saudável;
+- cenários com backend pesado ou selects remotos podem pedir números maiores;
+- evite debounce muito baixo em filtros que disparam chamadas remotas frequentes.
+
+## Tags salvas
+
+`allowSaveTags` muda a experiência do filtro, não só a UI dos chips.
+
+Quando habilitar:
+
+- defina claramente se as tags são só visuais ou se representam presets reais;
+- documente como elas afetam a recuperação do estado na próxima sessão;
+- valide se faz sentido no contexto da sua tabela, porque nem todo filtro enterprise deve permitir salvar seleções ad hoc.
+
+## Erros comuns de integração
+
+1. Configurar `alwaysVisibleFields` com nomes que não existem no schema.
+2. Misturar nomes de `controlType` fora do contrato publicado com nomes canônicos.
+3. Persistir estado com `persistenceKey` instável.
+4. Escutar só `change` e esquecer estratégia de envio ao backend.
+5. Ativar demasiados campos sempre visíveis e destruir a legibilidade da toolbar.
+
+## Recomendação de rollout
+
+Para uma nova tabela enterprise:
+
+1. comece com poucos `alwaysVisibleFields`;
+2. use overrides só onde a barra compacta realmente precisa;
+3. valide payload com backend antes de abrir opções avançadas;
+4. só então ligue tags, settings editor e variantes inline mais complexas.