@praxisui/editorial-forms

@praxisui/editorial-forms

Lib dedicada ao runtime de formularios editoriais da plataforma.

Documentacao principal

• docs/architecture.md
• docs/continuation-plan.md
• docs/editorial-authoring-plan.md
• docs/event-registration-promotion-plan.md
• docs/employee-onboarding-promotion-plan.md
• docs/privacy-consent-promotion-plan.md
• docs/recovery-playbook.md
• docs/dynamic-form-hygiene-plan.md

Objetivo

Esta lib existe para tratar formularios editoriais como dominio proprio:

• jornadas
• presets
• blocos semanticos
• contexto editorial
• compliance
• runtime especializado

Ela nao deve usar FormConfig como modelo principal de authoring.

Regra arquitetural principal

Permitido:

• @praxisui/editorial-forms -> @praxisui/core
• @praxisui/editorial-forms -> @praxisui/dynamic-form apenas em adaptador/provider opcional

Proibido:

• @praxisui/core -> @praxisui/editorial-forms
• crescimento do dominio editorial central em @praxisui/dynamic-form

Adaptador opcional para dataCollection

O runtime central nao embute PraxisDynamicForm.

Para blocos dataCollection, a lib agora expoe:

• contrato raiz EditorialDataBlockAdapter
• token multi EDITORIAL_DATA_BLOCK_ADAPTER
• provideEditorialDataBlockAdapter(...)
• EditorialDataBlockAdapterRegistry
• outlet do renderer que resolve formBlockId e delega para o adaptador registrado

Para consolidacao do motor editorial, a lib agora expoe tambem:

• EditorialRuntimeInput
• EditorialRuntimeHostConfig
• EditorialRuntimeSnapshot
• EditorialResolvedJourney
• EditorialResolvedStep
• EditorialResolvedBlock
• EditorialRuntimeDiagnostic
• EditorialRuntimeOperationalEvent
• resolveEditorialRuntimeSnapshot(...)

Nesta fase, o themePreset entra no snapshot como preset efetivo de shell/metadados.

Ele ainda nao e tratado como origem de bloco nem materializa blocos por si so.

O snapshot resolvido agora tambem formaliza:

• proveniencia auditavel por bloco com primarySource e trail
• politica deterministica de override da instance (append, insertBefore, insertAfter, replace, remove)
• estado resolvido de dataCollection antes da engine concreta via dataCollectionState

O runtime atual distingue:

• erro global de runtime
• erro contextual de jornada/etapa/bloco

E aplica bloqueio coerente de avanço/navegacao lateral relevante quando existe erro estrutural bloqueador.

A politica de fallback operacional agora e derivada por helper central e reutilizavel:

• normal
• warning
• degraded
• blocked

Para hosts corporativos, EditorialFormRuntimeComponent e o outlet de dataCollection expõem operationalEvent com eventos leves de observabilidade, incluindo:

• diagnosticos emitidos
• fallback alterado
• erro bloqueador detectado
• conflito de override
• adapter de dataCollection resolvido, ausente ou invalido

Contrato estavel para hosts

Inputs estaveis do EditorialFormRuntimeComponent:

• solution
• instance
• runtimeContext
• hostConfig

Outputs estaveis:

• snapshotChange
• fallbackChange
• operationalEvent

Politica de consumo para hosts de produto:

• snapshotChange e o sinal estavel para leitura de estado resolvido, auditoria e derivacao de UX de produto
• fallbackChange e o sinal estavel para status operacional exposto ao usuario (normal, warning, degraded, blocked)
• operationalEvent e telemetria tecnica leve para logs, monitoracao, debugging e runbooks do host
• hosts controlados e de produto nao devem depender de parse de DOM para observabilidade
• hosts de produto nao devem expor o stream bruto de operationalEvent na superficie principal da pagina

Politica de fallback para hosts de produto:

• normal: UX nominal; sem contingencia adicional
• warning: UX nominal com monitoramento; nao bloquear progressao
• degraded: UX com contingencia parcial; manter o fluxo quando possivel e encaminhar observabilidade interna
• blocked: UX indisponivel ou bloqueada; impedir progressao e acionar canal de suporte/rollback do host

hostConfig hoje controla:

• emitOperationalEvents
• forwardAdapterOperationalEvents

operationalEvent segue envelope estavel com:

• eventType
• timestamp
• severity
• journeyId/stepId/blockId quando aplicavel
• payload tipado por tipo de evento

Quando o host quiser reutilizar @praxisui/dynamic-form, o caminho e registrar o provider opcional:

import { provideEditorialDynamicFormAdapter } from '@praxisui/editorial-forms';
import { PraxisDynamicForm } from '@praxisui/dynamic-form';

providers: [
  provideEditorialDynamicFormAdapter({ component: PraxisDynamicForm }),
];

Decisao de superficie publica desta fase:

