@praxisui/dynamic-fields 9.0.14 → 9.0.16

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

@@ -106,7 +106,8 @@ As secoes detalhadas abaixo continuam como referencia de UX/metadata, mas a tril
    - `aria-label` sempre disponível.
    - Placeholder visual custom deve ser `aria-hidden`.
    - Botões de limpar com `aria-label`.
-   - Foco visual visível em dark/light theme.
+   - O alvo interativo de limpar usa `24px` como padrão compacto canônico da família inline.
+   - Foco visual visível em dark/light theme e em `forced-colors`.
 
 6. Regra de clear button (corporativo):
    - Controles inline respeitam `metadata.clearButton` (`enabled`, `showOnlyWhenFilled`).
@@ -121,6 +122,12 @@ As secoes detalhadas abaixo continuam como referencia de UX/metadata, mas a tril
    - Para `inlineRelativePeriod`, `inlineSentiment` e `inlineColorLabel`, defina
      `metadata.clearButton` explicitamente quando quiser quick clear.
    - Fora da lista acima, o default corporativo de quick clear não é aplicado automaticamente.
+   - O tamanho pode ser ampliado por `--pdx-inline-clear-size`; componentes que
+     posicionam a ação sobre o trigger devem derivar a faixa reservada desse tamanho,
+     mantendo pelo menos `8px` entre o valor e a ação.
+   - Posicionamento e espaçamento usam propriedades lógicas para preservar a mesma
+     hierarquia em LTR e RTL. O `praxis-filter` apenas mapeia seu tema para o token
+     package-owned; não deve corrigir geometria interna de um field.
 
 Exemplo mínimo (quick clear explícito para os 3 inline especiais):
 
@@ -266,8 +273,8 @@ Esta seção formaliza o contrato único de metadata para todos os inline do `pr
 | `inlinePeriodRange`      | `range-slider.config.ts` | `extensão temporal genérica co-localizada` | granularidades `month`, `quarter`, `year`, `fiscal-year`                                 | `registrado por default no runtime inline`                 |
 | `inlineYearRange`        | `range-slider.config.ts` | `alias compatível de inlinePeriodRange`    | converte para `granularity: 'year'`                                                      | `compatível; prefira inlinePeriodRange em contratos novos` |
 | `inlineMonthRange`       | `range-slider.config.ts` | `alias compatível de inlinePeriodRange`    | converte para `granularity: 'month'`                                                     | `compatível; prefira inlinePeriodRange em contratos novos` |
-| `inlineDate`             | `date.config.ts`         | —                                          | datepicker inline com auto width + `inlineOverlay` opcional                               | `registrado por default no runtime inline`                 |
-| `inlineDateRange`        | `date-range.config.ts`   | —                                          | presets + `inlineOverlay.applyMode`                                                       | `registrado por default no runtime inline`                 |
+| `inlineDate`             | `date.config.ts`         | —                                          | datepicker inline com auto width + `inlineOverlay` opcional                              | `registrado por default no runtime inline`                 |
+| `inlineDateRange`        | `date-range.config.ts`   | —                                          | presets + `inlineOverlay.applyMode`                                                      | `registrado por default no runtime inline`                 |
 | `inlineTime`             | `time-picker.config.ts`  | —                                          | modo `auto/list/columns`; toggle e selected icon metadata-driven                         | `registrado por default no runtime inline`                 |
 | `inlineTimeRange`        | `time-range.config.ts`   | —                                          | faixa de horário com validações                                                          | `registrado por default no runtime inline`                 |
 | `inlineTreeSelect`       | `tree-select.config.ts`  | —                                          | busca em árvore + seleção de nó                                                          | `registrado por default no runtime inline`                 |
@@ -398,12 +405,12 @@ Override opcional por metadata:
 
 `inlineOverlay` é o contrato canônico para painéis inline editáveis. Ele não deve ser substituído por contratos locais como `confirm`, `commitPolicy` ou labels isolados por componente.
 
-| Classe de interação | Componentes típicos | Modo recomendado | Regra UX |
-| --- | --- | --- | --- |
-| Campo direto sem painel composto | `inlineInput`, `inlineNumber`, `inlineCurrency`, `inlineToggle` | Sem `inlineOverlay` | Alteração aplica imediatamente; `Cancelar`/`Aplicar` adicionaria fricção sem reduzir erro. |
-| Seleção simples conclusiva | `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineAutocomplete`, `inlineTreeSelect`, `inlineTime` | `auto` ou sem `inlineOverlay` | Escolher uma opção aplica o filtro; `Esc` e clique externo apenas fecham o painel. |
+| Classe de interação                                     | Componentes típicos                                                                                                                                                                                                                                                 | Modo recomendado                                                                    | Regra UX                                                                                                                                     |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Campo direto sem painel composto                        | `inlineInput`, `inlineNumber`, `inlineCurrency`, `inlineToggle`                                                                                                                                                                                                     | Sem `inlineOverlay`                                                                 | Alteração aplica imediatamente; `Cancelar`/`Aplicar` adicionaria fricção sem reduzir erro.                                                   |
+| Seleção simples conclusiva                              | `inlineSelect`, `inlineSearchableSelect`, `inlineAsyncSelect`, `inlineAutocomplete`, `inlineTreeSelect`, `inlineTime`                                                                                                                                               | `auto` ou sem `inlineOverlay`                                                       | Escolher uma opção aplica o filtro; `Esc` e clique externo apenas fecham o painel.                                                           |
 | Seleção múltipla, range, presets ou painel exploratório | `inlineMultiSelect`, `inlineRange`, `inlineCurrencyRange`, `inlineRating`, `inlineDistanceRadius`, `inlineScorePriority`, `inlinePipelineStatus`, `inlineRelativePeriod`, `inlineSentiment`, `inlineColorLabel`, `inlineDate`, `inlineDateRange`, `inlineTimeRange` | `explicit` quando houver rascunho real; `auto` quando a interação for filtro rápido | Em `explicit`, alterações ficam em rascunho; `Aplicar` comita; `Cancelar`, `Esc` e fechamento externo restauram o valor confirmado anterior. |
-| Lookup com dialog real | `inlineEntityLookup` | Semântica de dialog | `Cancelar` fecha sem alterar a seleção confirmada; a ação primária do dialog comita e o foco retorna ao trigger. |
+| Lookup com dialog real                                  | `inlineEntityLookup`                                                                                                                                                                                                                                                | Semântica de dialog                                                                 | `Cancelar` fecha sem alterar a seleção confirmada; a ação primária do dialog comita e o foco retorna ao trigger.                             |
 
 O vocabulário público de `inlineOverlay.applyMode` é `auto | explicit`. Componentes podem tolerar aliases legados em runtime para compatibilidade, mas documentação, exemplos e authoring visual devem emitir `explicit` para fluxos com `Aplicar`/`Cancelar`.
 
@@ -417,8 +424,11 @@ O vocabulário público de `inlineOverlay.applyMode` é `auto | explicit`. Compo
 No modo percentual (`numericFormat` ou `format` com valor `percent`), mantém o mesmo layout inline e exibe sufixo `%`, preservando overrides explícitos de `min/max/step`.
 `inlineCurrency` segue envelope adaptativo (`inlineAutoSize`) com máscara de moeda e símbolo antes/depois conforme metadata (`currencyPosition`).
 `inlineCurrencyRange` segue envelope adaptativo (`inlineAutoSize`) no chip e popover, com escala e resumo monetário formatados. No painel, o resumo completo é a leitura principal da faixa selecionada; os valores junto ao slider são usados apenas como orientação quando não duplicam a seleção ativa. `marks` materializa até três labels compactos e ativa ticks; `semanticBands` projeta faixas de significado no trilho; `distribution/rangeDistribution/histogram` continua sendo a camada para comparação com população real. Por padrão, alterações feitas no painel ficam em rascunho até `Aplicar`; `Cancelar`, `Esc` ou fechamento externo descartam o rascunho, e `Limpar` remove o filtro explicitamente. Labels, aria, `appearance`, `colorRole` e ícones dessas ações devem vir de `inlineOverlay.actions.*` e materializar tokens do tema. Quando `inlineOverlay.applyMode: "auto"` for explicitado, o slider comita durante a interação e a ação de cancelar deixa de ser exibida.
-`inlineEntityLookup` usa envelope adaptativo (`inlineAutoSize`) com faixa padrão maior para comportar `id + descrição`.
+`inlineEntityLookup` usa envelope adaptativo (`inlineAutoSize`) com faixa padrão maior para comportar `id + descrição`. Quando preenchido, o trigger e as ações materializadas formam um único compound control, preservando cada botão como irmão declarativo do `mat-select` e fora do `mat-select-trigger`. O próprio combobox é o affordance padrão para trocar a seleção; `actions.showChange: true` mantém um botão separado apenas quando essa decisão tiver sido explicitamente authorada. Detalhe, busca avançada e limpar continuam governados pela metadata/capabilities existentes, sem contrato visual paralelo.
+O segmento de ações só é materializado quando pelo menos uma ação estiver disponível. Isso evita divisória, padding e `role="group"` vazios em campos obrigatórios, readonly ou limitados por permissão. Em seleção múltipla, cada remoção opera pela identidade canônica e o label acessível vem do catálogo i18n; labels, ids e limites nunca devem ser interpolados manualmente pelo host.
+No dialog de busca avançada, `ArrowDown` ou `Tab` move o foco da busca para o resultado ativo; sem resultados, `Tab` alcança a primeira ação habilitada. `Shift+Tab` mantém o percurso reverso, `Escape` cancela e fecha, e o foco retorna ao acionador de origem após confirmação ou cancelamento.
 Em shells corporativos autenticados, como seletores globais de empresa, tenant ou órgão, `pdx-inline-entity-lookup` pode ser usado fora de `PraxisDynamicForm` com um `FormControl` externo e `initialMetadata` estático. Para fontes locais, informe `options`, `optionValueKey`, `optionLabelKey` e `loadOn: "open"`; o valor inicial do `FormControl` deve ser preservado sem disparar recarga remota nem reprocessamento contínuo de metadata. Hosts devem preferir uma referência estável de metadata, mas o runtime tolera recriação semântica equivalente para evitar loops de change detection em topbars.
+Para seletores globais obrigatórios, derive `showDetail`, `showChange`, `showCopyCode` e `showClear` das capabilities e permissões governadas; não replique essa decisão em CSS ou esconda botões depois da materialização. Um campo sem ação permitida continua sendo um compound trigger íntegro, sem segmento visual vazio.
 `inlineRange` usa envelope adaptativo de largura (`inlineAutoSize`) no chip e no popover para evitar bloco fixo largo quando usado na barra compacta. Por padrao, altera em modo `auto` para preservar filtros rápidos; com `inlineOverlay.applyMode: "explicit"`, slider, inputs e presets ficam em rascunho até `Aplicar`, enquanto `Cancelar`, `Esc` ou fechamento externo descartam o rascunho. Labels, aria, `appearance` e `colorRole` dos botoes devem vir de `inlineOverlay.actions.*` e materializar tokens do tema, nao CSS ad hoc.
 `inlineRating` usa o mesmo contrato `inlineOverlay` para fluxos em que explorar estrelas, inputs ou presets nao deve alterar o filtro aplicado imediatamente. Em `applyMode: "explicit"`, o painel exibe `Aplicar`, `Cancelar` e `Limpar`; a escala visual acompanha o rascunho e o valor final so muda no commit.
 `inlineDistanceRadius` usa o mesmo contrato `inlineOverlay` quando a decisao de UX exigir confirmacao: em `applyMode: "explicit"`, slider radial e presets ficam em rascunho ate `Aplicar`; `Cancelar`, `Esc` e fechamento externo descartam a alteracao. O modo default continua imediato para preservar filtros de raio rapidos.

package/docs/dynamic-fields-inline-filter-catalog.md

@@ -194,7 +194,18 @@ Para hosts oficiais:
 { "name": "customerId", "controlType": "inlineEntityLookup", "resourcePath": "/customers/options" }
 ```
 
