@praxisui/dynamic-fields 8.0.0-beta.27 → 8.0.0-beta.29

package/index.d.ts

@@ -400,6 +400,10 @@ interface PraxisDynamicFieldsI18nOverrides {
     };
     multiSelect?: {
         selectAllLabel?: PraxisDynamicFieldText;
+        selectedTokensAriaLabel?: PraxisDynamicFieldText;
+        removeSelectionAriaLabel?: PraxisDynamicFieldText;
+        selectedPanelTitle?: PraxisDynamicFieldText;
+        selectedPanelRemoveHint?: PraxisDynamicFieldText;
     };
     transferList?: {
         availableLabel?: PraxisDynamicFieldText;
@@ -1454,6 +1458,11 @@ declare class DynamicFieldLoaderDirective implements OnInit, OnDestroy, OnChange
         field: FieldMetadata;
         element: HTMLElement;
     }>;
+    /** @internal Emits when a field receives focus in canvas mode */
+    canvasFocus: EventEmitter<{
+        field: FieldMetadata;
+        element: HTMLElement;
+    }>;
     /** Mapa interno de componentes criados */
     private componentRefs;
     /** Mapa de shells criados */
@@ -1584,7 +1593,7 @@ declare class DynamicFieldLoaderDirective implements OnInit, OnDestroy, OnChange
      */
     private inferControlTypeFromField;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DynamicFieldLoaderDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DynamicFieldLoaderDirective, "[dynamicFieldLoader]", never, { "fields": { "alias": "fields"; "required": true; }; "formGroup": { "alias": "formGroup"; "required": true; }; "enableExternalControlBinding": { "alias": "enableExternalControlBinding"; "required": false; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; }; "debugTrace": { "alias": "debugTrace"; "required": false; }; "debugTraceLabel": { "alias": "debugTraceLabel"; "required": false; }; "readonlyMode": { "alias": "readonlyMode"; "required": false; }; "disabledMode": { "alias": "disabledMode"; "required": false; }; "presentationMode": { "alias": "presentationMode"; "required": false; }; "visible": { "alias": "visible"; "required": false; }; "canvasMode": { "alias": "canvasMode"; "required": false; }; }, { "componentsCreated": "componentsCreated"; "fieldCreated": "fieldCreated"; "fieldDestroyed": "fieldDestroyed"; "renderError": "renderError"; "canvasMouseEnter": "canvasMouseEnter"; "canvasMouseLeave": "canvasMouseLeave"; "canvasClick": "canvasClick"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DynamicFieldLoaderDirective, "[dynamicFieldLoader]", never, { "fields": { "alias": "fields"; "required": true; }; "formGroup": { "alias": "formGroup"; "required": true; }; "enableExternalControlBinding": { "alias": "enableExternalControlBinding"; "required": false; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; }; "debugTrace": { "alias": "debugTrace"; "required": false; }; "debugTraceLabel": { "alias": "debugTraceLabel"; "required": false; }; "readonlyMode": { "alias": "readonlyMode"; "required": false; }; "disabledMode": { "alias": "disabledMode"; "required": false; }; "presentationMode": { "alias": "presentationMode"; "required": false; }; "visible": { "alias": "visible"; "required": false; }; "canvasMode": { "alias": "canvasMode"; "required": false; }; }, { "componentsCreated": "componentsCreated"; "fieldCreated": "fieldCreated"; "fieldDestroyed": "fieldDestroyed"; "renderError": "renderError"; "canvasMouseEnter": "canvasMouseEnter"; "canvasMouseLeave": "canvasMouseLeave"; "canvasClick": "canvasClick"; "canvasFocus": "canvasFocus"; }, never, never, true, never>;
 }
 
 declare class MaterialButtonComponent extends SimpleBaseButtonComponent implements OnDestroy {
@@ -2543,6 +2552,7 @@ declare class MaterialAsyncSelectComponent extends SimpleBaseSelectComponent {
     readonly termControl: FormControl<string | null>;
     readonly activeLookupFilters: _angular_core.WritableSignal<LookupFilterRequest[]>;
     readonly selectedLookupSortKey: _angular_core.WritableSignal<string | null>;
+    protected readonly remoteTotalElements: _angular_core.WritableSignal<number | null>;
     private readonly store;
     readonly endReached: _angular_core.WritableSignal<boolean>;
     private cursorAfter;
@@ -2676,6 +2686,15 @@ interface EntityLookupViewModel {
     detailHref: string;
     detailRoute: string;
     badges: string[];
+    richFields: EntityLookupRichFieldViewModel[];
+}
+interface EntityLookupRichFieldViewModel {
+    key: string;
+    label: string;
+    value: string;
+    icon: string;
+    presentation: string;
+    tone: LookupStatusTone | 'info';
 }
 interface LookupClearButtonConfig {
     enabled?: boolean;
@@ -2715,6 +2734,9 @@ type EntityLookupMetadata = MaterialEntityLookupMetadata & {
 };
 declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     private readonly dialog;
+    private readonly globalActions;
+    private readonly resourceDiscovery;
+    private readonly surfaceOpenAdapter;
     inlineMinWidthPx: number;
     inlineMaxWidthPx: number;
     private fieldLabelText;
@@ -2727,11 +2749,13 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     onViewportResize(): void;
     errorStateMatcher(): _angular_material_error_options_d_CGdTZUYk.E;
     protected getSpecificCssClasses(): string[];
+    selectPanelClasses(): string[];
     hasSelection(): boolean;
     selectedCount(): number;
     displayText(): string;
     richLayoutEnabled(): boolean;
     selectedCardLayout(): boolean;
+    selectedCompactLayout(): boolean;
     fullFieldLayout(): boolean;
     showFieldDependencyHint(): boolean;
     showFieldSearchHint(): boolean;
@@ -2742,6 +2766,7 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     selectedLookupViews(): EntityLookupViewModel[];
     visibleSelectedLookupTokens(): SelectedLookupTokenViewModel[];
     hiddenSelectedLookupTokenCount(): number;
+    isSelected(option: LookupOption): boolean;
     showSelectedTokenRemove(): boolean;
     selectedTokenRemoveAriaLabel(text: string): string;
     onRemoveSelectedToken(event: MouseEvent, identity: string): void;
@@ -2759,6 +2784,7 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     statusBadgeClass(item: EntityLookupViewModel): string;
     lookupInitials(item: EntityLookupViewModel): string;
     showDetailAction(item: EntityLookupViewModel): boolean;
+    private hasGovernedDetailSurface;
     showChangeAction(): boolean;
     showCopyCodeAction(item: EntityLookupViewModel): boolean;
     showCopyIdAction(item: EntityLookupViewModel): boolean;
@@ -2771,6 +2797,12 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     clearActionText(): string;
     selectionLimitReachedText(maxSelections: number | null | undefined): string;
     onDetailAction(event: MouseEvent, item: EntityLookupViewModel): void;
+    private openDetailSurface;
+    private tryOpenGovernedDetailSurface;
+    private itemSurfacesHref;
+    private selectDetailSurface;
+    private lookupDetailPresentation;
+    private detailSurfaceTitle;
     onChangeAction(event: MouseEvent): void;
     onCopyCodeAction(event: MouseEvent, item: EntityLookupViewModel): void;
     onCopyIdAction(event: MouseEvent, item: EntityLookupViewModel): void;
@@ -2865,6 +2897,12 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     private lookupStatusKeys;
     private resolveLookupSelectable;
     private lookupBadges;
+    richFieldToneClass(field: EntityLookupRichFieldViewModel): string;
+    private lookupRichFields;
+    private lookupRichFieldFromDescriptor;
+    private asRichFieldArray;
+    private formatLookupRichFieldValue;
+    private normalizeLookupTone;
     private classifyLookupSelectionState;
     private resolveStatusTone;
     private lookupSeparator;
@@ -2876,6 +2914,11 @@ declare class InlineEntityLookupComponent extends MaterialAsyncSelectComponent {
     private uniqueLookupKeys;
     private equalsOptionValue;
     private resolveLookupIdentity;
+    displayPreset(): string;
+    private displayDensity;
+    private lookupDisplayConfig;
+    private lookupDisplayBoolean;
+    private readLookupPath;
     private isPrimitiveLookupValue;
     private asRecord;
     private lookupOptionSource;
@@ -3018,6 +3061,12 @@ declare class EntityLookupDialogComponent implements AfterViewInit {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<EntityLookupDialogComponent, "pdx-entity-lookup-dialog", never, {}, {}, never, never, true, never>;
 }
 
+interface InlineMultiSelectTokenViewModel {
+    value: unknown;
+    text: string;
+    title: string;
+    trackKey: string;
+}
 declare class InlineMultiSelectComponent extends SimpleBaseSelectComponent {
     readonlyMode: boolean;
     disabledMode: boolean;
@@ -3037,9 +3086,18 @@ declare class InlineMultiSelectComponent extends SimpleBaseSelectComponent {
     hasSelection(): boolean;
     selectedCount(): number;
     displayText(): string;
+    selectedTokens(): InlineMultiSelectTokenViewModel[];
+    visibleSelectedTokens(): InlineMultiSelectTokenViewModel[];
+    hiddenSelectedTokenCount(): number;
+    hiddenSelectedTokenTitle(): string;
+    selectedTokensAriaLabel(): string;
+    selectedTokenRemoveAriaLabel(text: string): string;
+    selectedPanelTitle(): string;
+    selectedPanelRemoveHint(): string;
     showQuickClear(): boolean;
     onTriggerIconMouseDown(event: MouseEvent): void;
     onQuickClear(event: MouseEvent): void;
+    onRemoveSelectedToken(event: MouseEvent, value: unknown): void;
     onOpenedChange(opened: boolean): void;
     onSearchInput(term: string): void;
     onSearchInputEvent(event: Event): void;
@@ -3051,6 +3109,8 @@ declare class InlineMultiSelectComponent extends SimpleBaseSelectComponent {
     private currentValues;
     private resolveOptionLabel;
     private equalsOptionValue;
+    private maxVisibleSelectedTokens;
+    private stringifyTokenValue;
     private resolveFieldLabelFromMetadata;
     private humanizeFieldName;
     private recalculateInlineSizeBounds;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "8.0.0-beta.27",
+  "version": "8.0.0-beta.29",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
     "@angular/common": "^20.1.0",
@@ -11,8 +11,8 @@
     "@angular/platform-browser": "^20.1.0",
     "@angular/router": "^20.1.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^8.0.0-beta.27",
-    "@praxisui/cron-builder": "^8.0.0-beta.27"
+    "@praxisui/core": "^8.0.0-beta.29",
+    "@praxisui/cron-builder": "^8.0.0-beta.29"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",

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

@@ -22,8 +22,8 @@ source_of_truth:
   - "projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts"
   - "projects/praxis-dynamic-fields/src/lib/utils/format-display.util.ts"
   - "projects/praxis-core/src/lib/models/component-metadata.interface.ts"
-source_of_truth_last_verified: "2026-03-06"
-last_updated: "2026-03-06"
+source_of_truth_last_verified: "2026-05-18"
+last_updated: "2026-05-18"
 toc: true
 sidebar: true
 tags:
@@ -175,6 +175,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `canvasMouseEnter` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
 | `canvasMouseLeave` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
 | `canvasClick` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
+| `canvasFocus` | unknown | focusin runtime-event | Experimental | Emitted when a projected field receives focus in canvas mode so `praxis-dynamic-form` can select the field and show the canonical canvas toolbar. |
 
 ### External side channels
 
@@ -197,7 +198,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 
 | Surface | Verified | Coverage status | Evidence | Notes |
 | --- | --- | --- | --- | --- |
-| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/field-shell/field-shell.component.ts`, `projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts` | Core runtime flows verified via focused component specs on 2026-03-06; editor/tooling coverage remains independent. |
+| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/field-shell/field-shell.component.ts`, `projects/praxis-dynamic-fields/src/lib/utils/field-state.util.ts` | Core runtime flows verified via focused component specs on 2026-05-18, including canvas focus selection; 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` | Not-covered | `projects/praxis-core/src/lib/metadata/field-selector-control-type.constants.ts`, `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts` | `praxis-field-shell` nao aparece no selector map default nem no alias map inline; cobertura de editor/tooling permanece nao confirmada. |
 

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

@@ -121,6 +121,13 @@ Este documento e a referencia canonica da API JSON de pdx-inline-entity-lookup.
 | `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
 
@@ -159,6 +166,7 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
 | `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. |
@@ -312,10 +320,20 @@ Use quando precisar:
 | `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.hrefTemplate` / `metadata.optionSource.detail.routeTemplate` | `string` | Ativo | Gera links/rotas de detalhe quando o payload remoto nao trouxer `detailHref`/`detailRoute` em `extra`. |
+| `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` | `"card" | "inline" | "compact" | "token"` | Ativo | Para `controlType: "entityLookup"`, `card` e o default renderizam valor selecionado como cartao rico. `token` preserva leitura compacta. |
+| `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`. |
@@ -323,11 +341,11 @@ Use quando precisar:
 | `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. 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 `detailHref` ou `detailRoute`. Default: `true`. |
+| `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. |
@@ -344,8 +362,9 @@ Resumo de composicao deste componente:
 
 ### 4. Mapeamento de Comportamento
 - Para `controlType: "inlineEntityLookup"`, o trigger preserva valor compacto composto por `buildLookupPrimaryText(id,label)`.
-- Para `controlType: "entityLookup"`, o trigger pode renderizar cartao de entidade com avatar, codigo, label, descricao, status, badges e acoes.
-- Opcoes podem mostrar linha secundaria (`subtitle`) para desambiguacao; em `entityLookup`, a linha rica tambem mostra avatar, status visual, badges e motivo de bloqueio.
+- 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.
@@ -388,7 +407,27 @@ Uso: lookup simples em lista local.
       "descriptionPropertyPaths": ["departamento"],
       "statusPropertyPath": "status",
       "detail": {
-        "routeTemplate": "/employees/:id"
+        "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": " | ",