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

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "8.0.0-beta.2",
+  "version": "8.0.0-beta.21",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0",
     "@angular/cdk": "^20.0.0",
-    "@praxisui/rich-content": "^8.0.0-beta.2",
-    "@praxisui/settings-panel": "^8.0.0-beta.2",
-    "@praxisui/visual-builder": "^8.0.0-beta.2",
-    "@praxisui/core": "^8.0.0-beta.2",
-    "@praxisui/cron-builder": "^8.0.0-beta.2"
+    "@angular/forms": "^20.0.0",
+    "@angular/material": "^20.0.0",
+    "@angular/router": "^20.0.0",
+    "@praxisui/ai": "^8.0.0-beta.21",
+    "@praxisui/dynamic-fields": "^8.0.0-beta.21",
+    "@praxisui/metadata-editor": "^8.0.0-beta.21",
+    "@praxisui/rich-content": "^8.0.0-beta.21",
+    "@praxisui/settings-panel": "^8.0.0-beta.21",
+    "@praxisui/visual-builder": "^8.0.0-beta.21",
+    "@praxisui/core": "^8.0.0-beta.21",
+    "rxjs": "^7.8.0"
   },
   "dependencies": {
     "tslib": "^2.3.0",

package/src/lib/components/praxis-form-actions/praxis-form-actions.json-api.md

@@ -0,0 +1,441 @@
+---
+title: "praxis-form-actions JSON API (Canonical)"
+slug: "praxis-form-actions-json-api"
+doc_type: "api-reference"
+component: "praxis-form-actions"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do componente praxis-form-actions."
+category: "components"
+sub_category: "dynamic-form"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+source_of_truth:
+  - "projects/praxis-dynamic-form/src/lib/components/praxis-form-actions/praxis-form-actions.component.ts"
+  - "projects/praxis-dynamic-form/src/lib/components/praxis-form-actions/praxis-form-actions.component.html"
+  - "projects/praxis-core/src/lib/models/form/form-layout.model.ts"
+source_of_truth_last_verified: "2026-03-05"
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "praxis-form-actions"
+api_stability: "canonical"
+schema_verified: true
+runtime_verified: false
+editor_coverage_verified: false
+runtime_scope: "public"
+legacy_paths_present: true
+has_known_mismatches: true
+related_components:
+  - "praxis-table"
+---
+
+# praxis-form-actions
+
+Este documento e a referencia canonica da API JSON de praxis-form-actions.
+
+## 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: `praxis-form-actions` renderiza e orquestra a barra de botoes de acao do formulario. Ele e JSON-first: recebe `actions` (derivado de `FormConfig.actions`) e emite um evento unico de acao para o host decidir o fluxo.
+
+## 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/components/praxis-form-actions/praxis-form-actions.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-dynamic-form/src/lib/components/praxis-form-actions/praxis-form-actions.component.html | template-style | Source de implementacao declarado no repositorio. |
+| projects/praxis-core/src/lib/models/form/form-layout.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 |
+| --- | --- | --- | --- | --- | --- |
+| `actions.submit/cancel/reset` | not-specified | not-specified | n/a | Active | Base para botoes padrao. |
+| `actions.custom[]` | not-specified | not-specified | n/a | Active | Adiciona botoes extras no fluxo. |
+| `actions.position/orientation/spacing/sticky/divider` | not-specified | not-specified | n/a | Active | Aplica classes de layout da barra. |
+| `actions.mobile.collapseToMenu` | not-specified | not-specified | n/a | Active | Ativa modo mobile com menu de overflow. |
+| `actions.containerClassName/containerStyles` | not-specified | not-specified | n/a | Active | Classe/estilo no container principal. |
+| `actions.showSaveButton/showCancelButton/showResetButton` | not-specified | not-specified | n/a | Active | Compatibilidade legada para visibilidade. |
+| `actions.submitButtonLabel/cancelButtonLabel/resetButtonLabel` | not-specified | not-specified | n/a | Active | Compatibilidade legada para labels. |
+| `actions.placement` | not-specified | not-specified | n/a | Declared-only | Declarado no modelo; nao aplicado neste componente isolado. |
+
+### Supported legacy paths
+
+| Legacy path | Canonical replacement | Support window | Runtime behavior | Notes |
+| --- | --- | --- | --- | --- |
+| extracted-from-detailed-api | see canonical paths | not-yet-verified | accepted for backward compatibility | Alias/legado identificado no conteúdo preservado. |
+
+### Internal-only paths
+
+| Path | Internal consumer | Runtime presence | Public support | Notes |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | not-yet-verified | No | Caminhos internos nao mapeados explicitamente nesta revisao automatizada. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | Experimental | not-yet-verified | Registrar somente quando houver evidencia em runtime/codigo. |
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| actions | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 8 path(s) mapeado(s), status predominante Active. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `actions.submit/cancel/reset` | not-specified | not-specified | n/a | component-defined | Base para botoes padrao. |
+| `actions.custom[]` | not-specified | not-specified | n/a | component-defined | Adiciona botoes extras no fluxo. |
+| `actions.position/orientation/spacing/sticky/divider` | not-specified | not-specified | n/a | component-defined | Aplica classes de layout da barra. |
+| `actions.mobile.collapseToMenu` | not-specified | not-specified | n/a | component-defined | Ativa modo mobile com menu de overflow. |
+| `actions.containerClassName/containerStyles` | not-specified | not-specified | n/a | component-defined | Classe/estilo no container principal. |
+| `actions.showSaveButton/showCancelButton/showResetButton` | not-specified | not-specified | n/a | component-defined | Compatibilidade legada para visibilidade. |
+| `actions.submitButtonLabel/cancelButtonLabel/resetButtonLabel` | not-specified | not-specified | n/a | component-defined | Compatibilidade legada para labels. |
+| `actions.placement` | not-specified | not-specified | n/a | component-defined | Declarado no modelo; nao aplicado neste componente isolado. |
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `actions` | `FormConfig['actions']` | not-specified | component-input | not-yet-verified | Contrato principal da barra de acoes. |
+| `isSubmitting` | `boolean` | not-specified | component-input | not-yet-verified | Bloqueia cliques e desabilita botoes durante envio. |
+| `formIsValid` | `boolean` | not-specified | component-input | not-yet-verified | Bloqueia botao `submit` quando invalido. |
+| `submitError` | `string \| null \| undefined` | not-specified | component-input | not-yet-verified | Exibe alerta acima da barra. |
+| `formId` | `string \| undefined` | not-specified | component-input | not-yet-verified | Namespace para atalhos de teclado. |
+| `actionOverrides` | `Record<string, Record<string, any>>` | not-specified | component-input | not-yet-verified | Patch de propriedades por actionId. |
+
+### Output events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `action` | `PraxisFormActionEvent` | Clique/atalho em acao habilitada. | Partial | Preservado da documentação anterior. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| host/services/storage | bidirectional | see-detailed-api | not-yet-verified | Side channels dependem do componente e do host consumidor. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| see-source-of-truth | true | browser/dev/prod/ssr | runtime linkage | Confirmar por componente quando necessario. |
+
+## 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. defaults do componente
+2. contrato JSON recebido
+3. overrides de host/runtime
+4. normalizacoes internas
+
+### Fallback order
+
+contrato explicito -> aliases legados (quando suportados) -> defaults internos -> comportamento seguro
+
+### Override points
+
+- inputs publicos do componente
+- configuracao JSON de runtime
+- integracoes de host (servicos/tokens/adapters)
+
+### Runtime normalization
+
+Campos e aliases preservados do documento anterior devem convergir progressivamente para paths canonicos declarados.
+
+### Precedence rules
+
+Quando houver conflito entre alias e path canonico, priorizar path canonico e manter alias apenas para backward compatibility.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| see-detailed-api | runtime | warn-or-reject | not-yet-standardized | Semantica de validacao preservada do documento anterior. |
+
+### Error semantics
+
+Erros devem ser classificados em warnings recuperaveis versus falhas bloqueantes. Quando a evidencia nao estiver explicita, tratar como not yet verified.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| invalid-or-unknown-field | component-defined | not-yet-verified | Variavel por componente; requer verificacao em runtime. |
+
+### 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
+`praxis-form-actions` renderiza e orquestra a barra de botoes de acao do formulario.
+Ele e JSON-first: recebe `actions` (derivado de `FormConfig.actions`) e emite um evento unico de acao para o host decidir o fluxo.
+
+Use quando precisar de:
+- botoes padrao (`submit`, `cancel`, `reset`) + custom;
+- layout responsivo da barra de acoes;
+- atalhos de teclado por acao;
+- overrides de runtime por regra (ex.: desabilitar, ocultar, trocar label).
+
+### 2. API do Componente
+
+#### 2.1 Inputs
+| Input | Tipo | Padrao | Status | Comportamento |
+| --- | --- | --- | --- | --- |
+| `actions` | `FormConfig['actions']` | `undefined` | Active | Contrato principal da barra de acoes. |
+| `isSubmitting` | `boolean` | `false` | Active | Bloqueia cliques e desabilita botoes durante envio. |
+| `formIsValid` | `boolean` | `true` | Active | Bloqueia botao `submit` quando invalido. |
+| `submitError` | `string \| null \| undefined` | `undefined` | Active | Exibe alerta acima da barra. |
+| `formId` | `string \| undefined` | `undefined` | Active | Namespace para atalhos de teclado. |
+| `actionOverrides` | `Record<string, Record<string, any>>` | `undefined` | Active | Patch de propriedades por actionId. |
+
+#### 2.2 Output
+| Output | Payload | Quando emite |
+| --- | --- | --- |
+| `action` | `PraxisFormActionEvent` | Clique/atalho em acao habilitada. |
+
+```ts
+interface PraxisFormActionEvent {
+  actionId: string;
+  button: FormActionButton;
+  originalEvent: Event;
+}
+```
+
+### 3. Cobertura JSON de `actions`
+| Caminho | Status | Runtime notes |
+| --- | --- | --- |
+| `actions.submit/cancel/reset` | Active | Base para botoes padrao. |
+| `actions.custom[]` | Active | Adiciona botoes extras no fluxo. |
+| `actions.position/orientation/spacing/sticky/divider` | Active | Aplica classes de layout da barra. |
+| `actions.mobile.collapseToMenu` | Active | Ativa modo mobile com menu de overflow. |
+| `actions.containerClassName/containerStyles` | Active | Classe/estilo no container principal. |
+| `actions.showSaveButton/showCancelButton/showResetButton` | Active | Compatibilidade legada para visibilidade. |
+| `actions.submitButtonLabel/cancelButtonLabel/resetButtonLabel` | Active | Compatibilidade legada para labels. |
+| `actions.placement` | Declared-only | Declarado no modelo; nao aplicado neste componente isolado. |
+
+### 4. Regras Operacionais Importantes
+- Fallback sem `actions`:
+  - renderiza apenas botao `submit` (ENVIAR).
+- Atalhos padrao quando nao definidos:
+  - submit: `ctrl+s`
+  - cancel: `esc`
+  - reset: `ctrl+shift+r`
+- Guardas:
+  - clique ignorado quando `isSubmitting=true`;
+  - `submit` sempre bloqueado quando `formIsValid=false`.
+
+### 5. Exemplo Minimo
+```html
+<praxis-form-actions
+  [actions]="formConfig.actions"
+  [formIsValid]="form.valid"
+  [isSubmitting]="isSubmitting"
+  (action)="onFormAction($event)"
+></praxis-form-actions>
+```
+
+### 6. Exemplo Corporativo (override por regra)
+```ts
+actionOverrides = {
+  submit: { disabled: !policy.canSave, label: 'Salvar Alteracoes' },
+  cancel: { tooltip: 'Voltar sem salvar' },
+  approve: { visible: policy.canApprove, color: 'primary' }
+};
+```
+
+```html
+<praxis-form-actions
+  [actions]="formConfig.actions"
+  [actionOverrides]="actionOverrides"
+  [formId]="formId"
+  [formIsValid]="form.valid"
+  [isSubmitting]="isSubmitting"
+  [submitError]="submitError"
+  (action)="dispatchFormAction($event)"
+></praxis-form-actions>
+```
+
+### 7. Problemas Comuns e Armadilhas
+1. Esperar submit automatico sem escutar `action`.
+Correcao: o host deve tratar `actionId='submit'` e executar pipeline.
+
+2. Usar `placement` achando que muda o posicionamento aqui.
+Correcao: `placement` e decidido no runtime host do formulario, nao nesta barra isolada.
+
+3. Nao limpar atalhos em destroy no fork/customizacao.
+Correcao: preserve ciclo de dispose (`ngOnDestroy`) ao extender comportamento.
+
+4. Definir acao custom sem `id`/`action`.
+Correcao: garanta identificador para rotear evento.
+
+5. Ignorar `formIsValid` e forcar submit por fora.
+Correcao: alinhe regra visual e regra de negocio no host.
+
+6. Misturar override e config original sem precedencia clara.
+Correcao: trate `actionOverrides` como ultima camada (patch final).
+
+### 8. Referencias Cruzadas
+- Runtime host de formulario: `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.ts`
+- Modelo de acoes: `projects/praxis-core/src/lib/models/form/form-layout.model.ts`
+- Editor de acoes: `projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts`
+
+### 9. Premissas
+- O componente nao executa side-effects de negocio; ele apenas emite evento de intencao.
+- Controle de permissao/autorizacao deve ocorrer no host/backend.
+- Mensagens de erro/sucesso devem ser coordenadas com `messages` do runtime de formulario.
+
+### 10. Relatorio de Validacao Estrutural
+- Visao geral: PASS
+- Inputs/outputs: PASS
+- Cobertura de `actions` por status: PASS
+- Regras operacionais: 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 |
+| --- | --- | --- | --- | --- | --- |
+| `actions.submit/cancel/reset` | not-specified | not-specified | n/a | Active | Base para botoes padrao. |
+| `actions.custom[]` | not-specified | not-specified | n/a | Active | Adiciona botoes extras no fluxo. |
+| `actions.position/orientation/spacing/sticky/divider` | not-specified | not-specified | n/a | Active | Aplica classes de layout da barra. |
+| `actions.mobile.collapseToMenu` | not-specified | not-specified | n/a | Active | Ativa modo mobile com menu de overflow. |
+| `actions.containerClassName/containerStyles` | not-specified | not-specified | n/a | Active | Classe/estilo no container principal. |
+| `actions.showSaveButton/showCancelButton/showResetButton` | not-specified | not-specified | n/a | Active | Compatibilidade legada para visibilidade. |
+| `actions.submitButtonLabel/cancelButtonLabel/resetButtonLabel` | not-specified | not-specified | n/a | Active | Compatibilidade legada para labels. |
+| `actions.placement` | not-specified | not-specified | n/a | Declared-only | Declarado no modelo; nao aplicado neste componente isolado. |
+
+## Events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `action` | `PraxisFormActionEvent` | Clique/atalho em acao habilitada. | Partial | Preservado da documentação anterior. |
+
+## Styling API
+
+| Token/Class | Scope | Purpose | Notes |
+| --- | --- | --- | --- |
+| see-detailed-api | component | styling/runtime | Consolidar naming canonico quando aplicavel. |
+
+## 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
+{}
+```
+
+### Typical/common
+
+```json
+{}
+```
+
+### Advanced
+
+```json
+{}
+```
+
+### Enterprise scenario
+
+```json
+{}
+```
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |
+
+## 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/components/praxis-form-actions/praxis-form-actions.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-dynamic-form/src/lib/components/praxis-form-actions/praxis-form-actions.component.html | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-core/src/lib/models/form/form-layout.model.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |