@praxisui/dynamic-form 1.0.0-beta.8 → 2.0.0-beta.0

package/README.md

@@ -1,7 +1,61 @@
+---
+title: "Dynamic Form"
+slug: "dynamic-form-overview"
+description: "Visao geral do @praxisui/dynamic-form com schema-driven UI, editor embutido, layout runtime e integracao orientada a contrato."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "dynamic-form"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "schema-driven"
+  - "runtime"
+  - "layout"
+  - "config-editor"
+order: 30
+icon: "dynamic_form"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 12
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-form-hot-metadata-updates"
+  - "praxis-dynamic-form-json-api"
+  - "host-integration-guide"
+  - "consumer-integration-quickstart"
+keywords:
+  - "FormConfig"
+  - "schema-driven"
+  - "layout editor"
+  - "settings integration"
+last_updated: "2026-03-22"
+---
+
 # @praxisui/dynamic-form
 
 > Standalone dynamic form component with schema-driven UI, native field cascades, settings integration, and a built-in configuration editor.
 
+## Documentation
+
+- Official documentation: https://praxisui.dev
+- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Recommended for: schema-driven screens that need runtime forms, settings integration and contract-first metadata
+
+## When to use
+
+- Build forms from metadata instead of hand-coding each screen
+- Keep runtime customization and layout governance inside the host application
+- Integrate with other `@praxisui/*` packages through shared contracts and settings flows
+
 ## Install
 
 ```bash
@@ -36,7 +90,7 @@ import type { FormConfig } from '@praxisui/core';
     <praxis-dynamic-form
       [config]="config"
       [mode]="'create'"
-      [editModeEnabled]="true"
+      [enableCustomization]="true"
       (formSubmit)="onSubmit($event)"
     ></praxis-dynamic-form>
   `,
