---
title: "pdx-inline-entity-lookup JSON API (Canonical)"
slug: "pdx-inline-entity-lookup-json-api"
doc_type: "api-reference"
component: "pdx-inline-entity-lookup"
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-inline-entity-lookup."
category: "components"
sub_category: "dynamic-fields"
audience:
  - "frontend"
  - "architect"
  - "platform-team"
level: "advanced"
status: "active"
owner: "praxis-ui"
source_of_truth:
  - "projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts"
  - "projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts"
  - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
source_of_truth_last_verified: "2026-04-16"
last_updated: "2026-04-16"
toc: true
sidebar: true
tags:
  - "json-api"
  - "canonical-contract"
  - "pdx-inline-entity-lookup"
api_stability: "canonical"
schema_verified: true
runtime_verified: true
editor_coverage_verified: false
runtime_scope: "public"
legacy_paths_present: false
has_known_mismatches: false
related_components:
  - "praxis-table"
  - "pdx-material-async-select"
  - "pdx-base-select-runtime-contract"
---

# pdx-inline-entity-lookup

Este documento e a referencia canonica da API JSON de pdx-inline-entity-lookup.

## 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: Contrato JSON metadata-driven com comportamento definido por runtime e schema associado.

## Purpose and scope

- O componente consome payload JSON metadata-driven e expoe comportamento runtime configuravel por contrato.
- Esta referencia cobre contrato publico, classificacao de paths e semantica de cobertura (runtime/schema/editor).
- Fora de escopo: quickstart, tutorial narrativo e notas arquiteturais que nao alteram contrato publico.

## Consulta rapida (obrigatorio)

| Regra/tema | Observado | Canonico desejado | Status | Evidencia |
| --- | --- | --- | --- | --- |
| Component id | `pdx-inline-entity-lookup` | Manter ID canonico estavel e versionado por contrato | Active | frontmatter.component |
| Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis | Partial | frontmatter.contract_source + source_of_truth |
| Runtime coverage | `true` | Comportamentos runtime criticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts` |
| Schema/type coverage | `true` | Tipos e schema devem refletir paths publicos do contrato | Active | source_of_truth + Detailed API reference |
| Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato publico suportado | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
| Path hygiene | `false` | Manter consistencia entre contrato canonico e caminhos documentados | Active | frontmatter.legacy_paths_present |
| Known mismatches | `false` | Registrar observed vs desired de forma auditavel | Active | frontmatter.has_known_mismatches |

## Source of truth

| Source | Kind | Notes |
| --- | --- | --- |
| projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
| projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |

## Support legend

- **Active**: suportado em runtime e liberado para uso externo.
- **Partial**: suporte parcial, com restricoes, lacunas ou validacao incompleta.
- **Declared-only**: declarado em tipos/schema sem evidencia operacional completa.
- **Schema-only**: presente em schema/tipos sem cobertura runtime confirmada.

## Contract status snapshot

| Item | Value | Notes |
| --- | --- | --- |
| Reference mode | `canonical` | Deve permanecer canonico |
| Contract format | `json` | Contrato metadata-driven |
| Contract source | `runtime-and-code` | Alinhar com source_of_truth |
| Runtime scope | `public` | Escopo publicado para consumidores |
| Runtime verified | `true` | Revisar sempre com evidencia de runtime |
| Schema verified | `true` | Revisar sempre com evidencia de tipos/schema |
| Editor coverage verified | `false` | Revisar sempre com evidencia de editor/tooling |
| Current path hygiene | `false` | Segregar consistencia do contrato canonico |
| Has known mismatches | `false` | Divergencias devem aparecer em secao dedicada |

## Contract classification (obrigatorio)

### Canonical paths (public contract)

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `metadata` | object | true | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.lookupIdKey` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.lookupLabelKey` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.lookupSubtitleKey` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.lookupSeparator` | unknown | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.searchPlaceholder` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.optionValueKey` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.optionLabelKey` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
| `metadata.optionSource` | object | false | n/a | Active | Fonte canonica de lookup remoto e semantica RESOURCE_ENTITY. |
| `metadata.optionSource.resourcePath` | string | false | n/a | Active | Habilita carga remota, busca, paginacao e reidratacao por IDs. |
| `metadata.optionSource.valuePropertyPath` | string | false | n/a | Active | Campo canonico de identidade da entidade no payload de lookup. |
| `metadata.optionSource.labelPropertyPath` | string | false | n/a | Active | Campo canonico de label humano da entidade. |
| `metadata.optionSource.codePropertyPath` | string | false | n/a | Active | Campo canonico de codigo curto exibido antes do label. |
| `metadata.optionSource.descriptionPropertyPaths` | string[] | false | n/a | Active | Campos concatenados na linha secundaria do lookup. |
| `metadata.optionSource.statusPropertyPath` | string | false | n/a | Active | Campo canonico de status exibido na linha secundaria. |
| `metadata.optionSource.display` | object | false | n/a | Active | Intencao canonica de UX para a entidade referenciada. |
| `metadata.optionSource.display.preset` | string | false | `rich` para formulario, `compact` para inline | Active | Preset semantico: `compact`, `rich`, `directory`, `status`, `reference` ou `hierarchical`. |
| `metadata.optionSource.display.usage` | string | false | n/a | Active | Contexto preferencial de uso: `form`, `filter`, `table-cell`, `dashboard`, `wizard` ou `review`. |
| `metadata.optionSource.display.density` | string | false | n/a | Active | Densidade preferencial: `compact`, `comfortable` ou `rich`. |
| `metadata.optionSource.display.secondaryPropertyPaths` | string[] | false | n/a | Active | Campos de subtitulo usados para diferenciar entidades parecidas. |
| `metadata.optionSource.display.fields` | object[] | false | n/a | Active | Campos ricos semanticos exibidos na lista e no valor selecionado. Cada item aceita `key`, `propertyPath`, `label`, `icon`, `presentation`, `tone` e `format`. |
| `metadata.optionSource.display.badgePropertyPaths` | string[] | false | n/a | Active | Campos publicados como badges/chips quando o backend tambem os materializa no payload de option. |

