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

package/docs/dynamic-filter-troubleshooting-guide.md

@@ -0,0 +1,220 @@
+---
+title: "Dynamic Filter Troubleshooting Guide"
+slug: "dynamic-filter-troubleshooting-guide"
+description: "Runbook de troubleshooting do filtro dinamico, cobrindo payload invalido, ranges, schema desatualizado, persistencia local e falhas comuns entre table, dynamic-fields e metadata-starter."
+doc_type: "troubleshooting"
+document_kind: "runbook"
+component: "table"
+category: "troubleshooting"
+audience:
+  - "host"
+  - "frontend"
+  - "backend"
+  - "ops"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "troubleshooting"
+  - "FILTER_PAYLOAD_INVALID"
+  - "schema"
+  - "range"
+order: 32
+icon: "healing"
+toc: true
+sidebar: true
+search_boost: 1.2
+reading_time: 20
+estimated_setup_time: 35
+version: "1.0"
+related_docs:
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-filter-backend-contract-cheatsheet"
+keywords:
+  - "FILTER_PAYLOAD_INVALID"
+  - "schemaOutdated"
+  - "metaChanged"
+  - "schemaStatusChange"
+source_of_truth:
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/rest/exceptionhandler/GlobalExceptionHandler.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/specification/GenericSpecificationsBuilder.java"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Troubleshooting Guide
+
+## Objetivo
+
+Fornecer um runbook direto para diagnosticar e corrigir problemas recorrentes do filtro dinâmico em produção e em integração local.
+
+## Pré-requisitos
+
+- Conhecimento básico do pipeline `PraxisFilter -> payload -> metadata-starter`.
+- Acesso ao payload enviado pelo host e à resposta HTTP do backend.
+- Familiaridade com `related_docs` desta trilha.
+
+## Operational Response
+
+Ao investigar um incidente no filtro, siga esta ordem:
+
+1. validar o payload efetivamente enviado pelo host;
+2. confirmar se o schema do filtro está atualizado;
+3. verificar se houve normalização ou rejeição de range no backend;
+4. checar persistência local e preferências reaplicadas;
+5. revisar `controlType` inline e overrides de metadata.
+
+```mermaid
+flowchart TD
+  incident["Incident in dynamic filter"] --> payload["Inspect payload sent by host"]
+  payload --> schema["Validate current schema and drift"]
+  schema --> range["Check range normalization and backend rejection"]
+  range --> persistence["Inspect local persistence and restored state"]
+  persistence --> inline["Review inline controlType and metadata overrides"]
+```
+
+## Sintoma: `400 FILTER_PAYLOAD_INVALID`
+
+### Causa provável
+
+O backend rejeitou o payload durante normalização ou construção da specification.
+
+### Onde olhar
+
+- `GlobalExceptionHandler`
+- `RangePayloadNormalizer`
+- `GenericSpecificationsBuilder`
+
+### Casos típicos
+
+- payload escalar de range;
+- lista com mais de dois limites;
+- `BETWEEN_EXCLUSIVE` sem dois limites válidos;
+- alias conflitante para o mesmo range;
+- tipo incompatível com a operação (`LIKE` com valor não textual, `IN` sem lista etc.).
+
+### Resposta esperada
+
+HTTP `400` com `errors[].properties.code = FILTER_PAYLOAD_INVALID`.
+
+## Sintoma: range não filtra ou filtra errado
+
+### Causa provável
+
+O shape enviado não respeita o contrato ou foi interpretado de maneira diferente da esperada.
+
+### Checklist
+
+1. O campo backend usa operação `BETWEEN`, `BETWEEN_EXCLUSIVE`, `NOT_BETWEEN` ou `OUTSIDE_RANGE`?
+2. O frontend enviou lista canônica ou objeto canônico?
+3. Há `null` explícito preservando upper-only ou lower-only?
+4. Existe mistura de aliases como `from` e `minPrice` ao mesmo tempo?
+
+### Ação
+
+Compare o payload com o guia de ranges antes de tentar “corrigir no controller”.
+
+## Sintoma: campo inline não aparece na barra compacta
+
+### Causa provável
+
+O host pode ter aplicado opt-out para a variante inline ou o campo não foi promovido corretamente para `alwaysVisibleFields`.
+
+### Onde olhar
+
+- `alwaysVisibleFields`
+- `alwaysVisibleFieldMetadataOverrides`
+- flags `useInline*Variant`
+- catálogo inline canônico
+
+### Ação
+
+Confirme:
+
+- se o nome do campo existe no schema;
+- se a variante inline está habilitada;
+- se o `controlType` é o nome canônico publicado;
+- se o campo deveria mesmo estar na toolbar e não apenas no avançado.
+
+## Sintoma: schema mudou e o filtro ficou inconsistente
+
+### Sinais
+
+- `schemaStatusChange` emitindo `outdated: true`
+- comportamento divergente entre o schema atual e o estado local persistido
+
+### Causa provável
+
+O schema do backend mudou, mas o estado local ou as preferências ainda refletem a versão antiga.
+
+### Ação
+
+1. observar `metaChanged` e `schemaStatusChange`;
+2. reconciliar schema quando necessário;
+3. limpar persistência local se o contrato mudou estruturalmente;
+4. revalidar `alwaysVisibleFields` e overrides.
+
+## Sintoma: filtro parece “preso” ou restaura estado inesperado
+
+### Causa provável
+
+Persistência local ativa com `filter-dto:<key>` e `filter-config:<key>`.
+
+### Ação
+
+- revisar o `persistenceKey`;
+- limpar config e DTO persistidos;
+- confirmar se o ambiente de teste não está herdando estado anterior.
+
+## Sintoma: tags não funcionam como esperado
+
+### Causa provável
+
+`allowSaveTags` não está habilitado, ou a expectativa do produto sobre tags não está alinhada com o runtime.
+
+### Ação
+
+- confirmar `allowSaveTags`;
+- revisar se as tags são só visualização ou presets operacionais;
+- evitar documentar tags como comportamento universal do filtro.
+
+## Sintoma: comportamento diferente entre modal e drawer
+
+### Causa provável
+
+Configuração distinta em `advancedOpenMode` e/ou `advancedClearButtonsEnabled`.
+
+### Ação
+
+Verificar:
+
+- modo de abertura atual;
+- clear buttons avançados;
+- densidade e largura dos campos no contexto real.
+
+## Matriz rápida de causa e correção
+
+| Sintoma | Causa mais provável | Correção inicial |
+| --- | --- | --- |
+| `400 FILTER_PAYLOAD_INVALID` | payload incompatível com operação | revisar payload e contrato backend |
+| range vazio “vira filtro” | serialização indevida no host | remover objeto vazio antes do envio |
+| inline não aparece | flag inline ausente ou campo não pinado | revisar settings editor |
+| schema fica desatualizado | drift entre backend e estado local | reconciliar schema e limpar persistência |
+| filtro restaura valor antigo | `persistenceKey`/storage reaplicando estado | limpar `filter-dto:*` e `filter-config:*` |
+
+## Regra operacional final
+
+Nunca trate bug de filtro só como problema de UI.
+
+No Praxis, a falha pode estar em qualquer uma destas camadas:
+
+- metadata/schema;
+- runtime do `praxis-filter`;
+- configuração do host;
+- payload enviado;
+- normalização do `metadata-starter`;
+- specification backend.

