@praxisui/table 10.0.0-rc.37 → 10.0.0-rc.39

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.