@praxisui/dynamic-fields 8.0.0-beta.6 → 8.0.0-beta.60

package/docs/dynamic-fields-inventory.md

@@ -0,0 +1,206 @@
+---
+title: "Dynamic Fields Inventory"
+slug: "dynamic-fields-inventory"
+description: "Inventario governado dos controlTypes realmente registrados por default em @praxisui/dynamic-fields, com cobertura de metadata, JSON API e exemplos."
+doc_type: "reference"
+document_kind: "governance-reference"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "inventory"
+  - "controlType"
+  - "runtime"
+order: 33
+icon: "inventory_2"
+toc: true
+sidebar: true
+search_boost: 0.95
+reading_time: 18
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-fields-overview"
+  - "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-inline-components-guide"
+keywords:
+  - "component registry"
+  - "registered control types"
+  - "metadata coverage"
+  - "json api coverage"
+last_updated: "2026-03-26"
+---
+
+# Dynamic Fields Inventory
+
+## Source of truth
+
+Este inventario foi montado a partir do runtime real:
+
+- `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts`
+- `projects/praxis-dynamic-fields/src/lib/providers.ts`
+- `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`
+
+Regras deste documento:
+
+- lista apenas `controlType` efetivamente registrados por default;
+- separa controles de formulario comuns de controles inline especializados;
+- trata aliases/compatibilidade em trilha separada para nao confundir escolha de novos contratos.
+
+## Runtime inventory vs published catalog
+
+Este documento continua sendo a auditoria `runtime-first` da lib. Ele existe para responder:
+
+- o que esta realmente registrado por default;
+- quais aliases de compatibilidade ainda existem;
+- qual e a cobertura de metadata, JSON API e exemplos.
+
+Para consumo por hosts, landing page e playgrounds oficiais, a superficie canonica agora e o catalogo exportado pela propria lib em `src/lib/catalog/dynamic-fields-playground.catalog.ts`, reexportado pelo `public-api`.
+
+Regra editorial:
+
+- `inventory`: prova o runtime real;
+- `catalog`: organiza descoberta, snippets, estados, `interactionPattern`, semantica de `icon` e links oficiais para consumidores;
+- `docs markdown`: governam a narrativa e a referencia, mas nao dirigem o preview runtime.
+
+Quando houver diferenca entre uma necessidade de UX de descoberta e a listagem deste inventario:
+
+- o ajuste deve nascer no catalogo exportado da lib, nao em listas manuais do host;
+- este inventario continua focado em registro, cobertura e auditoria de runtime;
+- hosts oficiais devem projetar menus, vitrines e cues a partir do catalogo, nao desta tabela runtime-first.
+
+## Coverage legend
+
+- `metadata`: existe arquivo `*.metadata.ts` no componente.
+- `json-api`: existe arquivo `*.json-api.md` no componente.
+- `README`: aparece textualmente no `README.md` da lib.
+- `examples`: aparece textualmente no `USAGE-EXAMPLES.md`.
+
+## A. Primary form controls
+
+| Familia | controlType | Angular component | metadata | json-api | README | examples | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| texto | `input` | `TextInputComponent` | `components/text-input/text-input.metadata.ts` | `components/text-input/pdx-text-input.json-api.md` | yes | yes | texto livre canônico |
+| texto | `email` | `EmailInputComponent` | `components/email-input/email-input.metadata.ts` | `components/email-input/pdx-email-input.json-api.md` | yes | yes | email especializado |
+| texto | `password` | `PasswordInputComponent` | `components/password-input/password-input.metadata.ts` | `components/password-input/pdx-password-input.json-api.md` | yes | yes | senha |
+| texto | `textarea` | `MaterialTextareaComponent` | `components/material-textarea/material-textarea.metadata.ts` | `components/material-textarea/pdx-material-textarea.json-api.md` | yes | yes | texto longo |
+| texto | `search` | `SearchInputComponent` | `components/search-input/search-input.metadata.ts` | `components/search-input/pdx-search-input.json-api.md` | yes | yes | busca textual |
+| texto | `phone` | `PhoneInputComponent` | `components/phone-input/phone-input.metadata.ts` | `components/phone-input/pdx-phone-input.json-api.md` | no | yes | telefone |
+| texto | `url` | `UrlInputComponent` | `components/url-input/url-input.metadata.ts` | `components/url-input/pdx-url-input.json-api.md` | no | no | URL |
+| texto | `cpfCnpjInput` | `MaterialCpfCnpjInputComponent` | `components/material-cpf-cnpj-input/material-cpf-cnpj-input.metadata.ts` | `components/material-cpf-cnpj-input/pdx-material-cpf-cnpj-input.json-api.md` | no | no | documento BR |
+| numero/moeda/range | `numericTextBox` | `NumberInputComponent` | `components/number-input/number-input.metadata.ts` | `components/number-input/pdx-number-input.json-api.md` | no | no | numero canônico |
+| numero/moeda/range | `currency` | `MaterialCurrencyComponent` | `components/material-currency/material-currency.metadata.ts` | `components/material-currency/pdx-material-currency.json-api.md` | yes | no | moeda |
+| numero/moeda/range | `slider` | `MaterialSliderComponent` | `components/material-slider/material-slider.metadata.ts` | `components/material-slider/pdx-material-slider.json-api.md` | yes | no | valor unico em faixa |
+| numero/moeda/range | `rangeSlider` | `PdxMaterialRangeSliderComponent` | `components/material-range-slider/material-range-slider.metadata.ts` | `components/material-range-slider/pdx-material-range-slider.json-api.md` | no | no | faixa simples ou dupla |
+| numero/moeda/range | `priceRange` | `MaterialPriceRangeComponent` | `components/material-price-range/material-price-range.metadata.ts` | `components/material-price-range/pdx-material-price-range.json-api.md` | no | no | faixa monetaria |
+| numero/moeda/range | `rating` | `MaterialRatingComponent` | `components/material-rating/material-rating.metadata.ts` | `components/material-rating/pdx-material-rating.json-api.md` | yes | yes | pontuacao visual |
+| data e tempo | `dateInput` | `DateInputComponent` | `components/date-input/date-input.metadata.ts` | `components/date-input/pdx-date-input.json-api.md` | no | no | input de data nativo |
+| data e tempo | `date` | `MaterialDatepickerComponent` | `components/material-datepicker/material-datepicker.metadata.ts` | `components/material-datepicker/pdx-material-datepicker.json-api.md` | yes | yes | datepicker Material |
+| data e tempo | `dateRange` | `MaterialDateRangeComponent` | `components/material-date-range/material-date-range.metadata.ts` | `components/material-date-range/pdx-material-date-range.json-api.md` | no | yes | intervalo de datas |
+| data e tempo | `dateTimeLocal` | `DatetimeLocalInputComponent` | `components/datetime-local-input/datetime-local-input.metadata.ts` | `components/datetime-local-input/pdx-datetime-local-input.json-api.md` | no | no | data/hora local |
+| data e tempo | `month` | `MonthInputComponent` | `components/month-input/month-input.metadata.ts` | `components/month-input/pdx-month-input.json-api.md` | no | yes | mes/ano |
+| data e tempo | `time` | `TimeInputComponent` | `components/time-input/time-input.metadata.ts` | `components/time-input/pdx-time-input.json-api.md` | yes | yes | hora simples |
+| data e tempo | `timePicker` | `MaterialTimepickerComponent` | `components/material-timepicker/material-timepicker.metadata.ts` | `components/material-timepicker/pdx-material-timepicker.json-api.md` | yes | yes | seletor de horario |
+| data e tempo | `timeRange` | `PdxMaterialTimeRangeComponent` | `components/pdx-material-time-range/pdx-material-time-range.metadata.ts` | `components/pdx-material-time-range/pdx-material-time-range.json-api.md` | no | no | intervalo de horario |
+| data e tempo | `week` | `WeekInputComponent` | `components/week-input/week-input.metadata.ts` | `components/week-input/pdx-week-input.json-api.md` | no | no | semana ISO |
+| data e tempo | `year` | `PdxYearInputComponent` | `components/pdx-year-input/pdx-year-input.metadata.ts` | `components/pdx-year-input/pdx-year-input.json-api.md` | no | yes | ano |
+| selecao | `select` | `MaterialSelectComponent` | `components/material-select/material-select.metadata.ts` | `components/material-select/pdx-material-select.json-api.md` | yes | yes | lista local/remota |
+| selecao | `searchable-select` | `MaterialSearchableSelectComponent` | `components/material-searchable-select/material-searchable-select.metadata.ts` | `components/material-searchable-select/pdx-material-searchable-select.json-api.md` | no | yes | select com busca |
+| selecao | `async-select` | `MaterialAsyncSelectComponent` | `components/material-async-select/material-async-select.metadata.ts` | `components/material-async-select/pdx-material-async-select.json-api.md` | no | yes | select remoto |
+| selecao | `entityLookup` | `InlineEntityLookupComponent` | `editorial/wave1/entity-lookup.editorial.ts` | `components/inline-entity-lookup/pdx-inline-entity-lookup.json-api.md` | no | no | lookup corporativo para `RESOURCE_ENTITY`, reidratacao e politica de selecao |
+| selecao | `autoComplete` | `MaterialAutocompleteComponent` | `components/material-autocomplete/material-autocomplete.metadata.ts` | `components/material-autocomplete/pdx-material-autocomplete.json-api.md` | yes | yes | autocomplete |
+| selecao | `multiSelect` | `MaterialMultiSelectComponent` | `components/material-multi-select/material-multi-select.metadata.ts` | `components/material-multi-select/pdx-material-multi-select.json-api.md` | no | yes | multipla selecao |
+| arvores/listas | `multiSelectTree` | `MaterialMultiSelectTreeComponent` | `components/material-multi-select-tree/material-multi-select-tree.metadata.ts` | `components/material-multi-select-tree/pdx-material-multi-select-tree.json-api.md` | no | no | arvore multipla |
+| arvores/listas | `treeSelect` | `MaterialTreeSelectComponent` | `components/material-tree-select/material-tree-select.metadata.ts` | `components/material-tree-select/pdx-material-tree-select.json-api.md` | no | no | arvore simples |
+| arvores/listas | `array` | `EditableCollectionComponent` | `editorial/wave1/editable-collection.editorial.ts` | n/a | no | no | colecao repetivel com `FormArray` e subcampos metadata-driven |
+| arvores/listas | `selectionList` | `MaterialSelectionListComponent` | `components/material-selection-list/material-selection-list.metadata.ts` | `components/material-selection-list/pdx-material-selection-list.json-api.md` | no | yes | lista de opcoes; runtime basico funcional, mas `searchable` e `selectAll` ainda nao estao completos na superficie do componente |
+| arvores/listas | `transferList` | `MaterialTransferListComponent` | `components/material-transfer-list/material-transfer-list.metadata.ts` | `components/material-transfer-list/pdx-material-transfer-list.json-api.md` | no | no | mover entre listas |
+| arvores/listas | `chipInput` | `MaterialChipsComponent` | `components/material-chips/material-chips.metadata.ts` | `components/material-chips/pdx-material-chips.json-api.md` | no | no | entrada em chips |
+| arvores/listas | `chipList` | `MaterialChipsComponent` | `components/material-chips/material-chips.metadata.ts` | `components/material-chips/pdx-material-chips.json-api.md` | no | no | lista de chips |
+| toggle/choice | `checkbox` | `MaterialCheckboxGroupComponent` | `components/material-checkbox-group/material-checkbox-group.metadata.ts` | `components/material-checkbox-group/pdx-material-checkbox-group.json-api.md` | yes | yes | grupo de checkboxes |
+| toggle/choice | `radio` | `MaterialRadioGroupComponent` | `components/material-radio-group/material-radio-group.metadata.ts` | `components/material-radio-group/pdx-material-radio-group.json-api.md` | yes | yes | grupo de radio |
+| toggle/choice | `toggle` | `MaterialSlideToggleComponent` | `components/material-slide-toggle/material-slide-toggle.metadata.ts` | `components/material-slide-toggle/pdx-material-slide-toggle.json-api.md` | yes | no | booleano on/off |
+| toggle/choice | `buttonToggle` | `MaterialButtonToggleComponent` | `components/material-button-toggle/material-button-toggle.metadata.ts` | `components/material-button-toggle/pdx-material-button-toggle.json-api.md` | no | no | grupo segmentado |
+| upload | `upload` | `MaterialFileUploadComponent` | `components/material-file-upload/material-file-upload.metadata.ts` | `components/material-file-upload/pdx-material-file-upload.json-api.md` | yes | no | upload |
+| cor | `color` | `ColorInputComponent` | `components/color-input/color-input.metadata.ts` | `components/color-input/pdx-color-input.json-api.md` | yes | yes | input textual/cor |
+| cor | `colorPicker` | `PdxColorPickerComponent` | `components/color-picker/pdx-color-picker.metadata.ts` | `components/color-picker/pdx-color-picker.json-api.md` | yes | no | picker avançado |
+| visual/acao | `avatar` | `MaterialAvatarComponent` | `components/material-avatar/material-avatar.metadata.ts` | `components/material-avatar/pdx-material-avatar.json-api.md` | yes | no | representacao visual |
+| visual/acao | `button` | `MaterialButtonComponent` | `components/material-button/material-button.metadata.ts` | `components/material-button/pdx-material-button.json-api.md` | yes | yes | acao nao-CVA |
+| visual/acao | `cronBuilder` | `PdxCronBuilderComponent` | n/a (lib externa) | n/a (lib externa) | no | no | depende de `@praxisui/cron-builder` |
+
+## B. Specialized inline filter controls
+
+Estes `controlType` sao registrados por default no mesmo registry, mas pertencem a uma trilha especializada de filtro inline. Eles nao devem ser apresentados como escolha padrao para formularios corporativos comuns.
+As colunas de implementacao e metadata abaixo descrevem artefatos internos co-localizados ao `controlType`; caminhos fisicos e nomes historicos do workspace nao fazem parte do contrato recomendado.
+
+| Familia | controlType | implementacao Angular | metadata | json-api | README | examples | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| inline de filtro | `inlineSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | select compacto |
+| inline de filtro | `inlineSearchableSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | select com busca |
+| inline de filtro | `inlineAsyncSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | select remoto |
+| inline de filtro | `inlineEntityLookup` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | lookup de entidade |
+| inline de filtro | `inlineAutocomplete` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | autocomplete compacto |
+| inline de filtro | `inlineNumber` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | numero compacto |
+| inline de filtro | `inlineCurrency` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | moeda compacta |
+| inline de filtro | `inlineCurrencyRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | range monetario |
+| inline de filtro | `inlineMultiSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | multipla selecao |
+| inline de filtro | `inlineInput` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | texto compacto |
+| inline de filtro | `inlineToggle` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | toggle compacto |
+| inline de filtro | `inlineRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | slider compacto |
+| inline de filtro | `inlineDate` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | date inline |
+| inline de filtro | `inlineDateRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | date range inline |
+| inline de filtro | `inlineTime` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | time inline |
+| inline de filtro | `inlineTimeRange` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | time range inline |
+| inline de filtro | `inlineTreeSelect` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | tree select inline |
+| inline de filtro | `inlineRating` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | yes | yes | rating especializado |
+| inline de filtro | `inlineDistanceRadius` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | distancia/raio |
+| inline de filtro | `inlinePipelineStatus` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | status de pipeline |
+| inline de filtro | `inlineScorePriority` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | score/prioridade |
+| inline de filtro | `inlineRelativePeriod` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | periodo relativo |
+| inline de filtro | `inlineSentiment` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | sentimento |
+| inline de filtro | `inlineColorLabel` | `registrada por default no registry inline` | `metadata co-localizada ao controlType` | `co-localizado ao metadata (*.json-api.md)` | no | no | etiquetas por cor |
+
+## C. Preferred Published Control Types
+
+Estes valores existem no runtime, mas os contratos novos devem seguir a coluna `prefer`.
+
+| Registered runtime value | Routed component | Prefer in new contracts | Notes |
+| --- | --- | --- | --- |
+| `dateTime` | `DatetimeLocalInputComponent` | `dateTimeLocal` | manter `dateTimeLocal` como nome publicado |
+| `dateTimeRange` | `MaterialDateRangeComponent` | `dateRange` | reutiliza date range |
+| `treeView` | `MaterialTreeSelectComponent` | `treeSelect` | publicar `treeSelect` |
+
+## D. Coverage findings
+
+### Strong coverage
+
+- maioria dos fields principais possui `metadata` + `json-api`;
+- inline filters especializados possuem cobertura estrutural forte em `metadata` + `json-api`;
+- runtime de extensao do host esta documentado em `hot-metadata-updates.md` e no README.
+
+### Runtime present but documentation still shallow
+
+- `cronBuilder`: registrado por default, mas a documentacao detalhada vive na lib externa;
+- `entityLookup`: contrato de formulario principal registrado e descobrivel, reutilizando a implementacao inline enquanto a documentacao detalhada permanece no JSON API de `inline-entity-lookup`;
+- `array`: contrato de colecao repetivel registrado e descobrivel; a documentacao detalhada ainda deve ser aprofundada em JSON API proprio do `EditableCollectionComponent`;
+- `dateInput`, `dateTimeLocal`, `numericTextBox`, `priceRange`, `rangeSlider`, `timeRange`, `multiSelectTree`, `treeSelect`, `transferList`, `buttonToggle`, `chipInput`, `chipList`: possuem runtime e arquivos de componente, mas aparecem pouco no README/USAGE examples;
+- varios inline filters nao aparecem no README ou no `USAGE-EXAMPLES.md`, embora tenham metadata e JSON API.
+
+### Governance decision
+
+- `field catalog`: cobre os fields de formulario comuns e os componentes visuais/acao usados pelo runtime principal;
+- `inline filter catalog`: fica separado para nao poluir a narrativa de formularios comuns;
+- `inventory`: permanece como documento de auditoria do runtime real;
+- `playable catalog exportado`: e a superficie de consumo recomendada para landing page, playground e outros hosts oficiais.
+- `interactionPattern` e `icon`: fazem parte da semantica de descoberta do catalogo exportado, nao da prova de registro deste inventario.

package/docs/dynamic-fields-playground-catalog-plan.md

@@ -0,0 +1,243 @@
+---
+title: "Dynamic Fields Playground Catalog Plan"
+slug: "dynamic-fields-playground-catalog-plan"
+description: "Plano canonico para publicar um catalogo jogavel de Dynamic Fields consumido pela landing/playground sem duplicar fonte de verdade no host."
+doc_type: "reference"
+document_kind: "governance-reference"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "draft"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "playground"
+  - "catalog"
+  - "governance"
+  - "platform"
+order: 31
+icon: "view_quilt"
+toc: true
+sidebar: false
+search_boost: 0.7
+reading_time: 16
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-fields-inventory"
+  - "dynamic-fields-field-catalog"
+  - "dynamic-fields-field-selection-guide"
+  - "dynamic-fields-inline-filter-catalog"
+keywords:
+  - "playable catalog"
+  - "landing playground"
+  - "source of truth"
+  - "registry parity"
+last_updated: "2026-03-26"
+---
+
+# Dynamic Fields Playground Catalog Plan
+
+## Objective
+
+Definir a modelagem canonica para um catalogo jogavel de `@praxisui/dynamic-fields` que possa ser consumido por `praxis-ui-landing-page` na rota `playground` sem criar uma lista manual paralela no host.
+
+## Problem statement
+
+Hoje existem tres camadas com papeis diferentes:
+
+1. `ComponentRegistryService`
+   - define o suporte runtime real dos fields registrados por default
+2. metadata exports e docs governadas
+   - descrevem friendly names, iconografia, uso recomendado, inventario e narrativa oficial
+3. landing/playground
+   - publica docs e experiencias exploratorias para squads
+
+O problema atual e que a landing ainda precisa montar algumas sementes manuais para navegacao/catalogo, enquanto o `playground` existente foi desenhado para macrocomponentes (`praxis-table`, `praxis-list`, `praxis-dynamic-form`), nao para dezenas de fields.
+
+## Canonical source-of-truth model
+
+### Runtime truth
+
+A fonte de verdade do suporte default continua sendo o runtime da lib:
+
+- `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts`
+- `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`
+
+Essa camada responde:
+
+- quais `controlType` existem
+- quais sao canonicamente registrados por default
+- quais aliases existem por compatibilidade
+
+### Published catalog truth
+
+O catalogo jogavel nao deve nascer na landing. Ele deve ser publicado pela lib canonica como um export agregado e tipado.
+
+Essa camada responde:
+
+- quais `controlType` devem aparecer para descoberta publica
+- em qual `track` e `family` cada item entra
+- quais estados sao demonstraveis
+- qual snippet usar
+- quais docs oficiais linkar
+- quais tags e notas de UX expor
+
+### Documentation truth
+
+As docs governadas continuam sendo a narrativa oficial e a superficie editorial publica:
+
+- inventario runtime-first
+- field catalog
+- field selection guide
+- inline filter catalog
+
+Essas docs nao devem ser parseadas para dirigir o preview. Elas devem ser referenciadas pelo catalogo exportado.
+
+## Non-goals
+
+Este plano nao pretende:
+
+- transformar markdown em fonte primária do runtime
+- permitir que a landing invente `controlType` ou families locais
+- misturar aliases reconhecidos internamente como se fossem escolhas novas recomendadas
+- substituir o `ComponentRegistryService` como prova de suporte real
+- virar um builder visual completo dentro do `playground`
+
+## Proposed architecture
+
+Criar uma nova superficie publica em `@praxisui/dynamic-fields`:
+
+- `DynamicFieldCatalogEntry`
+- `DynamicFieldCatalogTrack`
+- `DynamicFieldCatalogFamily`
+- `DynamicFieldPreviewRecipe`
+- `DYNAMIC_FIELDS_PLAYGROUND_CATALOG`
+
+Essa superficie deve ser:
+
+- publicada no `public-api.ts`
+- derivada do runtime real
+- enriquecida com metadata/governanca
+- consumida pela landing e pelo playground
+
+## Catalog entry contract
+
+Cada entry do catalogo deve conter no minimo:
+
+- `id`
+- `controlType`
+- `track`
+  - `primary-form`
+  - `inline-filter`
+- `family`
+- `status`
+- `friendlyName`
+- `description`
+- `tags`
+- `keywords`
+- `valueShape`
+- `recommendedWhen`
+- `avoidWhen`
+- `dataSourceKind`
+- `supportsStates`
+- `docs`
+  - `catalogSlug`
+  - `detailFragment`
+  - `selectionGuideSlug`
+  - `overviewSlug?`
+  - `jsonApiPath?`
+- `previewRecipe`
+- `snippetRecipe`
+- `a11yNotes?`
+- `themingNotes?`
+
+## Governance rules
+
+### Rule 1. The landing is a consumer
+
+`praxis-ui-landing-page` nao pode manter o catalogo de Dynamic Fields como fonte primaria.
+
+### Rule 2. Runtime parity is mandatory
+
+Todo item publicado no catalogo precisa corresponder a um `controlType` realmente registrado por default no runtime, exceto quando marcado explicitamente como `experimental` ou `host-owned`.
+
+### Rule 3. Docs are linked, not parsed
+
+O catalogo aponta para docs governadas por slug/fragment. O preview nao depende de parsing de markdown.
+
+### Rule 4. Inline filters remain a separate track
+
+`inline*` continua sendo trilha especializada. O catalogo jogavel pode expor essa trilha, mas sem misturar a narrativa de formulario comum.
+
+### Rule 5. Aliases are not discovery-first
+
+Aliases como `dateTime` ou `treeView` continuam existindo por compatibilidade, mas nao entram como escolha principal no catalogo.
+
+### Rule 6. States are governed
+
+Estados como `default`, `filled`, `disabled`, `readonly` e `error` devem ser definidos por recipes governadas na lib, nao por patches soltos no host.
+
+## Recommended rollout
+
+### Phase 1. Contract and recipes
+
+Publicar tipos e recipes basicas de estado dentro da lib.
+
+### Phase 2. Canonical catalog export
+
+Publicar o catalogo agregado da lib e exporta-lo em `public-api.ts`.
+
+### Phase 3. Registry parity tests
+
+Adicionar testes de paridade catalogo x runtime.
+
+### Phase 4. Docs alignment
+
+Atualizar inventario e catalogos governados para reconhecer o novo artefato publicado.
+
+### Phase 5. Landing adoption
+
+Trocar seeds manuais de `dynamic-fields` na landing por derivacao do catalogo exportado.
+
+### Phase 6. Playground adoption
+
+Adaptar o playground para suportar items do tipo `field`, com preview host canonico minimo e painel de detalhe.
+
+## Validation requirements
+
+Validacoes minimas esperadas ao implementar este plano:
+
+- build focal de `praxis-dynamic-fields`
+- teste focal de paridade catalogo x registry
+- build focal da landing
+- smoke da vitrine/playground
+- verificacao de foco, teclado, contraste e links para docs oficiais
+
+## Success criteria
+
+O plano sera considerado bem-sucedido quando:
+
+- a landing deixar de manter listas soltas de Dynamic Fields
+- a fonte de verdade do catalogo jogavel passar a estar na lib canonica
+- docs, runtime e vitrine permanecerem coerentes
+- novos fields conseguirem entrar no ecossistema com uma trilha previsivel:
+  - runtime
+  - metadata
+  - catalogo
+  - docs
+  - preview
+
+## Implementation note
+
+Este documento e um artefato de planejamento de plataforma. Ele nao substitui:
+
+- `dynamic-fields-inventory.md` como auditoria runtime-first
+- `dynamic-fields-field-catalog.md` como referencia funcional
+- `dynamic-fields-inline-filter-catalog.md` como trilha especializada
+
+Ele apenas fixa a fronteira correta para a evolucao da surface jogavel.

package/docs/generic-crud-service.md

@@ -0,0 +1,152 @@
+# GenericCrudService — Diretrizes de Uso em Campos Dinâmicos
+
+> IMPORTANTE: Não remova o GenericCrudService do `providers` de componentes de campos dinâmicos que carregam dados remotos (selects, radio, lists, etc.). Cada componente deve manter sua própria instância do serviço.
+
+## Por que uma instância por componente?
+
+- Isolamento de estado: `GenericCrudService.configure(resourcePath, endpointKey?)` altera o estado interno (baseApiUrl, resourcePath, endpoints). Dois selects com recursos distintos em uma mesma página precisam de estados independentes.
+- Concorrência segura: com instância compartilhada (global), dois selects que configuram recursos diferentes em momentos próximos podem disputar o estado e causar requisições para o recurso “errado”.
+- Ciclo de vida previsível: cada select controla quando configurar o recurso e quando recarregar opções, sem efeitos colaterais em outros selects.
+
+## Evitando logs/duplicidades de configuração
+
+- Short‑circuit no serviço: `GenericCrudService.configure` possui guarda para ignorar reconfigurações quando `baseApiUrl`, `resourcePath` e `endpointKey` não mudam.
+- Guarda no componente: componentes como `MaterialAsyncSelectComponent` e `MaterialSearchableSelectComponent` mantêm `lastConfiguredPath` e só chamam `configureCrudService(path)` quando o `resourcePath` realmente mudar.
+- Autoload controlado: para evitar requisições remotas duplicadas no ciclo de montagem, os componentes aplicam `super.setMetadata()` (base input) e gerenciam o carregamento remoto explicitamente (ex.: apenas quando o select abre/ao digitar), em vez de delegar ao autoload do base para selects.
+
+## Padrões adotados nos componentes
+
+- `MaterialAsyncSelectComponent` e `MaterialSearchableSelectComponent`:
+  - Providers incluem `GenericCrudService` local (não remover).
+  - Implementam `setSelectMetadata()` sem acionar o autoload do base.
+  - Usam guarda `lastConfiguredPath` para evitar reconfiguração redundante.
+  - Disparam carregamentos apenas em interações (abrir, digitar, retry), via `filterOptions` (POST /options/filter) e correlatos.
+- Outros selects remotos (ex.: `material-select`, `material-radio-group`, `material-selection-list`) também mantêm `GenericCrudService` no `providers` e devem seguir o mesmo padrão quando necessário.
+
+## Sintomas comuns ao remover o provider local
+
+- Requisições com `resourcePath` incorreto quando existem múltiplos selects na mesma view.
+- Logs “configure” intercalados para recursos diferentes.
+- Comportamentos intermitentes em dev (re-renderizações) por competição de estado do serviço.
+
+## Resumo das boas práticas
+
+- Mantenha `GenericCrudService` no `providers` dos componentes que dependem de dados remotos.
+- Adote guarda de reconfiguração (`lastConfiguredPath`) nos componentes.
+- Centralize autoload em pontos previsíveis (ao abrir select, ao digitar), evitando autoload do base para selects.
+- Confie no short‑circuit do serviço para evitar logs/estado redundante.
+
+---
+
+## Endpoints suportados para selects (Options vs Filter)
+
+- Options (OptionDTO) — recomendados para selects assíncronos
+  - `POST /{resource}/options/filter` → `filterOptions(criteria, pageable, opts)`
+    - Query params: `page`, `size`, `sort`, `includeIds` (reexibir rótulos já selecionados na primeira página)
+    - Corpo: `criteria` (ex.: `{ [optionLabelKey]: termo, ...filterCriteria }`)
+    - Cabeçalho: `X-Data-Version` quando `observeVersionHeader` estiver habilitado
+    - Retorna: `Page<OptionDTO<ID>>` (e opcionalmente `dataVersion`)
+  - `GET /{resource}/options/by-ids` → `getOptionsByIds(ids)`
+    - Query params: `ids=1&ids=2` ...
+    - Retorna: `OptionDTO<ID>[]`
+  - Cursor (quando disponível) → `POST /{resource}/filter/cursor` retornando `OptionDTO` em `CursorPage`
+
+- Filter (entidade)
+  - `POST /{resource}/filter` → `filter(criteria, pageable)`
+    - Exige mapear no front: `optionLabelKey` e `optionValueKey` do item retornado para `{ label, value }`.
+
+Notas
+- Termo de busca: os componentes aplicam o termo em `criteria` usando a chave `optionLabelKey()`.
+- `filterCriteria`: sempre compõe o corpo do POST (Options e Filter). Informe chaves conforme o backend espera.
+- `OptionDTO`: `{ id: ID, label: string }` — formato esperado pelos selects assíncronos.
+- Se o backend não expõe `/options`, prefira `filter` + `optionLabelKey/optionValueKey` em selects não‑assíncronos.
+
+---
+
+## Exemplos de metadata (Options vs Filter)
+
+Exemplo — Options (async-select, backend com `/options`)
+
+```ts
+const fields: FieldMetadata[] = [
+  {
+    name: 'rotaId',
+    label: 'Rota',
+    controlType: 'async-select',
+    resourcePath: 'requests/routes',
+    // async-select usa OptionDTO do backend; não exige optionLabelKey/optionValueKey
+    loadOn: 'open', // 'init' para carregar já na inicialização se desejado
+    searchable: true,
+    // filtros adicionais enviados no corpo do POST /options/filter
+    filterCriteria: { active: true },
+  },
+];
+```
+
+Exemplo — Filter genérico (select, backend só com `/filter`)
+
+```ts
+const fields: FieldMetadata[] = [
+  {
+    name: 'destinoReqId',
+    label: 'Destino',
+    controlType: 'select',
+    resourcePath: 'requests/destinations',
+    // necessárias para mapear entidade → {label,value}
+    optionLabelKey: 'nome',
+    optionValueKey: 'id',
+    searchable: true, // habilita busca local; termo remoto é aplicado via optionLabelKey
+    filterCriteria: {},
+  },
+];
+```
+
+Exemplo — Cursor (lista grande; OptionDTO por cursor)
+
+```ts
+const fields: FieldMetadata[] = [
+  {
+    name: 'propriedadeReqId',
+    label: 'Propriedade',
+    controlType: 'async-select',
+    resourcePath: 'requests/destination-properties',
+    useCursor: true,   // ativa POST /filter/cursor
+    searchable: true,
+  },
+];
+```
+
+---
+
+## Diagrama de fluxo (simplificado)
+
+Options (async-select)
+
+```
+Componente (async-select)
+   │  configura GenericCrudService(resourcePath)
+   ▼
+GenericCrudService
+   │  POST /{resource}/options/filter  (criteria + pageable + includeIds)
+   │  GET  /{resource}/options/by-ids  (ids) [pré-carregar rótulos]
+   ▼
+Backend (OptionDTO)
+   │  { id, label } + paginação/cursor
+   ▼
+Componente mapeia OptionDTO → opções visíveis
+```
+
+Filter genérico (select)
+
+```
+Componente (select)
+   │  configura GenericCrudService(resourcePath)
+   ▼
+GenericCrudService
+   │  POST /{resource}/filter  (criteria + pageable)
+   ▼
+Backend (Entidade)
+   │  [{ ... entidade ... }]
+   ▼
+Componente mapeia entidade usando optionLabelKey/optionValueKey → {label,value}
+```

package/fesm2022/praxisui-dynamic-fields-index-CBogy3si.mjs

@@ -0,0 +1 @@
+export { EditableCollectionComponent, PDX_EDITABLE_COLLECTION_COMPONENT_METADATA } from './praxisui-dynamic-fields.mjs';

package/fesm2022/praxisui-dynamic-fields-index-CWPZdn1Y.mjs

@@ -0,0 +1,6 @@
+import { MaterialRatingComponent } from './praxisui-dynamic-fields.mjs';
+export { PDX_MATERIAL_RATING_COMPONENT_METADATA } from './praxisui-dynamic-fields.mjs';
+
+
+
+export { MaterialRatingComponent };

package/fesm2022/praxisui-dynamic-fields-index-CrHhyUMO.mjs

@@ -0,0 +1 @@
+export { EntityLookupDialogComponent, InlineEntityLookupComponent, PDX_ENTITY_LOOKUP_COMPONENT_METADATA, PDX_INLINE_ENTITY_LOOKUP_COMPONENT_METADATA } from './praxisui-dynamic-fields.mjs';

package/fesm2022/praxisui-dynamic-fields-index-DhGo5In4.mjs

@@ -0,0 +1,6 @@
+import { PdxColorPickerComponent } from './praxisui-dynamic-fields.mjs';
+export { PDX_COLOR_PICKER_COMPONENT_METADATA } from './praxisui-dynamic-fields.mjs';
+
+
+
+export { PdxColorPickerComponent };