### Path audit

Nenhum desvio de caminho foi identificado nesta revisao.

### Internal-only paths

Nao ha paths internal-only confirmados no contrato publico desta revisao.

### Experimental paths

Nao ha paths experimentais confirmados no contrato publico desta revisao.

## Public contract surface (obrigatorio)

### Top-level configuration blocks

| Block | Purpose | Required | Merge strategy | Notes |
| --- | --- | --- | --- | --- |
| `metadata` | Payload declarativo principal do componente | true | deep-merge | runtime linkage verified for core flows (component specs, 2026-03-06). |
| `resourcePath` | Configuracao especifica de runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
| `readonlyMode` | Override de readonly no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
| `disabledMode` | Override de disabled no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
| `visible` | Override de visibilidade no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
| `presentationMode` | Renderizacao de apresentacao sem interacao | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |

### Nested configuration blocks

| Path | Type | Required | Default | Constraints | Notes |
| --- | --- | --- | --- | --- | --- |
| `metadata.lookupIdKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.lookupLabelKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.lookupSubtitleKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.lookupSeparator` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.searchPlaceholder` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.optionValueKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.optionLabelKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
| `metadata.optionSource` | object | false | n/a | `RESOURCE_ENTITY` recomendado para entidades de negocio | Fonte canonica para resourcePath, identidade, label, codigo, descricao, status e detalhe. |
| `metadata.optionSource.display` | object | false | n/a | contrato semantico de UX, nao CSS | Governanca de preset, uso, densidade, campos ricos, secundarios e badges do resultado. |
| `metadata.resourcePath` | string | 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.searchable` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |

### Input bindings (inbound data)

| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
| --- | --- | --- | --- | --- | --- |
| `metadata` | object | true | host-json | component-defined | Primary inbound contract payload. |
| `readonlyMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
| `disabledMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
| `visible` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
| `presentationMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |

### Output events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `searchTermChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `selectionChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `openedChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `valueChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `focusChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `nativeBlur` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
| `nativeChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |

### External side channels

| Channel | Direction | Contract | Failure mode | Notes |
| --- | --- | --- | --- | --- |
| `host/services/storage` | bidirectional | component-defined | component-defined | Side channels variam por componente e host; verificar em source_of_truth. |

### Host/runtime dependencies

| Dependency | Required | Environment | Purpose | Notes |
| --- | --- | --- | --- | --- |
| `inline-entity-lookup.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts`. |
| `material-async-select.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts`. |
| `material-field-metadata.interface.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-core/src/lib/models/material-field-metadata.interface.ts`. |

## Coverage by surface (obrigatorio)

### Coverage matrix (runtime, schema/type, editor/tooling)

| Surface | Verified | Coverage status | Evidence | Notes |
| --- | --- | --- | --- | --- |
| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts`, `projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts` | Core runtime flows verified via focused component specs on 2026-03-06; 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/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Alias/selector tooling linkage verified for inline filters; visual editor end-to-end coverage remains not-yet-verified. |

