@praxisui/manual-form 1.0.0-beta.7 → 2.0.0-beta.0

package/README.md

@@ -1,5 +1,62 @@
+---
+title: "Manual Form"
+slug: "manual-form-overview"
+description: "Visao geral do @praxisui/manual-form com formularios declarativos, autodeteccao de campos, autosave, persistencia e hot update de metadata."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "manual-form"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "manual-form"
+  - "forms"
+  - "autosave"
+  - "metadata-editor"
+  - "dynamic-fields"
+order: 38
+icon: "file-pen"
+toc: true
+sidebar: true
+search_boost: 0.95
+reading_time: 14
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "manual-form-api-reference"
+  - "host-manual-form-integration"
+  - "manual-form-toolbar-execution"
+  - "consumer-integration-quickstart"
+  - "host-integration-guide"
+keywords:
+  - "praxis manual form"
+  - "manual form toolkit"
+  - "form autosave"
+  - "field metadata bridge"
+last_updated: "2026-03-07"
+---
+
 # Manual Form Toolkit
 
+Biblioteca voltada a formularios declarativos baseados em componentes `pdx-*`, com suporte a persistencia, autodeteccao de campos e ponte com editores de metadata.
+
+## Documentation
+
+- Documentação oficial: https://praxisui.dev
+- Aplicação de referência: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Indicado para: equipes que precisam montar formularios Praxis manualmente sem perder consistencia, autosave e governanca
+
+## When to use
+
+- Declarar formularios manualmente com componentes `pdx-*` sem abrir mao de infraestrutura
+- Adicionar autosave, persistencia e hot update de metadata ao fluxo do host
+- Reduzir o atrito entre formularios manuais e o restante do ecossistema Praxis UI
+
 ## Instalação
 
 ```bash
@@ -35,6 +92,74 @@ O exemplo `/cargos/manual-form` demonstra uso declarativo:
 </praxis-manual-form>
 ```
 
+### Padrão didático para exemplos renderizados
+
+Para páginas de documentação que precisam mostrar o componente antes de blocos longos de texto,
+use o wrapper `praxis-manual-form-doc-example`. Ele já entrega:
+
+- Banner curto com foco no exemplo live.
+- Tabs para alternar entre `Live`, `Template`, `TS` e `Config`.
+- Toggle de modo de customização (liga/desliga) com evento.
+- Botão de cópia do snippet ativo.
+- Callouts opcionais de `IMPORTANTE`, `NOTA` e `DICA`.
+
+```html
+<praxis-manual-form-doc-example
+  title="Cadastro de cargo"
+  subtitle="Preview primeiro, explicações depois."
+  level="Intermediario"
+  bannerTitle="Veja o componente em ação"
+  bannerDescription="Explore o live e abra código apenas quando necessário."
+  [templateCode]="templateSnippet"
+  [tsCode]="tsSnippet"
+  [configCode]="configSnippet"
+  [customizationEnabled]="editMode()"
+  (customizationEnabledChange)="editMode.set($event)"
+  important="Persista o draft no submit."
+  note="A aba Live abre por padrão."
+  tip="Use a aba Config para explicar contratos JSON."
+>
+  <div exampleLive>
+    <praxis-manual-form
+      [formGroup]="form"
+      formId="cargo-manual-form"
+      [enableCustomization]="editMode()"
+    >
+      <pdx-text-input formControlName="nome" label="Nome"></pdx-text-input>
+    </praxis-manual-form>
+  </div>
+
+  <div exampleDiagram>
+    <!-- Mermaid, SVG ou fluxo simplificado -->
+  </div>
+</praxis-manual-form-doc-example>
+```
+
+Também existe um showcase pronto para consumo direto:
+
+```html
+<praxis-manual-form-doc-example-showcase></praxis-manual-form-doc-example-showcase>
+```
+
+Esse showcase já inclui providers locais de `API_URL` e `ASYNC_CONFIG_STORAGE`, evitando erro de injeção em páginas de documentação.
+
+### Diagrama de funcionamento (alto nível)
+
+```mermaid
+flowchart LR
+  Host[Template com <pdx-*>] --> ManualForm[praxis-manual-form]
+  ManualForm --> Detect[Detecta campos]
+  Detect --> Meta[Infere FieldMetadata]
+  Meta --> Group[Cria/Adota FormGroup]
+  Group --> Render[Renderiza campos + validações]
+  ManualForm --> Instance[ManualFormInstance]
+  Instance --> Storage[ConfigStorage]
+  ManualForm -->|editMode| Editor[Metadata Editor]
+  Editor --> Patch[Aplica patch]
+  Patch --> Instance
+  Instance --> Persist[saveDraft / resetToSeed]
+```
+
 ### Editor de metadados integrado
 
 Use o `ManualFieldMetadataBridgeService` para abrir o editor visual a partir de qualquer campo detectado pelo container. O serviço carrega o módulo sob demanda, aplica o patch retornado e chama `saveDraft()` para persistir as alterações no runtime.