package/docs/dynamic-inline-filter-catalog.md

@@ -0,0 +1,147 @@
+---
+title: "Dynamic Inline Filter Catalog"
+slug: "dynamic-inline-filter-catalog"
+description: "Catalogo de referencia da trilha inline do filtro dinamico em praxis-table, com foco em decisao de uso e dependencia de runtime."
+doc_type: "reference"
+document_kind: "host-guide"
+component: "table"
+category: "integration"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+  - "designer"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "dynamic-filter"
+  - "inline"
+  - "catalog"
+last_updated: "2026-03-07"
+toc: true
+sidebar: true
+deprecated_paths:
+  - "dynamic-filter-inline-catalog.md"
+deprecated_slugs:
+  - "dynamic-filter-inline-catalog"
+related_docs:
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-filter-editor-settings-guide"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-fields-inline-filter-catalog"
+keywords:
+  - "praxis-filter"
+  - "inline controls"
+  - "toolbar filters"
+  - "always visible filters"
+---
+
+# Dynamic Inline Filter Catalog
+
+## Objetivo
+
+Mapear a trilha inline do `praxis-table` sem confundir o consumidor com fields de formulario comum.
+
+```mermaid
+flowchart LR
+    Host["Host define filtros visiveis"] --> Table["praxis-table governa a jornada inline"]
+    Table --> Toolbar["toolbar sempre visivel"]
+    Table --> Payload["payload emitido para filter"]
+    Table --> DynamicFields["dynamic-fields fornece controlType inline"]
+    DynamicFields --> Components["componentes compactos e metadata-driven"]
+```
+
+## Pre-requisitos
+
+- entendimento basico de `praxis-table`, `praxis-filter` e `@praxisui/dynamic-fields`
+- familiaridade com filtros always visible vs painel avancado
+
+## Como ler este catalogo
+
+- `table` e a feature owner da jornada de filtro
+- `dynamic-fields` e o owner dos componentes inline
+- este documento existe para conectar jornada, UX e integracao host
+
+## Quando usar inline
+
+Prefira filtros inline quando:
+
+- o campo precisa ficar visivel na toolbar;
+- a interacao cabe em espaco compacto;
+- o resumo do valor continua legivel sem abrir painel avancado;
+- o backend ja entende o payload emitido por essa trilha.
+
+## Quando evitar inline
+
+Evite inline quando:
+
+- o campo exige leitura longa ou configuracao extensa;
+- o resumo do valor vira ruido (`primeiro +N` sem contexto suficiente);
+- o fluxo depende de lookup rico, formulario multi-etapas ou ajuda contextual pesada;
+- a acessibilidade degrada por excesso de compactacao.
+
+## Familias principais
+
+### Texto
+
+- `inlineInput`
+
+### Selecao
+
+- `inlineSelect`
+- `inlineSearchableSelect`
+- `inlineAsyncSelect`
+- `inlineMultiSelect`
+- `inlineAutocomplete`
+- `inlineEntityLookup`
+
+`entityLookup` vindo de metadata canonica e projetado como always visible usa `inlineEntityLookup` na toolbar compacta. O host deve preferir `controlType: "entityLookup"` no schema e reservar `inlineEntityLookup` para overrides visuais explicitos.
+
+### Numero e range
+
+- `inlineNumber`
+- `inlineCurrency`
+- `inlineCurrencyRange`
+- `inlineRange`
+- `inlineRating`
+- `inlineDistanceRadius`
+- `inlineScorePriority`
+
+### Data e tempo
+
+- `inlineDate`
+- `inlineDateRange`
+- `inlineTime`
+- `inlineTimeRange`
+- `inlineRelativePeriod`
+
+### Outros especializados
+
+- `inlineTreeSelect`
+- `inlinePipelineStatus`
+- `inlineSentiment`
+- `inlineColorLabel`
+- `inlineToggle`
+
+## Fonte de verdade do componente
+
+Para detalhe de cada controlType, shape de valor e metadata:
+
+- consulte [Dynamic Fields Inline Filter Catalog](../../praxis-dynamic-fields/docs/dynamic-fields-inline-filter-catalog.md)
+
+## Fonte de verdade da jornada
+
+Para integracao real do filtro:
+
+- consulte [Dynamic Filter Host Integration Guide](./dynamic-filter-host-integration-guide.md)
+- consulte [Dynamic Filter Payload Contract](./dynamic-filter-payload-contract.md)
+- consulte [Dynamic Filter Range Filters Guide](./dynamic-filter-range-filters-guide.md)
+
+## Regra editorial
+
+- `dynamic-fields` documenta o componente
+- `table` documenta quando ele entra na jornada
+- o host decide quais campos ficam sempre visiveis e quais degradam para painel avancado

