@praxisui/dynamic-form 1.0.0-beta.67 → 1.0.0-beta.68

package/README.md

@@ -120,6 +120,69 @@ 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.
+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
 
@@ -305,6 +368,32 @@ See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 - `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:
@@ -322,7 +411,7 @@ Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que
 - 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`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
+  - `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`.