@praxisui/dynamic-fields 8.0.0-beta.9 → 8.0.0-beta.90

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "8.0.0-beta.9",
+  "version": "8.0.0-beta.90",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
-    "@angular/common": "^20.1.0",
-    "@angular/core": "^20.1.0",
-    "@angular/forms": "^20.1.0",
-    "@angular/material": "^20.1.0",
-    "@angular/cdk": "^20.1.0",
-    "@angular/router": "^20.1.0",
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/forms": "^21.0.0",
+    "@angular/material": "^21.0.0",
+    "@angular/cdk": "^21.0.0",
+    "@angular/platform-browser": "^21.0.0",
+    "@angular/router": "^21.0.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^8.0.0-beta.9",
-    "@praxisui/cron-builder": "^8.0.0-beta.9",
-    "@praxisui/dialog": "^8.0.0-beta.9"
+    "@praxisui/core": "^8.0.0-beta.90",
+    "@praxisui/cron-builder": "^8.0.0-beta.90"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",
@@ -41,14 +41,15 @@
   ],
   "sideEffects": false,
   "module": "fesm2022/praxisui-dynamic-fields.mjs",
-  "typings": "index.d.ts",
+  "typings": "types/praxisui-dynamic-fields.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/praxisui-dynamic-fields.d.ts",
       "default": "./fesm2022/praxisui-dynamic-fields.mjs"
     }
-  }
+  },
+  "type": "module"
 }

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

