@praxisui/manual-form 0.0.1

package/LICENSE

@@ -0,0 +1,6 @@
+This package is licensed under the Apache License, Version 2.0.
+
+For the full license text, see the repository root LICENSE file:
+../../LICENSE
+
+Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,303 @@
+# Manual Form Toolkit
+
+## Instalação
+
+```bash
+npm install praxis-manual-form
+```
+
+Peers necessários (instale no app host):
+- `@angular/core` `^20.1.0`, `@angular/common` `^20.1.0`
+- `@praxisui/core` (ConfigStorage, GenericCrudService, ícones)
+- `@praxisui/dynamic-fields` (componentes de campo `pdx-*`)
+- `@praxisui/settings-panel` (integração com painel de configurações)
+- `@praxisui/metadata-editor` (edição visual de campos, opcional)
+
+## Problema
+
+Montar formulários Praxis manualmente (usando `<pdx-*>`) exigia montar `FormConfig`, `FormGroup`, persistência e metadados manualmente. Isso gerava atrito para hosts e dificultava a evolução.
+
+## Solução
+
+Criamos a biblioteca `@praxisui/manual-form` com:
+
+- **ManualFormComponent**: container que detecta campos, infere `FieldMetadata`, cria o `FormGroup`, mantém hot update e persiste via `ManualFormInstance`. Aceita inputs `formId`, `formTitle`, `actions`, `enableAutoSave` etc.
+- **ManualFormInstanceFactory**: runtime que cuida da persistência (`createManualFormSeed`, `saveDraft`, `resetToSeed`).
+- **ManualFormHeader/Actions**: componentes auxiliares para título/descritivo e ações (`submit/cancel/reset/custom`).
+- **ManualFieldMetadataBridgeService**: integra com o `@praxisui/metadata-editor`, aplica patches e garante persistência via `ManualFormInstance`.
+
+O exemplo `/cargos/manual-form` demonstra uso declarativo:
+
+```html
+<praxis-manual-form formId="cargo">
+  <pdx-text-input formControlName="nome" label="Nome" required></pdx-text-input>
+  <pdx-material-currency formControlName="salario" label="Salário"></pdx-material-currency>
+</praxis-manual-form>
+```
+
+### 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.
+
+```ts
+@Component({
+  /* ... */
+})
+export class CargoManualFormComponent {
+  @ViewChild(ManualFormComponent) manualForm?: ManualFormComponent;
+
+  constructor(private readonly metadataBridge: ManualFieldMetadataBridgeService) {}
+
+  openFieldEditor(fieldName: string): void {
+    const instance = this.manualForm?.instance;
+    if (!instance) {
+      return;
+    }
+    void this.metadataBridge.openEditor(instance, fieldName);
+  }
+}
+```
+
+## Motivações
+
+- DX coerente para formulários manuais (sem JSON).
+- Compatibilidade com o ecossistema (metadados, persistência, metadata editor).
+- Facilita adoção por hosts sem precisar do builder completo.
+
+## Estado atual
+
+- Container autodetecta campos (`selector`/`constructor → FieldControlType`), infere `label`, `validators.required`.
+- Persistência automática (`ManualFormInstance`/`ConfigStorage`).
+- Header/Ações padrões com `FormActionsLayout` (normalizado por `DEFAULT_ACTIONS`).
+- Seeds usam `ensureIds`.
+- Autosave opcional com debounce configurável (`enableAutoSave` + `autoSaveDebounceMs`).
+
+## Próximos passos
+
+1. Enriquecer inferência (opções, limites numéricos, etc.).
+2. Permitir layout personalizado via `@Input() sections` ou `layoutConfig`.
+3. Expandir testes unitários (detecção de campos, persistência, normalização de ações, nested paths).
+4. Documentar API pública com exemplos (README + docs).
+5. Adicionar feedbacks visuais pós-edição (notificações, toasts). 
+
+## Notas para evolução
+
+- Continue a trabalhar em `projects/praxis-manual-form` e atualize demos (ex. `/src/app/features/cargo-manual-form`).
+- Ao rodar `ng-packagr`, confirme que libs referenciadas (`@praxisui/core`, `@praxisui/dynamic-fields`) estão construídas ou apontam para `dist/`.
+- Respeite contratos de `FieldMetadata` e use helpers (`ensureIds`, `deepClone`).
+- Atenção a inputs obrigatórios (alguns componentes exigem `metadata`, `readonlyMode`, etc.).
+- Prefira inline styles para evitar warnings de arquivo ausente.
+
+Essa base permite que hosts manualmente criem formulários com componentes Praxis, mantendo compatibilidade com o restante do ecossistema (persistência, metadados e editor). 
+
+## 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.
+
+## Configurações avançadas
+
+- `@Input() usePathNames: boolean` (padrão: `false`)
+  - Quando habilitado, usa `FormControlName.path` (segmentos unidos por `.`) como `FieldMetadata.name`. Requer suporte a grupos aninhados — já implementado em `DynamicFormService`.
+- Mapeamentos de inferência via DI
+  - `MANUAL_FORM_SELECTOR_TO_CONTROL_TYPE` e `MANUAL_FORM_CONSTRUCTOR_TO_CONTROL_TYPE` permitem sobrescrever o mapa padrão de seletores/constructors → `FieldControlType`.
+- Autosave
+  - `@Input() enableAutoSave: boolean` (padrão: `true`) e `@Input() autoSaveDebounceMs: number` (padrão: `800`).
+
+## SSR (ConfigStorage sem localStorage)
+
+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.
+
+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';
+
+class MemoryConfigStorage implements ConfigStorage {
+  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); }
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: CONFIG_STORAGE,
+      useFactory: () => isPlatformServer(inject(PLATFORM_ID))
+        ? new MemoryConfigStorage()
+        : inject(LocalStorageConfigService),
+    },
+  ],
+};
+```
+
+Alternativas no servidor: usar cookies, cache distribuído (ex.: Redis) ou persistir por sessão do usuário. Basta implementar a interface `ConfigStorage`.
+
+### Exemplo (nested form)
+
+```html
+<form [formGroup]="form">
+  <praxis-manual-form formId="nested" [usePathNames]="true">
+    <div formGroupName="endereco">
+      <pdx-text-input formControlName="logradouro" label="Logradouro"></pdx-text-input>
+      <pdx-text-input formControlName="numero" label="Número"></pdx-text-input>
+    </div>
+  </praxis-manual-form>
+</form>
+```
+
+Com `usePathNames=true`, os metadados serão gerados com nomes `endereco.logradouro` e `endereco.numero`, mantendo o `FormGroup` aninhado do host.
+
+## Quando usar (e quando não)
+
+Use esta biblioteca quando:
+- Você quer controlar o layout via HTML, reaproveitando os componentes Praxis.
+- Prefere começar simples e evoluir metadados gradualmente (inferência + editor visual opcional).
+- Precisa integrar com persistência de rascunhos e editar propriedades de campos em runtime.
+
+Prefira o formulário totalmente dinâmico (JSON com `@praxisui/dynamic-form`) quando:
+- O layout deve ser 100% dirigido por metadados/JSON (sem HTML manual).
+- É necessário trocar telas apenas alterando seeds/backends.
+- Precisa de recursos avançados do motor dinâmico (regras, seções condicionais, layouts declarativos complexos).
+
+## Guia rápido (host tipado)
+
+```ts
+// component.ts
+@Component({ /* … */ })
+export class MinhaPagina {
+  private readonly fb = inject(FormBuilder);
+  readonly form = this.fb.group({
+    nome: this.fb.control('', { nonNullable: true, validators: [Validators.required] }),
+    endereco: this.fb.group({ logradouro: this.fb.control('', { nonNullable: true }) }),
+  });
+}
+```
+
+```html
+<praxis-manual-form
+  [formGroup]="form"
+  formId="meu-form"
+  [usePathNames]="true"
+  formTitle="Cadastro"
+  (submitted)="onSubmit($event)"
+>
+  <pdx-text-input formControlName="nome" label="Nome"></pdx-text-input>
+  <div formGroupName="endereco">
+    <pdx-text-input formControlName="logradouro" label="Logradouro"></pdx-text-input>
+  </div>
+</praxis-manual-form>
+```
+
+## API do ManualFormComponent (resumo)
+
+- Inputs (sinais):
+  - `formId: string` (obrigatório)
+  - `formTitle?: string`, `formDescription?: string`
+  - `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)
+  - `persistenceOptions?: { namespace?, tenantId?, profileId?, locale? }`
+  - `usePathNames = false` (usa `FormControlName.path` como nome do campo)
+- Outputs (sinais):
+  - `submitted({ value, instance })`, `saved(instance)`, `reset(instance)`
+  - `metadataChange(FormConfig)`
+
+- Métodos públicos:
+  - `tryOpenFieldEditor(fieldName: string)`: tenta abrir o editor do campo, respeitando `editModeEnabled` (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()`.
+- `<praxis-manual-form-actions>`: recebe `actions: FormActionsLayout`, emite `actionClick` e aceita `trackByFn` opcional para listas grandes.
+
+## Editor de Metadados (visual)
+
+```ts
+@ViewChild(ManualFormComponent) manual?: ManualFormComponent;
+constructor(private readonly bridge: ManualFieldMetadataBridgeService) {}
+openEditor(fieldName: string) {
+  const inst = this.manual?.instance; if (!inst) return;
+  this.bridge.openEditor(inst, fieldName).catch(console.error);
+}
+```
+
+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()`.
+
+### 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:
+
+```html
+<praxis-manual-form formId="cargo" [editModeEnabled]="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.
+
+### 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`.
+
+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()">
+  <!-- campos -->
+</praxis-manual-form>
+```
+
+## Extensibilidade por DI
+
+- Customize a inferência de `FieldControlType` via tokens:
+  - `MANUAL_FORM_SELECTOR_TO_CONTROL_TYPE`
+  - `MANUAL_FORM_CONSTRUCTOR_TO_CONTROL_TYPE`
+
+## ManualFieldDirective
+
+```html
+<ng-container *praxisManualField="'nome'; praxisManualFieldInstance: manual.instance as ctx">
+  Label atual: {{ ctx?.label }}
+</ng-container>
+```
+
+## ManualFieldEditorOnDblclickDirective (`pdxManualEdit`)
+
+- Usa o duplo clique para abrir o editor do campo, respeitando `editModeEnabled` do `ManualFormComponent`.
+- Apenas funciona quando aplicada a elementos dentro de `<praxis-manual-form>`.
+
+```html
+<praxis-manual-form formId="cargo" [editModeEnabled]="custom.enabled()">
+  <pdx-text-input formControlName="nome" label="Nome" pdxManualEdit="nome"></pdx-text-input>
+</praxis-manual-form>
+```
+
+## Boas práticas
+
+- 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).
+
+## Licença
+
+Apache-2.0 — consulte `LICENSE` neste pacote ou no repositório raiz.
+
+## Limitações
+
+- Inferência automática é propositalmente minimalista (label, required, tipo básico). Propriedades avançadas exigem metadados explícitos/edição visual.
+- 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.
+
+## 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.
+- Dinâmico: telas dirigidas por JSON com alto poder de reconfiguração; ideal para múltiplas telas e variações rápidas sem alterar HTML.