@praxisui/manual-form 1.0.0-beta.5 → 1.0.0-beta.52

package/README.md

@@ -1,5 +1,55 @@
+---
+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
 
+## 🔰 Exemplos / Quickstart
+
+Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+
+- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
+- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+
 ## Instalação
 
 ```bash
@@ -35,6 +85,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"
+      [editModeEnabled]="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 +176,24 @@ export class CargoManualFormComponent {
 }
 ```
 
+### Toolbar de campo (modo de edicao)
+
+Quando `editModeEnabled` 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 +229,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 +240,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
+
+- `ManualFormInstance.metadataChanges()`
+  - Emite sempre que o mapa de `FieldMetadata` é atualizado no runtime.
+  - Timing: após `patchFieldMetadata()`, `replaceConfig()`, `resetToSeed()` e cargas de config persistida.
 
-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.
+## 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 +335,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):
@@ -255,6 +406,20 @@ Exemplo de uso no host:
 </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:
@@ -285,7 +450,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 +462,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 `editModeEnabled` 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.