@praxisui/dynamic-fields 1.0.0-beta.4 → 1.0.0-beta.40

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,38 @@ 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 `--md-sys-*`).
+
+Tema e escopo (host)
+- 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 os componentes reflitam corretamente o tema do app host, garanta no mínimo:
+
+- 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`
+
+Notas:
+- Color pickers agora derivam paletas por padrão de tokens M3. Se quiser cores específicas, use `paletteColors`/`paletteSettings`.
+- A classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+- Datepicker usa `panelClass="pdx-datepicker-panel"`; personalize o overlay via essa classe no tema do host.
+
 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 +110,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 +141,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
@@ -395,3 +473,67 @@ const field: FieldMetadata = {
 - Suporta `setInputMetadata` ou signal `metadata` com `.set(...)` para hot updates.
 - Opcional: aceita `[readonlyMode]`, `[disabledMode]`, `[visible]`, `[presentationMode]`.
 - O `controlType` do campo coincide com o `id` do `ComponentDocMeta` (para resolver título/ícone no editor).
+
+### 🧼 Botão de limpar (clearButton)
+
+Muitos campos suportam um botão de limpar configurável via metadata. Ele aparece como um `mat-icon-button` no suffix do `mat-form-field` e respeita `readonly`, `disabled` e `presentationMode`.
+
+Exemplo de uso:
+
+```ts
+const field: FieldMetadata = {
+  name: 'search',
+  label: 'Buscar',
+  controlType: FieldControlType.INPUT,
+  clearButton: {
+    enabled: true,
+    icon: 'mi:clear',
+    iconColor: 'primary', // ou cor CSS (#496ddb, rgb(73,109,219), red)
+    tooltip: 'Limpar',
+    ariaLabel: 'Limpar busca',
+    showOnlyWhenFilled: true,
+  },
+};
+```
+
+Observações:
+- `iconColor` aceita tokens de tema (`primary`, `accent`, `warn`) ou cores CSS.
+- Em campos com comportamentos especializados (ex.: currency), o clear também limpa o valor visual.
+- `clearButton` também aceita boolean (`true/false`) por compatibilidade retroativa.
+- No `pdx-color-picker`, o clear é exibido no menu interno, mas aceita `clearButton` como boolean ou objeto (ícone/cor/tooltip).
+
+### ⭐ Filter Inline Rating (faixa)
+
+Use `controlType: 'filter-rating-inline'` quando o filtro de avaliação precisar trabalhar com intervalo no toolbar.
+
+Contrato de valor (payload):
+- `null` => sem filtro aplicado
+- `{ start: number | null, end: number | null }` => faixa de avaliação
+
+Exemplo:
+
+```ts
+const ratingRangeField: FieldMetadata = {
+  name: 'ratingRange',
+  label: 'Avaliação',
+  controlType: 'filter-rating-inline',
+  min: 1,
+  max: 5,
+  allowHalf: true,
+  ratingToneLowColor: '#ef4444',
+  ratingToneMidColor: '#f59e0b',
+  ratingToneHighColor: '#22a45d',
+  ratingBadgeColor: '#f59e0b',
+  clearButton: { enabled: true, showOnlyWhenFilled: true },
+};
+```
+
+Compatibilidade corporativa:
+- `FieldControlType.RATING` continua sendo valor único (ex.: `4`).
+- A conversão para faixa ocorre apenas com `controlType` explícito de inline rating (`filter-rating-inline` ou aliases inline).
+- Para permitir meia estrela, use `allowHalf: true` (ou `step: 0.5` quando precisar de controle manual).
+- Cores das estrelas no popover podem ser definidas por:
+  - `ratingToneLowColor`
+  - `ratingToneMidColor`
+  - `ratingToneHighColor`
+  - `ratingBadgeColor`