### Runtime coverage boundaries

- Ambientes suportados: browser/dev/prod; SSR/hydration appears to be component-dependent unless explicitly verified.
- Pre-condicoes: payload JSON valido, bindings de host consistentes e dependencias descritas no source_of_truth.
- Fora de cobertura confirmada: caminhos internos, experimentais ou aliases nao enumerados formalmente.

### Editor and tooling notes

- Evidencia de tooling: aliases `pdx-inline-*` resolvidos por `inline-filter-controls.util.ts` e consumidos no `ComponentRegistryService`; editor visual E2E permanece not-yet-verified.
- O que esta exposto no editor visual depende da cobertura real do workspace e nao deve ser inferido como suporte runtime total.
- Campos disponiveis apenas via JSON/manual devem continuar no contrato, com rotulo explicito de cobertura parcial.
- Quando houver divergencia entre editor e runtime, manter mismatch rastreavel em secao dedicada.

## Resolution and precedence model (obrigatorio)

### Merge order

1. defaults do componente
2. contrato JSON recebido
3. overrides de host/runtime
4. normalizacoes internas

### Fallback order

contrato explicito -> aliases historicos (quando suportados) -> defaults internos -> comportamento seguro

### Override points

- inputs publicos do componente
- configuracao JSON de runtime
- integracoes de host (servicos/tokens/adapters)

### Runtime normalization

Alias e defaults devem convergir para paths canonicos; onde nao houver evidencia, manter not-yet-verified de forma explicita.

### Precedence rules

Em conflito entre caminho historico e path canonico, priorizar path canonico e registrar janela de migracao do historico.

## Validation and error semantics (obrigatorio)

### Validation model

| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
| --- | --- | --- | --- | --- |
| canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referencia tecnica por componente. |

### Invalid and unknown field handling

- Campos desconhecidos: comportamento component-defined (ignore, warn ou reject).
- Tipos invalidos: pode haver fallback, warning ou falha, conforme runtime especifico.
- Valores fora de dominio: registrar observed vs desired em Known limitations and mismatches.

### Fail-open / fail-closed behavior

| Condition | Mode | Runtime behavior | Consumer impact |
| --- | --- | --- | --- |
| invalid-or-unknown-field | component-defined | not-yet-verified | Pode gerar warning, fallback silencioso ou rejeicao; validar por componente. |

### 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. |
| mismatch-confirmed | error-or-warning | componente/host observability | Planejar migracao e corrigir contrato/runtime. |

## Detailed API reference
### Preserved technical reference (normalized from previous revision)

### 1. Visao Geral e Quando Usar
`pdx-inline-entity-lookup` e um lookup corporativo inline para selecionar entidades por identificador + descricao.

Use quando precisar:
- localizar registros por codigo e descricao na mesma opcao;
- combinar busca local/remota em painel compacto;
- padronizar exibicao do trigger como `ID - Label`.

### 2. API do Componente (Inputs/Outputs)
| Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
| --- | --- | --- | --- | --- |
| `metadata` | `MaterialSelectMetadata` | - | Sim | Contrato principal do lookup inline. |
| `readonlyMode/disabledMode/visible/presentationMode` | `boolean` | `false/false/true/false` | Nao | Estados de host do campo inline. |
| `selectionChange` | `T` | - | Output herdado | Valor selecionado da entidade. |
| `optionSelected` | `SelectOption` | - | Output herdado | Opcao selecionada no painel. |
| `optionsLoaded` | `SelectOption[]` | - | Output herdado | Lote carregado (local/remoto). |