@@ -46,18 +100,29 @@ export class FormDemoComponent {
     sections: [
       {
         id: 'main',
-        label: 'Employee',
+        title: 'Employee',
+        sectionHeader: {
+          mode: 'auto',
+          sourceField: 'employeePhoto',
+          initialsSourceField: 'fullName',
+          altField: 'fullName',
+        },
         rows: [
           {
             columns: [
-              { fields: [{ name: 'fullName', label: 'Full Name', controlType: 'text' }] },
-              { fields: [{ name: 'email', label: 'E-mail', controlType: 'email' }] },
+              { id: 'col-fullName', fields: ['fullName'] },
+              { id: 'col-email', fields: ['email'] },
             ],
           },
         ],
       },
     ],
-  } as any;
+    fieldMetadata: [
+      { name: 'employeePhoto', label: 'Photo', controlType: 'input' } as any,
+      { name: 'fullName', label: 'Full Name', controlType: 'input', required: true } as any,
+      { name: 'email', label: 'E-mail', controlType: 'email' } as any,
+    ],
+  };
 
   onSubmit(evt: any) {
     console.log('Submitted:', evt);
@@ -65,7 +130,70 @@ export class FormDemoComponent {
 }
 ```
 
-Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The component can fetch schemas and reconcile local layout with server metadata when `editModeEnabled` is true.
+Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The component can fetch schemas and reconcile local layout with server metadata when `enableCustomization` is true.
+When a late `config` hydration rebuilds the surface, the runtime preserves the current form values already mounted in memory only when the logical context remains the same (`resourcePath`, `resourceId`, and mode). If the form was preloaded from `resourceId`, that entity hydration remains visible after the rebuild only for the same entity context; entity switches and create-mode transitions do not restore the previous record snapshot.
+
+### Canonical DI contract for hosts
+
+`praxis-dynamic-form` does not register `GenericCrudService` internally.
+When the runtime uses `resourcePath`, `resourceId`, schema fetch, CRUD submit, or custom endpoints, the host must provide the service in the effective host scope.
+
+Canonical rule:
+- `praxis-table` is self-hosted for `GenericCrudService`.
+- `praxis-dynamic-form` is host-driven for `GenericCrudService`.
+- If the host needs a specific `endpointKey` or pre-configuration, it must provide and configure the same `GenericCrudService` instance before rendering the form.
+
+Minimal host example:
+
+```ts
+import { Component } from '@angular/core';
+import { GenericCrudService } from '@praxisui/core';
+import { PraxisDynamicForm } from '@praxisui/dynamic-form';
+
+@Component({
+  selector: 'app-form-host',
+  standalone: true,
+  imports: [PraxisDynamicForm],
+  providers: [GenericCrudService],
+  template: `
+    <praxis-dynamic-form
+      [formId]="'employees-form'"
+      [resourcePath]="'employees'"
+      [mode]="'edit'"
+    ></praxis-dynamic-form>
+  `,
+})
+export class FormHostComponent {}
+```
+
+If the host must force a non-default API endpoint, configure the service in the same host scope:
+
+```ts
+import { Component } from '@angular/core';
+import { ApiEndpoint, GenericCrudService } from '@praxisui/core';
+import { PraxisDynamicForm } from '@praxisui/dynamic-form';
+
+@Component({
+  selector: 'app-form-host',
+  standalone: true,
+  imports: [PraxisDynamicForm],
+  providers: [GenericCrudService],
+  template: `
+    <praxis-dynamic-form
+      [formId]="'employees-form'"
+      [resourcePath]="'human-resources/employees'"
+      [mode]="'edit'"
+    ></praxis-dynamic-form>
+  `,
+})
+export class FormHostComponent {
+  constructor(private readonly crud: GenericCrudService<any>) {
+    this.crud.configure('human-resources/employees', ApiEndpoint.HumanResources);
+  }
+}
+```
+
+Without that provider, a standalone host can fail with `NG0201: No provider found for _GenericCrudService`.
 
 ### 2) Config Editor component
 
@@ -95,22 +223,373 @@ export class FormEditorLauncherComponent {
 }
 ```
 
-Alternatively, when `editModeEnabled` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
+Alternatively, when `enableCustomization` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
 
 ## API Surface
 
 - Components: `PraxisDynamicForm`, `PraxisDynamicFormConfigEditor`, `JsonConfigEditorComponent`, `LayoutEditorComponent`
 - Services: `FormConfigService`, `FormLayoutService`, `DynamicFormLayoutService`, `FormContextService`
-- Utilities: form rule converters, normalize date arrays
+- Utilities: form rule converters, normalize date arrays, **FormRulesService** (aplica regras de propriedades)
 - Metadata helpers: `providePraxisDynamicFormMetadata`
 
+## Editorial Hosting (Foundation)
+
+O `@praxisui/dynamic-form` agora aceita uma surface fundacional para hospedar blocos editoriais ao redor do formulario, sem misturar esses blocos com `fieldMetadata` nem com `formData`.
+
+Inputs relevantes:
+- `config.formBlocksBefore?: WidgetDefinition[]`
+- `config.formBlocksBeforeActions?: WidgetDefinition[]`
+- `config.formBlocksAfter?: WidgetDefinition[]`
+- `config.editorialContext?: Record<string, unknown>`
+- `[editorialContext]?: Record<string, unknown>`
+
+Precedencia de contexto editorial:
+1. runtime base do form
+2. `config.editorialContext`
+3. input host `[editorialContext]`
+
+As camadas posteriores sobrescrevem as anteriores.
+
+Exemplo minimo:
+
+```ts
+import type { FormConfig } from '@praxisui/core';
+
+const formConfig: FormConfig = {
+  editorialContext: {
+    accountName: 'Helena Costa',
+    accountRole: 'Gestora financeira',
+    accountContext: {
+      user: {
+        name: 'Helena Costa',
+        email: 'helena.costa@praxis.demo',
+        role: 'Gestora financeira',
+      },
+      tenant: {
+        name: 'Praxis Holding',
+      },
+    },
+  },
+  formBlocksBefore: [
+    {
+      id: 'widget:hero-banner',
+      inputs: {
+        instanceId: 'editorial:before:hero:1',
+        title: 'Praxis Summit 2026',
+        subtitle: 'Inscricao institucional',
+        description: 'Experiencia institucional com composicao editorial hospedada antes do formulario.',
+        variant: 'event',
+      },
+    },
+    {
+      id: 'widget:rich-text-block',
+      inputs: {
+        instanceId: 'editorial:before:rich-text:1',
+        title: 'Antes de comecar',
+        subtitle: 'Contexto editorial',
+        icon: 'info',
+        contentFormat: 'markdown',
+        content: 'Confirme os dados abaixo antes do envio e consulte a [documentacao](https://example.com/docs) se precisar de suporte.',
+      },
+    },
+    {
+      id: 'widget:legal-notice',
+      inputs: {
+        instanceId: 'editorial:before:legal:1',
+        title: 'Uso de dados',
+        contentFormat: 'plain',
+        content: 'Ao participar, voce reconhece a politica institucional aplicavel.',
+        severity: 'info',
+      },
+    },
+  ],
+  formBlocksBeforeActions: [
+    {
+      id: 'form:user-context-summary',
+      inputs: {
+        instanceId: 'editorial:before-actions:user-context:1',
+        title: 'Conta atual',
+        source: 'context',
+        context: '${accountContext}',
+        fields: [
+          { label: 'Nome', valuePath: 'user.name', fallback: '-' },
+          { label: 'E-mail', valuePath: 'user.email', fallback: '-' },
+        ],
+      },
+    },
+  ],
+  formBlocksAfter: [
+    {
+      id: 'widget:footer-links',
+      inputs: {
+        instanceId: 'editorial:after:footer-links:1',
+        brandText: 'Praxis',
+        secondaryText: 'Todos os direitos reservados.',
+        links: [
+          { label: 'Docs', href: '/components/dynamic-form/docs/overview' },
+          { label: 'API', href: '/components/dynamic-form/api' },
+        ],
+      },
+    },
+  ],
+  sections: [
+    {
+      id: 'registration',
+      title: 'Dados da inscricao',
+      rows: [
+        {
+          columns: [
+            { fields: ['fullName'] },
+            { fields: ['workEmail'] },
+          ],
+        },
+      ],
+    },
+  ],
+  fieldMetadata: [
+    { name: 'fullName', label: 'Nome completo', controlType: 'input', required: true },
+    { name: 'workEmail', label: 'E-mail corporativo', controlType: 'email', required: true },
+  ],
+};
+```
+
+Uso no host:
+
+```html
+<praxis-dynamic-form
+  [config]="formConfig"
+  [editorialContext]="{ accountName: 'Helena Costa', accountRole: 'Host override' }"
+  (widgetEvent)="onWidgetEvent($event)"
+></praxis-dynamic-form>
+```
+
+Notas:
+- `formBlocksBefore`, `formBlocksBeforeActions` e `formBlocksAfter` nao entram em `formData`.
+- `widgetEvent` reemite eventos dos widgets hospedados com `placement` (`before`, `beforeActions` ou `after`).
+- `editorialContext` deve ser tratado como imutavel; mutacoes in-place nao invalidam o cache do host.
+- A surface editorial ja suporta widgets reais compartilhados para hero, rich text, legal notice, user context summary e footer links.
+- `formBlocksBeforeActions` renderiza depois das secoes e antes da area principal de acoes, sendo o slot recomendado para blocos contextuais como `form:user-context-summary`.
+- `formBlocksAfter` permanece como slot de fechamento e continua renderizando depois do formulario inteiro, incluindo os CTAs.
+- secoes agora suportam `appearance` (`card|plain|step`) e `stepLabel` para cabecalhos mais estruturados.
+
 See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
+## Documentacao Tecnica da Lib
+
+- `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.json-api.md`
+- `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`
+
+## Header de seção com avatar dinâmico
+
+- `FormSection.icon` continua suportado como identidade visual estática do header.
+- `FormSection.sectionHeader` amplia o contrato para permitir avatar resolvido a partir do `formData`, sem perder compatibilidade com `icon`.
+- Modos suportados:
+  - `icon`: usa o ícone estático da seção.
+  - `avatar-image`: tenta resolver uma imagem a partir de `sourceField`.
+  - `avatar-initials`: deriva iniciais a partir de `initialsSourceField` e, na ausência dele, usa `altField`.
+  - `auto`: tenta imagem, depois iniciais e por fim aplica o fallback configurado.
+- Campos principais de `sectionHeader`:
+  - `sourceField`: field cujo valor atual representa foto/avatar.
+  - `initialsSourceField`: field textual usado para derivar iniciais.
+  - `altField`: field usado como texto acessível do avatar e fallback textual para iniciais.
+  - `fallbackIcon`: ícone usado quando a fonte dinâmica estiver vazia ou inválida.
+  - `emptyState`: `fallback-icon`, `placeholder-avatar` ou `none`, útil sobretudo em fluxos `create`; o padrão efetivo é `placeholder-avatar`, neutro para qualquer domínio.
+  - `initialsMaxLength`: máximo de letras no avatar textual, normalizado para `1..4`.
+- Formatos de imagem aceitos pelo runtime:
+  - URL
+  - data URL base64
+  - `File`/`Blob`
+  - objetos com `url`, `src`, `dataUrl`, `base64` ou `bytes`
+- Comportamento típico em cadastro:
+  - formulário vazio: mostra placeholder neutro por padrão, ou `fallbackIcon` se `emptyState` pedir isso
+  - nome preenchido, sem foto: `auto` pode mostrar iniciais
+  - foto preenchida: mostra a imagem
+
+## IA — catálogo de capacidades (composição)
+
+O assistente usa um catálogo agregado de capabilities para gerar patches seguros:
+
+- **Macro (FormConfig)**: layout, regras, ações, hooks e mensagens (`form-ai-capabilities`).
+- **Base (FieldMetadata)**: propriedades comuns de campos (`field-metadata-ai-capabilities`).
+- **Micro (por controlType)**: overlay específico de cada input (`@praxisui/dynamic-fields`).
+
+Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que os patches apontem para a raiz correta do formulário.
+
+## Regras de formulário (novo contrato)
+
+- Formato: cada regra tem `targetType` (`field | section | action | row | column`), `targets: string[]` (IDs canônicos, sem prefixo), e `effect` com `condition` (DSL ou Specification), `properties` e `propertiesWhenFalse`.
+- Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixos `section:/action:/row:/column:` são removidos e `targetType` é inferido se não vier explicitado.
+- Semântica de limpeza: valores `null` em `properties/propertiesWhenFalse` removem o override e retornam ao valor base do layout; ausência mantém o valor base.
+- Whitelist por tipo (somente propriedades a seguir são aplicadas; demais são descartadas e logadas em dev):
+  - `field`: `visible`, `required`, `readonly`, `disabled`, `className`, `style`, `label`, `description`, `placeholder`, `hint`, `tooltip`, `prefixIcon`, `suffixIcon`, `prefixText`, `suffixText`, `defaultValue`, `options` (array `{label,value,disabled?}`), `appearance` (`fill|outline`), `color` (`primary|accent|warn`), `floatLabel` (`auto|always|never`), `hintPosition` (`start|end`), `validators` (primitivos por chave).
+  - `section`: `visible`, `title`, `description`, `icon`, `sectionHeader` (objeto rico) e tambem subpropriedades tipadas como `sectionHeader.mode`, `sectionHeader.sourceField`, `sectionHeader.initialsSourceField`, `sectionHeader.altField`, `sectionHeader.fallbackIcon`, `sectionHeader.emptyState`, `sectionHeader.initialsMaxLength`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
+  - `action`: `visible`, `disabled`, `loading`, `label`, `icon`, `tooltip`, `color` (`primary|accent|warn|basic`), `variant` (`raised|stroked|flat|fab`), `size` (`small|medium|large`), `className`, `style`.
+  - `row`: `visible`, `gap`, `rowGap`, `className`, `style`.
+  - `column`: `visible`, `span`, `offset`, `order`, `hidden`, `align` (`start|center|end|stretch`), `padding`, `className`, `style`.
+- Runtime (FormRulesService): filtra por whitelist, converte tipos (enum/number/boolean/string), saneia objetos (`options/validators/style`), aplica remoção de chaves com `null` e retorna mapas `fieldProps/sectionProps/actionProps/rowProps/columnProps`.
+- Renderização: `PraxisDynamicForm` aplica overrides em campos/seções/ações/linhas/colunas (visibilidade, gaps, padding, classes, estilos, labels, etc.); colunas respeitam `align/span/offset/order/hidden/padding` vindo das regras.
+
+### Builder integrado
+
+- No editor visual, use a aba “Propriedades” (integrada ao builder) para selecionar o alvo (`targetType` + autocomplete de IDs de campos/seções/ações/linhas/colunas), escolher propriedades whitelisted e definir valores para `properties` (branch true) e `propertiesWhenFalse` (branch false). Botão “Limpar override” remove a propriedade (equivalente a `null`).
+- A aba de Propriedades usa inputs tipados (enum/number/boolean/string/JSON) conforme o schema injetado; valores inválidos são ignorados.
+- O config editor fornece `targetSchemas` (campos/seções/ações/linhas/colunas) e `targetPropertySchemas` para o builder; `formRules` são salvas no formato canônico (sem `context/targetField`).
+
+## Layout padrão (sem FormConfig)
+
+Quando o componente não recebe uma `FormConfig` prévia (primeira execução), ele gera um layout padrão a partir do metadata do backend:
+
+- Linhas/colunas: 2 campos por linha (padrão). Em telas pequenas (xs/sm) os campos empilham (1 por linha), e a partir de md ficam lado a lado.
+- Responsividade do grid (12 colunas):
+  - xs: 12, sm: 12, md: 6, lg: 6, xl: 6 (para 2 por linha). Para outros valores, a regra é `base = floor(12 / fieldsPerRow)`.
+- Largura dos campos: `mat-form-field { width: 100% }` e um **allow‑list** de tipos “input‑like” em `data-field-type` recebem `width: 100%`. Controles compactos (ex.: checkbox/radio/toggle/rating/slider) **não** são forçados a preencher a coluna.
+- Editor de Configuração: ao abrir a aba “Layout”, o editor reflete esse layout padrão; ao aplicar/salvar, persiste a `FormConfig` no storage do host.
+- Personalização: você pode ajustar o layout pelo Editor (arrastar/seções/linhas/colunas, alterar spans) ou fornecer uma `FormConfig` completa via `[config]`.
+
+## Form Actions — Layout & Styling
+
+A barra de ações (onde ficam "ENVIAR", "Cancelar", etc.) é configurável via `config.actions` e pelo Editor (aba "Ações").
+
+Defaults
+- Rótulo do botão principal: `ENVIAR`.
+- Posição estrutural: `afterSections` (renderiza abaixo da última seção).
+- Alinhamento: `right`.
+- Orientação: `horizontal`.
+- Espaçamento: `normal`.
+- Background: sem cor por padrão (herda da superfície). Configure via `containerStyles` ou `containerClassName` se desejar uma superfície própria.
+
+Estrutura (parcial)
+```ts
+interface FormActionsLayout {
+  submit: FormActionButton;     // id, label, color, type, variant, shortcut, etc.
+  cancel: FormActionButton;
+  reset: FormActionButton;
+  custom?: FormActionButton[];  // botões extras
+
+  // Layout/posicionamento
+  placement?: 'afterSections' | 'insideLastSection' | 'top';
+  position?: 'left' | 'center' | 'right' | 'justified' | 'split';
+  orientation?: 'horizontal' | 'vertical';
+  spacing?: 'compact' | 'normal' | 'spacious';
+  sticky?: boolean; // fixa a barra (bottom)
+
+  // Estilização do container
+  containerClassName?: string;      // adiciona classe ao container
+  containerStyles?: { [k: string]: any }; // estilos inline (camelCase)
+
+  // Mobile
+  mobile?: { position?: 'left'|'center'|'right'|'justified'; orientation?: 'horizontal'|'vertical'; collapseToMenu?: boolean };
+}
+```
+
+Exemplo (config)
+```ts
+config.actions = {
+  submit: { visible: true, label: 'ENVIAR', type: 'submit', color: 'primary', variant: 'raised', shortcut: 'ctrl+s' },
+  cancel: { visible: true, label: 'Cancelar', type: 'button', color: 'basic' },
+  reset:  { visible: false, label: 'Reset' },
+  placement: 'afterSections',
+  position: 'right',
+  orientation: 'horizontal',
+  spacing: 'normal',
+  sticky: false,
+  containerClassName: 'my-form-actions',
+  containerStyles: {
+    background: 'var(--md-sys-color-surface-container)',
+    border: '1px solid var(--md-sys-color-outline-variant)',
+    borderRadius: '12px',
+    padding: '12px 16px'
+  },
+  mobile: { collapseToMenu: true }
+};
+```
+
+CSS por classe (opcional)
+```scss
+.my-form-actions {
+  background: var(--md-sys-color-surface-container);
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: 12px;
+  padding: 12px 16px;
+}
+```
+
+Dicas
+- Cores do botão: use `color` = `primary|accent|warn|basic` (respeitam o tema Material).
+- Tokens M3: prefira `--md-sys-*` para cores/superfícies.
+- Mobile: ative `collapseToMenu` para colapsar botões extras em menu nas telas pequenas.
+- A classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+
+### Tokens M3 obrigatórios (host)
+
+Para que o builder e os editores respeitem o tema do app host:
+
+- Superfícies: `--md-sys-color-surface`, `--md-sys-color-surface-variant`, `--md-sys-color-surface-container-*`
+- Texto/contorno: `--md-sys-color-on-surface`, `--md-sys-color-on-surface-variant`, `--md-sys-color-outline`, `--md-sys-color-outline-variant`
+- Semânticos: `--md-sys-color-primary`, `--md-sys-color-secondary`, `--md-sys-color-tertiary`, `--md-sys-color-error`
+- Containers: `--md-sys-color-primary-container`, `--md-sys-color-secondary-container`, `--md-sys-color-tertiary-container`, `--md-sys-color-error-container`
+- Elevação: `--md-sys-elevation-level1`–`--md-sys-elevation-level3`
+
+
+## Section titles — espaçamento global
+
+O título de seção usa por padrão `margin: 0 0 6px 0`. Você pode ajustar globalmente via CSS var:
+
+```scss
+/* Global (app host) */
+:root { --pfx-section-title-mb: 10px; } // ex.: 10px abaixo do título
+```
+
+Ou por seção, via metadado `titleGapBottom` (em pixels), que aplica inline somente naquela seção.
+
 ## Compatibility
 
 - `@praxisui/dynamic-form` `0.0.x` → Angular `20.x`
 - Module format: `ESM2022`
 
+## Crash Recovery Checkpoint
+
+Estado registrado em `2026-03-15` para retomada rapida do trabalho de E2E do editor `/form-config-editor`.
+
+Suites Playwright ja adicionadas e validadas:
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-smoke.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-layout.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-cascades.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-json.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-hooks.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-actions.playwright.spec.ts`
+- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-actions-custom.playwright.spec.ts`
+
+Cobertura ja estabilizada:
+- smoke das tabs principais do editor integrado
+- `Layout`
+- `Regras`
+- `Cascatas`
+- `JSON` com edicao real e bloqueio de payload invalido
+- `Hooks`
+- `Acoes` (`Botoes Padrao` e `Layout`)
+- `Acoes` customizadas profundas (`showAlert` simples e estruturado)
+- `Comportamento`
+- `Mensagens`
+- `Dicas e Tooltips`
+
+Ajuste tecnico aplicado durante essa fase:
+- [praxis-dynamic-form-config-editor.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts) agora chama `this.jsonEditor?.updateJsonFromConfig(this.editedConfig)` em `onConfigChange(...)` para manter o editor JSON sincronizado com mudancas vindas de abas como `Hooks`.
+- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora mescla catalogo legado + catalogo global do app para o editor de acoes customizadas.
+- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora preserva draft local dos campos globais e usa `track` estavel em `actions.custom`.
+
+Comando base usado para rerodar suites isoladas:
+
+```bash
+node ./node_modules/playwright/cli.js test --config tools/e2e/playwright/praxis-dynamic-form-config-editor.playwright.config.ts <spec>
+```
+
+Se houver crash, retomar daqui:
+1. garantir que o app esteja no ar
+2. rerodar a ultima suite alterada
+3. proximo alvo pendente: consolidar a bateria completa ou seguir para outra area residual do editor
+
 ## License
 
 Apache-2.0 – see the `LICENSE` packaged with this library or the repository root.
@@ -119,9 +598,9 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 
 ### Concept Usage
 
-- [Data Driven Forms](../../../../docs/concepts/data-driven-forms.md)
-- [Declarative UI](../../../../docs/concepts/declarative-ui.md)
-- [Schema‑driven UI](../../../../docs/concepts/schema-driven-ui.md)
+- Data-driven forms
+- Declarative UI
+- Schema-driven UI
 
 ## Quando usar cada mecanismo
 
@@ -142,13 +621,13 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 
 ## Links úteis
 
-- Fluxo de Schema (ETag/304, schemaId, reconciliação): `docs/schemas/fluxo-schema.md`
+- Fluxo de Schema (ETag/304, schemaId, reconciliação): `projects/praxis-core/docs/schema-flow.md` (canônico) e `docs/schemas/fluxo-schema.md` (resumo operacional)
 - Guia de implementação e metadados da cascata: `docs/CASCADE-NATIVA.md`
-- Padrões de endpoints (Options vs Filter) para selects: `docs/DEVS-GENERIC-CRUD-SERVICE.md`
+- Padrões de endpoints (Options vs Filter) para selects: `projects/praxis-dynamic-fields/docs/generic-crud-service.md` (canônico) e `docs/DEVS-GENERIC-CRUD-SERVICE.md` (resumo operacional)
 
 ## Verificação de Schema (ETag/If-None-Match)
 
-- Inputs (opcionais; ativos apenas com `editModeEnabled=true`):
+- Inputs (opcionais; ativos apenas com `enableCustomization=true`):
   - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'`
   - `snoozeMs: number = 86400000`
   - `autoOpenSettingsOnOutdated: boolean = false`
@@ -161,6 +640,12 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 - Comportamento:
   - Quando já existe base local (ex.: `config.sections.length > 0`), o componente faz uma verificação leve via `/schemas/filtered` com `If-None-Match`.
   - 304 → apenas atualiza `lastVerifiedAt` e emite `schemaStatusChange(outdated=false)`.
-  - 200 → atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = editModeEnabled && hadBase`, emite `schemaStatusChange`. Não aplica schema automaticamente.
+  - 200 → atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = enableCustomization && hadBase`, emite `schemaStatusChange`. Não aplica schema automaticamente.
   - Primeira vez (sem base): baixa o corpo do schema para gerar o layout; persiste `form-schema-meta:{formId}`.
   - Notificações respeitam preferências e são one‑shot por hash; o banner/snackbar oferecem ações para Reconciliar, Lembrar depois (snooze) e Ignorar.
+
+### URL da API (absoluto vs relativo)
+
+- Quando `API_URL.default.baseUrl` for relativo (ex.: `'/api'`), a lib resolve a origem a partir de `location.origin` no browser. Isso cobre o cenário comum com proxy de dev (`/api`, `/schemas`).
+- Em SSR (sem `location.origin`), configure `baseUrl` absoluto (ex.: `https://api.acme.com/api`) para evitar erros do tipo “Invalid URL” ao construir chamadas de `/schemas/filtered`.
+- O `GenericCrudService.getSchemasFilteredBaseUrl()` retorna sempre uma URL absoluta; o `SchemaMetadataClient` também aceita `baseUrl` relativo quando há origin disponível.