@praxisui/dynamic-fields 9.0.0-beta.7 → 9.0.0-beta.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "9.0.0-beta.7",
+  "version": "9.0.0-beta.71",
   "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.0-beta.7",
-    "@praxisui/cron-builder": "^9.0.0-beta.7"
+    "@praxisui/core": "^9.0.0-beta.71",
+    "@praxisui/cron-builder": "^9.0.0-beta.71"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",
@@ -26,6 +26,7 @@
   "keywords": [
     "angular",
     "praxisui",
+    "praxis",
     "dynamic-fields",
     "material",
     "metadata-driven",
@@ -42,7 +43,10 @@
     ".": {
       "types": "./types/praxisui-dynamic-fields.d.ts",
       "default": "./fesm2022/praxisui-dynamic-fields.mjs"
+    },
+    "./ai/component-registry.json": {
+      "default": "./ai/component-registry.json"
     }
   },
   "type": "module"
-}
+}

package/src/lib/base/pdx-base-input-runtime-contract.json-api.md

@@ -349,6 +349,9 @@ Limites:
 | `metadata.validators.showInlineErrors` | `boolean` | Active | Forca/desliga exibicao inline de erros. |
 | `metadata.errorStateMatcher` | enum | Active | Estrategia de estado de erro usada pelo matcher utilitario. |
 | `metadata.hint` | `string` | Active | Exibe dica quando nao ha erro. |
+| `metadata.helpText` | `string` | Active | Texto de ajuda semantica publicado por DTO/schema; usado como fallback quando `hint` nao foi informado. |
+| `metadata.helpDisplay` | `'auto' \| 'inline' \| 'popover' \| 'hidden'` | Active | Politica efetiva de apresentacao de `hint`/`helpText`; normalmente materializada pelo host `praxis-dynamic-form` a partir de `FormConfig.helpPresentation`. |
+| `metadata.helpInlineMaxLength` | `number` | Active | Limite local usado quando `metadata.helpDisplay` e `auto`; textos acima do limite migram para affordance de ajuda. |
 | `metadata.hintAlign` | `'start' \| 'end'` | Active | Alinhamento da dica. |
 | `metadata.materialDesign.appearance` | `'fill' \| 'outline'` | Active | Aparencia do `mat-form-field`. |
 | `metadata.materialDesign.color` | `'primary' \| 'accent' \| 'warn'` | Active | Cor do `mat-form-field`. |
@@ -373,6 +376,19 @@ Limites:
 | `metadata.ariaDescribedby` | `string` | Active | `aria-describedby` no elemento nativo. |
 | `metadata.ariaLabelledby` | `string` | Active | `aria-labelledby` no elemento nativo. |
 
+#### Ajuda contextual em migracoes corporativas
+
+`metadata.helpText` pertence ao DTO/schema quando descreve semantica de negocio, impacto operacional ou criterio de decisao do campo. Ele nao deve ser gerado a partir de label, nome tecnico ou heuristica local.
+
+Use `metadata.helpDisplay` para excecoes por campo:
+
+- `inline`: texto curto que deve permanecer visivel para evitar erro operacional;
+- `popover`: texto longo, raro ou de apoio decisorio;
+- `hidden`: ajuda publicada mas inadequada para a superficie atual;
+- `auto`: delega a politica do host e ao limite `helpInlineMaxLength`.
+
+Em formularios densos, o host deve preferir uma politica global como `FormConfig.helpPresentation.display = "auto"` e mover textos longos para a affordance de ajuda. Mensagens de validacao continuam no canal de erro do campo e nao devem ser convertidas em `helpText`.
+
 #### Politica de label com prefixos e sufixos
 
 Quando um campo usa `metadata.prefixIcon`, `metadata.suffixIcon`, `clearButton`,

package/src/lib/components/field-shell/praxis-field-shell.json-api.md

@@ -22,8 +22,9 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts"
   - "projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts"
   - "projects/praxis-core/src/lib/models/component-metadata.interface.ts"
-source_of_truth_last_verified: "2026-05-18"
-last_updated: "2026-05-18"
+  - "projects/praxis-core/src/lib/models/field-presentation.model.ts"
+source_of_truth_last_verified: "2026-06-25"
+last_updated: "2026-06-25"
 toc: true
 sidebar: true
 tags:
@@ -78,6 +79,7 @@ Este documento e a referencia canonica da API JSON de praxis-field-shell.
 | projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
 | projects/praxis-core/src/lib/models/component-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
+| projects/praxis-core/src/lib/models/field-presentation.model.ts | schema-types/runtime-helper | Resolve `presentation` e `presentationRules` para presentationMode sem mutar valores. |
 
 ## Support legend
 
@@ -157,6 +159,9 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `field.controlType` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `field.controlType='avatar'` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `field.transformDisplayValue` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `field.valuePresentation` | object | false | n/a | component-defined | Canonical value formatter for readonly/display surfaces. |
+| `field.presentation` | object | false | n/a | component-defined | Semantic readonly/display presentation state. |
+| `field.presentationRules` | array | false | n/a | component-defined | Ordered Json Logic rules that override semantic presentation state. |
 
 ### Input bindings (inbound data)
 
@@ -321,6 +326,8 @@ Resumo de composicao deste componente:
 ### 4. Mapeamento de Comportamento
 - Sempre cria o `insertionPoint` (`vc`) para o componente real do campo.
 - Em modo apresentacao sem excecao de tipo, esconde conteudo editavel e mostra bloco textual.
+- Em modo apresentacao, `field.valuePresentation` formata o valor e `field.presentation`/`field.presentationRules` ajustam presenter, tone, icon, label, badge, tooltip e appearance por semantica declarativa.
+- `presentationRules` sao avaliadas com Json Logic contra o contexto do campo. Regras invalidas falham fechadas e nao alteram o `FormControl`.
 - `readonlyMode` aplica overlay bloqueando interacao, mantendo controle habilitado.
 - `canvasMode` injeta semantica de evento para editores visuais.
 
@@ -346,7 +353,24 @@ Uso: shell padrao para um campo dinamico simples.
     "name": "approvalStatus",
     "label": "Aprovacao",
     "controlType": "select",
-    "readOnly": true
+    "readOnly": true,
+    "presentation": {
+      "presenter": "status",
+      "tone": "neutral",
+      "icon": "schedule",
+      "label": "Em analise"
+    },
+    "presentationRules": [
+      {
+        "when": { "===": [{ "var": "value" }, "BLOQUEADO"] },
+        "set": {
+          "tone": "danger",
+          "icon": "lock",
+          "label": "Bloqueado",
+          "appearance": "filled"
+        }
+      }
+    ]
   },
   "readonlyMode": false,
   "presentationMode": true,
@@ -374,6 +398,9 @@ Correcao: garantir `canvasMode=true`.
 5. Valor mostrado em apresentacao esta incorreto.
 Correcao: revisar `transformDisplayValue` e formato do valor no `control`.
 
+6. Regra de apresentacao nao muda o visual.
+Correcao: validar o Json Logic em `field.presentationRules[].when`; o contexto minimo expoe `value`, `rawValue`, `fieldName` e o nome do campo.
+
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts`
 - `projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts`
@@ -403,6 +430,9 @@ Correcao: revisar `transformDisplayValue` e formato do valor no `control`.
 | `field.controlType` | string | false | n/a | Partial | See Detailed API reference. |
 | `field.controlType='avatar'` | unknown | false | n/a | Partial | See Detailed API reference. |
 | `field.transformDisplayValue` | unknown | false | n/a | Partial | See Detailed API reference. |
+| `field.valuePresentation` | object | false | n/a | Active | Formats values in presentation mode. |
+| `field.presentation` | object | false | n/a | Active | Semantic state for presentation mode. |
+| `field.presentationRules` | array | false | n/a | Active | Json Logic conditional presentation state. |
 | `presentationMode` | boolean | false | n/a | Partial | See Detailed API reference. |
 | `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference. |
 | `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference. |

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

@@ -154,7 +154,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.touchUi` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.clearButton` | object | 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.inlineOverlay.applyMode` | string | false | `auto` | `auto`, `explicit`, `confirm` | Shared inline overlay commit mode; `confirm` is accepted as explicit compatibility. |
+| `metadata.inlineOverlay.applyMode` | string | false | `auto` | `auto`, `explicit` | Shared inline overlay commit mode. |
 | `metadata.inlineOverlay.actions.apply` | object | false | n/a | component-defined | Theme-aware Apply action metadata. |
 | `metadata.inlineOverlay.actions.cancel` | object | false | n/a | component-defined | Theme-aware Cancel action metadata. |
 | `metadata.ariaLabel` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |

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

@@ -366,6 +366,7 @@ 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.
+- 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`.
 - Opcao de reset limpa filtro sem fechar contexto de trabalho.
 - `OptionDTO.extra.selectable === false` desabilita a opcao e permite exibir `disabledReason` sem remover a entidade da lista ou da reidratacao.

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

@@ -301,6 +301,7 @@ Resumo de composicao deste componente:
 
 ### 4. Mapeamento de Comportamento
 - Modo percentual ajusta semantica visual e valores default de faixa/passo.
+- `metadata.inlineVisualStyle = "graphic"` materializa leitura percentual enriquecida, mas o componente suprime gauge/rail decorativos quando esta dentro de `praxis-filter` compacto para manter a barra densa e escaneavel.
 - Campo recalcula largura com base no conteudo/placeholder e limites configurados.
 - Validadores `min/max` sao aplicados no control conforme metadata.
 

package/src/lib/components/inline-relative-period/pdx-inline-relative-period.json-api.md

@@ -300,7 +300,7 @@ Use quando precisar:
 | `metadata.relativePeriodIconKey/optionIconKey` | `string` | Ativo | Chave do ícone por opção. |
 | `metadata.relativePeriodSubtitleKey/optionSubtitleKey` | `string` | Ativo | Chave de subtítulo por opção. |
 | `metadata.relativePeriodTexts` / `inlineTexts` | `object \| string(JSON)` | Ativo | Textos de labels, empty state e aria; templates canônicos devem usar `{{label}}` e `{{percent}}` quando houver interpolação, com compatibilidade legada para `{...}` em metadata. |
-| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit" \| "confirm"` | Ativo | Quando `explicit`/`confirm`, seleções ficam em rascunho até `Aplicar`. |
+| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Quando `explicit`, seleções ficam em rascunho até `Aplicar`. |
 | `metadata.inlineOverlay.actions.apply.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do commit. |
 | `metadata.inlineOverlay.actions.cancel.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do descarte. |
 | `metadata.inlineOverlay.actions.clear.*` | `object` | Ativo | Label, aria, icon, appearance, colorRole e visibilidade da limpeza explícita. |
@@ -319,7 +319,7 @@ Resumo de composição deste componente:
 - Em single mode, pode fechar automaticamente por `relativePeriodCloseOnSelect`.
 - Barra de progresso calcula posição da opção selecionada no conjunto.
 - Busca filtra opções por label/subtítulo antes da seleção.
-- Com `inlineOverlay.applyMode: "explicit"` ou `"confirm"`, clique em card altera apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc`, detach ou clique externo descartam.
+- Com `inlineOverlay.applyMode: "explicit"`, clique em card altera apenas o rascunho do painel; `Aplicar` comita, enquanto `Cancelar`, `Esc`, detach ou clique externo descartam.
 
 ### 5. Exemplo Mínimo (JSON + Uso)
 ```json

package/src/lib/components/inline-time-range/pdx-inline-time-range.json-api.md

@@ -299,7 +299,7 @@ Use quando precisar:
 | `metadata.validators.rangeMessage` | `string` | Ativo | Mensagem para erro de ordem do intervalo. |
 | `metadata.validators.minDistanceMessage` | `string` | Ativo | Mensagem para distancia minima. |
 | `metadata.validators.maxDistanceMessage` | `string` | Ativo | Mensagem para distancia maxima. |
-| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit" \| "confirm"` | Ativo | Quando `explicit`/`confirm`, slider, inputs e presets ficam em rascunho ate `Aplicar`. |
+| `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Quando `explicit`, slider, inputs e presets ficam em rascunho ate `Aplicar`. |
 | `metadata.inlineOverlay.actions.apply.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do commit. |
 | `metadata.inlineOverlay.actions.cancel.*` | `object` | Ativo | Label, aria, icon, appearance e colorRole do descarte. |
 | `metadata.inlineOverlay.actions.clear.*` | `object` | Ativo | Label, aria, icon, appearance, colorRole e visibilidade da limpeza explicita. |
