@praxisui/dynamic-fields 9.0.0-beta.8 → 9.0.0-beta.80

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