@praxisui/dynamic-fields 9.0.4-rc.9 → 9.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "9.0.4-rc.9",
+  "version": "9.0.4",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -11,8 +11,8 @@
     "@angular/platform-browser": "^21.0.0",
     "@angular/router": "^21.0.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^9.0.4-rc.9",
-    "@praxisui/cron-builder": "^9.0.4-rc.9"
+    "@praxisui/core": "^9.0.4",
+    "@praxisui/cron-builder": "^9.0.4"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",

package/src/lib/components/inline-entity-lookup/pdx-inline-entity-lookup.json-api.md

@@ -21,8 +21,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts"
   - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
-source_of_truth_last_verified: "2026-07-26"
-last_updated: "2026-07-26"
+source_of_truth_last_verified: "2026-08-03"
+last_updated: "2026-08-03"
 toc: true
 sidebar: true
 tags:
@@ -128,10 +128,19 @@ Este documento e a referencia canonica da API JSON de pdx-inline-entity-lookup.
 | `metadata.optionSource.display.secondaryPropertyPaths` | string[] | false | n/a | Active | Campos de subtitulo usados para diferenciar entidades parecidas. |
 | `metadata.optionSource.display.fields` | object[] | false | n/a | Active | Campos ricos semanticos exibidos na lista e no valor selecionado. Cada item aceita `key`, `propertyPath`, `label`, `icon`, `presentation`, `tone` e `format`. |
 | `metadata.optionSource.display.badgePropertyPaths` | string[] | false | n/a | Active | Campos publicados como badges/chips quando o backend tambem os materializa no payload de option. |
-| `metadata.searchable` | boolean | false | `true` para fontes nao categoricas | Active | Materializa a acao acessivel de busca no sufixo e abre o dialogo governado sem inserir controles interativos no listbox do `MatSelect`. |
+| `metadata.optionSource.display.statusLabelMap` | Record<string, string> | false | n/a | Active | Traduz somente o rótulo visual do status; o código canônico continua governando seleção, filtros e tons. |
+| `metadata.searchable` | boolean | false | `true` para fontes nao categoricas | Active | Materializa a acao acessivel de busca como irma externa do `MatSelect` e abre o dialogo governado sem inserir controles interativos no listbox. |
 | `metadata.dialog` | object | false | configuracao derivada do campo | Active | Customiza titulo, tamanho, preview, colunas e acoes da busca governada. |
 | `metadata.dialog.enabled` | boolean | false | herda `metadata.searchable` | Active | `false` desativa explicitamente a superficie de busca; `true` a habilita mesmo quando `searchable=false`. |
 
+The governed search dialog owns a visible close action, focuses the search
+input when it opens, restores focus on close, constrains itself to the viewport,
+and presents remote failures with a retry action. Canonical search strategy
+`kind` values are translated into business-facing labels; internal strategy
+keys are not exposed as the primary copy. Remote option sources may require an
+authenticated host context. The component preserves that boundary and never
+falls back to an unprotected resource endpoint when authorization fails.
+
 ### Path audit
 
 Nenhum desvio de caminho foi identificado nesta revisao.