@@ -318,7 +318,7 @@ Resumo de composicao deste componente:
 - `quickPresets` podem ser declarados ou gerados por defaults internos.
 - Slider e inputs textuais permanecem sincronizados (`timeRangeForm` + `sliderRangeForm`).
 - `timeInputStepSeconds()` deriva de `stepMinute` para entrada `type=time`.
-- Com `inlineOverlay.applyMode: "explicit"` ou `"confirm"`, alteracoes no painel nao emitem valor externo ate `Aplicar`; `Cancelar`, `Esc`, detach ou clique externo restauram o valor confirmado anterior.
+- Com `inlineOverlay.applyMode: "explicit"`, alteracoes no painel nao emitem valor externo ate `Aplicar`; `Cancelar`, `Esc`, detach ou clique externo restauram o valor confirmado anterior.
 
 ### 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-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-07-06"
+last_updated: "2026-07-06"
 toc: true
 sidebar: true
 tags:
@@ -319,6 +319,10 @@ Garantias:
 - input de busca e carga incremental estao habilitados no painel.
 - `loadOn` controla a primeira carga (`open`, `init`, `none`).
 - `useCursor` pode trocar estrategia de pagina quando backend suporta cursor.
+- Com `resourcePath` e `loadOn='open'`, o painel abre mesmo antes da primeira pagina remota para disparar a carga inicial; a opcao sentinela usada para isso e interna, invisivel e nao compoe contrato visual publico.
+- `Carregar mais` so aparece depois de uma primeira pagina remota carregada com sucesso e com proxima pagina disponivel.
+- 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:
 
@@ -351,6 +355,7 @@ Precedencia de comportamento:
 #### Checklist corporativo
 
 - alinhe backend para pesquisa por termo e include de selecionados.
+- retorne `totalPages` e `totalElements` consistentes para evitar chamadas extras de paginacao.
 - padronize `optionLabelKey`/`optionValueKey` entre dominios.
 - defina `dependencyLoadOnChange` conforme UX esperada em cascata.
 - use `maxSelections` quando multi-select exigir limite de negocio.
@@ -393,8 +398,12 @@ Precedencia de comportamento:
 
 Notas de runtime:
 
-- em remoto, `loadOptions` usa filtro com include de selecionados na pagina 0.
+- em remoto generico, `loadOptions` pode usar `includeIds` na pagina 0.
+- em `optionSource`, o filtro envia `includeIds` somente quando `optionSource.includeIds=true`; quando ausente ou `false`, valores selecionados sao reidratados por `/option-sources/{sourceKey}/options/by-ids`.
+- em `optionSource`, dependencias declaradas por `dependsOn` e `dependencyFilterMap` sao materializadas como filtros estruturados `equals` no envelope canonico de opcoes.
 - `onSearch` limpa estado local e reinicia pagina para novo termo.
+- `loadMore` nao inicia a primeira carga remota; a primeira pagina respeita `loadOn`, abertura do painel, reload explicito ou mudanca de dependencia.
+- `loadMore` incrementa pagina somente quando ja existe pagina remota carregada e `endReached=false`.
 
 Contrato compartilhado completo:
 
@@ -417,7 +426,7 @@ Correcao: revise `loadOn`, `resourcePath` e permissao de endpoint.
 Correcao: alinhe `optionLabelKey` e `optionValueKey` ao payload real.
 
 4. Item selecionado some apos nova busca.
-Correcao: backend deve suportar include de ids selecionados na pagina inicial.
+Correcao: para `optionSource.includeIds=false`, backend deve suportar reidratacao por `/by-ids`; para remoto generico ou `optionSource.includeIds=true`, pode suportar include de ids selecionados na pagina inicial.
 
 5. Cascata nao atualiza automaticamente.
 Correcao: use `dependencyLoadOnChange='immediate'` ou dispare recarga no host.

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

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.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-04-27"
-last_updated: "2026-04-27"
+source_of_truth_last_verified: "2026-06-25"
+last_updated: "2026-06-25"
 toc: true
 sidebar: true
 tags:
