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

package/README.md

@@ -33,7 +33,25 @@ npm install @praxisui/dynamic-fields
 }
 ```
 
-Sem essas variáveis, a aparência deriva do tema M3 (tokens `--mat-sys-*` / `--md-sys-*`).
+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`
@@ -455,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`