package/docs/e2e-column-drag-playwright.md

@@ -0,0 +1,62 @@
+# PraxisTable E2E (Playwright) - Column Drag
+
+Este pacote valida gesto real de drag de colunas (pointer) em ambiente browser, reduzindo risco de regressao de drop area/layout que nao aparece em testes unitarios.
+
+## Arquivos
+
+- `projects/praxis-table/test-dev/e2e/column-drag.playwright.spec.ts`
+- `projects/praxis-table/test-dev/e2e/column-drag-visual-evidence.playwright.spec.ts`
+- `tools/e2e/playwright/praxis-table-column-drag.playwright.config.ts`
+- `tools/e2e/playwright/run-praxis-table-column-drag.sh`
+
+## Cobertura do teste
+
+1. Abre `http://127.0.0.1:4003/table-local-data-features-demo` com storage limpo.
+2. Valida contrato default: `Reordenar colunas por arraste` inicia habilitado no editor.
+3. Valida affordance primario de drag no header (`grab` no idle, `grabbing` durante gesto quando suportado pelo browser).
+4. Valida o contrato visual do grip: sem fundo/borda de botao, dimensao discreta e opacidade baixa no estado idle.
+5. Valida a discoverability do grip em hover/focus (estado visivel sem ruído visual excessivo).
+6. Valida o mesmo contrato na rota `http://127.0.0.1:4003/filter-demo`.
+7. Desabilita drag via editor, persiste (`Salvar & Fechar`) e valida que os handles somem no runtime.
+8. Valida gesto real: arrastar pelo titulo reordena; arrastar pelo icone visual de drag tambem reordena.
+9. Executa o mesmo gesto com `prefers-reduced-motion: reduce`, validando transicoes desativadas e reorder funcional.
+
+## Como executar
+
+1. Suba a aplicacao:
+   - `npm start`
+2. Em outro terminal:
+   - `tools/e2e/playwright/run-praxis-table-column-drag.sh`
+
+Pre-requisito:
+
+- `@playwright/test` instalado no workspace (`npm install -D @playwright/test`).
+
+Variaveis opcionais:
+
+- `PLAYWRIGHT_BASE_URL` (default: `http://127.0.0.1:4003`)
+- `PLAYWRIGHT_CHROMIUM_EXECUTABLE` (override do binario Chromium)
+- `PLAYWRIGHT_USE_WEB_SERVER=1` (delega start/stop do server ao Playwright usando `tools/e2e/playwright/start-filter-demo-server.sh`)
+
+## Captura de evidencia visual (before/after)
+
+1. BEFORE:
+   - `EVIDENCE_OUT_DIR=artifacts/praxis-table/filter-demo-drag-affordance/before node node_modules/playwright/cli.js test --config tools/e2e/playwright/praxis-table-column-drag.playwright.config.ts projects/praxis-table/test-dev/e2e/column-drag-visual-evidence.playwright.spec.ts`
+2. AFTER:
+   - `EVIDENCE_OUT_DIR=artifacts/praxis-table/filter-demo-drag-affordance/after node node_modules/playwright/cli.js test --config tools/e2e/playwright/praxis-table-column-drag.playwright.config.ts projects/praxis-table/test-dev/e2e/column-drag-visual-evidence.playwright.spec.ts`
+
+Artefatos gerados por run:
+
+- `01-full-page.png`
+- `02-component-table.png`
+- `03-bug-element-crop.png`
+- `04-dom-dump-header-cell.json`
+- `05-computed-styles-handle.json`
+
+## Notas enterprise
+
+- O teste usa seletor funcional (settings button + switches + handles) e valida efeito final (ordem de colunas), nao apenas classes CSS.
+- O contrato de UX fica coberto em pontos criticos de governanca: default seguro, opt-out no editor, cursor como affordance principal, discoverability do grip e modo de movimento reduzido.
+- Em `pointer: coarse`, o grip permanece visivel em baixa opacidade para melhorar discoverability sem voltar ao padrao de botao circular.
+- Seletores E2E sao locale-agnostic com `data-testid` estavel (evita flake por traducao/copy).
+- O runner tenta usar Chromium do sistema para reduzir dependencia de download de browser no CI.