@praxisui/dynamic-fields 9.0.0-rc.1 → 9.0.0-rc.3

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-24T21:07:35.880Z",
+  "generatedAt": "2026-07-25T01:22:20.531Z",
   "packageName": "@praxisui/dynamic-fields",
-  "packageVersion": "9.0.0-rc.1",
+  "packageVersion": "9.0.0-rc.3",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 76,
@@ -122379,7 +122379,7 @@
     },
     "pdx-material-async-select": {
       "id": "pdx-material-async-select",
-      "description": "Select com carregamento assíncrono de opções.",
+      "description": "Combobox de selecao com busca e carregamento assincrono de opcoes.",
       "inputs": [
         {
           "name": "metadata",
@@ -122425,6 +122425,8 @@
         "widget",
         "field",
         "select",
+        "combobox",
+        "search",
         "async",
         "material"
       ],
@@ -125752,9 +125754,9 @@
         {
           "chunkIndex": 0,
           "chunkKind": "summary",
-          "content": "Component ID: pdx-material-async-select\nSelector: pdx-material-async-select\nFriendly Name: Async Select (Material)\nDescription: Select com carregamento assíncrono de opções.\nLib/Package: @praxisui/dynamic-fields\nTags: widget, field, select, async, material\nInputs:\n  - metadata (MaterialSelectMetadata)\n  - readonlyMode (boolean)\n  - disabledMode (boolean)\n  - visible (boolean)\n  - presentationMode (boolean)\n",
+          "content": "Component ID: pdx-material-async-select\nSelector: pdx-material-async-select\nFriendly Name: Async Select (Material)\nDescription: Combobox de selecao com busca e carregamento assincrono de opcoes.\nLib/Package: @praxisui/dynamic-fields\nTags: widget, field, select, combobox, search, async, material\nInputs:\n  - metadata (MaterialSelectMetadata)\n  - readonlyMode (boolean)\n  - disabledMode (boolean)\n  - visible (boolean)\n  - presentationMode (boolean)\n",
           "sourcePointer": "projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.metadata.ts",
-          "contentHash": "84ed8baf0ed74946d0a602a53e3d9bcdf8f35ee9a1f0a21e72d2a4e3d0fb9af0",
+          "contentHash": "7771e7b327e31fabf9c121de968d212af0238a36009945ef750c9ae0cc06ca5a",
           "sourceKind": "component_definition",
           "sourceId": "pdx-material-async-select",
           "corpusVersion": "1.0.0"

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

@@ -87,11 +87,6 @@ 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.
 
-O runtime usa `subscriptSizing: 'dynamic'` como padrao seguro: hints e erros
-multiline participam do fluxo vertical e nao podem invadir o proximo campo.
-Use `'fixed'` somente como opt-in explicito quando o conteudo do subscript for
-comprovadamente limitado a uma linha.
-
 ## 1. Texto livre vs selecao
 
 ### Use `input` / `textarea` quando
@@ -120,21 +115,26 @@ Se o schema usa `input` para algo que depois exige validacao pesada, busca seman
 | 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 |
 
-### Bootstrap assíncrono de seleção
+### Invariante de UX para selecao pesquisavel
 
-O valor selecionado e as options podem chegar em momentos diferentes. Para
-options locais, o host deve manter o `FormControl` vazio até a option canonica
-estar disponível. Caso o valor persistido já tenha chegado, o
-`inlineEntityLookup` o preserva como pendente: não o apresenta como seleção
-ativa nem emite evento de seleção até encontrar a option correspondente.
+Uma selecao simples pesquisavel deve ocupar um unico campo visual. O runtime
+pode manter dois estados internos, mas eles nao podem ser confundidos:
 
-Para fonte remota ou `RESOURCE_ENTITY`, preserve o ID e use a reidratação
-canônica por by-ids. Não substitua esse fluxo por uma lista local e não limpe
-silenciosamente um valor que ainda está sendo reidratado.
+- o controle de exibicao recebe o texto digitado e apresenta o label;
+- o `FormControl` de negocio preserva somente o valor canonico da opcao;
+- digitar, apagar ou abandonar uma pesquisa nao altera o valor persistido;
+- somente selecionar uma opcao ou acionar o comando explicito de limpar muda o
+  valor de negocio;
+- ao perder foco sem selecao, o campo restaura o label da opcao vigente;
+- busca, lista de resultados, loading, vazio e paginacao formam um unico
+  combobox acessivel, sem um segundo input empilhado sobre um select.
+- limpar, indicador de abertura e ajuda permanecem agrupados em uma unica faixa
+  de sufixo, sem aumentar a altura do campo em layouts estreitos.
 
-Em ambos os casos, teste valor antes das options, options antes do valor, ID
-ausente e mudança de contexto durante a carga. A reconciliação não é uma ação
-do usuário e não deve emitir `selectionChange` nem disparar refresh da rota.
+Em `async-select`, `searchable=true` e `multiple=false` materializam esse
+combobox unico. Nao insira input, botao, toolbar ou footer interativo dentro de
+`mat-select`; para resultados remotos, a carga incremental do combobox ocorre
+automaticamente ao aproximar-se do fim da lista.
 
 ### Promocao oficial de exemplos `entityLookup`
 
@@ -267,6 +267,55 @@ Use `rich-content` quando:
 - 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.
 
+### Composicao segura de selects
+
+`MatSelect` implementa um combobox cujo painel e um listbox gerenciado pelo CDK.
+Por isso, o conteudo projetado em `mat-select` deve se limitar a opcoes,
+optgroups e elementos estritamente apresentacionais suportados pelo controle.
+
+Regras obrigatorias:
+
+- toolbar, footer, paginacao, limpar selecao e demais botoes ficam fora de
+  `mat-select`, como irmaos declarativos no template;
+- `SelectPanelActionsComponent` e apresentacional: nao injeta `MatSelect`, nao
+  assina `openedChange`, nao move o proprio host e nao manipula o CDK overlay;
+- `mat-select-trigger` exibe somente valor, label, status ou icone
+  apresentacional; acoes interativas ficam fora do trigger;
+- nao use `ElementRef`, `DOCUMENT`, `append`, `insertBefore` ou placeholders
+  para transportar uma view Angular entre a arvore declarada e o overlay;
+- preserve o fluxo nativo de teclado. Um helper visual nao deve interceptar
+  `Tab`, `Shift+Tab` ou `Escape` para simular um composite control.
+- um controle declarado como irmao pertence ao fluxo da pagina; ele nao deve
+  ser apresentado como footer do overlay. Para busca/paginacao remota rica,
+  prefira o dialog/drawer de `entityLookup`, um autocomplete/composite overlay
+  proprio ou carregamento automatico nao interativo.
+
+O gate `node tools/check-mat-select-content-model.mjs` falha quando:
+
+- `pdx-select-panel-actions` volta a aparecer dentro de `mat-select`;
+- marcadores conhecidos de relocacao de DOM reaparecem;
+- um novo componente introduz `input` dentro do painel ou `button` dentro do
+  trigger sem que a arquitetura seja corrigida.
+
+Os warnings atuais identificam divida legada, nao autorizacao para copiar o
+padrao. A baseline so pode diminuir.
+
+### Contextos globais corporativos
+
+Seletores globais de empresa, tenant, unidade ou ambiente sao controles de
+seguranca e contexto, nao filtros opcionais:
+
+- o valor precisa pertencer a lista autorizada carregada para a sessao;
+- valor nulo, desconhecido ou injetado programaticamente deve ser rejeitado e
+  restaurado sem emitir uma nova troca;
+- o contexto anterior permanece autoritativo ate o backend confirmar a mudanca;
+- falha de troca deve manter a tela operavel e apresentar feedback recuperavel;
+- metadados locais podem controlar apresentacao, mas nao substituir
+  autorizacao, escopo ou identidade publicados pelo backend.
+- listas globais pequenas devem ser carregadas integralmente e usar typeahead
+  nativo; nao habilite busca remota/paginacao apenas para imitar um seletor
+  simples de empresa ou tenant.
+
 ## 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.