---
title: "pdx-base-select-runtime-contract JSON API (Canonical)"
slug: "pdx-base-select-runtime-contract-json-api"
doc_type: "api-reference"
component: "pdx-base-select-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-select-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-select.component.ts"
  - "projects/praxis-core/src/lib/models/component-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-select-runtime-contract"
api_stability: "canonical"
schema_verified: true
runtime_verified: false
editor_coverage_verified: false
runtime_scope: "public"
legacy_paths_present: false
has_known_mismatches: true
related_components:
  - "praxis-table"
  - "pdx-material-select"
  - "pdx-material-autocomplete"
  - "pdx-material-async-select"
  - "pdx-material-searchable-select"
  - "pdx-material-multi-select"
---

# pdx-base-select-runtime-contract

Este documento e a referencia canonica da API JSON de pdx-base-select-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: `SimpleBaseSelectComponent` e o contrato runtime compartilhado dos selects da plataforma. Ele padroniza selecao local/remota, cascata de dependencia e comportamento de busca por JSON metadata-driven. Nao e apenas um helper de UI; e a base de compatibilidade dos componentes `pdx-material-*select*`.

## 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-select.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-core/src/lib/models/component-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.options` | `SelectOption[]` | not-specified | n/a | Active | Fonte base de opcoes para selects locais. |
| `metadata.multiple` | `boolean` | not-specified | n/a | Active | Ativa modo multipla selecao no runtime base. |
| `metadata.searchable` | `boolean` | not-specified | n/a | Active | Habilita estado de busca (componente filho decide UI). |
| `metadata.selectAll` | `boolean` | not-specified | n/a | Active | Ativa utilitario de selecionar todos em multi-select. |
| `metadata.maxSelections` | `number` | not-specified | n/a | Active | Limite maximo de selecoes no modo multiplo. |
| `metadata.resourcePath` | `string` | not-specified | n/a | Active | Habilita carregamento remoto via `GenericCrudService`. |
| `metadata.filterCriteria` | `Record<string, any>` | not-specified | n/a | Active | Filtros base para consultas remotas. |
| `metadata.optionLabelKey` | `string` | not-specified | n/a | Active | Chave usada para extrair label de itens remotos. |
| `metadata.optionValueKey` | `string` | not-specified | n/a | Active | Chave usada para extrair value de itens remotos. |
| `metadata.emptyOptionText` | `string` | not-specified | n/a | Active | Texto para opcao nula em selects simples. |
| `metadata.displayWith` | `function` | not-specified | n/a | Active | Funcao de exibicao de valor selecionado (quando suportado pelo filho). |
| `metadata.compareWith` | `function` | not-specified | n/a | Active | Comparacao customizada para igualdade de opcoes. |
| `metadata.loadOn` | `'open' \| 'init' \| 'none'` | not-specified | n/a | Partial | Campo do contrato de select; efetivo em componentes filhos que implementam estrategia lazy. |

### Supported legacy paths

Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.

### 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.options` | `SelectOption[]` | not-specified | n/a | component-defined | Fonte base de opcoes para selects locais. |
| `metadata.multiple` | `boolean` | not-specified | n/a | component-defined | Ativa modo multipla selecao no runtime base. |
| `metadata.searchable` | `boolean` | not-specified | n/a | component-defined | Habilita estado de busca (componente filho decide UI). |
| `metadata.selectAll` | `boolean` | not-specified | n/a | component-defined | Ativa utilitario de selecionar todos em multi-select. |
| `metadata.maxSelections` | `number` | not-specified | n/a | component-defined | Limite maximo de selecoes no modo multiplo. |
| `metadata.resourcePath` | `string` | not-specified | n/a | component-defined | Habilita carregamento remoto via `GenericCrudService`. |
| `metadata.filterCriteria` | `Record<string, any>` | not-specified | n/a | component-defined | Filtros base para consultas remotas. |
| `metadata.optionLabelKey` | `string` | not-specified | n/a | component-defined | Chave usada para extrair label de itens remotos. |
| `metadata.optionValueKey` | `string` | not-specified | n/a | component-defined | Chave usada para extrair value de itens remotos. |

### 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 |
| --- | --- | --- | --- | --- |
| `selectionChange` | `T \| T[]` | Mudanca do valor selecionado. | Partial | Preservado da documentação anterior. |
| `optionSelected` | `SelectOption` | Selecao individual de opcao. | Partial | Preservado da documentação anterior. |
| `optionsLoaded` | `SelectOption[]` | Conclusao de carga remota de opcoes. | Partial | Preservado da documentação anterior. |
| `openedChange` | `boolean` | Abre/fecha do `MatSelect`. | Partial | Preservado da documentação anterior. |
| `searchTermChange` | `string` | Mudanca no termo de busca. | 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)