@@ -58,6 +183,24 @@ export class CargoManualFormComponent {
 }
 ```
 
+### Toolbar de campo (modo de edicao)
+
+Quando `enableCustomization` estiver ativo, o manual-form exibe uma toolbar flutuante ao clicar
+no campo. Ela permite alternar `required`, `readOnly`, `hidden` e `disabled`, e abrir o editor
+completo de metadados.
+
+Atalhos de teclado (quando o campo esta focado):
+- `F2` ou `Alt+F10` abre a toolbar e move o foco para o primeiro botao.
+- `ESC` fecha a toolbar.
+
+Observacao: se um componente de campo interromper o clique (stopPropagation), a toolbar nao
+abrira via mouse. Use os atalhos de teclado ou evite bloquear o click no host do campo.
+
+Token de z-index:
+- `--pdx-manual-toolbar-z` (default: `2001`).
+Classe de overlay (para temas corporativos):
+- `.pdx-manual-toolbar-panel` (aplicada no CDK Overlay para customizacoes).
+
 ## Motivações
 
 - DX coerente para formulários manuais (sem JSON).
@@ -93,7 +236,7 @@ Essa base permite que hosts manualmente criem formulários com componentes Praxi
 ## Padrão corporativo recomendado
 
 - Host tipado: o host deve criar um `FormGroup` tipado e passá‑lo via `[formGroup]`. O container adota esse grupo, aplica metadados/validators e evita interceptações internas. Isso habilita o Angular Language Service a validar `formControlName` e melhora a DX.
-- Modo dinâmico: se nenhum `[formGroup]` for informado, o container cria e gerencia um `FormGroup` interno (útil para PoCs), sem garantia de validação estática de nomes.
+- Modo dinâmico: opção para PoCs e exemplos rápidos; veja os detalhes na seção “Guia rápido”.
 
 ## Configurações avançadas
 
@@ -104,37 +247,44 @@ Essa base permite que hosts manualmente criem formulários com componentes Praxi
 - Autosave
   - `@Input() enableAutoSave: boolean` (padrão: `true`) e `@Input() autoSaveDebounceMs: number` (padrão: `800`).
 
-## SSR (ConfigStorage sem localStorage)
+### API pública adicional
 
-Em SSR, `localStorage` não existe. Como `praxis-manual-form` apenas depende do token `CONFIG_STORAGE`, você pode prover uma implementação segura no servidor (ex.: in‑memory) e manter `LocalStorageConfigService` no browser.
+- `ManualFormInstance.metadataChanges()`
+  - Emite sempre que o mapa de `FieldMetadata` é atualizado no runtime.
+  - Timing: após `patchFieldMetadata()`, `replaceConfig()`, `resetToSeed()` e cargas de config persistida.
+
+## SSR (AsyncConfigStorage sem localStorage)
+
+Em SSR, `localStorage` não existe. Como `praxis-manual-form` depende do token `ASYNC_CONFIG_STORAGE`, você pode prover uma implementação segura no servidor (ex.: in‑memory) e manter `LocalStorageAsyncAdapter` no browser.
 
 Exemplo (Angular com `app.config.server.ts`):
 
 ```ts
 // app.config.server.ts
 import { ApplicationConfig, PLATFORM_ID, inject, isPlatformServer } from '@angular/core';
-import { CONFIG_STORAGE, LocalStorageConfigService, type ConfigStorage } from '@praxisui/core';
+import { ASYNC_CONFIG_STORAGE, LocalStorageAsyncAdapter, type AsyncConfigStorage } from '@praxisui/core';
+import { EMPTY, of } from 'rxjs';
 
