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

package/README.md

@@ -1,5 +1,12 @@
 # @praxisui/dynamic-fields — Dynamic Form Fields
 
+## 🔰 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.
+
 ### Concept Usage
 
 - [Dynamic Component Rendering](../../../../docs/concepts/dynamic-component-rendering.md)
@@ -14,6 +21,20 @@ Biblioteca de campos dinâmicos para aplicações Angular (v20+) com Material De
 npm install @praxisui/dynamic-fields
 ```
 
+### Estilos e tokens (opcional)
+
+- Largura dos campos: quando o host usa `providePraxisDynamicFields()`, a lib injeta um estilo escopado que garante `mat-form-field { width: 100% }` dentro dos componentes. Não é necessário repetir no app.
+- Gradiente de inputs/toolbar (se desejar): o host pode definir um gradiente de marca que alguns detalhes visuais consomem (ex.: inputs com gradiente configurado e toolbars de edição):
+
+```scss
+:root {
+  --p-primary-gradient: linear-gradient(90deg, #1f8a8a, #6c63ff);
+  --p-input-gradient: var(--p-primary-gradient);
+}
+```
+
+Sem essas variáveis, a aparência deriva do tema M3 (tokens `--mat-sys-*` / `--md-sys-*`).
+
 Peers (instale no app host):
 - `@angular/core` `^20.1.0`, `@angular/common` `^20.1.0`, `@angular/forms` `^20.1.0`
 - `@angular/material` `^20.1.0`, `@angular/cdk` `^20.1.0`, `@angular/router` `^20.1.0`
@@ -71,6 +92,7 @@ O sistema usa as constantes do `@praxisui/core` para garantir consistência:
 - `FieldControlType.TIME_PICKER` - Seletor de horário
 - `FieldControlType.RATING` - Classificação por estrelas
 - `FieldControlType.COLOR_PICKER` - Seletor de cores
+- `FieldControlType.AVATAR` - Avatar visual (imagem/ícone/iniciais)
 
 Campos com `FieldControlType.AUTO_COMPLETE` utilizam internamente o `MaterialSearchableSelectComponent`, habilitando busca automaticamente.
 
@@ -101,6 +123,44 @@ Grupo de botões de rádio que consome metadados ou dados remotos para criar sel
 - **Carregamento Dinâmico**: mesmas chaves de configuração de `MaterialSelectComponent` para buscar opções.
 - **Layout Flexível**: configuração de orientação, `labelPosition` e `color` segundo a [documentação oficial](https://material.angular.dev/components/radio/overview).
 
+## 🧩 Avatar Field
+
+Componente visual para exibir representação de usuário/entidade/estado, com prioridade de conteúdo:
+
+- imageSrc > icon > initials > ng-content
+
+Propriedades principais: `themeColor`, `rounded`, `size`, `fillMode`, `border`, `tooltip`, `ariaLabel`.
+
+Exemplos:
+
+```html
+<pdx-material-avatar [imageSrc]="user.img" size="large" themeColor="tertiary"></pdx-material-avatar>
+<pdx-material-avatar initials="MB" themeColor="secondary"></pdx-material-avatar>
+<pdx-material-avatar icon="person" fillMode="outline"></pdx-material-avatar>
+<pdx-material-avatar><app-status-badge></app-status-badge></pdx-material-avatar>
+```
+
+Uso em formulários dinâmicos (via metadata):
+
+```ts
+import { FieldControlType, type FieldMetadata } from '@praxisui/core';
+
+const fields: FieldMetadata[] = [
+  {
+    name: 'avatar',
+    label: 'Avatar',
+    controlType: FieldControlType.AVATAR,
+    // opções específicas via `extra` (quando aplicável)
+    extra: { imageSrc: 'https://example.com/u/42.png', size: 'large' }
+  }
+];
+```
+
+Tokens M3 aplicados:
+
+- `--pfx-avatar-bg`, `--pfx-avatar-fg`, `--pfx-avatar-border-color`, `--pfx-avatar-border-w`
+- `--pfx-avatar-size`, `--pfx-avatar-radius-[full|lg|md|sm]`
+
 ## 📦 Instalação
 
 ```bash