@praxisui/dynamic-fields 8.0.0-beta.19 → 8.0.0-beta.20

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,181 @@
+---
+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.
+
+## 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.

package/docs/dynamic-fields-host-custom-field-guide.md

@@ -0,0 +1,252 @@
+---
+title: "Dynamic Fields Host Custom Field Guide"
+slug: "dynamic-fields-host-custom-field-guide"
+description: "Guia enterprise para criar, registrar e operar fields custom no host usando @praxisui/dynamic-fields."
+doc_type: "guide"
+document_kind: "host-guide"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "host"
+  - "frontend"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "host extension"
+  - "custom field"
+  - "environment initializer"
+order: 36
+icon: "extension"
+toc: true
+sidebar: true
+search_boost: 1.1
+reading_time: 20
+estimated_setup_time: 35
+version: "1.0"
+related_docs:
+  - "dynamic-fields-field-catalog"
+  - "dynamic-fields-field-selection-guide"
+  - "dynamic-fields-host-custom-field-troubleshooting"
+  - "dynamic-fields-inventory"
+  - "dynamic-form-overview"
+keywords:
+  - "ComponentRegistryService.register"
+  - "ComponentMetadataRegistry.register"
+  - "ENVIRONMENT_INITIALIZER"
+  - "custom controlType"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Fields Host Custom Field Guide
+
+## Objetivo
+
+Permitir que times host criem novos fields sem forkar `@praxisui/dynamic-fields` ou `@praxisui/dynamic-form`.
+
+## Pre-requisitos
+
+- Host Angular com `ApplicationConfig` ou bootstrap equivalente.
+- `@praxisui/dynamic-fields` instalado com providers ativos.
+- Familiaridade basica com `FieldMetadata`, `controlType` e Angular Forms.
+
+## Contract for a good custom field
+
+Um field custom enterprise precisa atender quatro camadas:
+
+1. `runtime render`: o registry precisa saber qual componente carregar para o `controlType`.
+2. `forms integration`: o componente precisa funcionar com `ControlValueAccessor` e/ou `[formControl]`.
+3. `metadata editor`: o editor precisa saber nome amigavel, icone e metadados do componente.
+4. `hot metadata`: o componente precisa responder a patches sem rebuild global sempre que possivel.
+
+## Runtime registry vs metadata registry
+
+### Runtime registry
+
+Responsavel por renderizar o componente no loader:
+
+```ts
+ComponentRegistryService.register('my-custom', () =>
+  import('./my-custom-field.component').then((m) => m.MyCustomFieldComponent),
+);
+```
+
+### Metadata registry
+
+Responsavel por:
+
+- nome amigavel no editor;
+- icone;
+- superficie editorial associada ao `controlType`.
+
+O `ComponentDocMeta.id` precisa bater com o `controlType` de runtime.
+
+## Canonical package-owned fields vs host custom fields
+
+Regra de fronteira:
+
+- fields mantidos por `@praxisui/dynamic-fields` devem entrar pela trilha canonica da lib: descriptor editorial + metadata derivado + catalogo derivado;
+- fields custom do host continuam suportados via `ComponentMetadataRegistry.register(ComponentDocMeta)`;
+- o host nao precisa copiar a trilha inteira da lib para continuar funcionando no `dynamic-form`;
+- se o host quiser semantica editorial propria, ela deve nascer no seu proprio registry/contrato, nao por override local de catalogo ou patch no `dynamic-form`.
+
+Na pratica, o `dynamic-form` tenta primeiro a resolucao canonica editorial e, se ela nao existir para um `controlType` do host, usa o `ComponentDocMeta` registrado pelo proprio host como fallback tecnico controlado.
+
+## Minimal component requirements
+
+### Forms compatibility
+
+O componente host deve:
+
+- implementar `ControlValueAccessor`, ou
+- aceitar `[formControl]`/`formControlName` de forma correta.
+
+Sem isso, o field pode ate renderizar, mas quebra integracao com o formulario dinamico.
+
+### Hot metadata compatibility
+
+Com base no runtime documentado em `hot-metadata-updates.md`, prefira:
+
+- `setInputMetadata(metadata)` no componente, ou
+- um `WritableSignal` para metadata.
+
+Isso permite que o dynamic form reaplique metadata viva sem rebuild estrutural sempre que a mudanca nao for estrutural.
+Use como referencia operacional governada o arquivo `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`.
+
+## Example: ApplicationConfig with ENVIRONMENT_INITIALIZER
+
+```ts
+import { ApplicationConfig, ENVIRONMENT_INITIALIZER, inject } from '@angular/core';
+import { providePraxisDynamicFields } from '@praxisui/dynamic-fields';
+import { ComponentRegistryService } from '@praxisui/dynamic-fields';
+import { ComponentMetadataRegistry, type ComponentDocMeta } from '@praxisui/core';
+
+const myCustomMeta: ComponentDocMeta = {
+  id: 'my-custom',
+  title: 'My Custom Field',
+  icon: 'extension',
+  category: 'host-fields',
+  description: 'Field custom do host para selecionar SLA operacional.',
+};
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...providePraxisDynamicFields(),
+    {
+      provide: ENVIRONMENT_INITIALIZER,
+      multi: true,
+      useValue: () => {
+        const registry = inject(ComponentRegistryService);
+        registry.register('my-custom', () =>
+          import('./fields/my-custom-field.component').then((m) => m.MyCustomFieldComponent),
+        );
+      },
+    },
+    {
+      provide: ENVIRONMENT_INITIALIZER,
+      multi: true,
+      useValue: () => {
+        const metadataRegistry = inject(ComponentMetadataRegistry);
+        metadataRegistry.register(myCustomMeta);
+      },
+    },
+  ],
+};
+```
+
+## Example: component skeleton
+
+```ts
+import { Component, input, signal } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR, FormControl, ReactiveFormsModule } from '@angular/forms';
+import type { FieldMetadata } from '@praxisui/core';
+
+@Component({
+  selector: 'app-my-custom-field',
+  standalone: true,
+  imports: [ReactiveFormsModule],
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      multi: true,
+      useExisting: MyCustomFieldComponent,
+    },
+  ],
+  template: `
+    <input [formControl]="control" />
+  `,
+})
+export class MyCustomFieldComponent implements ControlValueAccessor {
+  readonly control = new FormControl('');
+  readonly metadata = signal<FieldMetadata | null>(null);
+
+  setInputMetadata(metadata: FieldMetadata): void {
+    this.metadata.set(metadata);
+  }
+
+  writeValue(value: unknown): void {
+    this.control.setValue(value, { emitEvent: false });
+  }
+
+  registerOnChange(fn: (value: unknown) => void): void {
+    this.control.valueChanges.subscribe(fn);
+  }
+
+  registerOnTouched(fn: () => void): void {
+    // ligue ao blur/touch do host
+  }
+
+  setDisabledState(disabled: boolean): void {
+    disabled ? this.control.disable({ emitEvent: false }) : this.control.enable({ emitEvent: false });
+  }
+}
+```
+
+## Using the custom field in form contract
+
+```ts
+const fieldMetadata = [
+  {
+    name: 'sla',
+    label: 'SLA operacional',
+    controlType: 'my-custom',
+  },
+];
+```
+
+## Provider defaults vs no-defaults
+
+### `providePraxisDynamicFields()`
+
+- registra providers core;
+- inclui defaults do selector registry;
+- e a escolha comum para host app padrao.
+
+### `providePraxisDynamicFieldsNoDefaults()`
+
+- desabilita o mapa default de selector -> controlType;
+- use apenas quando o host quer governar totalmente o mapa base.
+
+## Selector registry / aliases
+
+Nao confunda:
+
+- `ComponentRegistryService.register(...)`: carrega o componente Angular real.
+- `ComponentMetadataRegistry.register(...)`: registra nome/icone/superficie editorial.
+- `FieldSelectorRegistry` / aliases: resolve seletor/roteamento complementar em modo config-first.
+
+Em cenarios enterprise:
+
+- prefira `controlType` estavel e unico;
+- use aliases apenas quando um programa de migracao exigir compatibilidade.
+
+## Checklist for host teams
+
+- `runtime registra`: `ComponentRegistryService.register(...)`.
+- `metadata registra`: `ComponentMetadataRegistry.register(...)`.
+- `controlType alinhado`: o mesmo id em runtime e metadata.
+- `forms compatível`: CVA ou `[formControl]`.
+- `hot update compatível`: `setInputMetadata` e/ou signal metadata.
+- `tema/tokens`: sem quebrar contraste, estados e largura no host.