@praxisui/dynamic-fields 8.0.0-beta.7 → 8.0.0-beta.70

package/README.md

@@ -115,6 +115,12 @@ Notas:
 - 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.
 
+### Prefixos Material e labels flutuantes
+
+O Angular Material documenta uma limitação real em `mat-form-field` com aparência `fill` ou `outline`: prefixos/sufixos de texto não alinham bem com o label em repouso, e a recomendação oficial atual é usar `floatLabel="always"` nesses casos. A plataforma segue essa recomendação para adornos estruturais permanentes, como swatches de cor e símbolos que fazem parte do valor visual.
+
+Não substitua essa política por offsets CSS locais. Offsets dependem de densidade, fonte, idioma, aparência Material e do tamanho do prefixo, e tendem a quebrar quando o Angular Material muda a estrutura MDC interna. Se o Angular Material passar a oferecer suporte nativo melhor para prefixos em `fill`/`outline`, reavalie esta decisão de plataforma e prefira voltar a delegar o alinhamento ao Material.
+
 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`
@@ -181,6 +187,19 @@ Estado atual da trilha:
 - familias fora da wave 1 ainda podem expor `ComponentDocMeta` proprio, mas isso nao as transforma em nova fonte canonica;
 - ao promover uma nova familia para a trilha canonica, a ordem correta e: descriptor editorial -> metadata derivado -> catalogo derivado -> consumo no `dynamic-form`.
 
+## Agentic Authoring & Manifest
+
+`@praxisui/dynamic-fields` publica `PRAXIS_DYNAMIC_FIELDS_AUTHORING_MANIFEST` como contrato executavel de authoring para a familia de controles. Diferente de componentes com um unico config editor, este manifesto governa a cadeia runtime/editorial/tooling.
+
+- **Component family:** `praxis-dynamic-fields`
+- **Config Schema:** `FieldMetadata`
+- **Editable targets:** 7 target kinds: `controlType`, `controlAlias`, `editorialDescriptor`, `selectorMapping`, `fieldMetadataPath`, `runtimeCoverage`, `editorCoverage`.
+- **Operation families:** 8 operations: `controlType.register`, `controlType.alias.add`, `controlType.alias.remove`, `descriptor.update`, `selector.mapping.set`, `metadata.mapping.set`, `editorCoverage.validate`, `runtimeCoverage.validate`.
+- **Validation:** 14 validators separam cobertura runtime de cobertura editorial/tooling, protegem aliases e selector mappings deterministas, alinham capabilities de `FieldMetadata` e exigem evidencia de cobertura.
+- **Control profiles:** 18 perfis (`text-input`, `numeric`, `currency`, `select`, `entity-lookup`, `tree-select`, `list-transfer`, `date`, `date-range`, `time-range`, `toggle`, `color`, `regional-document`, `file-upload`, `collection`, `avatar`, `display-action`, `field-shell`) adicionam operacoes, validators e examples granulares por classe de controle sem duplicar 1 manifesto completo por componente.
+- **Registry projection:** o manifesto e projetado na entrada agregada `praxis-dynamic-fields` e tambem nos componentes de `@praxisui/dynamic-fields` no `ai_registry`; cada componente projetado recebe `authoringManifestProfiles` com o perfil aplicavel, e runtime render sozinho nao e evidencia suficiente de suporte editorial.
+- **Selector mappings:** `selector.mapping.set` governa entradas do `FieldSelectorRegistry`; selectors de host precisam ser registrados explicitamente em vez de depender de convencao textual ou fallback por nome parecido.
+
 ### Componentes Suportados
 
 A fonte de verdade do suporte default e o `ComponentRegistryService`.

package/docs/dynamic-fields-field-catalog.md

@@ -0,0 +1,217 @@
+---
+title: "Dynamic Fields Field Catalog"
+slug: "dynamic-fields-field-catalog"
+description: "Catalogo principal dos fields padrao registrados em @praxisui/dynamic-fields para formularios metadata-driven."
+doc_type: "reference"
+document_kind: "governance-reference"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "catalog"
+  - "controlType"
+  - "forms"
+order: 34
+icon: "toc"
+toc: true
+sidebar: true
+search_boost: 1.05
+reading_time: 24
+estimated_setup_time: 30
+version: "1.0"
+related_docs:
+  - "dynamic-fields-overview"
+  - "dynamic-fields-inventory"
+  - "dynamic-fields-field-selection-guide"
+  - "dynamic-fields-host-custom-field-guide"
+  - "dynamic-fields-inline-filter-catalog"
+keywords:
+  - "field catalog"
+  - "which field to use"
+  - "controlType"
+  - "metadata snippet"
+last_updated: "2026-03-26"
+---
+
+# Dynamic Fields Field Catalog
+
+## Overview
+
+Este catalogo cobre os fields padrao registrados por default para formularios dinamicos comuns.
+
+Nao entram aqui:
+
+- aliases de compatibilidade (`dateTime`, `treeView`);
+- fields inline especializados de filtro.
+
+Para auditoria completa do runtime, consulte [Dynamic Fields Inventory](./dynamic-fields-inventory.md). Para inline filter controls, consulte [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md).
+
+## Published surface for hosts
+
+Este markdown continua sendo a referencia governada de narrativa, recomendacoes de uso e snippets curtos.
+
+Para consumo operacional por hosts oficiais, a superficie canonica e o catalogo exportado pela lib em `src/lib/catalog/dynamic-fields-playground.catalog.ts`, reexportado pelo `public-api` de `@praxisui/dynamic-fields`.
+
+Regra de uso:
+
+- host, landing e playground consomem o catalogo exportado;
+- este documento explica quando usar, quando evitar e para onde navegar;
+- mudancas de runtime ou descoberta devem nascer primeiro na lib canonica, nao em listas locais do host.
+
+## Canonical editorial source
+
+Para os controls ja cobertos pela trilha editorial/i18n canonica, este catalogo nao e a fonte primaria de `friendlyName`, `description` ou `icon`.
+
+Regra de governanca:
+
+- descriptor em `src/lib/editorial/**`: fonte canonica da semantica editorial;
+- `ComponentDocMeta`: artefato derivado da mesma semantica para builders/registry;
+- catalogo playground/showcase: artefato derivado para discovery e narrativa de uso;
+- `dynamic-form`: consumidor do resolver canonico, sem mapa editorial local.
+
+Se um novo field precisar entrar neste catalogo com copy governada, ele deve primeiro entrar na trilha canonica da lib. Nao e aceitavel publicar copy nova apenas aqui.
+
+## How to read this catalog
+
+- `quando usar`: caso de uso preferencial;
+- `quando evitar`: quando outro field entrega UX melhor;
+- `valor esperado`: shape mental do valor no form;
+- `snippet`: exemplo curto de metadata, focado no `controlType`.
+
+## Published discovery semantics
+
+O catalogo exportado por `@praxisui/dynamic-fields` agora publica semantica de descoberta para hosts oficiais:
+
+- `track`: separa `primary-form` de `inline-filter`;
+- `family`: agrupa a taxonomia funcional do field;
+- `interactionPattern`: resume o padrao dominante de uso, como `single-value`, `lookup`, `range`, `visual` ou `trigger`;
+- `icon.key` + `icon.tone`: entregam identidade visual canonica para menus, vitrines e playgrounds.
+
+Regra editorial:
+
+- este markdown continua explicando `quando usar` e `quando evitar`;
+- landing, playground e outros hosts devem derivar navegacao, cues e mini-cards do catalogo exportado da lib;
+- a documentacao nao deve manter uma tabela paralela de icones ou interaction patterns fora da fonte canonica.
+
+## Texto
+
+| Field          | controlType                                   | Quando usar                  | Quando evitar                        | Valor esperado | Snippet                                               | Detail doc                                |
+| -------------- | --------------------------------------------- | ---------------------------- | ------------------------------------ | -------------- | ----------------------------------------------------- | ----------------------------------------- |
+| Text input     | <span id="input"></span>`input`               | texto livre curto            | quando ha formato fechado            | `string`       | `{ name: 'fullName', controlType: 'input' }`          | `pdx-text-input.json-api.md`              |
+| Email input    | <span id="email"></span>`email`               | email validado               | se o campo aceita qualquer texto     | `string`       | `{ name: 'email', controlType: 'email' }`             | `pdx-email-input.json-api.md`             |
+| Password input | <span id="password"></span>`password`         | segredo/senha                | quando o valor precisa ficar legivel | `string`       | `{ name: 'password', controlType: 'password' }`       | `pdx-password-input.json-api.md`          |
+| Textarea       | <span id="textarea"></span>`textarea`         | descricao longa, observacoes | conteudo curto de uma linha          | `string`       | `{ name: 'notes', controlType: 'textarea', rows: 4 }` | `pdx-material-textarea.json-api.md`       |
+| Search input   | <span id="search"></span>`search`             | busca textual dedicada       | entrada comum sem semantica de busca | `string`       | `{ name: 'query', controlType: 'search' }`            | `pdx-search-input.json-api.md`            |
+| Phone input    | <span id="phone"></span>`phone`               | telefone                     | se o dominio nao usa telefone        | `string`       | `{ name: 'phone', controlType: 'phone' }`             | `pdx-phone-input.json-api.md`             |
+| URL input      | <span id="url"></span>`url`                   | links/URLs                   | strings livres sem validacao de URL  | `string`       | `{ name: 'website', controlType: 'url' }`             | `pdx-url-input.json-api.md`               |
+| CPF/CNPJ input | <span id="cpfcnpjinput"></span>`cpfCnpjInput` | documento brasileiro         | dominio internacional/generalista    | `string`       | `{ name: 'document', controlType: 'cpfCnpjInput' }`   | `pdx-material-cpf-cnpj-input.json-api.md` |
+
+## Numero, moeda e range
+
+| Field          | controlType                                       | Quando usar                                                                           | Quando evitar                        | Valor esperado  | Snippet                                                                                            | Detail doc                              |
+| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Number input   | <span id="numerictextbox"></span>`numericTextBox` | numero simples                                                                        | intervalo guiado por slider          | `number`        | `{ name: 'age', controlType: 'numericTextBox' }`                                                   | `pdx-number-input.json-api.md`          |
+| Currency input | <span id="currency"></span>`currency`             | valor monetario unico                                                                 | faixa monetaria                      | `number`        | `{ name: 'budget', controlType: 'currency' }`                                                      | `pdx-material-currency.json-api.md`     |
+| Slider         | <span id="slider"></span>`slider`                 | valor unico em faixa continua, com marks, value label, bandas semanticas e histograma responsivo ao valor | campos financeiros complexos         | `number`        | `{ name: 'score', controlType: 'slider', min: 0, max: 10, valueLabelDisplay: 'on' }`               | `pdx-material-slider.json-api.md`       |
+| Range slider   | <span id="rangeslider"></span>`rangeSlider`       | faixa numerica com marks, inputs opcionais, distancia min/max, bandas e distribuicao responsiva ao range  | datas/horarios                       | `{ start,end }` | `{ name: 'range', controlType: 'rangeSlider', mode: 'range', min: 0, max: 100, showInputs: true }` | `pdx-material-range-slider.json-api.md` |
+| Price range    | <span id="pricerange"></span>`priceRange`         | faixa monetaria                                                                       | uma moeda unica                      | `{ min,max }`   | `{ name: 'priceBand', controlType: 'priceRange' }`                                                 | `pdx-material-price-range.json-api.md`  |
+| Rating         | <span id="rating"></span>`rating`                 | nota/avaliacao visual                                                                 | quando precisao numerica e dominante | `number`        | `{ name: 'satisfaction', controlType: 'rating' }`                                                  | `pdx-material-rating.json-api.md`       |
+
+### Contrato de preview do catalogo jogavel
+
+`previewRecipe.presets[].initialValue` define a semente padrao do preset apos aplicar o metadata do estado ativo. Quando um preset precisa que um estado especifico tenha valor proprio, use `previewRecipe.presets[].stateInitialValues`.
+
+Precedencia da semente no playground:
+
+1. `preset.stateInitialValues[state]`
+2. `state.initialValue`
+3. `preset.initialValue`
+4. `defaultState.initialValue`
+5. fallback gerado pelo runtime do playground
+
+Use `stateInitialValues` apenas quando o valor do preset precisa continuar coerente com a semantica daquele estado, como `Currency + Filled` em `rangeSlider`.
+
+## Data e tempo
+
+| Field          | controlType                                     | Quando usar                   | Quando evitar                                   | Valor esperado          | Snippet                                                 | Detail doc                             |
+| -------------- | ----------------------------------------------- | ----------------------------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------- | -------------------------------------- |
+| Date input     | <span id="dateinput"></span>`dateInput`         | integracao com input nativo   | quando o host precisa UX Material forte         | `string \| Date`        | `{ name: 'birthDate', controlType: 'dateInput' }`       | `pdx-date-input.json-api.md`           |
+| Date picker    | <span id="date"></span>`date`                   | selecao de data no formulario | se o fluxo pede intervalo                       | `Date \| string`        | `{ name: 'startDate', controlType: 'date' }`            | `pdx-material-datepicker.json-api.md`  |
+| Date range     | <span id="daterange"></span>`dateRange`         | intervalo de datas            | data unica                                      | `{ startDate,endDate }` | `{ name: 'period', controlType: 'dateRange' }`          | `pdx-material-date-range.json-api.md`  |
+| Datetime local | <span id="datetimelocal"></span>`dateTimeLocal` | data + hora local em um campo | quando o fluxo precisa seletor dedicado de hora | `string`                | `{ name: 'appointment', controlType: 'dateTimeLocal' }` | `pdx-datetime-local-input.json-api.md` |
+| Month input    | <span id="month"></span>`month`                 | mes/ano                       | datas completas                                 | `string`                | `{ name: 'competence', controlType: 'month' }`          | `pdx-month-input.json-api.md`          |
+| Time input     | <span id="time"></span>`time`                   | hora simples                  | intervalo de horario                            | `string`                | `{ name: 'startAt', controlType: 'time' }`              | `pdx-time-input.json-api.md`           |
+| Time picker    | <span id="timepicker"></span>`timePicker`       | seletor de horario Material   | campo simples sem picker                        | `string`                | `{ name: 'slot', controlType: 'timePicker' }`           | `pdx-material-timepicker.json-api.md`  |
+| Time range     | <span id="timerange"></span>`timeRange`         | janela de horario             | apenas uma hora                                 | `{ start,end }`         | `{ name: 'window', controlType: 'timeRange' }`          | `pdx-material-time-range.json-api.md`  |
+| Week input     | <span id="week"></span>`week`                   | semana ISO                    | quando o negocio trabalha por data convencional | `string`                | `{ name: 'weekRef', controlType: 'week' }`              | `pdx-week-input.json-api.md`           |
+| Year input     | <span id="year"></span>`year`                   | ano isolado                   | mes/ano ou data completa                        | `number \| string`      | `{ name: 'fiscalYear', controlType: 'year' }`           | `pdx-year-input.json-api.md`           |
+
+## Selecao
+
+| Field             | controlType                                             | Quando usar                                                                    | Quando evitar                                              | Valor esperado               | Snippet                                                                                                            | Detail doc                                   |
+| ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| Select            | <span id="select"></span>`select`                       | lista fechada simples                                                          | bases muito grandes sem busca                              | `string \| number \| object` | `{ name: 'status', controlType: 'select', options: [...] }`                                                        | `pdx-material-select.json-api.md`            |
+| Searchable select | <span id="searchable-select"></span>`searchable-select` | lista maior com busca                                                          | consultas remotas pesadas                                  | `string \| number \| object` | `{ name: 'department', controlType: 'searchable-select' }`                                                         | `pdx-material-searchable-select.json-api.md` |
+| Async select      | <span id="async-select"></span>`async-select`           | opcoes remotas                                                                 | lista pequena local                                        | `string \| number \| object` | `{ name: 'city', controlType: 'async-select', resourcePath: 'cities' }`                                            | `pdx-material-async-select.json-api.md`      |
+| Entity lookup     | <span id="entitylookup"></span>`entityLookup`           | entidade corporativa com identidade, status, reidratacao e politica de selecao | opcoes simples sem semantica de entidade                   | `entity id \| EntityRef`     | `{ name: 'supplierId', controlType: 'entityLookup', optionSource: { key: 'suppliers', type: 'RESOURCE_ENTITY' } }` | `pdx-inline-entity-lookup.json-api.md`       |
+| Autocomplete      | <span id="autocomplete"></span>`autoComplete`           | busca progressiva com sugestoes                                                | quando o usuario deve escolher so de lista fechada simples | `string \| number \| object` | `{ name: 'role', controlType: 'autoComplete' }`                                                                    | `pdx-material-autocomplete.json-api.md`      |
+| Multi select      | <span id="multiselect"></span>`multiSelect`             | multiplas escolhas                                                             | se o usuario so pode escolher uma opcao                    | `unknown[]`                  | `{ name: 'tags', controlType: 'multiSelect' }`                                                                     | `pdx-material-multi-select.json-api.md`      |
+
+## Arvores e listas
+
+| Field               | controlType                                         | Quando usar                                              | Quando evitar                                   | Valor esperado                   | Snippet                                                                                | Detail doc                                   |
+| ------------------- | --------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Multi select tree   | <span id="multiselecttree"></span>`multiSelectTree` | hierarquia com multiplas selecoes                        | lista plana pequena                             | `unknown[]`                      | `{ name: 'permissions', controlType: 'multiSelectTree' }`                              | `pdx-material-multi-select-tree.json-api.md` |
+| Tree select         | <span id="treeselect"></span>`treeSelect`           | hierarquia com selecao simples                           | multiplas selecoes                              | `string \| number \| object`     | `{ name: 'category', controlType: 'treeSelect' }`                                      | `pdx-material-tree-select.json-api.md`       |
+| Editable collection | <span id="array"></span>`array`                     | lista repetivel de objetos com subcampos metadata-driven | uma entidade unica ou selecao simples de opcoes | `Array<Record<string, unknown>>` | `{ name: 'contacts', controlType: 'array', array: { itemSchema: { fields: [...] } } }` | `pdx-editable-collection`                    |
+| Selection list      | <span id="selectionlist"></span>`selectionList`     | lista grande com affordance de lista                     | layouts que pedem dropdown compacto             | `unknown[]`                      | `{ name: 'channels', controlType: 'selectionList' }`                                   | `pdx-material-selection-list.json-api.md`    |
+| Transfer list       | <span id="transferlist"></span>`transferList`       | mover itens entre disponivel/selecionado                 | selecoes simples                                | `unknown[]`                      | `{ name: 'members', controlType: 'transferList' }`                                     | `pdx-material-transfer-list.json-api.md`     |
+| Chip input          | <span id="chipinput"></span>`chipInput`             | lista textual editavel                                   | se ordem/edicao nao importam                    | `string[]`                       | `{ name: 'emails', controlType: 'chipInput' }`                                         | `pdx-material-chips.json-api.md`             |
+| Chip list           | <span id="chiplist"></span>`chipList`               | exibicao/edicao em chips                                 | entrada de valor unico                          | `string[]`                       | `{ name: 'labels', controlType: 'chipList' }`                                          | `pdx-material-chips.json-api.md`             |
+
+## Toggle e choice
+
+| Field         | controlType                                   | Quando usar                                                                                           | Quando evitar                                    | Valor esperado                | Snippet                                                                         | Detail doc                                |
+| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
+| Checkbox      | <span id="checkbox"></span>`checkbox`         | booleano simples com `selectionMode: 'boolean'` ou multiplas escolhas com `selectionMode: 'multiple'` | contrato novo sem `selectionMode`; escolha unica | `boolean \| unknown[]`        | `{ name: 'privacyConsent', controlType: 'checkbox', selectionMode: 'boolean' }` | `pdx-material-checkbox-group.json-api.md` |
+| Radio group   | <span id="radio"></span>`radio`               | escolha unica explicita com `selectionMode: 'single'`                                                 | muitas opcoes/espaco restrito                    | `string \| number \| boolean` | `{ name: 'priority', controlType: 'radio', selectionMode: 'single' }`           | `pdx-material-radio-group.json-api.md`    |
+| Toggle        | <span id="toggle"></span>`toggle`             | booleano binario                                                                                      | multiplos estados                                | `boolean`                     | `{ name: 'active', controlType: 'toggle' }`                                     | `pdx-material-slide-toggle.json-api.md`   |
+| Button toggle | <span id="buttontoggle"></span>`buttonToggle` | escolha segmentada curta                                                                              | listas longas                                    | `string \| number`            | `{ name: 'mode', controlType: 'buttonToggle' }`                                 | `pdx-material-button-toggle.json-api.md`  |
+
+## Upload
+
+| Field       | controlType                       | Quando usar         | Quando evitar                    | Valor esperado               | Snippet                                         | Detail doc                             |
+| ----------- | --------------------------------- | ------------------- | -------------------------------- | ---------------------------- | ----------------------------------------------- | -------------------------------------- |
+| File upload | <span id="upload"></span>`upload` | anexos e documentos | quando o fluxo nao exige arquivo | `File \| File[] \| metadata` | `{ name: 'attachment', controlType: 'upload' }` | `pdx-material-file-upload.json-api.md` |
+
+## Cor
+
+| Field        | controlType                                 | Quando usar                   | Quando evitar             | Valor esperado | Snippet                                          | Detail doc                     |
+| ------------ | ------------------------------------------- | ----------------------------- | ------------------------- | -------------- | ------------------------------------------------ | ------------------------------ |
+| Color input  | <span id="color"></span>`color`             | cor simples por valor textual | UX rica de paleta         | `string`       | `{ name: 'brandColor', controlType: 'color' }`   | `pdx-color-input.json-api.md`  |
+| Color picker | <span id="colorpicker"></span>`colorPicker` | paleta, presets, selecao rica | entrada rapida sem picker | `string`       | `{ name: 'accent', controlType: 'colorPicker' }` | `pdx-color-picker.json-api.md` |
+
+## Visual e acao
+
+| Field        | controlType                                 | Quando usar                              | Quando evitar                  | Valor esperado     | Snippet                                                                          | Detail doc                        |
+| ------------ | ------------------------------------------- | ---------------------------------------- | ------------------------------ | ------------------ | -------------------------------------------------------------------------------- | --------------------------------- |
+| Avatar       | <span id="avatar"></span>`avatar`           | representacao visual de usuario/entidade | captura de dado textual        | `string \| object` | `{ name: 'ownerAvatar', controlType: 'avatar' }`                                 | `pdx-material-avatar.json-api.md` |
+| Button       | <span id="button"></span>`button`           | acao auxiliar dentro do layout           | submit/cancel padrao do form   | n/a                | `{ name: 'validateBtn', controlType: 'button', action: 'validateCustomerData' }` | `pdx-material-button.json-api.md` |
+| Cron builder | <span id="cronbuilder"></span>`cronBuilder` | agenda/expressao cron                    | datas simples ou ranges comuns | `string`           | `{ name: 'schedule', controlType: 'cronBuilder' }`                               | `@praxisui/cron-builder`          |
+
+## Notes for enterprise use
+
+- prefira `select`/`searchable-select`/`async-select` conforme o tamanho e a origem dos dados;
+- prefira `entityLookup` quando o valor representa uma entidade real do dominio e precisa de `RESOURCE_ENTITY`, reidratacao por id, status, permissao de selecao ou dependencias;
+- prefira `array` quando o usuario precisa editar uma colecao repetivel de objetos, como contatos, linhas de pedido ou itens de contrato;
+- prefira `date` sobre `dateInput` quando o design system precisa consistencia Material;
+- trate `button`, `avatar` e `cronBuilder` como controls especializados, nao como default;
+- para trilha de filtros compactos, use o catalogo separado de inline filters;
+- para vitrine jogavel e descoberta entre squads, prefira derivar categorias, tags, snippets, `interactionPattern` e `icon` a partir do catalogo exportado da lib.

package/docs/dynamic-fields-field-selection-guide.md

@@ -0,0 +1,204 @@
+---
+title: "Dynamic Fields Field Selection Guide"
+slug: "dynamic-fields-field-selection-guide"
+description: "Guia para escolher o field certo em @praxisui/dynamic-fields, considerando UX, contrato, origem dos dados e extensao no host."
+doc_type: "guide"
+document_kind: "governance-reference"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "decision guide"
+  - "controlType"
+  - "ux"
+order: 35
+icon: "rule"
+toc: true
+sidebar: true
+search_boost: 1.08
+reading_time: 14
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-fields-field-catalog"
+  - "dynamic-fields-inventory"
+  - "dynamic-fields-host-custom-field-guide"
+  - "dynamic-fields-inline-filter-catalog"
+  - "dynamic-fields-inline-components-guide"
+keywords:
+  - "choose field"
+  - "select vs autocomplete"
+  - "custom host field"
+  - "inline filter"
+last_updated: "2026-03-26"
+---
+
+# Dynamic Fields Field Selection Guide
+
+## Objective
+
+Escolher o `controlType` certo nao e apenas um detalhe visual. A decisao afeta:
+
+- clareza de UX;
+- shape do valor no contrato;
+- performance do runtime;
+- chance de hot update funcionar sem refresh estrutural;
+- custo de manutencao no host.
+
+## Fonte canonica para descoberta
+
+Para decisao humana, este guia e o field catalog continuam sendo a referencia editorial principal.
+
+Para descoberta operacional em landing pages, playgrounds e outros hosts oficiais, use o catalogo exportado por `@praxisui/dynamic-fields`. Ele centraliza `controlType`, trilha (`primary-form` ou `inline-filter`), categorias, `interactionPattern`, semantica de `icon`, estados relevantes, snippets e links oficiais, com validacao de paridade contra o runtime.
+
+Regra pratica para hosts:
+
+- use `interactionPattern` para comunicar como o field decide ou captura valor;
+- use `dataSourceKind` para deixar claro se o caso e local, remoto, misto ou especializado;
+- use `icon.key` e `icon.tone` apenas como projecao visual do catalogo canonico, nunca como regra inventada no host.
+
+## Politica visual para labels, icones e prefixos
+
+Campos Material com `appearance: 'fill'` ou `'outline'` e conteudo em
+`matPrefix`/`matSuffix` precisam de cuidado especial. Isso inclui `prefixIcon`,
+`suffixIcon`, `clearButton`, datepicker toggle, seletor de cor, simbolo de moeda
+e controles equivalentes.
+
+Para esses casos, use a configuracao canonica:
+
+```json
+{
+  "materialDesign": {
+    "floatLabel": "always",
+    "subscriptSizing": "dynamic"
+  }
+}
+```
+
+Essa configuracao deve vir da metadata ou da politica global do host que gera os
+campos, nao de CSS local. O Angular Material documenta que, em campos
+`fill`/`outline`, prefixos/sufixos nao se alinham bem com labels em repouso; por
+isso a recomendacao oficial e manter o label sempre flutuante nesses cenarios.
+
+## 1. Texto livre vs selecao
+
+### Use `input` / `textarea` quando
+
+- o usuario realmente precisa escrever;
+- o dominio aceita grande variacao lexical;
+- nao existe catalogo confiavel de opcoes.
+
+### Use `select` / `searchable-select` / `async-select` / `autoComplete` quando
+
+- o valor deve vir de um conjunto governado;
+- o backend precisa consistencia sem normalizacao extra;
+- a opcao precisa carregar label + id de forma previsivel.
+
+### Sinal de erro de escolha
+
+Se o schema usa `input` para algo que depois exige validacao pesada, busca semantica ou reconciliacao contra catalogo, provavelmente deveria ser selecao.
+
+## 2. Local vs remoto
+
+| Scenario | Prefer | Why |
+| --- | --- | --- |
+| poucas opcoes estaveis | `select` | simples, previsivel, barato |
+| lista media/grande com busca local | `searchable-select` | reduz carga visual |
+| lista remota/paginada | `async-select` | evita preload caro |
+| entidade de negocio remota com status, permissao, reidratacao ou dependencias | `entityLookup` | preserva identidade de entidade e usa contrato `RESOURCE_ENTITY` em vez de tratar entidade como opcao simples |
+| busca incremental com semantica de sugestao | `autoComplete` | boa UX para descoberta |
+
+## 3. Simples vs range
+
+| Need | Prefer | Avoid |
+| --- | --- | --- |
+| um numero | `numericTextBox` | `rangeSlider` |
+| um valor monetario | `currency` | `priceRange` |
+| uma data | `date` | `dateRange` |
+| uma hora | `time` ou `timePicker` | `timeRange` |
+| faixa numerica | `rangeSlider` | dois `numericTextBox` desconectados |
+| faixa monetaria | `priceRange` | dois `currency` soltos |
+| faixa temporal | `dateRange` ou `timeRange` | dois campos sem semantica de range |
+| lista repetivel de objetos | `array` | varios grupos duplicados manualmente |
+
+## 4. Padrao vs custom host
+
+### Fique no catalogo padrao quando
+
+- o field ja esta registrado por default;
+- a diferenca e apenas visual ou de metadata;
+- o comportamento cabe em inputs/props do componente existente;
+- o runtime ja cobre CVA, hot update e editor metadata.
+
+### Crie field custom no host quando
+
+- o dominio pede interacao especializada que nao cabe no catalogo;
+- o componente precisa de semantica propria no editor;
+- o contrato precisa de `controlType` exclusivo e governado pelo host.
+
+Antes de criar, consulte [Dynamic Fields Host Custom Field Guide](./dynamic-fields-host-custom-field-guide.md).
+
+## 5. Form field vs inline filter field
+
+Nao misture as duas narrativas:
+
+- formulario comum: use `input`, `select`, `date`, `upload`, `toggle`, etc.;
+- filtro inline compacto: use `inline*` apenas em trilhas de filtro.
+
+Se o caso e filtro corporativo compacto, consulte:
+
+- [Dynamic Fields Inline Filter Catalog](./dynamic-fields-inline-filter-catalog.md)
+- [Dynamic Fields Inline Components Guide](./dynamic-fields-inline-components-guide.md)
+
+## 6. Decision table
+
+| Question | Prefer |
+| --- | --- |
+| o usuario escreve texto curto? | `input` |
+| o usuario escreve texto longo? | `textarea` |
+| o usuario escolhe 1 opcao de lista pequena? | `select` |
+| o usuario escolhe 1 opcao de lista grande? | `searchable-select` |
+| a lista vem do backend sob demanda? | `async-select` |
+| o usuario escolhe entidade real do dominio? | `entityLookup` |
+| a UX parece busca com sugestoes? | `autoComplete` |
+| o valor e monetario? | `currency` / `priceRange` |
+| o valor e data? | `date` / `dateRange` |
+| o valor e horario? | `time` / `timePicker` / `timeRange` |
+| o padrao e lookup governado com busca? | `entityLookup` quando houver identidade/status/politica; `searchable-select` / `async-select` / `autoComplete` para opcoes simples |
+| o padrao e range com semantica propria? | `priceRange` / `dateRange` / `timeRange` / `inlineDateRange` |
+| o padrao e visual semantico? | `rating` / `inlinePipelineStatus` / `inlineSentiment` / `inlineColorLabel` |
+| o valor e booleano? | `toggle` |
+| a escolha unica precisa ser muito explicita? | `radio` ou `buttonToggle` |
+| ha multiplas escolhas discretas? | `checkbox` ou `multiSelect` |
+| ha hierarquia? | `treeSelect` / `multiSelectTree` |
+| ha uma colecao repetivel de objetos? | `array` |
+| ha anexos? | `upload` |
+| o controle e acao, nao dado? | `button` |
+| nada do catalogo resolve sem gambiarra? | field custom do host |
+
+## 7. Enterprise recommendations
+
+- prefira nomes canonicos de `controlType`; deixe aliases apenas para compatibilidade;
+- nao use inline filter controls em formularios normais para “economizar espaco”;
+- para campos remotos, explicite origem de dados e comportamento de busca;
+- para entidades de negocio, use `entityLookup` com `optionSource.type = RESOURCE_ENTITY`, `byIds`, `dependsOn`, `dependencyFilterMap` e `selectionPolicy` quando a selecao depender de status, permissao ou contexto;
+- para colecoes repetiveis, use `array` com `array.itemSchema.fields` em vez de criar campos numerados como `item1`, `item2`, `item3`;
+- para custom fields, alinhe runtime registry + metadata registry + hot update desde o inicio.
+
+## Nota de governanca para hosts
+
+Se um host precisar montar vitrine, filtros ou snippets jogaveis, derive isso do catalogo exportado da lib em vez de manter listas autorais locais.
+
+Isso inclui explicitamente:
+
+- cues de decisao;
+- navegacao por tipo de interacao;
+- iconografia de cards e menus;
+- agrupamentos por track/family para descoberta operacional.