@@ -172,7 +181,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.optionSource.display` | object | false | n/a | contrato semantico de UX, nao CSS | Governanca de preset, uso, densidade, campos ricos, secundarios e badges do resultado. |
 | `metadata.resourcePath` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.inlineAutoSize.*` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.searchable` | boolean | false | `true` para fontes nao categoricas | boolean | Active; abre a busca governada por uma acao irma do `mat-select`. |
+| `metadata.searchable` | boolean | false | `true` para fontes nao categoricas | boolean | Active; abre a busca governada por uma acao externa irma do `mat-select`, nunca projetada no trigger ou no painel de opcoes. |
 | `metadata.dialog` | object | false | derivado do campo | `LookupDialogMetadata` | Active; configura a busca avancada sem redefinir identidade ou option source. |
 | `metadata.dialog.enabled` | boolean | false | herda `metadata.searchable` | boolean | Active; opt-out explicito quando `false`. |
 
@@ -329,13 +338,14 @@ Use quando precisar:
 | `metadata.optionSource.detail.surfaceId` | `string` | Ativo | Id da surface item-level preferida para o detalhe. Quando ausente, o runtime escolhe `detail`, `view` ou a primeira surface item-level de leitura disponivel. |
 | `metadata.optionSource.detail.presentation` | `"drawer" | "modal"` | Ativo | Apresentacao desejada para `surface.open`. Default vem do preset/host de surface. |
 | `metadata.optionSource.detail.preferredWidget` / `metadata.optionSource.detail.mode` | `string` | Documental | Hints semanticos para autoria/discovery. A materializacao final vem da surface descoberta e do `ResourceSurfaceOpenAdapterService`. |
-| `metadata.optionSource.detail.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Legado | Fallback quando nao houver surface governada. Quando ambos existem, `routeTemplate` tem precedencia por representar a rota navegavel do host. `hrefTemplate` que aponta para `/api/**` e tratado como evidencia de recurso, nao como destino de UX, e nao habilita a acao Detalhe isoladamente. |
+| `metadata.optionSource.detail.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Legado | Navegacao usada somente quando o contrato nao declara surface governada. Uma falha ao materializar `detail.kind: "surface"` nunca degrada para rota/href, evitando 404, vazamento de endpoint ou mudanca inesperada de contexto. Quando somente os fallbacks legados existem, `routeTemplate` tem precedencia; `hrefTemplate` de `/api/**` e evidencia de recurso, nao destino de UX. |
 | `metadata.optionSource.display.preset` | `"compact" | "rich" | "directory" | "status" | "reference" | "hierarchical"` | Ativo | Define a intencao visual canonica. `directory` e recomendado para pessoas/equipes; `reference` para codigo + descricao; `status` para entidades com estado operacional forte. |
 | `metadata.optionSource.display.usage` | `"form" | "filter" | "table-cell" | "dashboard" | "wizard" | "review"` | Ativo | Indica onde a option-source costuma aparecer. O runtime pode ajustar densidade e acoes sem duplicar regra por host. |
 | `metadata.optionSource.display.density` | `"compact" | "comfortable" | "rich"` | Ativo | Densidade preferencial. Campos de formulario usam `comfortable`; filtros inline e celulas de tabela tendem a `compact`; revisoes podem usar `rich`. |
 | `metadata.optionSource.display.secondaryPropertyPaths` | `string[]` | Ativo | Campos usados como subtitulo quando o payload local ou remoto preserva essas propriedades. O runtime tambem aceita `descriptionPropertyPaths` como fallback. |
 | `metadata.optionSource.display.fields` | `object[]` | Ativo | Subinformacoes ricas com `propertyPath`, `label`, `icon`, `presentation` (`text`, `chip`, `badge`, `date`, `currency`, `metric`), `tone` e `format`. Quando o endpoint materializa `OptionDTO.extra.richFields[]`, esses valores sao usados diretamente. |
 | `metadata.optionSource.display.badgePropertyPaths` | `string[]` | Ativo | Campos usados para badges/chips quando materializados no payload da option-source. |
+| `metadata.optionSource.display.statusLabelMap` | `Record<string, string>` | Ativo | Mapeia códigos canônicos para rótulos localizados sem alterar o valor usado por `selectionPolicy`. |
 | `metadata.resourcePath` | `string` | Ativo | Caminho operacional herdado. Para Entity Lookup de plataforma, preferir `metadata.optionSource.resourcePath`. |
 | `metadata.inlineAutoSize.*` | `object` | Ativo | Largura responsiva da pill lookup. |
 | `metadata.selectedLayout` | `"compact" | "inline" | "card" | "token"` | Ativo | Para `controlType: "entityLookup"`, `compact` e o default preservam altura de campo de formulario. `card` renderiza valor selecionado como cartao rico quando a superficie pedir revisao/detalhe. `token` preserva leitura compacta herdada. |
@@ -348,6 +358,7 @@ Use quando precisar:
 | `metadata.showDisabledReason` | `boolean` | Ativo | Controla exibicao do motivo de bloqueio quando `selectable=false`. Default: `true`. |
 | `metadata.showResultCount` | `boolean` | Ativo | Controla contador de resultados no painel de busca. Quando `totalElements` remoto for maior que os itens carregados, mostra `carregados de total` para deixar claro que a lista visivel ainda e uma pagina parcial; em fontes locais/cursor, mostra o total carregado. Default: `true`. |
 | `metadata.statusToneMap` | `Record<string, "success" | "warning" | "danger" | "neutral">` | Ativo | Permite mapear status de dominio para tom visual governado. |
+| `metadata.statusLabelMap` | `Record<string, string>` | Ativo | Override local do mapa de rótulos; prefira `optionSource.display.statusLabelMap` como fonte governada. |
 | `metadata.badgeKeys` | `string[]` | Ativo | Chaves adicionais lidas do valor de entidade para compor badges auxiliares. |
 | `metadata.maxVisibleBadges` | `number` | Ativo | Limita quantidade de badges auxiliares exibidos. Default: `3`. |
 | `metadata.actions.showDetail` | `boolean` | Ativo | Controla acao de detalhe quando houver surface canonica, `detailRoute` navegavel ou `detailHref` nao-API. `detailHref` de API nao abre nova aba para evitar link morto em hosts corporativos. Default: `true`. |
@@ -371,6 +382,8 @@ Resumo de composicao deste componente:
 - `metadata.optionSource.display` e a fonte preferencial de UX para a entidade; campos top-level como `selectedLayout`, `density`, `showAvatar` e `showStatus` funcionam como override local de host.
 - Opcoes podem mostrar linha secundaria (`subtitle`) para desambiguacao; em `entityLookup`, a linha rica tambem mostra avatar, campos ricos com icones/chips/datas, status visual, badges e motivo de bloqueio.
 - Com `metadata.optionSource.resourcePath`, busca emite termo no pipeline remoto de option-source; sem endpoint, filtra local.
+- Com fonte remota e `loadOn: "open"`, o seletor rapido permanece abrivel antes da primeira pagina para disparar a carga inicial. A opcao sentinela que viabiliza essa abertura e interna, invisivel e nao integra o contrato visual ou o valor do campo.
+- Ao confirmar uma opcao no seletor rapido, a selecao simples fecha o painel e devolve o foco ao campo; a selecao multipla preserva o painel aberto para continuidade da tarefa. Mouse e teclado seguem a mesma regra.
 - Em uso standalone de shell/topbar autenticado, o componente aceita `FormControl` externo com `initialMetadata` estático e `options` locais. Um valor inicial já selecionado no controle deve materializar o texto da opção local sem bloquear a montagem da rota nem realimentar change detection quando a metadata recebida for semanticamente equivalente.
 - `metadata.resourcePath` continua aceito como configuracao operacional herdada, mas nao substitui a semantica canonica de entidade publicada em `metadata.optionSource`.
 - As acoes de painel ficam em um rodape materializado como irmao do `listbox` no overlay: `Limpar selecao` e uma acao secundaria alinhada ao inicio; `Carregar mais` e uma acao de largura total, com alvo minimo de 44 px, estado ocupado e foco visivel. `Tab` transfere o foco da busca para a primeira acao habilitada. Nenhuma delas participa da navegacao semantica de opcoes.
@@ -434,6 +447,10 @@ Uso: lookup simples em lista local.
         "showCode": false,
         "showDescription": true,
         "showStatus": true,
+        "statusLabelMap": {
+          "ACTIVE": "Ativa",
+          "BLOCKED": "Bloqueada"
+        },
         "showBadges": true,
         "showResultCount": true
       }

package/src/lib/components/inline-multi-select/pdx-inline-multi-select.json-api.md

@@ -319,12 +319,13 @@ Resumo de composicao deste componente:
 - `Parcial`: `multiple` declarado, mas runtime e forçado para `true`.
 
 ### 4. Mapeamento de Comportamento
-- Trigger mostra label e badge com quantidade selecionada.
-- Painel opcionalmente inclui busca no topo (`searchable=true`).
+- O trigger e um unico botao combobox; tokens selecionados sao apresentacionais e nao criam botoes aninhados.
+- O painel conectado inclui busca no cabecalho quando `searchable=true`, lista de opcoes em `listbox` e acoes em footer irmao.
 - `showOptionDisabled()` bloqueia novas escolhas quando `maxSelections` e atingido.
 - Sem `resourcePath`, busca filtra lista local; com endpoint, usa pipeline remoto.
 - Em `inlineOverlay.applyMode: "explicit"`, clique em opcoes, remocao e `Limpar` do painel alteram apenas o rascunho; `Aplicar` emite `valueChange/selectionChange`, enquanto `Cancelar`, `Esc` ou fechamento externo restauram a selecao confirmada.
-- O quick-clear no trigger continua sendo uma acao explicita fora do painel e comita imediatamente.
+- O quick-clear e irmao do trigger, fora do combobox e do painel, e comita imediatamente.
+- Busca, botoes de opcao e footer existem apenas no overlay anexado; nenhuma acao e projetada como conteudo de `mat-select`/`mat-option`.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json

package/src/lib/components/material-async-select/pdx-material-async-select.json-api.md

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts"
   - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
-source_of_truth_last_verified: "2026-07-06"
-last_updated: "2026-07-06"
+source_of_truth_last_verified: "2026-08-11"
+last_updated: "2026-08-11"
 toc: true
 sidebar: true
 tags:
@@ -328,17 +328,17 @@ Garantias:
 - no combobox simples pesquisavel, a proxima pagina e carregada
   automaticamente quando o scroll se aproxima do fim da lista; nao existe
   botao interativo dentro do `listbox`.
-- no caminho `MatSelect`, a acao opcional de carregar mais permanece irma
-  declarativa do select e fora do overlay.
+- no caminho de selecao por painel, busca, opcoes e a acao opcional de carregar
+  mais sao regioes irmas dentro do overlay conectado; o footer so existe no DOM
+  enquanto o painel esta aberto e nunca integra o `listbox`.
 - fontes locais (`selectOptions`/`options`) e `loadOn='none'` antes da primeira carga nao exibem acao de paginacao.
 - em paginacao numerada, o fim usa `totalPages`/`totalElements` quando fornecidos pelo backend; se ausentes, usa `content.length < pageSize` como fallback.
 
 Limites:
 
 - debounce de busca interno permanece fixo em `300ms`.
-- selecao multipla permanece no caminho `MatSelect`; um composite multi-select
-  pesquisavel exige arquitetura propria de chips/listbox e nao reutiliza o
-  combobox simples.
+- selecao multipla usa o overlay conectado com `listbox` multisselecao; ela nao
+  projeta busca ou acoes dentro de `mat-select` e nao reutiliza o combobox simples.
 - ordenacao nao possui contrato dedicado nesta camada.
 - `loadOn` e `useCursor` dependem da capacidade do backend e da configuracao global.
 
@@ -406,7 +406,7 @@ Precedencia de comportamento:
 | `metadata.filterCriteria` | `Record<string, any>` | Active | Filtros base para consulta remota. |
 | `metadata.optionLabelKey` | `string` | Active | Chave de label no payload remoto. |
 | `metadata.optionValueKey` | `string` | Active | Chave de value no payload remoto. |
-| `metadata.searchable` | `boolean` | Active | Em single, escolhe entre combobox pesquisavel e `MatSelect`; em multiple, habilita a busca auxiliar do caminho multiplo. |
+| `metadata.searchable` | `boolean` | Active | Em single, escolhe o combobox pesquisavel; nos demais casos, habilita `pdx-collection-search` no cabecalho do overlay de colecao. |
 | `metadata.loadOn` | `'open' \| 'init' \| 'none'` | Runtime-extension | Estrategia de primeira carga remota. |
 | `metadata.dependencyLoadOnChange` | `'respectLoadOn' \| 'immediate' \| 'manual'` | Runtime-extension | Regras de recarga por dependencia. |
 
@@ -490,6 +490,7 @@ Correcao: use `dependencyLoadOnChange='immediate'` ou dispare recarga no host.
 | `--pdx-select-panel-action-hover-surface` / `--pdx-select-panel-action-focus-ring` | overlay footer | Estados hover e foco visivel | O host deve preservar contraste AA em temas claro e escuro. |
 | `--pdx-select-panel-load-more-surface` / `--pdx-select-panel-load-more-outline` | overlay footer | Tratamento do botao `Carregar mais` | Permite distinguir a acao sem acoplamento a internals MDC. |
 | `--pdx-select-panel-actions-gap` / `--pdx-select-panel-actions-padding` / `--pdx-select-panel-action-min-height` / `--pdx-select-panel-action-padding` / `--pdx-select-panel-action-radius` / `--pdx-select-panel-action-disabled-opacity` | overlay footer | Densidade, geometria e estado desabilitado | Altura default de 44 px preserva alvo corporativo acessivel. |
+| `--praxis-collection-search-*` | overlay header | Superficie, texto, outline, foco, densidade, tipografia e raio da busca | Contrato compartilhado com Table. `--praxis-collection-search-radius` aceita `0`, valores intermediarios e pill; nao criar aliases locais. |
 
 ## Examples (obrigatorio)
 

package/src/lib/components/material-date-range/pdx-material-date-range.json-api.md

@@ -170,6 +170,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 ### Manual date parsing
 
 - Digitacao manual usa `PraxisNativeDateAdapter` e respeita o `LOCALE_ID` do host.
+- Rotulos acessiveis do calendario Material usam o locale canonico do `PraxisI18nService` via `PraxisMatDatepickerIntl`, mantendo navegacao, atalhos e leitores de tela no mesmo idioma.
 - Em locales nao ingleses, como `pt-BR`, datas numericas sao interpretadas como `dd/MM/yyyy`.
 - Em locales ingleses, datas numericas sao interpretadas como `MM/dd/yyyy`.
 - Strings ISO date-only (`YYYY-MM-DD`) sao tratadas como data local, sem deslocamento por timezone.

package/src/lib/components/material-datepicker/pdx-material-datepicker.json-api.md

@@ -164,7 +164,8 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 
 ### Manual date parsing
 
-- Digitacao manual usa `PraxisNativeDateAdapter` e respeita `metadata.locale`; quando ausente, usa o `LOCALE_ID` do host.
+- Digitacao manual usa `PraxisNativeDateAdapter` e respeita `metadata.locale`; quando ausente, usa o locale canonico do `PraxisI18nService`.
+- Rotulos visiveis e acessiveis do calendario Material (abrir, fechar, navegacao entre meses/anos e alternancia de visao) usam o mesmo locale efetivo do campo via `PraxisMatDatepickerIntl`.
 - Em locales nao ingleses, como `pt-BR`, datas numericas sao interpretadas como `dd/MM/yyyy`.
 - Em locales ingleses, datas numericas sao interpretadas como `MM/dd/yyyy`.
 - `metadata.locale` e ordem de data sao independentes: `displayFormat`, `dateFormat` ou `mask` como `dd/MM/yyyy` habilitam apresentacao day-first; `MM/dd/yyyy` habilita month-first.

package/src/lib/components/material-select/pdx-material-select.json-api.md

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-select/material-select.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts"
   - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-08-11"
+last_updated: "2026-08-11"
 toc: true
 sidebar: true
 tags:
@@ -337,12 +337,12 @@ Garantias:
 Limites:
 
 - componente opera em selecao unica (nao e multi-select).
-- `searchable=true` nao renderiza caixa de busca embutida neste template.
+- `searchable=true` materializa a busca no cabecalho do overlay conectado, como regiao irma do `listbox`.
 - `clearButton` e suportado via runtime base, mas nao tipado explicitamente em `MaterialSelectMetadata`.
 
 #### Controle de comportamento
 
-**O que isso habilita:** padrao unico de carregamento local/remoto e exibicao de opcoes no `mat-select`.
+**O que isso habilita:** padrao unico de carregamento local/remoto e exibicao de opcoes no overlay conectado de colecao.
 
 **Quando usar:** quando a regra de negocio exige previsibilidade de UX e compatibilidade entre squads.
 
@@ -395,7 +395,7 @@ Precedencia de comportamento:
 | `metadata.selectOptions` | `Array<{ value; text; label?; disabled? }>` | Active | Fonte principal de opcoes locais. |
 | `metadata.options` | `Array<any>` | Runtime-extension | Alias legado quando `selectOptions` nao e informado. |
 | `metadata.emptyOptionText` | `string` | Active | Exibe opcao vazia com valor `null`. |
-| `metadata.searchable` | `boolean` | Partial | Campo existe no contrato base, mas nao renderiza input de busca aqui. |
+| `metadata.searchable` | `boolean` | Active | Renderiza `pdx-collection-search` no cabecalho do overlay, fora do `listbox`. |
 | `metadata.multiple` | `boolean` | Partial | Campo declarado, porem runtime deste componente permanece single (`false`). |
 | `metadata.selectAll` | `boolean` | Partial | Sem efeito funcional em modo single. |
 | `metadata.maxSelections` | `number` | Partial | Sem efeito funcional em modo single. |
@@ -421,8 +421,8 @@ Contrato compartilhado completo:
 1. Multi-selecao nao funciona neste componente.
 Correcao: use `pdx-material-multi-select` ou `pdx-material-async-select` com `multiple=true`.
 
-2. `searchable=true` nao exibe campo de busca.
-Correcao: use `pdx-material-searchable-select` para busca embutida.
+2. A busca nao aparece com `searchable=true`.
+Correcao: confirme que o painel esta aberto e que o metadata efetivo nao sobrescreveu `searchable`; a busca so existe no DOM enquanto o overlay esta anexado.
 
 3. Opcoes nao carregam no remoto.
 Correcao: valide `resourcePath`, `filterCriteria` e mapeamento `optionLabelKey/optionValueKey`.