@@ -133,6 +133,7 @@ Este documento e a referencia canonica da API JSON de pdx-material-checkbox-grou
 | --- | --- | --- | --- | --- |
 | `metadata.options` | `metadata.checkboxOptions` | not-yet-defined | accepted for backward compatibility | Alias legado para opcoes do grupo. |
 | ausencia de `metadata.selectionMode` | `metadata.selectionMode` explicito | not-yet-defined | runtime infere `boolean` sem opcoes e `multiple` com opcoes | Fallback legado preservado para migracao. |
+| valores booleanos legados `S`/`N`, `1`/`0`, `true`/`false` no `FormControl` | `boolean` real | not-yet-defined | em `selectionMode: 'boolean'`, o runtime normaliza antes de renderizar e emitir eventos | Compatibilidade para telas migradas que recebem flags legadas do backend. |
 
 ### Internal-only paths
 
@@ -197,6 +198,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 ### Runtime semantics addendum
 
 - `selectionMode` explicito governa a semantica interna de selecao; heuristica por presenca de opcoes so vale quando `selectionMode` nao e informado.
+- Em `selectionMode: 'boolean'`, o valor de entrada aceita `boolean` real e flags legadas textuais/numéricas (`S`/`N`, `T`/`F`, `1`/`0`, `true`/`false`, `sim`/`não`) e normaliza para `boolean` antes da interação.
 - `required`/`requiredChecked` propagam sinalizacao acessivel (`aria-required`) para o checkbox renderizado.
 - No modo boolean, cliques no shell de conteudo tambem emitem `selectionChange` e `optionSelected` para alinhamento operacional com o runtime base de selecao.
 - Estados governados (`disabledMode`, `readonlyMode`, `presentationMode`, `metadata.readonly` e `FormControl.disabled`) bloqueiam mutacoes em modo boolean, option e select-all.
@@ -224,7 +226,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 
 | Surface | Verified | Coverage status | Evidence | Notes |
 | --- | --- | --- | --- | --- |
-| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.ts` | Core runtime flows and governed states verified via focused component specs on 2026-04-27; editor/tooling coverage remains independent. |
+| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.ts` | Core runtime flows, governed states and legacy boolean value normalization verified via focused component specs on 2026-06-25; editor/tooling coverage remains independent. |
 | Schema/Types | `true` | Active | source_of_truth + Detailed API reference | Reconcile schema/types with canonical paths during follow-up when needed. |
 | Editor/Tooling | `false` | Partial | `projects/praxis-core/src/lib/metadata/field-selector-control-type.constants.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Selector/control-type tooling linkage verified via default selector map and registry seeding; visual editor end-to-end coverage remains not-yet-verified. |
 

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

@@ -21,8 +21,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.metadata.ts"
   - "projects/praxis-dynamic-fields/src/lib/components/material-file-upload/material-file-upload.component.ts"
   - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-06-24"
+last_updated: "2026-06-24"
 toc: true
 sidebar: true
 tags:
@@ -149,10 +149,14 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `metadata.hint` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.placeholder` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
 | `metadata.validators.*` | object | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.accept` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.multiple` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
-| `metadata.maxFileSize` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.accept` | string | false | n/a | comma-separated extensions or MIME patterns | Active; applied to native input and local file validation. |
+| `metadata.multiple` | boolean | false | `false` | boolean | Active; selected value is `File[]` when true and `File | null` otherwise. |
+| `metadata.maxFileSize` | number | false | n/a | positive byte count | Active; rejects selected files above the configured limit. |
+| `metadata.maxFiles` | number | false | n/a | positive integer | Active; rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | component-defined | Partial; verify per source_of_truth. |
+| `metadata.imagePreview` | boolean | false | `false` | boolean | Active; renders local image preview for selected image files. |
+| `metadata.preview` | string | false | n/a | `image` | Active; `image` is an alias for local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | component-defined | Active; accessible alt text for the local preview image. |
 
 ### Input bindings (inbound data)
 
@@ -268,12 +272,13 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
 ### Preserved technical reference (normalized from previous revision)
 
 ### 1. Visao Geral e Quando Usar
-`pdx-material-file-upload` e um upload basico (placeholder funcional) com `<input type="file">` simples e integracao CVA.
+`pdx-material-file-upload` e um upload basico de campo com `<input type="file">`, integracao CVA, validacao local de tipo/tamanho e preview local de imagem.
 
 Use quando precisar:
 - prototipar upload rapido no form;
-- capturar um unico arquivo selecionado;
-- evoluir depois para fluxo corporativo completo (preview/chunk/validacoes avancadas).
+- capturar um arquivo selecionado ou uma lista curta de arquivos;
+- mostrar preview local para fluxos de foto/avatar antes da persistencia;
+- delegar persistencia, presign, progresso, conflito e storage governado para a camada canonica de upload.
 
 ### 2. API do Componente (Inputs/Outputs)
 | Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
@@ -283,7 +288,7 @@ Use quando precisar:
 | `disabledMode` | `boolean` | `false` | Nao | Sobrescreve disabled no host. |
 | `visible` | `boolean` | `true` | Nao | Controla exibicao no host. |
 | `presentationMode` | `boolean` | `false` | Nao | Modo apresentacao sem edicao. |
-| `valueChange` | `File \| null` | - | Output base input | Arquivo selecionado no input. |
+| `valueChange` | `File \| File[] \| null` | - | Output base input | Arquivo selecionado no input; quando `multiple=true`, emite array. |
 
 ### 3. Matriz de Cobertura JSON (Completa)
 #### 3.1 Campos especificos do componente
@@ -294,25 +299,29 @@ Use quando precisar:
 | `metadata.hint` | `string` | Ativo | Mensagem de apoio quando sem erro. |
 | `metadata.placeholder` | `string` | Parcial | `setFileUploadMetadata` remove placeholder do estado efetivo. |
 | `metadata.validators.*` | `object` | Parcial | Validacoes basicas do `SimpleBaseInput` podem atuar no control, sem parser de arquivo dedicado. |
-| `metadata.accept` | `string` | Declared-only | Nao aplicado ao atributo `accept` no input atual. |
-| `metadata.multiple` | `boolean` | Declared-only | Input atual usa apenas o primeiro arquivo selecionado. |
-| `metadata.maxFileSize` | `number` | Declared-only | Nao ha validacao de tamanho especifica no componente. |
+| `metadata.accept` | `string` | Ativo | Aplicado ao atributo `accept` e validado localmente por extensao/MIME antes de atualizar o control. |
+| `metadata.multiple` | `boolean` | Ativo | Permite selecionar varios arquivos e atualiza o valor como `File[]`. |
+| `metadata.maxFileSize` | `number` | Ativo | Rejeita arquivos acima do limite em bytes antes de atualizar o control. |
+| `metadata.maxFiles` | `number` | Ativo | Rejeita selecoes acima da quantidade maxima configurada. |
 | `metadata.allowedTypes` | `string[]` | Declared-only | Nao ha filtro dedicado por tipo no componente atual. |
+| `metadata.imagePreview` | `boolean` | Ativo | Mostra preview local para o primeiro arquivo de imagem selecionado. |
+| `metadata.preview` | `'image'` | Ativo | Alias declarativo para habilitar preview local de imagem. |
+| `metadata.previewAlt` | `string` | Ativo | Texto alternativo do preview local. |
 
 #### 3.2 Campos herdados compartilhados (exaustivo)
 Contrato compartilhado de input base:
 - [pdx-base-input-runtime-contract.json-api.md](projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md)
 
 Resumo de composicao deste componente:
-- `Ativo`: fluxo basico de selecao de um arquivo e bind no control.
+- `Ativo`: fluxo basico de selecao, bind no control, preview local de imagem e validacao local de tipo/tamanho/quantidade.
 - `Parcial`: placeholder e validacoes genericas do base.
-- `Declared-only`: capacidade avancada de upload ainda nao implementada.
+- `Declared-only`: politica avancada por `allowedTypes`.
 
 ### 4. Mapeamento de Comportamento
-- Selecao: ao `change`, pega `files[0]` e grava no control.
-- Valor: tipo `File | null`.
-- Renderizacao: label + input file + erro/hint.
-- Estado corporativo: componente se declara "placeholder" no proprio codigo.
+- Selecao: ao `change`, valida arquivos e grava `File` ou `File[]` no control.
+- Valor: `File | null` quando `multiple` esta ausente/falso; `File[]` quando `multiple=true`.
+- Renderizacao: label, input file, resumo da selecao, preview local de imagem, erro/hint e acao de limpar.
+- Persistencia corporativa: fora deste componente. Use `@praxisui/files-upload` para presign, progresso, conflito, retry e storage governado.
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json
@@ -345,12 +354,30 @@ Uso: captura um arquivo unico para envio posterior.
 ```
 Uso: etapa inicial de upload, deixando validacoes profundas para API backend.
 
+### 6.1 Exemplo para troca de avatar (JSON + Uso)
+```json
+{
+  "componentId": "pdx-material-file-upload",
+  "metadata": {
+    "name": "profileImageFile",
+    "label": "Foto de perfil",
+    "controlType": "upload",
+    "accept": "image/*",
+    "maxFileSize": 4194304,
+    "maxFiles": 1,
+    "imagePreview": true,
+    "hint": "Escolha uma imagem para revisar antes de salvar a foto do perfil."
+  }
+}
+```
+Uso: combine este campo com `pdx-material-avatar` para preview/display e com a capability canonica de persistencia de arquivo para publicar a URL final consumida pelo avatar.
+
 ### 7. Troubleshooting e Armadilhas Comuns
-1. Esperar upload multiplo.
-Correcao: componente atual captura somente o primeiro arquivo.
+1. Esperar persistencia automatica.
+Correcao: este componente escolhe e valida localmente; persistencia pertence ao host ou a `@praxisui/files-upload`.
 
-2. Esperar filtro automatico por tipo/tamanho.
-Correcao: nao ha `accept`/validacao dedicada implementada nesta versao.
+2. Esperar crop/zoom.
+Correcao: preview local nao e editor de imagem. Crop deve nascer em contrato proprio de avatar/image authoring.
 
 3. Placeholder nao aparece.
 Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
@@ -358,8 +385,8 @@ Correcao: `setFileUploadMetadata` remove placeholder explicitamente.
 4. Arquivo nao persiste no payload final.
 Correcao: verificar serializacao de `File` no host e estrategia de envio multipart.
 
-5. Necessidade de preview/progresso/chunk.
-Correcao: esse renderer e baseline; implementar camada avancada para cenarios enterprise.
+5. Necessidade de progresso/chunk/presign.
+Correcao: usar `@praxisui/files-upload`, que e a fronteira canonica de upload operacional.
 
 ### 8. Cross-links
 - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md`
@@ -388,10 +415,14 @@ Correcao: esse renderer e baseline; implementar camada avancada para cenarios en
 | `metadata.hint` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.placeholder` | string | false | n/a | Partial | See Detailed API reference. |
 | `metadata.validators.*` | object | false | n/a | Partial | See Detailed API reference. |
-| `metadata.accept` | string | false | n/a | Partial | See Detailed API reference. |
-| `metadata.multiple` | boolean | false | n/a | Partial | See Detailed API reference. |
-| `metadata.maxFileSize` | number | false | n/a | Partial | See Detailed API reference. |
+| `metadata.accept` | string | false | n/a | Active | Applied to native input and local type validation. |
+| `metadata.multiple` | boolean | false | `false` | Active | Emits `File[]` when true. |
+| `metadata.maxFileSize` | number | false | n/a | Active | Rejects files above the byte limit. |
+| `metadata.maxFiles` | number | false | n/a | Active | Rejects selections above the configured number of files. |
 | `metadata.allowedTypes` | string[] | false | n/a | Partial | See Detailed API reference. |
+| `metadata.imagePreview` | boolean | false | `false` | Active | Enables local image preview. |
+| `metadata.preview` | string | false | n/a | Active | `image` enables local image preview. |
+| `metadata.previewAlt` | string | false | localized fallback | Active | Accessible alt text for preview image. |
 
 ## Events reference (obrigatorio)
 

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

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/components/material-searchable-select/material-searchable-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-04-27"
-last_updated: "2026-04-27"
+source_of_truth_last_verified: "2026-07-06"
+last_updated: "2026-07-06"
 toc: true
 sidebar: true
 tags:
