@praxisui/table 10.0.0-rc.4 → 10.0.0-rc.41

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

@@ -42,7 +42,7 @@ 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"
+last_updated: "2026-10-27"
 ---
 
 # Dynamic Filter Host Integration Guide
@@ -108,6 +108,28 @@ O host precisa garantir que a fonte de metadata do filtro e o backend estejam al
 
 Sem isso, o runtime até renderiza o formulário, mas o payload não será previsível.
 
+### Projetar tipos e validar antes de buscar/salvar
+
+Para filtros escalares em array, mantenha `items`/`enumValues` do schema de operação
+nos metadados dos campos. `items` descreve tipo, formato e enum dos itens; não
+substitui o schema de uma coleção de objetos. O normalizador compartilhado de Core
+interpreta somente os tokens admitidos por esse contrato, sem parser específico no
+host ou no controle de filtro.
+
+Use os payloads de `change`/`submit` do componente. O caminho avançado/modal usa a
+projeção do `PraxisFilterForm` filho ao aplicar e salvar, em vez de ler valores raw
+que podem conter strings de UI ou campos com política de omissão. O merge com
+`initialDto` para um atalho é novamente projetado para não restaurar campos
+omitidos. Campos sempre visíveis e avançados seguem a mesma regra; salvar um
+atalho não altera o contrato do backend.
+
+Grupos inválidos/pendentes ou tokens fora do tipo/enum não emitem busca nem atalho,
+e um debounce anterior também precisa respeitar o estado atual. Preserve o
+rascunho para correção. Sem filtros ativos, o DTO vazio pode representar limpeza;
+não transformar o status `DISABLED` desse grupo vazio em bloqueio de clear. Essas
+regras não tornam `contextChange` um DTO: somente sua propriedade `filter` contém
+a consulta; labels e metadata permanecem evidência de apresentação.
+
 ### 2. Configurar `advancedFilters.settings`
 
 Essas chaves são as mais importantes na prática:
@@ -231,6 +253,27 @@ Os eventos principais para integração são:
 - `selectedFieldIdsChange`: acompanha customização de campos visíveis;
 - `metaChanged` e `schemaStatusChange`: importantes para observabilidade e reconciliação de schema.
 
+### 5. Teleporte da barra de filtros para `<praxis-scope-bar>` ou container externo
+
+Em páginas orientadas a recurso (`<praxis-resource-page>` ou `<praxis-crud>`), os filtros inline (`alwaysVisibleFields` / `inlineFields`) e o acionador de filtros avançados podem ser exibidos na barra de ferramentas da tabela (`placement: 'table-toolbar'`, padrão) ou teleportados para dentro do card superior `<praxis-scope-bar>` (`placement: 'scope-bar'` ou `scopeBar.includeInlineFilters: true`):
+
+```ts
+export const FOLHA_PAGAMENTO_CRUD_METADATA: CrudMetadata = {
+  component: 'praxis-crud',
+  resource: { path: 'human-resources/folhas-pagamento', idField: 'id' },
+  filterBar: {
+    placement: 'scope-bar',
+    inlineFields: ['mesBetween', 'anoBetween', 'funcionarioId', 'salarioLiquidoBetween'],
+  },
+  // ...
+};
+```
+
+Quando `placement: 'scope-bar'` está ativo:
+- O `<praxis-table>` ativa `filterTeleport`, suprimindo a renderização duplicada na toolbar interna e expondo o `TemplateRef` reativo via `filterTemplateSignal`.
+- O `<praxis-resource-page>` projeta `<praxis-filter-outlet scope-bar-filters [target]="crudSurface()" />` na segunda faixa dedicada (`.prx-scope-bar__filters`) do `<praxis-scope-bar>`.
+- Os chips de escopo rápido (`quickFilters`) e os controles inline operam sobre o mesmo DTO de filtro com sincronização bidirecional (`filterCriteriaChange`), preservando filtros ortogonais preenchidos pelo operador ao alternar entre escopos rápidos.
+
 ## Exemplo mental de integração
 
 O fluxo típico é:

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

@@ -33,7 +33,6 @@ related_docs:
   - "dynamic-filter-range-filters-guide"
   - "dynamic-fields-inline-components-guide"
   - "dynamic-fields-inline-filter-runtime-contract"
-  - "table-overview"
 keywords:
   - "submit"
   - "change"
@@ -42,11 +41,9 @@ keywords:
 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"
+  - "projects/praxis-table/src/lib/components/praxis-filter/filter-payload-projection.ts"
+  - "projects/praxis-core/src/lib/helpers/scalar-array-value.ts"
+last_updated: "2026-10-27"
 ---
 
 # Dynamic Filter Payload Contract
@@ -131,6 +128,32 @@ Aspectos relevantes do runtime:
 - 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.
 
+### Arrays escalares, enum e campos omitidos
+
+O schema de operação pode publicar um array escalar com `items`, por exemplo
+`{ "type": ["array", "null"], "items": { "type": "integer" } }` para um operando
+`IN`. Core conserva `FieldScalarItemsSchema` em `FieldMetadata.items`; o mesmo
+`normalizeScalarArrayValue` valida e converte tokens na projeção do payload.
+`array.itemSchema.fields`, usado para coleções de objetos, é um contrato distinto.
+
+A projeção interna de Table alcança os campos sempre visíveis, o painel avançado,
+`change`, `submit` e atalhos salvos. Ela conserva o shape flat ou aninhado do DTO,
+aplica `submitPolicy: "omit"` e as constraints `items`/`enumValues` publicadas, sem
+modificar o rascunho. Para um request com container, o payload pode ser
+`{ "customFields": { "years": [2024, 2025, 2026] } }`; números não viram datas por
+terem três posições e labels não viram valores de consulta.
+
+Tokens inválidos, valor fora do enum e grupos inválidos/pendentes impedem a emissão,
+inclusive de um debounce agendado antes da invalidez. Não há descarte parcial de
+itens inválidos. `null`/ausência do container e `[]` opcionais não significam que um
+item `null` seja válido. Um grupo sem filtros ativos e `DISABLED` pode produzir a
+limpeza intencional do filtro; isso não equivale a autorizar emissão de um grupo
+com campos ativos inválidos.
+
+O host deve consumir a projeção emitida, não reconstruir o DTO a partir de
+`getRawValue()`, chips ou labels. O backend continua validando o DTO e a operação;
+validação no browser não concede autorização nem certifica execução da consulta.
+
 ### 2. Envio HTTP
 
 O host é responsável por:

package/docs/governed-page-widget-adapter.md

@@ -0,0 +1,55 @@
+# Table em páginas governadas
+
+O adapter do owner mantém `definition.inputs.config` como a única fonte de configuração do filho.
+A página guarda autoria; o documento nativo é reconstruído a partir desses inputs. A projeção de
+execução é transitória e nunca deve ser gravada de volta no documento da página.
+
+O perfil inicial vem do contrato P0 `page-publication-p0` de `praxis-config-starter` (PR #506).
+Core valida estrutura, referências, limites e exige validators dos owners. Este adapter valida o
+perfil nativo local; não autoriza uma fonte, registra uma seed ou substitui a admissão no servidor.
+
+`decodeTablePageInputs` reconstrói `praxis.table.editor` v1 com config e somente os bindings
+presentes (`resourcePath`, `horizontalScroll`). `resourcePath: null` é desconexão explícita;
+ausência não é desconexão. Config precisa ser autoria compacta: `columns: []` e
+`columnProjection.source: 'schema'`. Null em qualquer nível de config é negado.
+
+`encodeTablePageInputs` é a projeção inversa sem defaults. Campos fora do perfil,
+blocos vazios sem representação nos inputs, identidade/storage e dados de execução recebem
+diagnóstico. O adapter não filtra silenciosamente autoria incompatível.
+
+`projectTablePageEditorChanges(authoredInputs, editorBaseline, editorValue)` aplica apenas
+deltas explícitos sobre a autoria original usando o reconciliador nativo do owner. Capture o
+baseline após a normalização/montagem do editor e preserve-o durante aquela sessão. Alterar
+bindings ou contexto do mesmo widget retorna `seed.replacement-required`; a página precisa
+substituir o widget com nova key e nova fonte admitida. A API de projeção altera somente o draft
+que o chamador recebe; ela não salva preferências nem persiste a página.
+
+`materializeTablePageRuntimeInputs(inputs, pageId, widgetKey)` usa o helper canônico Core para
+identidades `page:<pageId>:widget:<widgetKey>`, projeta `configPersistenceStrategy: 'volatile'`
+e desabilita customização/copiloto independentes no filho. Submit e dados continuam nos contratos
+de domínio existentes. Não existe input runtime `authoringDocument`.
+
+A estratégia `volatile` impede leitura, gravação e limpeza de preferências próprias e conexão
+persistida. Table também repassa o `disablePersistence` existente ao filtro embutido e impede
+reset por chave do filtro; largura, densidade e outros ajustes não escrevem preferências.
+Defaults visuais/materializações transitórias permanecem internos ao runtime e ao editor.
+
+Limites: JSON lossless, 256 KiB UTF-8 e profundidade 64 pelo helper Core compartilhado; o documento
+integral da página também tem o mesmo orçamento. Não há host publicado, endpoint de publicação,
+fonte admitida, banco ou release novos neste incremento. A integração Page Builder/host governado
+é trabalho posterior; os wrappers comuns continuam atendendo os fluxos não governados existentes.
+
+`volatile` também exclui overlays pessoais de configuração global nos defaults/estado de autoria
+que o owner consome. A instância compartilhada `GlobalConfigService` pode ler sua chave global;
+isso não é prova de zero leitura na aplicação. Tenant, cache, locale e CSP continuam infraestrutura
+do host. O gate comprova ausência de I/O nas chaves do filho e ausência de influência da autoria
+pessoal sobre a configuração publicada. Em Table, `TableDefaultsProvider.getDefaults(id,
+{ includeGlobal: false })` preserva defaults nativos sem duplicá-los; mudanças globais e reset
+seguem a mesma política, inclusive o fallback de timezone usado em regras JSON Logic.
+
+Native Table diagnostics historically use dot paths without escaping dynamic override field names.
+For those diagnostics, the page adapter deliberately points to the exact `columnProjection.overrides`
+ancestor rather than inventing a JSON Pointer by splitting a field such as `a.b` or `a[0]`.
+The diagnostic code still names the rejected native constraint.
+
+Respostas e filas de preferências capturam a geração, a identidade e a estratégia do filho. Trocar identidade, documento ou estratégia (inclusive A → volatile → A), ou destruir a instância, invalida a continuação antiga antes do próximo I/O ou da materialização. Uma requisição já enviada não é cancelada retroativamente. Respostas tardias de erro também passam pelo mesmo fence.

package/docs/local-data-mode-precedence.md

@@ -11,6 +11,27 @@ Regras de conflito:
 - `resourcePath` + `data` ao mesmo tempo resolve para `remote`.
 - Limpar `document.bindings.resourcePath` no documento autorado é a forma explícita de remover a conexão remota via editor.
 
+## Estratégia contextual de paginação e ordenação
+
+`pagination.strategy` e `sorting.strategy` são opcionais. Quando ausentes, o
+runtime usa `server` para uma origem remota e `client` para dados locais. Os
+defaults compartilhados e o reset dos editores preservam essa ausência; não
+transformam uma configuração parcial em uma escolha explícita de cliente.
+
+Os editores apresentam **Automática (pela fonte de dados)**. Essa opção
+remove a propriedade do documento. As únicas estratégias públicas continuam
+sendo `client` e `server`; não existe um valor serializado `auto`. Uma escolha
+explícita é preservada, respeitando as restrições e diagnostics do modo local.
+Uma operação parcial de authoring que omite a estratégia mantém uma escolha
+anterior; omissão em um patch não significa limpar essa escolha.
+
+Na paginação remota, o total vem da resposta do backend. O paginator e o sort
+cliente do `MatTableDataSource` não devem ser anexados nessa estratégia, pois
+seus callbacks assíncronos podem substituir o total pela quantidade de registros
+da página e voltar o índice para zero. A prova deve aguardar esses callbacks e
+as materializações de capabilities, navegar à segunda página e confirmar que o
+total e o intervalo continuam corretos. Uma captura intermediária não basta.
+
 ## Ciclo da primeira consulta remota
 
 Quando `resourcePath`, `config` e `queryContext` chegam no primeiro ciclo de inputs, o