• factory createEditorialDynamicFormAdapter(...)
• provider provideEditorialDynamicFormAdapter(...)
• exportados pelo pacote raiz @praxisui/editorial-forms
• documentados assim para evitar ambiguidade sobre sub-entrypoint, que nao foi mantido nesta iteracao

Sem esse provider, blocos dataCollection degradam para fallback acessivel e informativo no runtime editorial.

Mesmo sem provider, o snapshot ja deixa claro:

• formBlockId
• formConfigRef
• se existe config inline
• origem da config resolvida
• prontidao do bloco (requiresAdapter, missingConfig, invalid)

Politica deterministica atual de resolucao de config para dataCollection:

• block.formConfig
• instance.overrides.runtimeFormConfigs
• instance.compatibilityFormConfigs

Regras complementares:

• quando formConfigRef e formBlockId apontarem para candidatos diferentes, a primeira correspondencia valida na ordem acima continua sendo aplicada
• quando mais de uma fonte candidata for encontrada, o runtime nao falha silenciosamente: ele mantem a selecao deterministica e emite diagnostico data-collection-config-ambiguous
• resolvedFormConfigSource e resolvedFormConfigLookupKey continuam sendo a referencia auditavel para o host

Validacao oficial no workspace atual

A lib possui specs automatizados para o resolvedor, para o componente de runtime e para os hosts controlados.

Comando oficial da suite da lib:

• node ./node_modules/@angular/cli/bin/ng.js test praxis-editorial-forms --watch=false --progress=false --browsers=ChromiumHeadlessNoSandbox

Validacao minima de retomada:

• npm run build:praxis-core
• npm run build:praxis-editorial-forms
• npm run typecheck

Criterio completo desta fase:

• suite da lib via ChromiumHeadlessNoSandbox
• specs dos hosts controlados no app
• Playwright do runtime editorial em host real

No workspace atual, a fase de runtime/integrations controladas foi fechada tambem com E2E reais de host:

• editor tecnico integrado em /form-config-editor:
  • bateria Playwright consolidada com 22 passed
• runtime editorial em host real:
  • /lab/editorial-runtime
  • /experiments/editorial-runtime/privacy-consent
  • /experiments/editorial-runtime/event-registration
  • /experiments/editorial-runtime/employee-onboarding
  • bateria Playwright consolidada com 8 passed

Cobertura complementar de pagina no host Angular:

• privacy-consent-editorial-runtime.page.spec.ts
  • valida solutionId, jornada privacy-consent-journey, labels de step e consent-form
  • valida degradacao com diagnostico data-collection-adapter-missing
  • valida reativacao com evento data-collection-adapter-resolved
• event-registration-editorial-runtime.page.spec.ts
  • valida solutionId, jornada event-registration-journey, labels de step e registration-form
  • valida degradacao com diagnostico data-collection-adapter-missing
  • valida reativacao com evento data-collection-adapter-resolved
• employee-onboarding-editorial-runtime.page.spec.ts
  • valida solutionId, jornada employee-onboarding-journey e os dois blocos dataCollection
  • valida identity-form e operations-form como blocos resolvidos no snapshot
  • valida degradacao com diagnostico data-collection-adapter-missing
  • valida reativacao com evento data-collection-adapter-resolved

Harness tecnico interno

Para validar o motor sem depender do app principal, a lib agora possui:

• fixtures tecnicas em src/lib/testing/editorial-runtime.fixtures.ts
• harness interno em src/lib/testing/editorial-runtime-technical-harness.component.ts

Esse harness existe para specs e verificacao tecnica da lib:

• resolution de journey/snapshot
• diagnostics
• fallback
• adapter resolution de dataCollection

Ordem correta de build para retomadas e validacao local:

• npm run build:praxis-core
• npm run build:praxis-editorial-forms
• npm run typecheck

Integracao controlada no host Angular

Agora existe uma rota tecnica isolada no app do workspace para validar consumo real do host:

• path: /lab/editorial-runtime

Essa rota:

• nao e feature final
• nao e showcase publico de produto
• existe para validar integracao host-runtime em Angular real

Ela exercita:

• fixture saudavel
• fixture com warning
• fixture com erro global
• dataCollection sem adapter
• dataCollection com adapter opcional registrado

E expõe de forma tecnica:

• resumo do snapshot recebido via snapshotChange
• fallback recebido via fallbackChange
• stream recente de operationalEvent

Para validar localmente a integracao:

• npm run build:praxis-core
• npm run build:praxis-editorial-forms
• npm run typecheck
• npm run build -- --configuration development

Primeiro caso experimental quase real

Agora existe tambem uma rota experimental isolada para o primeiro caso editorial real no novo runtime:

• path: /experiments/editorial-runtime/privacy-consent

privacy-consent foi escolhido primeiro porque:

• e o caso mais enxuto e regulatorio do catalogo editorial novo
• permite validar dataCollection com menor variabilidade de jornada
• reaproveita o catalogo editorial canonico sem recolocar FormConfig no centro do motor

Essa rota deixa explicito:

• rota antiga relacionada: /legacy/privacy-consent-template
• rota nova experimental: /experiments/editorial-runtime/privacy-consent
• a rota nova consome getEditorialSolutionById('privacy-consent')
• o host fornece runtimeContext, hostConfig, snapshotChange, fallbackChange e operationalEvent
• o adapter opcional de dataCollection pode ser ligado ou desligado localmente para validar o comportamento real do host

Essa pagina:

• nao substitui o demo legado
• nao representa UX final de produto
• nao substitui o laboratorio tecnico /lab/editorial-runtime

Primeira superficie tecnica da fase de authoring:

• /lab/editorial-authoring

Terceiro caso experimental quase real

Agora existe tambem uma terceira rota experimental isolada para o fluxo mais complexo entre os casos canônicos atuais:

• path: /experiments/editorial-runtime/employee-onboarding

employee-onboarding foi escolhido como terceiro passo porque:

• possui dois blocos dataCollection (identity-form e operations-form)
• amplia a validacao do runtime em jornada multi-step com mais variabilidade operacional
• mantem comparacao simples com o demo legado /demo/employee-onboarding-template

Essa rota deixa explicito:

• rota antiga relacionada: /demo/employee-onboarding-template
• rota nova experimental: /experiments/editorial-runtime/employee-onboarding
• a rota nova consome getEditorialSolutionById('employee-onboarding')
• o host fornece runtimeContext, hostConfig, snapshotChange, fallbackChange e operationalEvent
• o host deriva dois runtimeFormConfigs locais a partir do template legado apenas para alimentar identity-form e operations-form
• o adapter opcional de dataCollection pode ser ligado ou desligado localmente para validar o comportamento real do host

Estado de saida da fase

A fase de runtime/integrations controladas fica considerada concluida neste estado porque agora existe:

• runtime editorial com snapshot, fallback e telemetria operacional estaveis
• laboratorio tecnico isolado em /lab/editorial-runtime
• tres integracoes quase reais e isoladas:
  • /experiments/editorial-runtime/privacy-consent
  • /experiments/editorial-runtime/event-registration
  • /experiments/editorial-runtime/employee-onboarding
• validacao E2E do editor tecnico que ainda serve de engine adaptada para dataCollection
• validacao E2E das rotas editoriais experimentais e do laboratorio tecnico

Esta conclusao de fase nao significa rollout de produto.

O que continua fora de escopo nesta etapa:

• promover as rotas experimentais para feature final
• substituir os demos legados
• criar o editor especialista de autoria editorial

O proximo salto arquitetural passa a ser:

• criterios de promocao dos experimentos
• endurecimento operacional residual
• editor especialista para autoria editorial

Criterio de promocao dos experimentos

No estado atual, os tres fluxos integrados permanecem experimentais.

Promocao para migracao oficial exige, no minimo:

• build/typecheck do workspace verdes
• validacao Playwright do editor tecnico e do runtime editorial verdes
• snapshotChange, fallbackChange e operationalEvent observaveis em host real
• dataCollection validado sem adaptador e com adaptador
• ausencia de regressao para centralidade de FormConfig
• definicao de fallback/observabilidade da UX final

Leitura operacional atual:

• privacy-consent: primeiro candidato a promocao
• event-registration: segundo candidato
• employee-onboarding: caso de robustez antes de rollout

Primeiro host de promocao controlada ja criado:

• /privacy-consent
• /controlled/editorial-runtime/privacy-consent

Esse host:

• reaproveita o runtime editorial validado
• remove inspector e toggles manuais do experimento
• mantem observabilidade operacional discreta
• assume o caminho principal do fluxo
• mantem a rota experimental
• mantem o legado apenas como contingencia explicita em /legacy/privacy-consent-template

Essa pagina:

• nao substitui o demo legado
• nao representa UX final de produto
• nao substitui o laboratorio tecnico /lab/editorial-runtime

Segundo caso experimental quase real

Agora existe tambem uma segunda rota experimental isolada para ampliar a validacao em um fluxo com mais narrativa e mais blocos semanticos:

• path: /experiments/editorial-runtime/event-registration

event-registration foi escolhido como segundo passo porque:

• continua tendo apenas um bloco dataCollection, reduzindo risco em relacao a employee-onboarding
• exercita melhor a combinacao de hero, contextSummary, legalNotice, reviewSummary e footerLinks
• mantem comparacao simples com o demo legado /demo/event-registration-template

Essa rota deixa explicito:

• rota antiga relacionada: /demo/event-registration-template
• rota nova experimental: /experiments/editorial-runtime/event-registration
• a rota nova consome getEditorialSolutionById('event-registration')
• o host fornece runtimeContext, hostConfig, snapshotChange, fallbackChange e operationalEvent
• o adapter opcional de dataCollection pode ser ligado ou desligado localmente para validar o comportamento real do host

Essa pagina:

• nao substitui o demo legado
• nao representa UX final de produto
• nao substitui o laboratorio tecnico /lab/editorial-runtime