@@ -347,6 +347,9 @@ Precedencia de comportamento:
 2. `options` atua como alias legado quando `selectOptions` nao e enviado.
 3. `optionSource` ativa consulta remota pelo endpoint canonico `/option-sources/{key}/options/filter`.
 4. `resourcePath` ativa consulta remota paginada legada com termo de busca.
+5. Com `resourcePath` e `loadOn='open'`, o painel abre mesmo antes da primeira pagina remota para disparar a carga inicial; a opcao sentinela usada para isso e interna, invisivel e nao compoe contrato visual publico.
+6. `Carregar mais` so aparece depois de uma primeira pagina remota carregada com sucesso e com proxima pagina disponivel.
+7. fontes locais (`selectOptions`/`options`) e `loadOn='none'` antes da primeira carga nao exibem acao de paginacao.
 
 #### Status model
 
@@ -357,6 +360,7 @@ Precedencia de comportamento:
 #### Checklist corporativo
 
 - alinhe backend para pesquisa por termo e include de selecionados.
+- retorne `totalPages` e `totalElements` consistentes para evitar chamadas extras de paginacao.
 - para lookups metadata-driven, publique `optionSource.dependsOn` e `optionSource.dependencyFilterMap` no schema canonico.
 - padronize `optionLabelKey`/`optionValueKey` entre dominios.
 - defina `dependencyLoadOnChange` conforme UX esperada em cascata.
@@ -393,7 +397,7 @@ Precedencia de comportamento:
 | `metadata.resourcePath` | `string` | Active | Ativa carga remota de opcoes. |
 | `metadata.optionSource` | `OptionSourceMetadata` | Active | Ativa endpoint canonico de option-source e busca pelo parametro `search`. |
 | `metadata.optionSource.dependsOn` | `string[]` | Active | Fonte canonica backend/editor para cascata; o mapper deriva `dependencyFields`. |
-| `metadata.optionSource.dependencyFilterMap` | `Record<string, string>` | Active | Mapeia campo dependente para chave de filtro enviada ao backend. |
+| `metadata.optionSource.dependencyFilterMap` | `Record<string, string>` | Active | Mapeia campo dependente para chave de filtro estruturado enviada ao backend. |
 | `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. |
@@ -406,6 +410,9 @@ Notas de runtime:
 - em remoto, `loadOptions` usa filtro com include de selecionados na pagina 0.
 - com `optionSource`, `loadOptions` chama `filterOptionSourceOptions` e envia termo de busca como `search`, nao como campo de filtro textual.
 - `onSearch` limpa estado local e reinicia pagina para novo termo.
+- `loadNextPage` nao inicia a primeira carga remota; a primeira pagina respeita `loadOn`, abertura do painel, reload explicito ou mudanca de dependencia.
+- `loadNextPage` incrementa pagina somente quando ja existe pagina remota carregada e `endReached=false`.
+- em paginacao numerada, `endReached` usa `totalPages`/`totalElements` quando fornecidos pelo backend; se ausentes, usa `content.length < pageSize` como fallback.
 - estados governados bloqueiam busca, abertura, selecao, reload, clear e `loadNextPage`.
 
 Contrato compartilhado completo:

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

@@ -336,7 +336,7 @@ Resumo de composicao deste componente:
 - Ordenacao: nao se aplica.
 - Selecao: texto multiline livre (respeitando regras de validacao).
 - Eventos: usa outputs herdados e processa eventos locais de teclado/paste/cut para UX avancada.
-- Renderizacao: `mat-form-field` + `<textarea matInput>` com autosize opcional, clear button opcional e hints de suporte.
+- Renderizacao: `mat-form-field` + `<textarea matInput>` com autosize opcional, clear button opcional e ajuda de campo pelo contrato herdado (`helpDisplay='inline'|'popover'|'hidden'|'auto'`).
 
 ### 5. Exemplo Minimo (JSON + Uso)
 ```json