@praxisui/dynamic-form 8.0.0-beta.2 → 8.0.0-beta.21

package/src/lib/json-config-editor/form-json-config-editor.json-api.md

@@ -0,0 +1,491 @@
+---
+title: "form-json-config-editor JSON API (Canonical)"
+slug: "form-json-config-editor-json-api"
+doc_type: "api-reference"
+component: "form-json-config-editor"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do componente form-json-config-editor."
+category: "components"
+sub_category: "config-editor"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+source_of_truth:
+  - "projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts"
+  - "projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts"
+  - "projects/praxis-dynamic-form/src/lib/services/form-config.service.ts"
+  - "projects/praxis-core/src/lib/models/form/form-config.model.ts"
+source_of_truth_last_verified: "2026-03-05"
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "form-json-config-editor"
+api_stability: "canonical"
+schema_verified: true
+runtime_verified: false
+editor_coverage_verified: false
+runtime_scope: "public"
+legacy_paths_present: false
+has_known_mismatches: false
+related_components:
+  - "praxis-table"
+---
+
+# form-json-config-editor
+
+Este documento e a referencia canonica da API JSON de form-json-config-editor.
+
+## Summary
+
+- Tipo documental: API reference canonica de contrato JSON.
+- Source of truth: runtime e codigo declarados no frontmatter.
+- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
+- Resumo funcional herdado: `form-json-config-editor` e a superficie de edicao JSON direta para `FormConfig`. Ele oferece validacao local, formatacao, aplicacao manual de JSON e eventos de telemetria do editor.
+
+## Scope and positioning
+
+- Escopo: contrato JSON publico e limites de comportamento observavel.
+- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
+- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.
+
+## Source of truth
+
+| Source | Kind | Notes |
+| --- | --- | --- |
+| projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-dynamic-form/src/lib/services/form-config.service.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-core/src/lib/models/form/form-config.model.ts | runtime-code | Source de implementacao declarado no repositorio. |
+
+## Support legend
+
+- Active: suportado e observado no runtime atual.
+- Partial: suporte parcial, com restricoes conhecidas.
+- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
+- Schema-only: presente em schema/modelo sem confirmacao de execucao.
+- Deprecated: mantido por compatibilidade legada com migracao prevista.
+
+## Contract classification
+
+### Canonical paths (public contract)
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `FormConfig \| null` | No | `null` | Active | Payload principal editado/aplicado pelo componente. |
+| `hooks.beforeValidate[]` | array | No | `[]` | Partial | Inserido por helper `insertHooksTemplate()` quando usado. |
+| `hooks.beforeSubmit[]` | array | No | `[]` | Partial | Inserido por helper `insertHooksTemplate()` quando usado. |
+| `behavior.reactiveValidation` | boolean | No | component-defined | Partial | Ativado por helper `enableReactiveValidation()`. |
+| `behavior.reactiveValidationDebounceMs` | number | No | `200` (helper) | Partial | Configurado apenas quando helper é acionado. |
+
+### Supported legacy paths
+
+Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.
+
+### Internal-only paths
+
+| Path | Internal consumer | Runtime presence | Public support | Notes |
+| --- | --- | --- | --- | --- |
+| `jsonText` (estado interno) | editor textarea/runtime validation | Yes | No | Buffer temporário da edição textual, não persistido no contrato público. |
+| `jsonTextChanges$` | pipeline debounce/validação | Yes | No | Subject interno para validação em 300ms. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| `hooks.beforeValidate[]` (inserção assistida) | ação manual `insertHooksTemplate()` | Partial | Não é aplicado automaticamente; depende de interação do usuário | Helper de produtividade, sem garantia de aderência semântica do hook. |
+
+## Overview
+
+Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.
+
+## Public contract surface
+
+### Top-level configuration blocks
+
+| Block | Purpose | Required | Merge strategy | Notes |
+| --- | --- | --- | --- | --- |
+| `config` | Snapshot do `FormConfig` em edição | No | replace-object on apply | Fonte vem de input ou `FormConfigService.currentConfig`. |
+| `hooks` | Bloco de hooks (opcional) | No | deep-merge helper-driven | Pode ser enriquecido por templates de ajuda. |
+| `behavior` | Regras comportamentais do form | No | deep-merge helper-driven | Pode receber `reactiveValidation` por helper. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `hooks.beforeValidate[]` | array | No | `[]` | hook-contract | Inserido por helper com dedupe básico por conteúdo. |
+| `hooks.beforeSubmit[]` | array | No | `[]` | hook-contract | Inserido por helper com dedupe básico por conteúdo. |
+| `behavior.reactiveValidation` | boolean | No | false | boolean | Ativado por helper de validação reativa. |
+| `behavior.reactiveValidationDebounceMs` | number | No | `200` | integer >= 0 | Preenchido quando ausente pelo helper. |
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `FormConfig \| null` | No | component-input/service | `JSON.stringify(config, null, 2)` | Se ausente, usa `FormConfigService.currentConfig`. |
+
+### Output events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. | Partial | Preservado da documentação anterior. |
+| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). | Partial | Preservado da documentação anterior. |
+| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. | Partial | Preservado da documentação anterior. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| `FormConfigService.currentConfig` | inbound | `FormConfig` snapshot | fail-soft | Fonte inicial quando `@Input() config` não é fornecido. |
+| `FormConfigService.validateConfig()` | outbound validate | `FormConfig -> string[]` | reject invalid apply | Base canônica de validação estrutural/semântica. |
+| `FormConfigService.loadConfig()` | outbound apply | `FormConfig` | fail-closed por try/catch | Atualiza estado global de configuração após apply válido. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| `FormConfigService` | Yes | browser/dev/prod/ssr | validação + apply | Serviço central para validar e carregar config. |
+| `ChangeDetectorRef` | Yes | browser/dev/prod/ssr | atualização visual | Atualiza estado de validação/formatação no editor. |
+| `rxjs` (`debounceTime`) | Yes | browser/dev/prod/ssr | pipeline de validação | Debounce fixo de 300ms para texto em edição. |
+
+## Coverage matrix
+
+| Surface | Verified | Coverage status | Evidence | Notes |
+| --- | --- | --- | --- | --- |
+| Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
+| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
+| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |
+
+## Runtime coverage boundaries
+
+- Cobertura consolidada com base em documentacao existente e source of truth declarado.
+- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
+- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.
+
+## Resolution model
+
+### Merge order
+
+1. `@Input() config` (quando presente)
+2. fallback para `FormConfigService.currentConfig`
+3. edição textual (`jsonText`) com validação incremental
+4. apply explícito (`applyJsonChanges`) substitui snapshot no serviço
+
+### Fallback order
+
+`config` input -> `FormConfigService.currentConfig` -> objeto vazio serializado (`{}`) em caso de falha de stringify.
+
+### Override points
+
+- `@Input() config`
+- ações de toolbar do editor (`applyJsonChanges`, `formatJson`, helpers)
+- estado compartilhado via `FormConfigService`
+
+### Runtime normalization
+
+- `JSON.stringify(..., null, 2)` padroniza saída formatada.
+- `validateJson()` força contrato de objeto JSON antes de qualquer apply.
+- helpers inserem blocos mínimos (`hooks`, `behavior`) com dedupe básico.
+
+### Precedence rules
+
+- `@Input() config` tem precedência sobre `currentConfig` na inicialização.
+- `applyJsonChanges()` só executa quando `isValidJson=true`.
+- `formatJson()` não altera estado quando JSON está inválido.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| texto vazio | pre-parse | reject | `JSON não pode estar vazio` | Atualiza `validationChange` e `editorEvent(validation)`. |
+| parse JSON | parse | reject | `Erro de sintaxe JSON` | Captura erro de parse e mantém `isValidJson=false`. |
+| raiz não-objeto | semantic | reject | `Configuração deve ser um objeto` | Arrays/primitivos não são aceitos como contrato raiz. |
+| `validateConfig(parsed)` | semantic | reject | `errors.join('; ')` | Usa `FormConfigService` como autoridade de validação. |
+| apply inválido | apply | no-op | `Erro ao aplicar configuração JSON` | Emite `editorEvent(type='apply')` com `isValid=false`. |
+
+### Error semantics
+
+Validação e apply são fail-closed: payload inválido não é aplicado no serviço. O componente mantém estado editável e reporta erros via `validationChange` e `editorEvent`.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| JSON inválido durante edição | fail-closed para apply | bloqueia `applyJsonChanges()` | evita propagar config inconsistente |
+| erro em `JSON.stringify` inicial | fail-open | usa `'{}'` no editor | editor permanece utilizável |
+| erro em `formatJson` | fail-soft | mantém texto atual e emite evento de erro | sem perda automática de conteúdo |
+| erros de validação de contrato | fail-closed para apply | mantém `isValidJson=false` até correção | exige correção explícita antes de aplicar |
+
+### Invalid or unknown field handling
+
+- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
+- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
+- Registrar divergencias observadas em Known limitations and mismatches.
+
+### Runtime warnings vs hard failures
+
+| Condition | Severity | Observability | Consumer action |
+| --- | --- | --- | --- |
+| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |
+
+## Detailed API
+
+### Preserved technical reference (normalized from previous revision)
+
+### 1. Visao Geral e Quando Usar
+`form-json-config-editor` e a superficie de edicao JSON direta para `FormConfig`.
+Ele oferece validacao local, formatacao, aplicacao manual de JSON e eventos de telemetria do editor.
+
+Use quando precisar de:
+- edicao avancada/manual de schema de formulario;
+- validacao continua de JSON com debounce;
+- fluxo explicito de "validar -> aplicar";
+- apoio didatico para hooks e validacao reativa via atalhos no proprio editor.
+
+### 2. Contrato da API
+
+#### 2.1 Inputs
+| Input | Tipo | Padrao | Obrigatorio | Status | Comportamento |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `FormConfig \| null` | `null` | Nao | Active | Se ausente, usa `FormConfigService.currentConfig`. |
+
+#### 2.2 Outputs
+| Output | Payload | Quando emite |
+| --- | --- | --- |
+| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. |
+| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). |
+| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. |
+
+Tipos relevantes:
+
+```ts
+interface JsonValidationResult {
+  isValid: boolean;
+  error?: string;
+  config?: FormConfig;
+}
+
+interface JsonEditorEvent {
+  type: 'apply' | 'format' | 'validation';
+  payload: JsonValidationResult;
+}
+```
+
+### 3. Mapeamento de Comportamento
+- Validacao:
+  - `onJsonTextChange` envia para subject interno com debounce de 300ms.
+  - `validateJson` exige objeto JSON e chama `FormConfigService.validateConfig`.
+- Aplicacao:
+  - `applyJsonChanges` so aplica quando `isValidJson=true`.
+  - Em sucesso: `loadConfig` no service + `configChange` + `editorEvent(type='apply')`.
+- Formatacao:
+  - `formatJson` reformata com `JSON.stringify(parsed, null, 2)`.
+- Helpers de produtividade:
+  - `insertHooksTemplate()` adiciona exemplos em `hooks.beforeValidate/beforeSubmit`.
+  - `enableReactiveValidation()` injeta `behavior.reactiveValidation=true` com debounce padrao.
+
+Cobertura de paths JSON:
+- `Active`: todo objeto que passa em `validateConfig`.
+- `Partial`: validacao estrutural/funcional depende do escopo de regras de `FormConfigService.validateConfig`.
+
+### 4. Exemplo Minimo
+```html
+<form-json-config-editor
+  [config]="formConfig"
+  (validationChange)="onJsonValidation($event)"
+  (configChange)="onJsonApply($event)"
+></form-json-config-editor>
+```
+
+### 5. Exemplo Corporativo (telemetria + gate de aplicacao)
+```ts
+onJsonValidation(result: JsonValidationResult) {
+  this.canApply = result.isValid;
+}
+
+onEditorEvent(event: JsonEditorEvent) {
+  audit.log('form-json-editor', event.type, { valid: event.payload.isValid });
+}
+```
+
+```html
+<form-json-config-editor
+  [config]="workingConfig"
+  (validationChange)="onJsonValidation($event)"
+  (editorEvent)="onEditorEvent($event)"
+  (configChange)="commitDraft($event)"
+></form-json-config-editor>
+```
+
+### 6. Problemas Comuns e Armadilhas
+1. Esperar `configChange` a cada digitacao.
+Correcao: `configChange` so sai em `Aplicar JSON`.
+
+2. Tratar `isValidJson` como garantia de regra de negocio final.
+Correcao: e validacao do contrato local; politica de negocio continua no host/backend.
+
+3. Aplicar JSON sem observar `validationChange`.
+Correcao: use `validationChange` para controlar UX de bloqueio/liberacao.
+
+4. Assumir que `formatJson` corrige erros semanticos.
+Correcao: formatacao so normaliza indentacao; nao corrige contrato invalido.
+
+5. Sobrescrever config corrente sem versionamento/auditoria.
+Correcao: em ambiente corporativo, registre diff e origem antes de persistir.
+
+6. Usar helpers (`insertHooksTemplate`, `enableReactiveValidation`) como contrato final.
+Correcao: sao aceleradores de autoria, nao template normativo obrigatorio.
+
+### 7. Referencias Cruzadas
+- Orquestrador superior: `projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts`
+- Service de validacao/carga: `projects/praxis-dynamic-form/src/lib/services/form-config.service.ts`
+- Modelo base: `projects/praxis-core/src/lib/models/form/form-config.model.ts`
+
+### 8. Premissas
+- O host controla persistencia definitiva do JSON aplicado.
+- O editor nao executa hooks nem simula submit; apenas valida/edita configuracao.
+- Integracao corporativa deve incluir rastreio de alteracoes (quem/quando/o que).
+
+### 9. Relatorio de Validacao Estrutural
+- Visao geral: PASS
+- Inputs/outputs e tipos de evento: PASS
+- Mapeamento de comportamento: PASS
+- Exemplo minimo: PASS
+- Exemplo corporativo: PASS
+- Problemas comuns (>=5): PASS
+- Referencias cruzadas: PASS
+- Premissas explicitas: PASS
+
+## JSON path index
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `$` | `FormConfig` | Yes | `{ "sections": [] }` | Active | Raiz do JSON editado e emitido por `configChange`. |
+| `sections[]` | `FormSection[]` | Conditional | `[]` | Active | Estrutura principal do formulário validada localmente via parse/JSON. |
+| `behavior.reactiveValidation` | `boolean` | No | `false` | Partial | Pode ser inserido pelo helper `enableReactiveValidation()`. |
+| `behavior.reactiveValidationDebounceMs` | `number` | No | `300` | Partial | Usado como sugestão de configuração no helper de validação reativa. |
+| `hooks.*` | `object` | No | n/a | Partial | Pode ser inserido por `insertHooksTemplate()` para acelerar autoria. |
+
+## Events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. | Partial | Preservado da documentação anterior. |
+| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). | Partial | Preservado da documentação anterior. |
+| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. | Partial | Preservado da documentação anterior. |
+
+## Styling API
+
+| Token/Class | Scope | Purpose | Notes |
+| --- | --- | --- | --- |
+| `.json-config-editor` | root container | layout principal do editor JSON | Container flex de alto nível para card + editor. |
+| `.educational-card` | summary card | contexto educacional e status de uso | Card introdutório com destaque visual e orientação de uso. |
+| `.json-editor-toolbar` | toolbar | ações de refresh/format/apply e templates | Barra de ações com fallback responsivo para telas menores. |
+| `.json-textarea` | editor field | edição monoespaçada de JSON | Ajusta fonte, overflow e legibilidade para payloads longos. |
+| `.badge.ok/.err/.warn` | status badges | feedback de validação e alteração | Estado visual de JSON válido/inválido e mudanças pendentes. |
+
+## Editor and tooling notes
+
+- Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
+- Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.
+
+## Examples
+
+### Minimal valid
+
+```json
+{
+  "sections": []
+}
+```
+
+### Typical/common
+
+```json
+{
+  "sections": [
+    {
+      "id": "main",
+      "title": "Dados",
+      "rows": []
+    }
+  ],
+  "actions": []
+}
+```
+
+### Advanced
+
+```json
+{
+  "sections": [],
+  "behavior": {
+    "reactiveValidation": true,
+    "reactiveValidationDebounceMs": 300
+  },
+  "hooks": {
+    "beforeSubmit": [
+      {
+        "type": "custom",
+        "handler": "sanitizePayload"
+      }
+    ]
+  }
+}
+```
+
+### Enterprise scenario
+
+```json
+{
+  "sections": [],
+  "metadata": {
+    "version": "2026.03",
+    "owner": "platform-team"
+  },
+  "behavior": {
+    "reactiveValidation": true,
+    "reactiveValidationDebounceMs": 500
+  },
+  "hooks": {
+    "beforeSubmit": [
+      {
+        "type": "custom",
+        "handler": "auditBeforeSubmit"
+      }
+    ]
+  }
+}
+```
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| none-reported | Nenhum mismatch explícito detectado na evidência preservada. | Manter monitoramento contínuo. | Baixo | n/a | n/a |
+
+## Compatibility and migration notes
+
+| Concern | Affected versions | Migration action | Deadline | Notes |
+| --- | --- | --- | --- | --- |
+| legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |
+
+## Source references
+
+| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
+| --- | --- | --- | --- | --- |
+| local-file | projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-dynamic-form/src/lib/services/form-config.service.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-core/src/lib/models/form/form-config.model.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |