@praxisui/dynamic-fields 9.0.59 → 9.0.60

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

@@ -88,6 +88,7 @@ As secoes detalhadas abaixo continuam como referencia de UX/metadata, mas a tril
    - Campos compactos (`inline*`, formato canônico) ficam na faixa `compact-fields` (flex).
    - Campos não compactos seguem na `fields-grid`.
    - Evitar largura fixa em componentes compactos; usar `min/max` responsivos.
+   - O componente inline governa sua largura intrínseca e seu teto por conteúdo; o contêiner consumidor governa a distribuição da linha. Em toolbars estreitas, intervalos longos de data e moeda devem ocupar a linha disponível para preservar leitura e manipulação; campos curtos podem compartilhar a linha, enquanto presets, horários curtos e comandos não devem ser esticados apenas para eliminar espaço vazio.
 
 3. Overlay/Popover:
    - Arredondamento superior e inferior preservado.
@@ -156,12 +157,12 @@ Exemplo mínimo (quick clear explícito para os 3 inline especiais):
 - `inlineAutocomplete`: autocomplete compacto em pill, com busca incremental e lista em popover arredondado.
 - `inlineNumber`: número compacto em pill, com validação `min/max`, clear e largura adaptativa. Em `numericFormat/format = percent`, renderiza sufixo `%` e defaults corporativos (`min=0`, `max=100`, `step=0.01`) quando não informados. O visual gráfico enriquecido fica sob opt-in explícito com `inlineVisualStyle = "graphic"`, mas é reduzido ao pill compacto quando renderizado dentro de `praxis-filter` compacto para preservar densidade, ritmo e legibilidade da barra.
 - `inlineCurrency`: moeda compacta em pill, com máscara, locale/moeda configuráveis e clear.
-- `inlineCurrencyRange`: faixa monetária compacta em pill, com slider duplo em popover, resumo `min-max`, ticks/marks semânticos compactos, bands opcionais, histograma/distribuição, readout adaptativo para evitar colisão de valores longos e confirmação explícita por `Aplicar`/`Cancelar`.
+- `inlineCurrencyRange`: faixa monetária compacta em pill, com slider duplo em popover, resumo `min-max`, ticks/marks semânticos compactos, bands opcionais, histograma/distribuição, indicadores discretos adaptativos sem colisão ou escape nas bordas e confirmação explícita por `Aplicar`/`Cancelar`.
 - `inlineMultiSelect`: listas múltiplas compactas em pill + popover, exibindo tokens selecionados com overflow `+N`, seção de selecionados no painel e confirmação explícita por `inlineOverlay` quando necessário.
 - `inlineInput`: texto compacto com ícone de busca, clear, largura adaptativa e mascara de
   display para campos textuais semanticamente conhecidos (CPF/CNPJ, telefone BR/E.164 e CEP),
   preservando o valor cru enviado ao filtro.
-- `inlineToggle`: toggle booleano compacto em pill, com `clear` para voltar a estado neutro (`null`).
+- `inlineToggle`: toggle booleano compacto em pill, com `clear` para voltar a estado neutro (`null`); quando o host limitar sua largura, o label usa ellipsis real e preserva a leitura integral no tooltip.
 - `inlineRange`: chip compacto + popover com slider, suportando `rangeSlider` em modo `single` e `range`, inputs numéricos opcionais (`showInputs`), labels/marks declarativos, value labels, histograma/distribuição e presets rápidos (`quickPresets` / `quickPresetsAuto`).
 - `inlinePeriodRange`: faixa temporal compacta por granularidade, cobrindo `month`, `quarter`, `year` e `fiscal-year` com chip e presets específicos por período.
 - `inlineYearRange`: alias compatível para `inlinePeriodRange` com `granularity: 'year'`.
@@ -359,14 +360,14 @@ Fonte de verdade: `projects/praxis-metadata-editor/src/lib/config/*.config.ts`.
 
 #### `price-range.config.ts`
 
-`label, hint, tooltip, inlinePanelTitle, startLabel, endLabel, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, startPlaceholder, endPlaceholder, defaultValue.minPrice, defaultValue.maxPrice, hideSubLabels, layout, gap, clearButtonPlacement, required, readonly, disabled, hidden, min, max, startMin, startMax, startMinMessage, startMaxMessage, endMin, endMax, endMinMessage, endMaxMessage, endMinOffset, endMinOffsetMessage, startMaxOffset, startMaxOffsetMessage, step, showTicks, marks, semanticBands, currency, currencyPosition, decimalPlaces, locale, thousandsSeparator, decimalSeparator, allowNegative, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.ariaLabel, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.appearance, materialDesign.color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, ariaLabel, ariaDescribedby, ariaLabelledby`
+`label, hint, tooltip, inlinePanelTitle, startLabel, endLabel, prefixIcon, prefixIconColor, suffixIcon, suffixIconColor, startPlaceholder, endPlaceholder, defaultValue.minPrice, defaultValue.maxPrice, hideSubLabels, layout, gap, clearButtonPlacement, required, readonly, disabled, hidden, min, max, startMin, startMax, startMinMessage, startMaxMessage, endMin, endMax, endMinMessage, endMaxMessage, endMinOffset, endMinOffsetMessage, startMaxOffset, startMaxOffsetMessage, step, showTicks, discrete, marks, semanticBands, currency, currencyPosition, decimalPlaces, locale, thousandsSeparator, decimalSeparator, allowNegative, clearButton.enabled, clearButton.icon, clearButton.iconColor, clearButton.tooltip, clearButton.ariaLabel, clearButton.showOnlyWhenFilled, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.apply.ariaLabel, inlineOverlay.actions.apply.appearance, inlineOverlay.actions.apply.colorRole, inlineOverlay.actions.cancel.label, inlineOverlay.actions.cancel.ariaLabel, inlineOverlay.actions.cancel.appearance, inlineOverlay.actions.cancel.colorRole, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.ariaLabel, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.appearance, materialDesign.color, inlineAutoSize.minWidth, inlineAutoSize.maxWidth, inlineAutoSize.minWidthMobile, inlineAutoSize.maxWidthMobile, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, ariaLabel, ariaDescribedby, ariaLabelledby`
 
 #### Matrizes especializadas (incrementais)
 
 - `inlineRating`:
   `ratingIcon, allowHalf, ratingAllowHalf, ratingPrecision, precision, ratingToneLowColor, ratingToneMidColor, ratingToneHighColor, ratingBadgeColor, ratingBadgeIcon, ratingBadgeIconColor, ratingActiveIcon, ratingInactiveIcon, ratingToneColors, ratingColors, starColors, ratingLowColor, ratingMidColor, ratingHighColor, ratingIndicatorColor, ratingMin, ratingMax, itemsCount, ratingStep, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, materialDesign.density`
 - `inlineDistanceRadius`:
-  `distanceIcon, distanceSubtitle, distanceUnit, distanceBaseUnit, distanceAllowUnitToggle, distanceUnits, distanceUnitLabels.km, distanceUnitLabels.mi, distanceDisplayDecimals, distancePresets, distanceRadialRings, distanceAccentColor, distanceRingColor, distanceTrackColor, distanceGlowColor, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.density`
+  `distanceIcon, distanceSubtitle, distanceUnit, distanceBaseUnit, distanceAllowUnitToggle, distanceUnits, distanceUnitLabels.km, distanceUnitLabels.mi, distanceDisplayDecimals, distancePresets, distanceRadialRings, distanceAccentColor, distanceRingColor, distanceTrackColor, distanceGlowColor, distanceGradientLowColor, distanceGradientMidColor, distanceGradientHighColor, distanceRangeBandOpacity, marks, showTicks, discrete, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, materialDesign.density`
 - `inlinePipelineStatus`:
   `pipelineSubtitle, pipelineOptions, pipelineSearchable, pipelineSearchPlaceholder, pipelineOptionSubtitleKey, pipelineOptionWeightKey, pipelineOptionColorKey, pipelineShowBar, pipelineShowSelectionPills, pipelineShowSelectAll, pipelineSelectAllText, pipelineShowClearAction, pipelineClearActionText, inlineOverlay.applyMode, inlineOverlay.actions.apply.label, inlineOverlay.actions.cancel.label, inlineOverlay.actions.clear.label, inlineOverlay.actions.clear.appearance, inlineOverlay.actions.clear.colorRole, pipelineChipMaxVisible, pipelineColors, pipelineEmptyStateText, pipelineSelectionActionsAriaLabel, pipelineOptionsGroupAriaLabelMultiple, pipelineOptionsGroupAriaLabelSingle, pipelineSelectionPillsAriaLabel, pipelineBarAriaLabelEmpty, pipelineBarAriaLabelSelected, pipelineTexts, pipelineIcon, pipelineSearchIcon, pipelineSearchIconColor, inlineAutoSize.panelMinWidth, inlineAutoSize.panelMaxWidth, inlineAutoSize.panelMinWidthMobile, inlineAutoSize.panelMaxWidthMobile`
 - `inlineScorePriority`:
@@ -423,15 +424,15 @@ O vocabulário público de `inlineOverlay.applyMode` é `auto | explicit`. Compo
 `inlineNumber` segue o mesmo envelope adaptativo de largura, usando valor numérico atual ou label como fallback quando vazio.
 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.
+`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. `step` governa a precisão e o encaixe da seleção. `showTicks` materializa uma guia de passos com quantidade limitada, e `"auto"` reduz sua densidade conforme a largura sem alterar `step`. `marks` materializa pontos de referência explícitos e até três labels compactos, sem restringir a seleção a esses valores. `discrete` exibe o valor monetário formatado junto ao thumb durante o ajuste; quando os dois indicadores não cabem lado a lado, o runtime os combina em uma leitura única da faixa e contém os indicadores separados nas bordas do painel. `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`. 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.
+`inlineRating` e um filtro de faixa: o slider de dois thumbs e o controle primario e a escala de estrelas e feedback visual nao interativo, inclusive com preenchimento parcial nas fronteiras de meia estrela. O modo padrao e `inlineOverlay.applyMode: "explicit"`; `auto` permanece como opt-in. No modo explicito, o painel exibe `Aplicar`, `Cancelar` e `Limpar`; escala, resumo, inputs e presets acompanham somente o rascunho. `Limpar` esvazia o rascunho e aguarda `Aplicar`, enquanto o X do chip limpa imediatamente o valor confirmado.
+`inlineDistanceRadius` publica `InlineDistanceRadiusMetadata` como contrato especializado. O runtime separa a cor de destaque do gradiente semântico baixo/médio/alto, projeta `marks` como referências visuais sem alterar o `step` e limita `showTicks: "auto"` para evitar trilhos excessivamente densos. Em `applyMode: "explicit"`, slider radial e presets ficam em rascunho até `Aplicar`; o trigger, o tooltip, o nome acessível e o payload continuam refletindo o valor confirmado. `Cancelar`, `Esc` e fechamento externo descartam a alteração. O catálogo oficial demonstra esse modo explícito por padrão; `auto` permanece disponível para filtros simples e reversíveis.
 `inlinePipelineStatus` usa `inlineOverlay` quando mudanças de etapa/status precisam ser revisadas antes de afetar o filtro aplicado. Em `applyMode: "explicit"`, cards, selecionar todos e limpar seleção alteram apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc` e fechamento externo restauram a seleção anterior. Labels, aria, `appearance`, `colorRole` e ícones das ações finais devem vir de `inlineOverlay.actions.*`.
 `inlineRelativePeriod` usa `inlineOverlay` quando presets temporais precisam ser explorados sem alterar imediatamente o filtro aplicado. Em `applyMode: "explicit"`, cards de período e progresso visual acompanham apenas o rascunho; `Aplicar` comita o preset, enquanto `Cancelar`, `Esc` e fechamento externo restauram a seleção anterior. Labels, aria, `appearance`, `colorRole` e ícones devem ser authorados em `inlineOverlay.actions.*`.
 

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

@@ -140,6 +140,8 @@ Não criar contratos locais como `confirm`, `commitPolicy` ou botões hardcoded
 
 `Limpar` não é `Cancelar`: no trigger/pill é uma ação direta de remover o valor aplicado; dentro de um overlay `explicit`, deve limpar o rascunho e aguardar `Aplicar`, salvo contrato específico documentado pelo componente.
 
+`inlineRating` materializa essa regra como filtro de faixa: o slider de dois thumbs altera o rascunho e a escala de estrelas apenas o representa. O componente usa `explicit` como padrao; `auto` precisa ser authorado deliberadamente. Cada thumb mantem identidade e nome acessivel proprios, e a escala visual nao atua como um segundo seletor escalar concorrente. O mesmo isolamento vale para `inlineDistanceRadius`: painel, radial e presets podem apresentar o rascunho, enquanto trigger, tooltip, nome acessivel e payload permanecem no valor confirmado ate `Aplicar`.
+
 ### Valores simples
 
 - texto: `string`