-class MemoryConfigStorage implements ConfigStorage {
+class MemoryAsyncStorage implements AsyncConfigStorage {
   private readonly map = new Map<string, any>();
-  loadConfig<T>(key: string): T | null { return (this.map.get(key) as T) ?? null; }
-  saveConfig<T>(key: string, config: T): void { this.map.set(key, config); }
-  clearConfig(key: string): void { this.map.delete(key); }
+  loadConfig<T>(key: string) { return of((this.map.get(key) as T) ?? null); }
+  saveConfig<T>(key: string, config: T) { this.map.set(key, config); return EMPTY; }
+  clearConfig(key: string) { this.map.delete(key); return EMPTY; }
 }
 
 export const appConfig: ApplicationConfig = {
   providers: [
     {
-      provide: CONFIG_STORAGE,
+      provide: ASYNC_CONFIG_STORAGE,
       useFactory: () => isPlatformServer(inject(PLATFORM_ID))
-        ? new MemoryConfigStorage()
-        : inject(LocalStorageConfigService),
+        ? new MemoryAsyncStorage()
+        : inject(LocalStorageAsyncAdapter),
     },
   ],
 };
 ```
 
-Alternativas no servidor: usar cookies, cache distribuído (ex.: Redis) ou persistir por sessão do usuário. Basta implementar a interface `ConfigStorage`.
+Alternativas no servidor: usar cookies, cache distribuído (ex.: Redis) ou persistir por sessão do usuário. Basta implementar a interface `AsyncConfigStorage`.
 
 ### Exemplo (nested form)
 
@@ -192,6 +342,14 @@ export class MinhaPagina {
 </praxis-manual-form>
 ```
 
+Observações importantes:
+- Aplique `[formGroup]` diretamente no seletor `<praxis-manual-form>` (no host).
+- Evite envolver o componente com um `<form [formGroup]>` externo; não há necessidade e pode causar forms aninhados.
+
+Modo dinâmico (sem host tipado):
+- Quando nenhum `[formGroup]` é informado no host, o container renderiza internamente um `<form [formGroup]="formGroup">` para atender o Angular Forms e evitar o erro NG01050.
+- Isso dispensa qualquer “shim” externo para os exemplos dinâmicos.
+
 ## API do ManualFormComponent (resumo)
 
 - Inputs (sinais):
@@ -200,7 +358,7 @@ export class MinhaPagina {
   - `actions?: FormActionsLayout | null`
   - `showHeader = true`, `showActions = true`
   - `enableAutoSave = true`, `autoSaveDebounceMs = 800`
-  - `editModeEnabled = false` (habilita ações de customização — ex.: abrir editor por duplo clique)
+  - `enableCustomization = false` (habilita ações de customização — ex.: abrir editor por duplo clique)
   - `persistenceOptions?: { namespace?, tenantId?, profileId?, locale? }`
   - `usePathNames = false` (usa `FormControlName.path` como nome do campo)
 - Outputs (sinais):
@@ -208,12 +366,12 @@ export class MinhaPagina {
   - `metadataChange(FormConfig)`
 
 - Métodos públicos:
-  - `tryOpenFieldEditor(fieldName: string)`: tenta abrir o editor do campo, respeitando `editModeEnabled` (no‑op quando `false`).
+  - `tryOpenFieldEditor(fieldName: string)`: tenta abrir o editor do campo, respeitando `enableCustomization` (no‑op quando `false`).
 
 ## Header e Actions
 
 - `<praxis-manual-form-header>`: recebe `instance`, `title`, `description`, `saveLabel`, `resetLabel` e emite `save/reset`.
-- Quando `editModeEnabled` está ativo no container, o header exibe um botão “Editar formulário” que emite `editForm`; o container trata esse evento chamando `openFormEditor()`.
+- Quando `enableCustomization` está ativo no container, o header exibe um botão “Editar formulário” que emite `editForm`; o container trata esse evento chamando `openFormEditor()`.
 - `<praxis-manual-form-actions>`: recebe `actions: FormActionsLayout`, emite `actionClick` e aceita `trackByFn` opcional para listas grandes.
 
 ## Editor de Metadados (visual)
@@ -227,34 +385,48 @@ openEditor(fieldName: string) {
 }
 ```
 
-Integração com Settings Panel: o `ManualFormComponent` utiliza `SettingsPanelService` para abrir o editor do formulário (lista de campos e flags) quando `editModeEnabled` está ativo. É possível abrir programaticamente via `manualForm.openFormEditor()`.
+Integração com Settings Panel: o `ManualFormComponent` utiliza `SettingsPanelService` para abrir o editor do formulário (lista de campos e flags) quando `enableCustomization` está ativo. É possível abrir programaticamente via `manualForm.openFormEditor()`.
 
 ### Duplo clique com modo de edição
 
-Para espelhar o comportamento das demais libs (permitir edição apenas quando o modo de edição está ativo), use o input `editModeEnabled` no container e a diretiva `pdxManualEdit` nos campos:
+Para espelhar o comportamento das demais libs (permitir edição apenas quando o modo de edição está ativo), use o input `enableCustomization` no container e a diretiva `pdxManualEdit` nos campos:
 
 ```html
-<praxis-manual-form formId="cargo" [editModeEnabled]="custom.enabled()">
+<praxis-manual-form formId="cargo" [enableCustomization]="custom.enabled()">
   <pdx-text-input formControlName="nome" label="Nome" pdxManualEdit="nome"></pdx-text-input>
   <pdx-material-currency formControlName="salario" label="Salário" pdxManualEdit="salario"></pdx-material-currency>
 </praxis-manual-form>
 ```
 
-A diretiva chama `manualForm.tryOpenFieldEditor(fieldName)` e respeita `editModeEnabled`, de modo que o duplo clique só abre o editor quando a edição está ligada.
+A diretiva chama `manualForm.tryOpenFieldEditor(fieldName)` e respeita `enableCustomization`, de modo que o duplo clique só abre o editor quando a edição está ligada.
 
 ### Editor do Formulário (lista de campos)
 
-O `ManualFormComponent` expõe `openFormEditor()` para abrir um editor simples do formulário que lista todos os campos e permite alternar: visibilidade (mostrar/ocultar), obrigatório, somente leitura e desabilitado — facilitando encontrar campos ocultos e reexibi‑los, além de ajustes rápidos. O editor respeita `editModeEnabled` e usa o `SettingsPanelService`.
+O `ManualFormComponent` expõe `openFormEditor()` para abrir um editor simples do formulário que lista todos os campos e permite alternar: visibilidade (mostrar/ocultar), obrigatório, somente leitura e desabilitado — facilitando encontrar campos ocultos e reexibi‑los, além de ajustes rápidos. O editor respeita `enableCustomization` e usa o `SettingsPanelService`.
 
 Exemplo de uso no host:
 
 ```html
 <button *ngIf="custom.enabled()" type="button" (click)="manualForm?.openFormEditor()">Editar formulário</button>
-<praxis-manual-form #manualForm [formGroup]="form" formId="'cargo'" [editModeEnabled]="custom.enabled()">
+<praxis-manual-form #manualForm [formGroup]="form" formId="'cargo'" [enableCustomization]="custom.enabled()">
   <!-- campos -->
 </praxis-manual-form>
 ```
 
+#### O que o editor cobre (tabs)
+
+O editor do formulario (Settings Panel) expõe:
+- **Campos**: visibilidade, obrigatorio, somente leitura, desabilitado.
+- **Acoes**: layout da barra, botoes padrao e acoes customizadas.
+- **Mensagens**: feedbacks de sucesso/erro, loading e confirmacoes.
+- **Comportamento**: flags de UX (ex.: focusFirstError, scrollToErrors).
+- **Dicas**: textos auxiliares para modos de tela (i18n/UX).
+- **Hooks**: JSON com hooks de lifecycle (antes/depois de init/submit).
+- **Regras**: regras de layout/visibilidade (JSON).
+- **Cascatas**: dependencias entre campos via metadados.
+
+Obs.: a execucao de hooks/regras depende do host registrar os providers correspondentes.
+
 ## Extensibilidade por DI
 
 - Customize a inferência de `FieldControlType` via tokens:
@@ -271,11 +443,11 @@ Exemplo de uso no host:
 
 ## ManualFieldEditorOnDblclickDirective (`pdxManualEdit`)
 
-- Usa o duplo clique para abrir o editor do campo, respeitando `editModeEnabled` do `ManualFormComponent`.
+- Usa o duplo clique para abrir o editor do campo, respeitando `enableCustomization` do `ManualFormComponent`.
 - Apenas funciona quando aplicada a elementos dentro de `<praxis-manual-form>`.
 
 ```html
-<praxis-manual-form formId="cargo" [editModeEnabled]="custom.enabled()">
+<praxis-manual-form formId="cargo" [enableCustomization]="custom.enabled()">
   <pdx-text-input formControlName="nome" label="Nome" pdxManualEdit="nome"></pdx-text-input>
 </praxis-manual-form>
 ```
@@ -285,7 +457,7 @@ Exemplo de uso no host:
 - Preferir host tipado e `usePathNames=true` para nested forms.
 - Habilitar autosave com debounce adequado.
 - Evitar lógica pesada em templates; delegar inferências ao container.
-- No SSR, sempre prover `CONFIG_STORAGE` compatível (sem localStorage).
+- No SSR, sempre prover `ASYNC_CONFIG_STORAGE` compatível (sem localStorage).
 
 ## Licença
 
@@ -297,6 +469,11 @@ Apache-2.0 — consulte `LICENSE` neste pacote ou no repositório raiz.
 - Layout é responsabilidade do host; não há reordenação automática por metadados.
 - Modo dinâmico sem `[formGroup]` não habilita validação estática de `formControlName` no IDE.
 
+## Notas adicionais
+
+- Quando `enableCustomization` estiver ativo, o container renderiza o assistente AI (Praxis AI) no header do formulario.
+- `componentInstanceId` ajuda a compor a chave de persistencia (com `formId` e `persistenceOptions`), evitando conflito entre instancias da mesma tela.
+
 ## Comparativo — Manual vs Dinâmico (JSON)
 
 - Manual: controle máximo do HTML; evolui por metadados incrementais; ótimo para telas estáveis com design específico.