-- UX note: sempre explicite `optionLabelKey` e `optionValueKey`
+- UX note: sempre explicite `optionLabelKey` e `optionValueKey`. Quando houver
+  seleção, valor e ações pertencem ao mesmo compound control; o próprio
+  combobox é o affordance padrão para trocar. Use `actions.showChange: true`
+  apenas quando a ação separada for intencional. O segmento de ações não é
+  renderizado se nenhuma ação estiver disponível, inclusive em filtros
+  obrigatórios, readonly ou limitados por permissão.
+- Teclado: na busca avançada, `ArrowDown`/`Tab` entrega foco ao resultado ativo;
+  sem resultados, `Tab` segue para as ações. `Escape` fecha sem alterar a
+  seleção confirmada e o foco retorna ao acionador.
+- Governança corporativa: seletores de empresa, tenant ou órgão devem consumir
+  capabilities/permissões para detalhe, troca, cópia e limpeza. Não esconda
+  ações governadas com CSS no host e não use label como identidade.
 - Docs relacionadas: `dynamic-fields-inline-filter-runtime-contract`, `dynamic-filter-payload-contract`
 
 ### <span id="inline-autocomplete"></span>`inlineAutocomplete`

package/docs/dynamic-fields-inline-filter-runtime-contract.md

@@ -202,6 +202,18 @@ Por isso:
 
 Esses campos sao de renderizacao.
 
+### Contrato visual da ação de limpar
+
+- `--pdx-inline-clear-size` controla o alvo interativo package-owned e tem fallback
+  canônico de `24px` em toda a família inline.
+- Componentes com clear posicionado sobre o trigger reservam uma faixa derivada do
+  tamanho efetivo da ação; não use padding fixo que volte a sobrepor labels em temas
+  corporativos com alvos maiores.
+- A faixa mantém pelo menos `8px` entre valor e ação, usa propriedades lógicas para
+  LTR/RTL e preserva foco visível em dark, light e `forced-colors`.
+- Consumidores como `praxis-filter` podem mapear tokens de tema, mas a geometria,
+  o contraste e o foco continuam pertencendo a `dynamic-fields`.
+
 ### Politica de `materialDesign` em filtros
 
 Filtros inline e filtros avancados frequentemente usam icones de prefixo,