Manual Form API Reference

Summary

  • Tipo documental: referencia de superficie publica TypeScript/Angular.
  • Escopo: exports publicos, ManualFormComponent, diretivas, servicos e runtime de persistencia.
  • Fora de escopo: schema-first completo; regras editaveis de formulario ainda seguem o contrato canonico de formRules com JSON Logic.

Source of truth

Source Kind Notes
projects/praxis-manual-form/src/public-api.ts public-api Lista canonica de exports publicos.
projects/praxis-manual-form/src/lib/components/manual-form/manual-form.component.ts component-runtime Inputs, outputs, metodos e comportamento de runtime.
projects/praxis-manual-form/src/lib/components/manual-form/manual-form.component.html template Header, form shell, semantic assistant shell e actions.
projects/praxis-manual-form/src/lib/services/manual-field-metadata-bridge.service.ts service Ponte publica para metadata editor.
projects/praxis-manual-form/src/lib/stores/manual-form-instance.ts runtime-store Persistencia, metadataChanges e composicao da chave.

Public API surface

Public exports

Arquivo canonico: projects/praxis-manual-form/src/public-api.ts

Exports principais:

  • ManualFormComponent
  • ManualFormHeaderComponent
  • ManualFormActionsComponent
  • ManualFormConfigEditorComponent
  • ManualFormDocExampleComponent
  • ManualFormDocExampleShowcaseComponent
  • ManualFormInstance
  • ManualFormInstanceFactory
  • createManualFormSeed
  • ManualFieldMetadataBridgeService
  • ManualFieldKeyService
  • ManualFieldDirective
  • ManualFieldEditorOnDblclickDirective
  • tipos e tokens de manual-form

ManualFormComponent

Selector:

  • praxis-manual-form

Inputs:

  • formId requerido
  • formTitle?
  • formDescription?
  • actions?
  • showHeader = true
  • showActions = true
  • enableAutoSave = true
  • componentInstanceId?
  • enableCustomization = false
  • persistenceOptions?
  • usePathNames = false
  • autoSaveDebounceMs = 800

Outputs:

  • submitted({ value, instance })
  • saved(instance)
  • reset(instance)
  • metadataChange(FormConfig)

Metodos publicos relevantes:

  • tryOpenFieldEditor(fieldName: string)

Comportamentos normativos:

  • adota FormGroup do host quando presente no seletor
  • cria shell de FormGroup interno quando o host nao fornece grupo
  • compoe chave de persistencia a partir de formId ou componentKeyId
  • ativa autosave somente quando enableAutoSave=true

Regras de formulario

formRules e a superficie autoravel de regras do formulario manual. effect.condition deve ser um objeto JSON Logic. Nao usar blocos legados de JSON Schema (allOf, if, then) nem expressoes textuais como campo != null.

formRulesState e metadata interna de round-trip do editor visual. A superficie publica pode preserva-la para reabrir o editor sem perda de estado, mas ferramentas, IA e hosts devem editar formRules em vez de escrever diretamente em formRulesState.

ManualFormInstance

Responsabilidades principais:

  • manter FormConfig e mapa de FieldMetadata
  • persistir draft e configuracao via storage assincrono
  • aplicar patchFieldMetadata()
  • expor metadataChanges() para sincronizacao de runtime
  • suportar resetToSeed() e operacoes de save

Diretivas publicas

  • ManualFieldDirective Uso: associar um campo manual a uma ManualFormInstance.

  • ManualFieldEditorOnDblclickDirective Uso: abrir o metadata editor por duplo clique, respeitando enableCustomization.

Servicos publicos

  • ManualFieldMetadataBridgeService Uso: abrir metadata editor, montar seed do editor e aplicar patch de volta na instancia.

  • ManualFieldKeyService Uso: resolver a chave estavel de um campo em cenarios com seletores/constructors ambiguos.

Integration contracts

Host form mode

Quando o host aplica [formGroup] diretamente em <praxis-manual-form>:

  • o componente adota o FormGroup do host
  • evita monkey patches em formularios externos
  • melhora DX e validacao por Angular Language Service

Dynamic mode

Quando o host nao fornece [formGroup]:

  • o container cria um FormGroup interno
  • registra controles detectados no conteudo projetado
  • continua suportando persistencia, autosave e metadata patching

Persistence model

Dependencias externas:

  • ASYNC_CONFIG_STORAGE
  • ComponentKeyService quando existir componentKeyId

Chave de persistencia:

  • manual-form:{namespace}:{tenantId}:{profileId}:{formId}
  • quando ha componentKeyId, a instancia pode usar uma chave derivada mais estavel

Constraints and limits

  • formId e obrigatorio para um ciclo corporativo previsivel.
  • enableCustomization deve ficar restrito a perfis de customizacao.
  • usePathNames=true depende de suporte coerente a caminhos aninhados.
  • componentes de campo que interrompem clique podem impedir abertura da toolbar por mouse.
  • Overview: manual-form-overview
  • Guia host: host-manual-form-integration
  • Toolbar: manual-form-toolbar-execution