@praxisui/editorial-forms 1.0.0-beta.61

package/LICENSE

@@ -0,0 +1,6 @@
+This package is licensed under the Apache License, Version 2.0.
+
+For the full license text, see the repository root LICENSE file:
+../../LICENSE
+
+Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,421 @@
+# @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:
+
+```ts
+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`:
+
+1. `block.formConfig`
+2. `instance.overrides.runtimeFormConfigs`
+3. `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:
+
+1. `npm run build:praxis-core`
+2. `npm run build:praxis-editorial-forms`
+3. `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:
+
+1. `npm run build:praxis-core`
+2. `npm run build:praxis-editorial-forms`
+3. `npm run typecheck`
+4. `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`