@praxisui/dynamic-form 1.0.0-beta.3 → 1.0.0-beta.30

package/README.md

@@ -2,6 +2,13 @@
 
 > 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
@@ -106,6 +113,101 @@ Alternatively, when `editModeEnabled` is true, `praxis-dynamic-form` renders a g
 
 See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
+## 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% }` dentro do `praxis-dynamic-form`, garantindo que o campo ocupe toda 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 `--mat-sys-*` / `--md-sys-*` para cores/superfícies.
+- Mobile: ative `collapseToMenu` para colapsar botões extras em menu nas telas pequenas.
+
+## 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`
@@ -164,3 +266,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.