`SimpleBaseSelectComponent` e o contrato runtime compartilhado dos selects da plataforma. Ele padroniza selecao local/remota, cascata de dependencia e comportamento de busca por JSON metadata-driven. Nao e apenas um helper de UI; e a base de compatibilidade dos componentes `pdx-material-*select*`.

### Prova em 20 segundos

```json
{
  "metadata": {
    "resourcePath": "customers",
    "optionLabelKey": "name",
    "optionValueKey": "id",
    "multiple": true,
    "maxSelections": 3
  }
}
```

- O runtime interpreta fonte remota e extracao de label/value por contrato.
- O mesmo bloco funciona em multiplos componentes filhos de select.
- As regras de cascata e carga permanecem versionaveis por metadata.

### 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:** contrato unico para selects locais/remotos com suporte a cascata entre campos e multi-selecao.

**Quando usar:** sempre que um componente extender `SimpleBaseSelectComponent`.

**Exemplo minimo:** `metadata.options` (local) ou `metadata.resourcePath` (remoto).

Garantias:

- campos `metadata.*` ativos sao consumidos no runtime base.
- estrategia de dependencia/cascata e aplicada de forma uniforme.
- eventos de selecao/carga sao emitidos por interface comum.

Limites:

- parte do contrato depende do componente filho (`Status: Partial`).
- campos `Declared-only` permanecem para compatibilidade sem efeito direto no base.
- validacao de regra de negocio continua externa ao componente.

#### Status model

- `Status: Active` - consumido diretamente no runtime base.
- `Status: Partial` - suporte condicional/dependente de componente filho.
- `Status: Declared-only` - declarado no contrato, sem efeito direto no runtime base.
- `Status: Runtime-extension` - chave adicional consumida por componentes filhos.

#### Checklist corporativo

- padronizar `optionLabelKey`/`optionValueKey` por dominio.
- mapear cascata com `dependencyFilterMap` explicito.
- definir `loadOn` conforme custo do endpoint.
- alinhar `maxSelections` com regra funcional e mensagens de validacao.

### Contrato tecnico completo

#### Matriz completa de cobertura (herdada)

| Caminho JSON | Tipo | Status | Comportamento em runtime |
| --- | --- | --- | --- |
| `metadata` | `ComponentMetadata` | Active | Payload principal do componente. |
| `metadata.options` | `SelectOption[]` | Active | Fonte base de opcoes para selects locais. |
| `metadata.multiple` | `boolean` | Active | Ativa modo multipla selecao no runtime base. |
| `metadata.searchable` | `boolean` | Active | Habilita estado de busca (componente filho decide UI). |
| `metadata.selectAll` | `boolean` | Active | Ativa utilitario de selecionar todos em multi-select. |
| `metadata.maxSelections` | `number` | Active | Limite maximo de selecoes no modo multiplo. |
| `metadata.resourcePath` | `string` | Active | Habilita carregamento remoto via `GenericCrudService`. |
| `metadata.filterCriteria` | `Record<string, any>` | Active | Filtros base para consultas remotas. |
| `metadata.optionLabelKey` | `string` | Active | Chave usada para extrair label de itens remotos. |
| `metadata.optionValueKey` | `string` | Active | Chave usada para extrair value de itens remotos. |
| `metadata.emptyOptionText` | `string` | Active | Texto para opcao nula em selects simples. |
| `metadata.displayWith` | `function` | Active | Funcao de exibicao de valor selecionado (quando suportado pelo filho). |
| `metadata.compareWith` | `function` | Active | Comparacao customizada para igualdade de opcoes. |
| `metadata.loadOn` | `'open' \| 'init' \| 'none'` | Partial | Campo do contrato de select; efetivo em componentes filhos que implementam estrategia lazy. |
| `metadata.clearButton` | `boolean \| object` | Active | Regras de exibicao/icone/tooltip/aria do clear. |
| `metadata.panelClass` | `string \| string[]` | Active | Classe aplicada ao painel do `MatSelect`. |
| `metadata.disableRipple` | `boolean` | Active | Desativa ripple no `MatSelect` quando suportado. |
| `metadata.disableOptionCentering` | `boolean` | Active | Ajusta centralizacao de opcao no `MatSelect`. |
| `metadata.tabIndex` | `number` | Active | Tab order do `MatSelect`. |
| `metadata.required` | `boolean` | Active | Estado de obrigatoriedade do controle. |
| `metadata.ariaLabel` | `string` | Active | ARIA label do `MatSelect`. |
| `metadata.ariaLabelledby` | `string` | Active | ARIA labelledby do `MatSelect`. |
| `metadata.dependencyFields` | `string[]` | Active | Liga cascata de filtros por dependencia em mesmo form. |
| `metadata.enableDependencyCascade` | `boolean` | Active | Ativa/desativa cascata de dependencia. |
| `metadata.resetOnDependentChange` | `boolean` | Active | Limpa valor quando dependencia muda. |
| `metadata.dependencyFilterMap` | `Record<string, string \| { key; valuePath? }>` | Active | Mapeia dependencia para chave de filtro backend. |
| `metadata.dependencyValuePath` | `string \| Record<string, string>` | Active | Caminho para extrair valor da dependencia. |
| `metadata.dependencyDebounceMs` | `number` | Active | Debounce da cascata entre dependencias. |
| `metadata.dependencyMergeStrategy` | `'replace' \| 'merge'` | Active | Estrategia de merge de fragmentos no filtro. |
| `metadata.dependencyLoadOnChange` | `'respectLoadOn' \| 'immediate' \| 'manual'` | Active | Estrategia de recarga quando dependencia muda. |
| `metadata.suppressInlineErrorsOnCascade` | `boolean` | Declared-only | Declarado no contrato geral; sem efeito direto no runtime base de select. |

#### Saidas runtime compartilhadas

| Output | Tipo | Quando ocorre |
| --- | --- | --- |
| `selectionChange` | `T \| T[]` | Mudanca do valor selecionado. |
| `optionSelected` | `SelectOption` | Selecao individual de opcao. |
| `optionsLoaded` | `SelectOption[]` | Conclusao de carga remota de opcoes. |
| `openedChange` | `boolean` | Abre/fecha do `MatSelect`. |
| `searchTermChange` | `string` | Mudanca no termo de busca. |

#### Regras corporativas recomendadas

1. Padronizar `optionLabelKey`/`optionValueKey` por dominio para reduzir acoplamento entre squads.
2. Em cascata, usar `dependencyFilterMap` explicito para evitar filtros ambiguos no backend.
3. Definir `loadOn` conforme custo de endpoint (`open` para endpoints pesados; `init` para UX critica).
4. Em multi-select, alinhar `maxSelections` com regra de negocio e mensagens de validacao de formulario.

#### Cross-links

- `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/components/material-autocomplete/pdx-material-autocomplete.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/components/material-async-select/pdx-material-async-select.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/components/material-searchable-select/pdx-material-searchable-select.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/components/material-multi-select/pdx-material-multi-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

## JSON path index

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `metadata` | `ComponentMetadata` | not-specified | n/a | Active | Payload principal do componente. |
| `metadata.options` | `SelectOption[]` | not-specified | n/a | Active | Fonte base de opcoes para selects locais. |
| `metadata.multiple` | `boolean` | not-specified | n/a | Active | Ativa modo multipla selecao no runtime base. |
| `metadata.searchable` | `boolean` | not-specified | n/a | Active | Habilita estado de busca (componente filho decide UI). |
| `metadata.selectAll` | `boolean` | not-specified | n/a | Active | Ativa utilitario de selecionar todos em multi-select. |
| `metadata.maxSelections` | `number` | not-specified | n/a | Active | Limite maximo de selecoes no modo multiplo. |
| `metadata.resourcePath` | `string` | not-specified | n/a | Active | Habilita carregamento remoto via `GenericCrudService`. |
| `metadata.filterCriteria` | `Record<string, any>` | not-specified | n/a | Active | Filtros base para consultas remotas. |
| `metadata.optionLabelKey` | `string` | not-specified | n/a | Active | Chave usada para extrair label de itens remotos. |
| `metadata.optionValueKey` | `string` | not-specified | n/a | Active | Chave usada para extrair value de itens remotos. |
| `metadata.emptyOptionText` | `string` | not-specified | n/a | Active | Texto para opcao nula em selects simples. |
| `metadata.displayWith` | `function` | not-specified | n/a | Active | Funcao de exibicao de valor selecionado (quando suportado pelo filho). |
| `metadata.compareWith` | `function` | not-specified | n/a | Active | Comparacao customizada para igualdade de opcoes. |
| `metadata.loadOn` | `'open' \| 'init' \| 'none'` | not-specified | n/a | Partial | Campo do contrato de select; efetivo em componentes filhos que implementam estrategia lazy. |

## Events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `selectionChange` | `T \| T[]` | Mudanca do valor selecionado. | Partial | Preservado da documentação anterior. |
| `optionSelected` | `SelectOption` | Selecao individual de opcao. | Partial | Preservado da documentação anterior. |
| `optionsLoaded` | `SelectOption[]` | Conclusao de carga remota de opcoes. | Partial | Preservado da documentação anterior. |
| `openedChange` | `boolean` | Abre/fecha do `MatSelect`. | Partial | Preservado da documentação anterior. |
| `searchTermChange` | `string` | Mudanca no termo de busca. | 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": {
    "resourcePath": "customers",
    "optionLabelKey": "name",
    "optionValueKey": "id",
    "multiple": true,
    "maxSelections": 3
  }
}
```

### 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-select.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-core/src/lib/models/component-metadata.interface.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |