@praxisui/dynamic-form 10.0.0-rc.37 → 10.0.0-rc.39

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

@@ -0,0 +1,58 @@
+# Dynamic Form 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.
+
+`decodeDynamicFormPageInputs` reconstrói `praxis.dynamic-form.editor` v1:
+config, bindings presentes (`mode`, `emptyState`, `presentationModeGlobal`) e contexto presente
+(`backConfig`, `presentation`, `schemaPrefs`). Schema prefs só existe se algum dos três inputs
+`notifyIfOutdated`, `snoozeMs`, `autoOpenSettingsOnOutdated` estiver presente. Ausência, `false`,
+zero, objeto vazio admitido e `null` são preservados. Null em objetos mesclados de config é negado;
+null dentro de arrays atômicos permanece autoria. `layoutScope` não cabe neste perfil.
+
+Os cinco modos nativos são `create`, `edit`, `view`, `presentation` e `dossier`. O editor visual
+continua preferindo os três modos de operação com `presentationModeGlobal` separado. Abrir um
+documento nativo dos demais modos não deve convertê-lo. Filter Form mantém somente seus três modos.
+
+`encodeDynamicFormPageInputs` é 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.
+
+`projectDynamicFormPageEditorChanges(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.
+
+`materializeDynamicFormPageRuntimeInputs(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. O Form preserva identidade operacional para montar o formulário, mas as trilhas de
+config/bindings/contexto/schema preferences ficam sem I/O de storage.
+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.
+
+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.
+
+O fence segue a chave do recurso: conexão, inputs e schema preferences usam identidade do owner e geração do host; apresentação acrescenta a chave `form-pres:<id>:<mode>`. Hidratar mode/path das próprias preferências iniciais não troca o owner. Eventos de inputs do host invalidam a geração e iniciam uma resolução atual. Schema, config e escritas também capturam os bindings de runtime.