@praxisui/dynamic-form 1.0.0-beta.5 → 1.0.0-beta.53

package/README.md

@@ -1,7 +1,56 @@
+---
+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-07"
+---
+
 # @praxisui/dynamic-form
 
 > Standalone dynamic form component with schema-driven UI, native field cascades, settings integration, and a built-in configuration editor.
 
+## 🔰 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.
+
 ## Install
 
 ```bash
@@ -50,7 +99,7 @@ export class FormDemoComponent {
         rows: [
           {
             columns: [
-              { fields: [{ name: 'fullName', label: 'Full Name', controlType: 'text' }] },
+              { fields: [{ name: 'fullName', label: 'Full Name', controlType: 'input' }] },
               { fields: [{ name: 'email', label: 'E-mail', controlType: 'email' }] },
             ],
           },
@@ -101,11 +150,153 @@ Alternatively, when `editModeEnabled` is true, `praxis-dynamic-form` renders a g
 
 - 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`
 
 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`
+
+## 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`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), 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`
@@ -119,9 +310,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,9 +333,9 @@ 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)
 
@@ -164,3 +355,9 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
   - 200 → atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = editModeEnabled && 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.