### 3. Matriz de Cobertura JSON (Completa)
#### 3.1 Campos especificos do componente
| Caminho JSON | Tipo | Status | Comportamento em runtime |
| --- | --- | --- | --- |
| `metadata.lookupIdKey` | `string` | Ativo | Chave primaria usada na parte "ID" do texto. |
| `metadata.lookupLabelKey` | `string` | Ativo | Chave do label principal da entidade. |
| `metadata.lookupSubtitleKey` | `string` | Ativo | Chave de subtitulo opcional da entidade. |
| `metadata.lookupSeparator` | `string` | Ativo | Separador entre ID e label no trigger/opcao. |
| `metadata.searchPlaceholder` | `string` | Ativo | Placeholder do campo de busca do painel; na ausencia de override, o runtime cai para o catalogo shared `inlineSelect.searchPlaceholder`. |
| `metadata.optionValueKey` / `metadata.optionLabelKey` | `string` | Ativo | Fallback para mapping de id/label. |
| `metadata.optionSource` | `object` | Ativo | Fonte canonica de plataforma para Entity Lookup remoto. Quando `resourcePath` existe dentro de `optionSource`, o runtime usa endpoints de option-source para busca/paginacao e reidratacao por IDs. |
| `metadata.optionSource.valuePropertyPath` | `string` | Ativo | Resolve identidade da entidade para comparacao/reidratacao quando o valor salvo e primitivo ou objeto. |
| `metadata.optionSource.labelPropertyPath` | `string` | Ativo | Resolve label principal quando o objeto local/remoto carrega o campo de dominio em vez de `label`. |
| `metadata.optionSource.codePropertyPath` | `string` | Ativo | Resolve codigo curto exibido como parte primaria do lookup. |
| `metadata.optionSource.descriptionPropertyPaths` | `string[]` | Ativo | Resolve descricao rica concatenando campos de dominio na linha secundaria. |
| `metadata.optionSource.statusPropertyPath` | `string` | Ativo | Resolve status exibido depois da descricao. |
| `metadata.optionSource.detail.kind` | `"surface" | "route" | "href"` | Ativo | `surface` e o contrato canonico para detalhe de entidade: o runtime descobre `/{resource}/{id}/surfaces` e abre a surface por `GlobalActionService`/`surface.open`. `route`/`href` ficam como fallback legado. |
| `metadata.optionSource.detail.surfaceId` | `string` | Ativo | Id da surface item-level preferida para o detalhe. Quando ausente, o runtime escolhe `detail`, `view` ou a primeira surface item-level de leitura disponivel. |
| `metadata.optionSource.detail.presentation` | `"drawer" | "modal"` | Ativo | Apresentacao desejada para `surface.open`. Default vem do preset/host de surface. |
| `metadata.optionSource.detail.preferredWidget` / `metadata.optionSource.detail.mode` | `string` | Documental | Hints semanticos para autoria/discovery. A materializacao final vem da surface descoberta e do `ResourceSurfaceOpenAdapterService`. |
| `metadata.optionSource.detail.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Legado | Fallback para abrir detalhe por link quando nao houver contrato de surface ou servico global disponivel. Nao deve ser a fonte primaria em novos lookups de plataforma. |
| `metadata.optionSource.display.preset` | `"compact" | "rich" | "directory" | "status" | "reference" | "hierarchical"` | Ativo | Define a intencao visual canonica. `directory` e recomendado para pessoas/equipes; `reference` para codigo + descricao; `status` para entidades com estado operacional forte. |
| `metadata.optionSource.display.usage` | `"form" | "filter" | "table-cell" | "dashboard" | "wizard" | "review"` | Ativo | Indica onde a option-source costuma aparecer. O runtime pode ajustar densidade e acoes sem duplicar regra por host. |
| `metadata.optionSource.display.density` | `"compact" | "comfortable" | "rich"` | Ativo | Densidade preferencial. Campos de formulario usam `comfortable`; filtros inline e celulas de tabela tendem a `compact`; revisoes podem usar `rich`. |
| `metadata.optionSource.display.secondaryPropertyPaths` | `string[]` | Ativo | Campos usados como subtitulo quando o payload local ou remoto preserva essas propriedades. O runtime tambem aceita `descriptionPropertyPaths` como fallback. |
| `metadata.optionSource.display.fields` | `object[]` | Ativo | Subinformacoes ricas com `propertyPath`, `label`, `icon`, `presentation` (`text`, `chip`, `badge`, `date`, `currency`, `metric`), `tone` e `format`. Quando o endpoint materializa `OptionDTO.extra.richFields[]`, esses valores sao usados diretamente. |
| `metadata.optionSource.display.badgePropertyPaths` | `string[]` | Ativo | Campos usados para badges/chips quando materializados no payload da option-source. |
| `metadata.resourcePath` | `string` | Ativo | Caminho operacional herdado. Para Entity Lookup de plataforma, preferir `metadata.optionSource.resourcePath`. |
| `metadata.inlineAutoSize.*` | `object` | Ativo | Largura responsiva da pill lookup. |
| `metadata.selectedLayout` | `"compact" | "inline" | "card" | "token"` | Ativo | Para `controlType: "entityLookup"`, `compact` e o default preservam altura de campo de formulario. `card` renderiza valor selecionado como cartao rico quando a superficie pedir revisao/detalhe. `token` preserva leitura compacta herdada. |
| `metadata.resultLayout` | `"list" | "denseList" | "table" | "card"` | Ativo | Para `controlType: "entityLookup"`, `list` e o default renderizam linhas ricas; `denseList` preserva leitura compacta. |
| `metadata.showCode` | `boolean` | Ativo | Controla exibicao do codigo curto na linha e no cartao. Default: `true`. |
| `metadata.showDescription` | `boolean` | Ativo | Controla exibicao da descricao composta. Default: `true`. |
| `metadata.showStatus` | `boolean` | Ativo | Controla exibicao do badge de status. Default: `true`. |
| `metadata.showAvatar` | `boolean` | Ativo | Controla exibicao de avatar por iniciais. Default: `true`. |
| `metadata.showBadges` | `boolean` | Ativo | Controla exibicao de badges auxiliares vindos de `badges`, `tags`, `riskLevel`, `homologationStatus` ou `badgeKeys`. Default: `true`. |
| `metadata.showDisabledReason` | `boolean` | Ativo | Controla exibicao do motivo de bloqueio quando `selectable=false`. Default: `true`. |
| `metadata.showResultCount` | `boolean` | Ativo | Controla contador de resultados no painel de busca. Quando o backend pagina com `totalElements`, mostra o total remoto; em fontes locais/cursor, mostra o total carregado. Default: `true`. |
| `metadata.statusToneMap` | `Record<string, "success" | "warning" | "danger" | "neutral">` | Ativo | Permite mapear status de dominio para tom visual governado. |
| `metadata.badgeKeys` | `string[]` | Ativo | Chaves adicionais lidas do valor de entidade para compor badges auxiliares. |
| `metadata.maxVisibleBadges` | `number` | Ativo | Limita quantidade de badges auxiliares exibidos. Default: `3`. |
| `metadata.actions.showDetail` | `boolean` | Ativo | Controla acao de detalhe quando houver surface canonica ou fallback `detailHref`/`detailRoute`. Default: `true`. |
| `metadata.actions.showChange` | `boolean` | Ativo | Controla acao de troca no cartao selecionado. Default: `true`. |
| `metadata.actions.showCopyCode` | `boolean` | Ativo | Controla acao de copiar codigo/id. Default: `true`. |
| `metadata.actions.showClear` | `boolean` | Ativo | Controla acao de limpar em conjunto com `clearButton`/clearable herdado. |
| `metadata.detailActionLabel` / `metadata.changeActionLabel` / `metadata.copyCodeActionLabel` / `metadata.clearActionLabel` | `string` | Ativo | Overrides textuais das acoes do cartao selecionado. |
| `metadata.searchable` | `boolean` | Ativo | Exibe/oculta barra de busca interna. |

#### 3.2 Campos herdados compartilhados (exaustivo)
- `projects/praxis-dynamic-fields/src/lib/components/material-async-select/pdx-material-async-select.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`

Resumo de composicao deste componente:
- `Ativo`: composicao lookup (id/label/subtitle), busca e reset rapido.
- `Extensao de runtime`: chaves `lookup*` para semantica corporativa.

### 4. Mapeamento de Comportamento
- Para `controlType: "inlineEntityLookup"`, o trigger preserva valor compacto composto por `buildLookupPrimaryText(id,label)`.
- Para `controlType: "entityLookup"`, o host publica `data-field-type="entityLookup"`, ocupa `width: 100%` e deve respeitar a coluna do `praxis-dynamic-form`; o trigger pode renderizar campo compacto ou cartao de revisao com avatar, codigo, label, descricao, status, badges e acoes.
- `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.
- `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.

### 5. Exemplo Minimo (JSON + Uso)
```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "employee",
    "label": "Funcionario",
    "controlType": "select",
    "lookupIdKey": "employeeId",
    "lookupLabelKey": "fullName",
    "selectOptions": [
      { "employeeId": "E-100", "fullName": "Ana Lima", "value": "E-100" }
    ]
  }
}
```
Uso: lookup simples em lista local.

### 6. Exemplo Corporativo (JSON + Uso)
```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "costCenterOwner",
    "label": "Responsavel",
    "controlType": "inlineEntityLookup",
    "optionSource": {
      "key": "employees",
      "type": "RESOURCE_ENTITY",
      "resourcePath": "people/employees",
      "entityKey": "employee",
      "valuePropertyPath": "id",
      "labelPropertyPath": "nome",
      "codePropertyPath": "matricula",
      "descriptionPropertyPaths": ["departamento"],
      "statusPropertyPath": "status",
      "detail": {
        "kind": "surface",
        "surfaceId": "view",
        "presentation": "drawer",
        "preferredWidget": "praxis-dynamic-form",
        "mode": "view"
      },
      "display": {
        "preset": "directory",
        "usage": "form",
        "density": "comfortable",
        "selectedLayout": "compact",
        "resultLayout": "list",
        "primaryPropertyPath": "nome",
        "secondaryPropertyPaths": ["cargo", "departamento"],
        "badgePropertyPaths": ["departamento"],
        "showAvatar": true,
        "showCode": false,
        "showDescription": true,
        "showStatus": true,
        "showBadges": true,
        "showResultCount": true
      }
    },
    "lookupSeparator": " | ",
    "searchable": true,
    "searchPlaceholder": "Buscar por matricula ou nome",
    "inlineAutoSize": { "minWidth": 156, "maxWidth": 420 },
    "clearButton": { "enabled": true, "showOnlyWhenFilled": true }
  }
}
```
Uso: lookup de colaborador em filtro corporativo com alto volume.

### 7. Troubleshooting e Armadilhas Comuns
1. Trigger mostra texto incompleto.
Correcao: validar `lookupIdKey` e `lookupLabelKey` no payload.

2. Subtitulo nao aparece nas opcoes.
Correcao: preencher `lookupSubtitleKey` e garantir dado no backend.

3. Busca nao retorna remoto.
Correcao: conferir `resourcePath` e contrato de endpoint.

4. Separador indesejado no texto.
Correcao: configurar `lookupSeparator`.

5. Campo estoura largura da toolbar.
Correcao: ajustar `inlineAutoSize.minWidth/maxWidth`.

### 8. Cross-links
- `projects/praxis-dynamic-fields/src/lib/components/material-async-select/pdx-material-async-select.json-api.md`
- `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`

### 9. Relatorio de Validacao Estrutural
- Visao geral: PASS
- API (inputs/outputs): PASS
- Cobertura JSON completa (especifico + herdado): PASS
- Mapeamento de comportamento: PASS
- Exemplo minimo: PASS
- Exemplo corporativo: PASS
- Troubleshooting: PASS

## JSON path index (obrigatorio)

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `metadata` | object | true | n/a | Partial | See Detailed API reference. |
| `metadata.lookupIdKey` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.lookupLabelKey` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.lookupSubtitleKey` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.lookupSeparator` | unknown | false | n/a | Partial | See Detailed API reference. |
| `metadata.searchPlaceholder` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.optionValueKey` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.optionLabelKey` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.resourcePath` | string | false | n/a | Partial | See Detailed API reference. |
| `metadata.inlineAutoSize.*` | object | false | n/a | Partial | See Detailed API reference. |
| `metadata.searchable` | boolean | false | n/a | Partial | See Detailed API reference. |
| `resourcePath` | string | 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. |
| `visible` | boolean | false | n/a | Partial | See Detailed API reference. |
| `presentationMode` | boolean | false | n/a | Partial | See Detailed API reference. |

## Events reference (obrigatorio)

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `searchTermChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `selectionChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `openedChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `valueChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `focusChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `nativeBlur` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
| `nativeChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |

## Styling API (obrigatorio quando aplicavel)

| Token/Class | Scope | Purpose | Notes |
| --- | --- | --- | --- |
| `not-yet-verified` | component | Styling contract not yet verified | Use Detailed API reference for component-specific styling notes. |

## Examples (obrigatorio)

| Example | Scenario | Validates | Notes |
| --- | --- | --- | --- |
| `Minimal valid` | baseline payload | required contract blocks | Extracted from preserved technical reference when available. |
| `Common setup` | common component usage | standard runtime behavior | Validate against host integration path. |
| `Advanced setup` | richer config with overrides | precedence and normalization | Requires runtime confirmation for edge cases. |
| `Enterprise scenario` | governance/legacy/migration context | auditability and compatibility boundaries | Include tenant-specific constraints when applicable. |

### Minimal valid

```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "employee",
    "label": "Funcionario",
    "controlType": "select",
    "lookupIdKey": "employeeId",
    "lookupLabelKey": "fullName",
    "selectOptions": [
      {
        "employeeId": "E-100",
        "fullName": "Ana Lima",
        "value": "E-100"
      }
    ],
    "searchable": false
  }
}
```

### Common setup

```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "costCenterOwner",
    "label": "Responsavel",
    "controlType": "select",
    "resourcePath": "employees/options",
    "lookupIdKey": "matricula",
    "lookupLabelKey": "nome",
    "lookupSubtitleKey": "departamento",
    "lookupSeparator": " | ",
    "optionValueKey": "id",
    "optionLabelKey": "nome",
    "searchable": true,
    "searchPlaceholder": "pdx-inline-entity-lookup-common",
    "inlineAutoSize": {
      "minWidth": 156,
      "maxWidth": 420
    },
    "clearButton": {
      "enabled": true,
      "showOnlyWhenFilled": true
    }
  }
}
```

### Advanced setup

```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "costCenterOwner",
    "label": "Responsavel",
    "controlType": "select",
    "resourcePath": "employees/options",
    "lookupIdKey": "matricula",
    "lookupLabelKey": "nome",
    "lookupSubtitleKey": "departamento",
    "lookupSeparator": " | ",
    "optionValueKey": "id",
    "optionLabelKey": "nome",
    "searchable": true,
    "searchPlaceholder": "Buscar por matricula ou nome",
    "inlineAutoSize": {
      "minWidth": 156,
      "maxWidth": 420
    },
    "clearButton": {
      "enabled": true,
      "showOnlyWhenFilled": true
    }
  },
  "readonlyMode": false,
  "disabledMode": false
}
```

### Enterprise scenario

```json
{
  "componentId": "pdx-inline-entity-lookup",
  "metadata": {
    "name": "costCenterOwner",
    "label": "Responsavel",
    "controlType": "select",
    "resourcePath": "employees/options",
    "lookupIdKey": "matricula",
    "lookupLabelKey": "nome",
    "lookupSubtitleKey": "departamento",
    "lookupSeparator": " | ",
    "optionValueKey": "id",
    "optionLabelKey": "nome",
    "searchable": true,
    "searchPlaceholder": "Buscar por matricula ou nome",
    "inlineAutoSize": {
      "minWidth": 156,
      "maxWidth": 420
    },
    "clearButton": {
      "enabled": true,
      "showOnlyWhenFilled": true
    }
  },
  "presentationMode": true,
  "visible": true,
  "resourcePath": "/api/pdx-inline-entity-lookup"
}
```

## Compatibility and migration notes (recomendado)

| Concern | Affected versions | Migration action | Deadline | Notes |
| --- | --- | --- | --- | --- |
| No legacy path detected in current revision | n/a | No migration action required for canonical paths | n/a | Re-evaluate if backward-compat aliases are introduced |

## Known limitations and mismatches (recomendado)

| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
| --- | --- | --- | --- | --- | --- |
| Canonical contract parity | Runtime e exemplos desta referencia foram realinhados em 2026-03-16 para refletir fallbacks shared de placeholder e busca via `inlineSelect.*` | Manter exemplos e host overrides coerentes com o catalogo shared e evitar reintroduzir copy local | Low | n/a | Monitor in periodic audit |

## Source references (obrigatorio)

| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
| --- | --- | --- | --- | --- |
| runtime-code | projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
| runtime-code | projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
| schema-types | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |