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

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

@@ -231,6 +231,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/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