@praxisui/dynamic-fields 9.0.5-rc.2 → 9.0.5-rc.21

package/README.md

@@ -178,11 +178,11 @@ Inline filter support has its own runtime and discovery contract. Use the offici
 
 ## Collection Selection Overlay
 
-Select controls that need search, pagination or panel actions use the public `PdxCollectionOverlayComponent` and `PdxCollectionSearchComponent` primitives. The trigger remains a single accessible combobox control; search, listbox options and footer actions are sibling regions inside the connected CDK overlay. No input, button, status row or footer action may be projected as option content inside `mat-select`.
+Select controls that need search, pagination or panel actions use the public `PdxCollectionOverlayComponent` and `PdxCollectionSearchComponent` primitives. Direct consumers may provide `panelId` when they need a stable dialog id; otherwise the primitive generates a unique id. The combobox `aria-controls` references the dialog ID while the options region keeps its own listbox ID. The trigger remains a single accessible combobox control with `aria-haspopup="dialog"`; the connected non-modal dialog contains search, listbox options and footer actions as sibling regions. No input, button, status row or footer action may be projected as option content inside `mat-select`.
 
-The overlay is attached only while open, prefers the space below the trigger, falls back above it, constrains itself to the viewport and owns scrolling in the options region. Closing by selection, `Escape`, outside click or detach restores the trigger/focus contract implemented by each control. Footer actions exist only while the overlay is attached and never participate in option keyboard navigation.
+The overlay is attached only while open, prefers the space below the trigger, falls back above it, constrains itself to the viewport and owns scrolling in the options region. While open, `Tab` and `Shift+Tab` cycle through the dialog controls without dismissing the collection or moving focus behind it. Selection, `Escape` and outside click are explicit close paths and restore focus to the trigger; detach does not steal focus from the next surface. Footer actions exist only while the overlay is attached and never participate in option keyboard navigation.
 
-Collection search styling is shared with `@praxisui/table` through the Core `--praxis-collection-search-*` contract. In particular, `--praxis-collection-search-radius` supports square (`0`), intermediate (for example `8px`) and pill (`999px`) themes without component-specific aliases.
+Collection search styling is shared with `@praxisui/table` through the Core `--praxis-collection-search-*` contract. In particular, `--praxis-collection-search-radius` supports square (`0`), intermediate (for example `8px`) and pill (`999px`) themes without component-specific aliases. The popup surface resolves from `--pdx-inline-panel-surface`, then the governed Praxis/Material surface chain, with an opaque final fallback; this prevents host token gaps from making options transparent. Narrow hosts may govern the default `22rem` popup limit through `--praxis-collection-overlay-narrow-max-height`.
 
 ## AI Authoring
 

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-08-11T20:12:18.507Z",
+  "generatedAt": "2026-08-14T20:54:13.811Z",
   "packageName": "@praxisui/dynamic-fields",
-  "packageVersion": "9.0.5-rc.2",
+  "packageVersion": "9.0.5-rc.21",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 76,

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

@@ -136,6 +136,25 @@ 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.
 
+### Busca governada por estratégia
+
+Quando `optionSource.filtering.searchStrategies` estiver presente, o runtime
+materializa a intenção declarada pelo backend em vez de inferi-la pelo texto:
+
+- uma única estratégia é selecionada automaticamente;
+- duas ou mais estratégias exigem escolha explícita e acessível antes do HTTP;
+- `minSearchChars` é aplicado à estratégia selecionada;
+- `inputFormat: digits` aceita somente dígitos ASCII;
+- `normalized-document` aceita dígitos, espaços, pontos e hífens, remove os
+  separadores visuais e aplica o mínimo ao valor normalizado;
+- a requisição envia a chave em `searchStrategy`, sem expor bindings, SQL,
+  documentos brutos ou detalhes privados do provider.
+
+Sem estratégias publicadas, permanece o comportamento compatível de busca do
+option source. Respostas `422` ainda recebem mensagem segura e localizada, mas
+ambiguidade, formato inválido e mínimo insuficiente são bloqueados antes da
+rede.
+
 ### Promocao oficial de exemplos `entityLookup`
 
 Um recurso so deve ser promovido como exemplo oficial de `entityLookup` quando
@@ -274,6 +293,9 @@ Use `rich-content` quando:
 `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.
+Quando a colecao exige busca, status e acoes, use o overlay compartilhado: o
+trigger declara `aria-haspopup="dialog"`, o dialog conectado governa o foco e a
+regiao de resultados preserva `role="listbox"`.
 
 Regras obrigatorias:
 
@@ -285,12 +307,13 @@ Regras obrigatorias:
   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.
+- no dialog de colecao, `Tab` e `Shift+Tab` permanecem contidos entre busca,
+  opcoes e acoes; `Escape`, selecao e clique externo sao saidas explicitas e
+  restauram o foco no trigger;
+- um controle declarado como irmao fora do overlay pertence ao fluxo da pagina;
+  busca e paginacao remota ricas devem ser regioes declarativas do dialog de
+  colecao compartilhado ou, em jornadas de lookup completas, do dialog/drawer
+  governado de `entityLookup`.
 - em `entityLookup`, `searchable=true` materializa uma acao acessivel no sufixo
   do campo que abre o dialogo governado. `dialog` customiza essa superficie e
   `dialog.enabled=false` e o opt-out explicito; a acao nunca vira uma

package/docs/dynamic-fields-inline-components-guide.md

@@ -197,8 +197,8 @@ Compatibilidade de mapeamento no `praxis-filter`:
 
 Observação técnica importante:
 
-- No `mat-select`, o `mat-select-trigger` customizado não é renderizado quando o campo está vazio.
-- Por isso, o estado `empty` do `inlineSelect` e do `inlineSearchableSelect` deve ser estilizado no branch de placeholder do Material (`.mat-mdc-select-placeholder`) para manter o visual de badge/pill.
+- `inlineSelect` e `inlineSearchableSelect` usam um botão-combobox estável; o pill vazio e preenchido pertence ao mesmo trigger, sem depender do placeholder interno de `mat-select`.
+- Busca, lista e rodapé são regiões irmãs no dialog de coleção conectado. A superfície, borda, raio, elevação, scrolling e camada pertencem ao overlay compartilhado, não ao `overlay-pane` de cada consumidor.
 
 Regra de curadoria enterprise:
 
@@ -410,7 +410,7 @@ O vocabulário público de `inlineOverlay.applyMode` é `auto | explicit`. Compo
 `Limpar` não é sinônimo de `Cancelar`: no trigger/pill, limpa diretamente o valor aplicado; dentro de um painel `explicit`, deve limpar o rascunho e só virar valor final quando o usuário acionar `Aplicar`, salvo contrato específico documentado pelo componente.
 
 `inlineSelect` usa o mesmo envelope de min/max por densidade/viewport (pill vazio e preenchido), mantendo largura por conteúdo para o texto selecionado.
-`inlineMultiSelect` também usa o envelope adaptativo e, com `inlineOverlay.applyMode: "explicit"`, mantém seleção, remoção e limpeza do painel em rascunho até `Aplicar`; `Cancelar`, `Esc` ou fechamento externo restauram a seleção confirmada anterior. Labels, aria, `appearance` e `colorRole` das ações do rodapé devem vir de `inlineOverlay.actions.*`. O `inlineSelect` single ainda comita no clique por herdar o comportamento nativo do `mat-select`; confirmação explícita ali exige uma superfície de painel própria para não fechar ao selecionar.
+`inlineMultiSelect` também usa o envelope adaptativo e, com `inlineOverlay.applyMode: "explicit"`, mantém seleção, remoção e limpeza do painel em rascunho até `Aplicar`; `Cancelar`, `Esc` ou fechamento externo restauram a seleção confirmada anterior. Labels, aria, `appearance` e `colorRole` das ações do rodapé devem vir de `inlineOverlay.actions.*`. O `inlineSelect` single comita quando uma opção do listbox é ativada e fecha pelo contrato explícito do overlay compartilhado; uma futura confirmação explícita deve reutilizar o mesmo estado de rascunho governado, sem reintroduzir semântica de `mat-select`.
 `inlineAsyncSelect` segue o mesmo envelope adaptativo de largura e mantém label como placeholder visual quando vazio.
 `inlineAutocomplete` também usa auto-width por conteúdo (valor/label), mantendo foco no shape pill e clear alinhado.
 `inlineNumber` segue o mesmo envelope adaptativo de largura, usando valor numérico atual ou label como fallback quando vazio.