@praxisui/dynamic-fields 1.0.0-beta.5 → 1.0.0-beta.53

package/README.md

@@ -1,10 +1,63 @@
+---
+title: "Dynamic Fields"
+slug: "dynamic-fields-overview"
+description: "Visao geral do @praxisui/dynamic-fields com renderizacao metadata-driven, registro lazy de componentes, tokens M3 e campos enterprise."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "metadata"
+  - "forms"
+  - "runtime"
+  - "material"
+order: 32
+icon: "toc"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 16
+estimated_setup_time: 25
+version: "1.0"
+related_docs:
+  - "dynamic-fields-field-catalog"
+  - "dynamic-fields-field-selection-guide"
+  - "dynamic-fields-host-custom-field-guide"
+  - "dynamic-fields-host-custom-field-troubleshooting"
+  - "dynamic-fields-inline-filter-catalog"
+  - "dynamic-fields-filter-inline-components-guide"
+  - "host-integration-guide"
+  - "consumer-integration-quickstart"
+keywords:
+  - "dynamic field loader"
+  - "metadata-driven fields"
+  - "material controls"
+  - "runtime registry"
+last_updated: "2026-03-07"
+---
+
 # @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)
-- [Headless UI & Design Systems](../../../../docs/concepts/headless-ui-and-design-systems.md)
-- [Data Driven Forms](../../../../docs/concepts/data-driven-forms.md)
+- Dynamic component rendering
+- Headless UI and design systems
+- Data-driven forms
 
 Biblioteca de campos dinâmicos para aplicações Angular (v20+) com Material Design. Renderiza campos a partir de metadados, com carregamento lazy e integração com Reactive Forms.
 
@@ -14,6 +67,37 @@ 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 marca (se desejar): o host pode definir um gradiente para detalhes visuais da lib (ex.: toolbar de edição):
+
+```scss
+:root {
+  --p-primary-gradient: linear-gradient(90deg, #1f8a8a, #6c63ff);
+}
+```
+
+Sem essa variável, o toolbar usa fallback sólido em `--md-sys-color-primary`.
+
+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-on-primary`, `--md-sys-color-secondary`, `--md-sys-color-on-secondary`, `--md-sys-color-tertiary`, `--md-sys-color-on-tertiary`, `--md-sys-color-error`, `--md-sys-color-on-error`
+- Containers: `--md-sys-color-primary-container`, `--md-sys-color-on-primary-container`, `--md-sys-color-secondary-container`, `--md-sys-color-on-secondary-container`, `--md-sys-color-tertiary-container`, `--md-sys-color-on-tertiary-container`, `--md-sys-color-error-container`, `--md-sys-color-on-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`
@@ -47,32 +131,34 @@ const component = await registry.getComponent(FieldControlType.INPUT);
 const isRegistered = registry.isRegistered(FieldControlType.INPUT);
 ```
 
+## 📄 Documentacao Tecnica da Lib
+
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inventory.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-field-catalog.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-field-selection-guide.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-troubleshooting.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-inventory.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-catalog.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-selection-guide.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-runtime-contract.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-custom-component-guide.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-troubleshooting.md`
+- `projects/praxis-dynamic-fields/docs/filter-inline-components-guide.md` (slug: `dynamic-fields-filter-inline-components-guide`)
+- `projects/praxis-dynamic-fields/docs/generic-crud-service.md`
+
 ### Componentes Suportados
 
-O sistema usa as constantes do `@praxisui/core` para garantir consistência:
-
-- `FieldControlType.INPUT` - Campo de texto Material Design
-- `FieldControlType.TEXTAREA` - Área de texto Material Design
-- `FieldControlType.SELECT` - Campo de seleção Material Design
-- `FieldControlType.CHECKBOX` - Caixa de seleção Material Design
-- `FieldControlType.RADIO` - Botão de rádio Material Design
-- `FieldControlType.DATE_PICKER` - Seletor de data Material Design
-- `FieldControlType.EMAIL_INPUT` - Campo de email
-- `FieldControlType.PASSWORD` - Campo de senha
-- `FieldControlType.CURRENCY_INPUT` - Campo monetário
-- `FieldControlType.NUMERIC_TEXT_BOX` - Campo numérico
-- `FieldControlType.MULTI_SELECT` - Seleção múltipla
-- `FieldControlType.AUTO_COMPLETE` - Auto completar (busca habilitada por padrão)
-- `FieldControlType.DATE_TIME_PICKER` - Data e hora
-- `FieldControlType.DATE_RANGE` - Intervalo de datas
-- `FieldControlType.FILE_UPLOAD` - Upload de arquivos
-- `FieldControlType.TOGGLE` - Interruptor Material Design
-- `FieldControlType.SLIDER` - Slider Material Design
-- `FieldControlType.TIME_PICKER` - Seletor de horário
-- `FieldControlType.RATING` - Classificação por estrelas
-- `FieldControlType.COLOR_PICKER` - Seletor de cores
-
-Campos com `FieldControlType.AUTO_COMPLETE` utilizam internamente o `MaterialSearchableSelectComponent`, habilitando busca automaticamente.
+A fonte de verdade do suporte default e o `ComponentRegistryService`.
+
+Use os documentos governados abaixo em vez de manter listas textuais soltas:
+
+- inventario auditavel do runtime: `dynamic-fields-inventory.md`
+- catalogo principal de fields de formulario: `dynamic-fields-field-catalog.md`
+- guia de escolha do field correto: `dynamic-fields-field-selection-guide.md`
+- extensao do host: `dynamic-fields-host-custom-field-guide.md`
+- troubleshooting de extensao: `dynamic-fields-host-custom-field-troubleshooting.md`
+- trilha especializada de filtros compactos: `dynamic-fields-inline-filter-catalog.md`
 
 ## 🧩 MaterialSelectComponent
 
@@ -101,6 +187,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
@@ -309,6 +433,18 @@ _Sistema desenvolvido seguindo diretrizes de simplicidade e foco no essencial._
 
 ## 🔌 Extensão pelo App Host (registrando seu próprio componente)
 
+Resumo executivo:
+
+- `ComponentRegistryService.register(...)`: registra o componente que o runtime carrega.
+- `ComponentMetadataRegistry.register(...)`: registra nome/ícone/superfície editorial.
+- `controlType` do contrato deve bater com `ComponentDocMeta.id`.
+- Hot metadata funciona melhor quando o componente expõe `setInputMetadata(...)` e/ou signal de metadata.
+
+Para o guia governado completo, consulte:
+
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-troubleshooting.md`
+
 Aplicações host podem registrar componentes próprios para uso no DynamicFieldLoader e expor metadados para título/ícone amigáveis no editor.
 
 ### 1) Registrar o componente no runtime (DynamicFieldLoader)
@@ -395,3 +531,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`