@@ -0,0 +1,526 @@
+---
+title: "pdx-base-input-runtime-contract JSON API (Canonical)"
+slug: "pdx-base-input-runtime-contract-json-api"
+doc_type: "api-reference"
+component: "pdx-base-input-runtime-contract"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do componente pdx-base-input-runtime-contract."
+category: "components"
+sub_category: "runtime-contract"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+source_of_truth:
+  - "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
+  - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
+source_of_truth_last_verified: "2026-03-05"
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "pdx-base-input-runtime-contract"
+api_stability: "canonical"
+schema_verified: true
+runtime_verified: false
+editor_coverage_verified: false
+runtime_scope: "public"
+legacy_paths_present: true
+has_known_mismatches: true
+related_components:
+  - "praxis-table"
+  - "pdx-text-input"
+  - "pdx-number-input"
+  - "pdx-date-input"
+  - "pdx-material-select"
+---
+
+# pdx-base-input-runtime-contract
+
+Este documento e a referencia canonica da API JSON de pdx-base-input-runtime-contract.
+
+## Summary
+
+- Tipo documental: API reference canonica de contrato JSON.
+- Source of truth: runtime e codigo declarados no frontmatter.
+- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
+- Resumo funcional herdado: `SimpleBaseInputComponent` e o contrato runtime compartilhado dos inputs da lib. Voce configura UX, validacao e acessibilidade em JSON (`metadata`) e cada input especifico herda esse comportamento. Nao e um detalhe interno de implementacao: e a base de compatibilidade entre `pdx-*-input`.
+
+## Scope and positioning
+
+- Escopo: contrato JSON publico e limites de comportamento observavel.
+- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
+- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.
+
+## Source of truth
+
+| Source | Kind | Notes |
+| --- | --- | --- |
+| projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | runtime-code | Source de implementacao declarado no repositorio. |
+
+## Support legend
+
+- Active: suportado e observado no runtime atual.
+- Partial: suporte parcial, com restricoes conhecidas.
+- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
+- Schema-only: presente em schema/modelo sem confirmacao de execucao.
+- Deprecated: mantido por compatibilidade legada com migracao prevista.
+
+## Contract classification
+
+### Canonical paths (public contract)
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `metadata` | `ComponentMetadata` | not-specified | n/a | Active | Payload principal do componente. |
+| `metadata.name` | `string` | not-specified | n/a | Active | Aplica `name` no input nativo. |
+| `metadata.id` | `string` | not-specified | n/a | Active | Aplica `id` no elemento nativo. |
+| `metadata.label` | `string` | not-specified | n/a | Active | Mapeado para label visivel do campo. |
+| `metadata.placeholder` | `string` | not-specified | n/a | Active | Mapeado para placeholder quando diferente do label. |
+| `metadata.required` | `boolean` | not-specified | n/a | Active | `Validators.required` + `aria-required`. |
+| `metadata.disabled` | `boolean` | not-specified | n/a | Active | Atualiza estado disabled do controle. |
+| `metadata.readonly` | `boolean` | not-specified | n/a | Active | Aplica atributo `readonly` nativo. |
+| `metadata.readOnly` | `boolean` | not-specified | n/a | Partial | Compat legado (dependente de uso no metadata final). |
+| `metadata.autocomplete` | `string` | not-specified | n/a | Active | Aplica atributo `autocomplete`. |
+| `metadata.inputMode` | `string` | not-specified | n/a | Active | Aplica atributo `inputmode`. |
+| `metadata.spellcheck` | `boolean` | not-specified | n/a | Active | Aplica atributo `spellcheck`. |
+| `metadata.tabIndex` | `number` | not-specified | n/a | Active | Aplica `tabIndex` no elemento nativo. |
+| `metadata.minLength` | `number` | not-specified | n/a | Active | `Validators.minLength` + atributo nativo. |
+
+### Supported legacy paths
+
+| Legacy path | Canonical replacement | Support window | Runtime behavior | Notes |
+| --- | --- | --- | --- | --- |
+| extracted-from-detailed-api | see canonical paths | not-yet-verified | accepted for backward compatibility | Alias/legado identificado no conteúdo preservado. |
+
+### Internal-only paths
+
+| Path | Internal consumer | Runtime presence | Public support | Notes |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | not-yet-verified | No | Caminhos internos nao mapeados explicitamente nesta revisao automatizada. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | Experimental | not-yet-verified | Registrar somente quando houver evidencia em runtime/codigo. |
+
+## Overview
+
+Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.
+
+## Public contract surface
+
+### Top-level configuration blocks
+
+| Block | Purpose | Required | Merge strategy | Notes |
+| --- | --- | --- | --- | --- |
+| metadata | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 14 path(s) mapeado(s), status predominante Active. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `metadata` | `ComponentMetadata` | not-specified | n/a | component-defined | Payload principal do componente. |
+| `metadata.name` | `string` | not-specified | n/a | component-defined | Aplica `name` no input nativo. |
+| `metadata.id` | `string` | not-specified | n/a | component-defined | Aplica `id` no elemento nativo. |
+| `metadata.label` | `string` | not-specified | n/a | component-defined | Mapeado para label visivel do campo. |
+| `metadata.placeholder` | `string` | not-specified | n/a | component-defined | Mapeado para placeholder quando diferente do label. |
+| `metadata.required` | `boolean` | not-specified | n/a | component-defined | `Validators.required` + `aria-required`. |
+| `metadata.disabled` | `boolean` | not-specified | n/a | component-defined | Atualiza estado disabled do controle. |
+| `metadata.readonly` | `boolean` | not-specified | n/a | component-defined | Aplica atributo `readonly` nativo. |
+| `metadata.readOnly` | `boolean` | not-specified | n/a | component-defined | Compat legado (dependente de uso no metadata final). |
+| `metadata.autocomplete` | `string` | not-specified | n/a | component-defined | Aplica atributo `autocomplete`. |
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| component-inputs | see-detailed-api | not-yet-verified | runtime-and-code | not-yet-verified | Inputs preservados na referência detalhada. |
+
+### Output events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `valueChange` | `any` | Mudanca de valor propagada pelo componente. | Partial | Preservado da documentação anterior. |
+| `focusChange` | `boolean` | Foco/blur do elemento nativo. | Partial | Preservado da documentação anterior. |
+| `nativeBlur` | `FocusEvent` | Evento blur nativo. | Partial | Preservado da documentação anterior. |
+| `nativeChange` | `Event` | Evento change nativo. | Partial | Preservado da documentação anterior. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| host/services/storage | bidirectional | see-detailed-api | not-yet-verified | Side channels dependem do componente e do host consumidor. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| see-source-of-truth | true | browser/dev/prod/ssr | runtime linkage | Confirmar por componente quando necessario. |
+
+## Coverage matrix
+
+| Surface | Verified | Coverage status | Evidence | Notes |
+| --- | --- | --- | --- | --- |
+| Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
+| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
+| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |
+
+## Runtime coverage boundaries
+
+- Cobertura consolidada com base em documentacao existente e source of truth declarado.
+- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
+- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.
+
+## Resolution model
+
+### Merge order
+
+1. defaults do componente
+2. contrato JSON recebido
+3. overrides de host/runtime
+4. normalizacoes internas
+
+### Fallback order
+
+contrato explicito -> aliases legados (quando suportados) -> defaults internos -> comportamento seguro
+
+### Override points
+
+- inputs publicos do componente
+- configuracao JSON de runtime
+- integracoes de host (servicos/tokens/adapters)
+
+### Runtime normalization
+
+Campos e aliases preservados do documento anterior devem convergir progressivamente para paths canonicos declarados.
+
+### Precedence rules
+
+Quando houver conflito entre alias e path canonico, priorizar path canonico e manter alias apenas para backward compatibility.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| see-detailed-api | runtime | warn-or-reject | not-yet-standardized | Semantica de validacao preservada do documento anterior. |
+
+### Error semantics
+
+Erros devem ser classificados em warnings recuperaveis versus falhas bloqueantes. Quando a evidencia nao estiver explicita, tratar como not yet verified.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| invalid-or-unknown-field | component-defined | not-yet-verified | Variavel por componente; requer verificacao em runtime. |
+
+### Invalid or unknown field handling
+
+- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
+- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
+- Registrar divergencias observadas em Known limitations and mismatches.
+
+### Runtime warnings vs hard failures
+
+| Condition | Severity | Observability | Consumer action |
+| --- | --- | --- | --- |
+| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |
+
+## Detailed API
+
+### Preserved technical reference (normalized from previous revision)
+
+`SimpleBaseInputComponent` e o contrato runtime compartilhado dos inputs da lib. Voce configura UX, validacao e acessibilidade em JSON (`metadata`) e cada input especifico herda esse comportamento. Nao e um detalhe interno de implementacao: e a base de compatibilidade entre `pdx-*-input`.
+
+### Prova em 20 segundos
+
+```json
+{
+  "metadata": {
+    "name": "email",
+    "label": "E-mail",
+    "required": true,
+    "validators": {
+      "validationTrigger": "blur",
+      "requiredMessage": "Campo obrigatorio"
+    },
+    "materialDesign": { "appearance": "outline" }
+  }
+}
+```
+
+- O runtime aplica validacao e estado visual sem logica duplicada por componente.
+- O mesmo contrato funciona para multiplos `pdx-*-input`.
+- A regra fica versionavel e auditavel por JSON.
+
+### Table of contents
+
+- [Start here](#start-here)
+  - [Promessa e limites](#promessa-e-limites)
+  - [Status model](#status-model)
+  - [Checklist corporativo](#checklist-corporativo)
+- [Contrato tecnico completo](#contrato-tecnico-completo)
+  - [Matriz completa de cobertura (herdada)](#matriz-completa-de-cobertura-herdada)
+  - [Saidas runtime compartilhadas](#saidas-runtime-compartilhadas)
+  - [Regras corporativas recomendadas](#regras-corporativas-recomendadas)
+  - [Cross-links](#cross-links)
+- [Referencias oficiais Angular](#referencias-oficiais-angular)
+
+### Start here
+
+#### Promessa e limites
+
+**O que isso habilita:** consistencia de input metadata-driven em validacao, material tokens e acessibilidade.
+
+**Quando usar:** sempre que o componente filho extender `SimpleBaseInputComponent`.
+
+**Exemplo minimo:** `metadata.required` + `metadata.validators.validationTrigger`.
+
+Garantias:
+
+- campos `metadata.*` ativos sao consumidos diretamente no runtime base.
+- mensagens de validacao e estrategia de erro seguem contrato unico.
+- atributos ARIA e propriedades nativas sao aplicados no elemento de input.
+
+Limites:
+
+- campos `Declared-only` podem existir no contrato sem efeito direto no runtime base.
+- validacao de dominio continua sendo responsabilidade do backend.
+
+#### Status model
+
+- `Status: Active` - consumido diretamente no runtime.
+- `Status: Partial` - consumido com restricoes.
+- `Status: Declared-only` - declarado em tipagem, sem consumo direto no runtime base.
+- `Status: Runtime-extension` - chave aceita por extensoes de componentes filhos.
+
+#### Checklist corporativo
+
+- alinhar `required` com regra de negocio para evitar bloqueio indevido de submit.
+- padronizar `materialDesign.*` por design system.
+- usar `ariaLabel/ariaDescribedby/ariaLabelledby` em campos criticos de jornada.
+- manter mensagens `validators.*Message` consistentes com tom de produto.
+
+### Contrato tecnico completo
+
+#### Matriz completa de cobertura (herdada)
+
+| Caminho JSON | Tipo | Status | Comportamento em runtime |
+| --- | --- | --- | --- |
+| `metadata` | `ComponentMetadata` | Active | Payload principal do componente. |
+| `metadata.name` | `string` | Active | Aplica `name` no input nativo. |
+| `metadata.id` | `string` | Active | Aplica `id` no elemento nativo. |
+| `metadata.label` | `string` | Active | Mapeado para label visivel do campo. |
+| `metadata.placeholder` | `string` | Active | Mapeado para placeholder quando diferente do label. |
+| `metadata.required` | `boolean` | Active | `Validators.required` + `aria-required`. |
+| `metadata.disabled` | `boolean` | Active | Atualiza estado disabled do controle. |
+| `metadata.readonly` | `boolean` | Active | Aplica atributo `readonly` nativo. |
+| `metadata.readOnly` | `boolean` | Partial | Compat legado (dependente de uso no metadata final). |
+| `metadata.autocomplete` | `string` | Active | Aplica atributo `autocomplete`. |
+| `metadata.inputMode` | `string` | Active | Aplica atributo `inputmode`. |
+| `metadata.spellcheck` | `boolean` | Active | Aplica atributo `spellcheck`. |
+| `metadata.tabIndex` | `number` | Active | Aplica `tabIndex` no elemento nativo. |
+| `metadata.minLength` | `number` | Active | `Validators.minLength` + atributo nativo. |
+| `metadata.maxLength` | `number` | Active | `Validators.maxLength` + atributo nativo. |
+| `metadata.pattern` | `string \| RegExp` | Active | `Validators.pattern` no controle. |
+| `metadata.validators.customValidator` | `function` | Active | Executa validador customizado e retorna erro `custom`. |
+| `metadata.validators.validationTrigger` | `'change' \| 'blur' \| 'submit' \| 'immediate'` | Active | Controla estrategia de exibicao/atualizacao de validacao. |
+| `metadata.validators.validationDebounce` | `number` | Active | Debounce da exibicao de erros em `change`. |
+| `metadata.validators.requiredMessage` | `string` | Active | Mensagem customizada para erro `required`. |
+| `metadata.validators.minLengthMessage` | `string` | Active | Mensagem customizada para erro `minlength`. |
+| `metadata.validators.maxLengthMessage` | `string` | Active | Mensagem customizada para erro `maxlength`. |
+| `metadata.validators.patternMessage` | `string` | Active | Mensagem customizada para erro `pattern`. |
+| `metadata.validators.minMessage` | `string` | Active | Mensagem customizada para erro `min`. |
+| `metadata.validators.maxMessage` | `string` | Active | Mensagem customizada para erro `max`. |
+| `metadata.validators.errorPosition` | `'tooltip' \| 'inline' \| 'both'` | Active | Estrategia de exibicao de erro (tooltip/inline). |
+| `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.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`. |
+| `metadata.materialDesign.floatLabel` | `'auto' \| 'always'` | Active | Comportamento do label flutuante. |
+| `metadata.materialDesign.subscriptSizing` | `'fixed' \| 'dynamic'` | Active | Tamanho do subscript do `mat-form-field`. |
+| `metadata.materialDesign.hideRequiredMarker` | `boolean` | Active | Oculta marcador de obrigatorio. |
+| `metadata.prefixIcon` | `string` | Active | Icone prefixo renderizado no campo. |
+| `metadata.prefixIconColor` | `string` | Active | Cor do icone prefixo. |
+| `metadata.suffixIcon` | `string` | Active | Icone sufixo renderizado no campo. |
+| `metadata.suffixIconColor` | `string` | Active | Cor do icone sufixo. |
+| `metadata.suffixIconTooltip` | `string` | Active | Tooltip do icone sufixo. |
+| `metadata.suffixIconAriaLabel` | `string` | Active | ARIA label do icone sufixo. |
+| `metadata.clearButton.enabled` | `boolean` | Active | Habilita botao de limpar. |
+| `metadata.clearButton.showOnlyWhenFilled` | `boolean` | Active | Exibe clear apenas com valor preenchido. |
+| `metadata.clearButton.icon` | `string` | Active | Icone do clear. |
+| `metadata.clearButton.iconColor` | `string` | Active | Cor do icone do clear. |
+| `metadata.clearButton.tooltip` | `string` | Active | Tooltip do clear. |
+| `metadata.clearButton.ariaLabel` | `string` | Active | ARIA label do clear. |
+| `metadata.textTransform` | `enum` | Active | Transformacao visual/funcional de texto. |
+| `metadata.textTransformApply` | `'displayOnly' \| 'saveOnly' \| 'both'` | Active | Define onde a transformacao e aplicada. |
+| `metadata.ariaLabel` | `string` | Active | `aria-label` no elemento nativo. |
+| `metadata.ariaDescribedby` | `string` | Active | `aria-describedby` no elemento nativo. |
+| `metadata.ariaLabelledby` | `string` | Active | `aria-labelledby` no elemento nativo. |
+
+#### Politica de label com prefixos e sufixos
+
+Quando um campo usa `metadata.prefixIcon`, `metadata.suffixIcon`, `clearButton`,
+datepicker toggle, seletor de cor, simbolo de moeda ou qualquer outro conteudo
+renderizado via `matPrefix`/`matSuffix`, a politica recomendada para
+`materialDesign.appearance = 'fill'` ou `'outline'` e:
+
+```json
+{
+  "materialDesign": {
+    "appearance": "outline",
+    "floatLabel": "always",
+    "subscriptSizing": "dynamic"
+  }
+}
+```
+
+Essa regra segue a limitacao documentada pelo Angular Material para campos
+`fill`/`outline`: label em repouso e valor do input nao compartilham o mesmo
+alinhamento, entao prefixos/sufixos podem conflitar visualmente com o label
+quando `floatLabel = 'auto'`.
+
+Para superficies geradas, como filtros avancados, preferir aplicar essa politica
+na camada global que materializa a metadata dos campos. Evite corrigir com CSS
+local movendo label, icone ou notch do `mat-form-field`; esses detalhes sao
+internos do Angular Material e podem mudar entre versoes.
+
+#### Saidas runtime compartilhadas
+
+| Output | Tipo | Quando ocorre |
+| --- | --- | --- |
+| `valueChange` | `any` | Mudanca de valor propagada pelo componente. |
+| `focusChange` | `boolean` | Foco/blur do elemento nativo. |
+| `nativeBlur` | `FocusEvent` | Evento blur nativo. |
+| `nativeChange` | `Event` | Evento change nativo. |
+
+#### Regras corporativas recomendadas
+
+1. Tratar `metadata.validators.*` como contrato de UX, sem substituir validacao de dominio no backend.
+2. Manter consistencia entre `required`, `visible` e regras de negocio para evitar bloqueio de submit com campo oculto.
+3. Padronizar `materialDesign` por design system (aparencia, cor e floatLabel) para reduzir variacao visual entre equipes.
+4. Usar `floatLabel: 'always'` em campos `fill`/`outline` com prefixos, sufixos ou icones Material.
+5. Usar `clearButton` com `ariaLabel` para conformidade de acessibilidade.
+
+#### Cross-links
+
+- `projects/praxis-dynamic-fields/src/lib/components/text-input/pdx-text-input.json-api.md`
+- `projects/praxis-dynamic-fields/src/lib/components/number-input/pdx-number-input.json-api.md`
+- `projects/praxis-dynamic-fields/src/lib/components/date-input/pdx-date-input.json-api.md`
+- `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
+
+### Referencias oficiais Angular
+
+- Acessibilidade em Angular: https://angular.dev/best-practices/a11y
+- Criacao e manutencao de libraries: https://angular.dev/tools/libraries/creating-libraries
+- Angular Material `mat-form-field`: https://material.angular.io/components/form-field/overview
+
+## JSON path index
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `metadata` | `ComponentMetadata` | not-specified | n/a | Active | Payload principal do componente. |
+| `metadata.name` | `string` | not-specified | n/a | Active | Aplica `name` no input nativo. |
+| `metadata.id` | `string` | not-specified | n/a | Active | Aplica `id` no elemento nativo. |
+| `metadata.label` | `string` | not-specified | n/a | Active | Mapeado para label visivel do campo. |
+| `metadata.placeholder` | `string` | not-specified | n/a | Active | Mapeado para placeholder quando diferente do label. |
+| `metadata.required` | `boolean` | not-specified | n/a | Active | `Validators.required` + `aria-required`. |
+| `metadata.disabled` | `boolean` | not-specified | n/a | Active | Atualiza estado disabled do controle. |
+| `metadata.readonly` | `boolean` | not-specified | n/a | Active | Aplica atributo `readonly` nativo. |
+| `metadata.readOnly` | `boolean` | not-specified | n/a | Partial | Compat legado (dependente de uso no metadata final). |
+| `metadata.autocomplete` | `string` | not-specified | n/a | Active | Aplica atributo `autocomplete`. |
+| `metadata.inputMode` | `string` | not-specified | n/a | Active | Aplica atributo `inputmode`. |
+| `metadata.spellcheck` | `boolean` | not-specified | n/a | Active | Aplica atributo `spellcheck`. |
+| `metadata.tabIndex` | `number` | not-specified | n/a | Active | Aplica `tabIndex` no elemento nativo. |
+| `metadata.minLength` | `number` | not-specified | n/a | Active | `Validators.minLength` + atributo nativo. |
+
+## Events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `valueChange` | `any` | Mudanca de valor propagada pelo componente. | Partial | Preservado da documentação anterior. |
+| `focusChange` | `boolean` | Foco/blur do elemento nativo. | Partial | Preservado da documentação anterior. |
+| `nativeBlur` | `FocusEvent` | Evento blur nativo. | Partial | Preservado da documentação anterior. |
+| `nativeChange` | `Event` | Evento change nativo. | Partial | Preservado da documentação anterior. |
+
+## Styling API
+
+| Token/Class | Scope | Purpose | Notes |
+| --- | --- | --- | --- |
+| see-detailed-api | component | styling/runtime | Consolidar naming canonico quando aplicavel. |
+
+## Editor and tooling notes
+
+- Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
+- Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.
+
+## Examples
+
+### Minimal valid
+
+```json
+{
+  "metadata": {
+    "name": "email",
+    "label": "E-mail",
+    "required": true,
+    "validators": {
+      "validationTrigger": "blur",
+      "requiredMessage": "Campo obrigatorio"
+    },
+    "materialDesign": { "appearance": "outline" }
+  }
+}
+```
+
+### Typical/common
+
+```json
+{}
+```
+
+### Advanced
+
+```json
+{}
+```
+
+### Enterprise scenario
+
+```json
+{}
+```
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |
+
+## Compatibility and migration notes
+
+| Concern | Affected versions | Migration action | Deadline | Notes |
+| --- | --- | --- | --- | --- |
+| legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |
+
+## Source references
+
+| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
+| --- | --- | --- | --- | --- |
+| local-file | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |