Praxis Fields Option Sources
This praxis-fields-* plus praxis-dynamic-fields-editorial skill family is the canonical Codex skill surface for @praxisui/dynamic-fields and projects/praxis-dynamic-fields; do not create parallel dynamic-fields guidance unless this family cannot express a proven contract gap.
Use this skill for select-like fields backed by canonical Praxis option sources. The goal is to prevent local autocomplete/select implementations when x-ui.optionSource, RESOURCE_ENTITY, async-select, searchable-select, or entityLookup already cover the workflow.
Canonical Boundary
- Backend metadata publishes
x-ui.optionSource.
@praxisui/core owns OptionSourceMetadata, GenericCrudService.filterOptionSourceOptions, GenericCrudService.getOptionSourceOptionsByIds, lookup DTOs, and resource discovery contracts.
@praxisui/dynamic-fields materializes option loading in SimpleBaseSelectComponent, MaterialAsyncSelectComponent, inline select variants, InlineEntityLookupComponent, OptionStore, and OptionDisplayResolverService.
- Backend
RESOURCE_ENTITY semantics belong with praxis-resource-entity-lookup-backend; this skill owns the Angular runtime/editorial consumption.
When backend metadata is wrong or incomplete, use praxis-metadata-domain-option-sources to audit @DomainGovernance, field access, x-ui.optionSource, entity lookup publication, selected reload policy, invalid sort policy, and filter/by-ids endpoints before adding Angular workarounds.
Do not route field intent through keywords such as "customer" or "status". Use the semantic optionSource contract, declared resource, and resolved controlType.
Required Inventory
First resolve the Angular workspace root. In the platform monorepo the files may live under
praxis-ui-angular/projects/...; in a standalone Angular checkout they may live directly under
projects/.... Audit the active praxis-ui-angular workspace, not stale issue worktrees such as
praxis-ui-angular-issue*, unless the user explicitly targets one of those worktrees.
Before editing, inspect:
src/lib/base/simple-base-select.component.ts
src/lib/base/option-store.ts
src/lib/services/option-display-resolver.service.ts
src/lib/components/inline-async-select/**
src/lib/components/inline-entity-lookup/**
src/lib/components/material-async-select/**
src/lib/components/material-searchable-select/**
src/lib/components/material-autocomplete/**
src/lib/components/material-select/**
src/lib/directives/dynamic-field-loader.presentation-mode.spec.ts
src/lib/directives/dynamic-field-loader.select-rebind.spec.ts
src/lib/base/pdx-base-select-runtime-contract.json-api.md
src/lib/ai/praxis-dynamic-fields-authoring-profiles.ts
src/lib/ai/praxis-dynamic-fields-authoring-manifest.ts and spec
src/lib/ai/inline-filter-recipes.spec.ts
src/lib/catalog/dynamic-fields-playground.catalog.ts and catalog specs
src/lib/editorial/wave1/entity-lookup.editorial.ts
src/lib/editorial/wave1/material-select.editorial.ts
src/lib/editorial/metadata-contract.spec.ts
src/lib/editorial/metadata-i18n-contract.spec.ts
- affected
material-select, material-searchable-select, material-async-select, inline-*select, or inline-entity-lookup component and spec
src/lib/components/**/pdx-*.json-api.md for public runtime claims
src/lib/editorial/** when the option-source field must be discoverable
projects/praxis-core/src/lib/models/option-source.model.ts and spec
projects/praxis-core/src/lib/services/types/options.ts
projects/praxis-core/src/lib/services/generic-crud.service.ts and spec
projects/praxis-core/src/lib/helpers/field-definition-mapper.ts and spec
projects/praxis-core/src/lib/helpers/metadata-normalizer.ts and spec
projects/praxis-core/src/lib/services/schema-normalizer.service.ts and spec
projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts
@praxisui/dynamic-form submit/runtime skills when selected value shape enters form payloads
@praxisui/metadata-editor cascade normalization skills when the editor authoring surface changes dependencies
- backend
x-ui.optionSource producer when the Angular runtime lacks required data
When the platform monorepo is available, inspect the backend option-source contract docs before
adding Angular fallbacks:
praxis-metadata-starter/README.md, especially the /option-sources/{sourceKey}/options/filter
and /options/by-ids checklist
praxis-metadata-starter/docs/guides/OPTION-SOURCE-PROVIDER-SPI.md
praxis-metadata-starter/docs/concepts/ui-schema.md when dependsOn,
dependencyFilterMap, or x-ui.optionSource publication changes
Option Source Rules
- Prefer
optionSource.key plus filterOptionSourceOptions(...) over ad hoc endpoints when the backend publishes an option source.
- Treat
filtering.searchStrategies as governed search intent. Auto-select the only declared strategy; when two or more exist, require an explicit accessible choice and do not send a search until it is selected. Never infer code, name, or document strategy from the entered text.
- Preserve the selected key as
searchStrategy in the option-source request. Apply its minSearchChars before HTTP. Honor inputFormat=digits with ASCII digits only; for kind=normalized-document, accept only digits plus spaces, periods, and hyphens, strip those visual separators, and apply the minimum to the normalized digits.
- Keep strategy validation provider-neutral and feedback safe. Do not expose the raw searched document, SQL, bindings, provider arguments, or backend exception text in UI messages, logs, metadata, or
OptionDTO.extra.
- Treat
optionSource.filterEndpoint and optionSource.byIdsEndpoint, when present in backend metadata, as execution evidence for the published contract. Angular code may route through GenericCrudService, but it must preserve the same source key, resource path, endpoint intent, and request envelope instead of synthesizing a different lookup route.
- Use
optionSource.resourcePath or the canonical resource path to configure the CRUD service; do not invent local routes or derive a path from label/value names.
- Treat option labels, translated display text, visible search results, local
options arrays, selected object labels, and OptionStore cached rows as presentation and hydration evidence only. Canonical identity is the selected value/id resolved through the configured value path plus the backend optionSource/entity lookup contract. Do not infer enum expansion, authorization, selectable policy, domain meaning, or backend validation from labels or currently loaded option rows.
- If Angular can only execute a deterministic legacy route because old metadata lacks endpoint publication, mark the path as compatibility and keep a diagnostic or test proving that backend publication is the desired fix. Do not normalize missing endpoints into a new local convention.
- Honor
optionSource.dependsOn and optionSource.dependencyFilterMap. Legacy dependencyFields and dependencyFilterMap may be runtime/manual metadata, but canonical backend-driven flows should come from optionSource.
- Convert dependency criteria to lookup filters through the existing option-source filter pipeline; do not encode dependency routing with local text matching.
- Honor
optionSource.includeIds. Send includeIds in filter requests only when the contract allows it.
- For selected-value hydration, prefer
getOptionSourceOptionsByIds(optionSource.key, ids, options) for option sources and getOptionsByIds(ids) only for generic resource options.
- For contextual selected-value reload, use the option-source by-ids endpoint with the same
structural filter context published by the backend. Do not rehydrate dependent selected IDs with
a generic unfiltered resource lookup when
selectedReloadPolicy says context matters.
- When
selectedReloadPolicy is required or supported, by-ids is part of the canonical proof for reopen/edit/presentation mode. A failure in by-ids should surface as an option-source contract or execution diagnostic, not silently degrade to a broad filter request that can display stale or unauthorized labels.
- When
selectedReloadPolicy is unsupported-with-waiver or the source lacks capabilities.byIds, the UI may preserve already available object labels/local options, but must label the scenario partial and avoid claiming full edit/reopen support.
- When the host
FilterDTO has fields named search, sort, filters, or includeIds, use the
explicit option-source request envelope (filter, filters, search, sort, includeIds) so
structural resource filters do not collide with option-source execution metadata.
byIds responses should contain concrete options only; missing IDs are omitted, and runtime/UI
code must not manufacture null options as if the backend selected value still existed.
- Preserve the requested ID order when displaying by-ids results. Backend and executor should already
normalize this, but Angular code should not reshuffle selected-value reloads by page/search order.
- Preserve
entityKey, selectionPolicy, capabilities, display property paths, status/disabled fields, and rich display fields when mapping backend lookup results to select/display DTOs. Those fields are governance evidence, not optional decoration for entity lookup.
- Presentation/read-only mode still needs selected display proof. Use by-ids/display resolver coverage; a working open panel does not prove saved values render after reopen.
- Presentation mode is a separate selected-display path through
FieldShellComponent and
OptionDisplayResolverService; do not assume the async/select component's preloadSelected()
proof covers read-only rendering. For dependent option sources, either prove the display resolver
receives the same dependency context for by-ids hydration, or mark presentation/reopen support as
partial and fix that display path instead of persisting labels locally.
- Preserve
selectedReloadPolicy, invalidSortPolicy, and backend waivers in UX/tooling claims. If by-ids reload is not supported, mark the scenario partial instead of pretending edit/reopen is fully supported.
- Respect
invalidSortPolicy: with reject, do not send arbitrary UI sort keys or fallback to client-side resorting as if the backend had accepted the request; with ignore or unsupported, explain the degraded sort behavior in diagnostics/tooling.
- Keep categorical buckets distinct: when the source is
CATEGORICAL_BUCKET, default loading/search behavior may intentionally differ from free-text remote search.
- Keep legacy top-level
valueField, displayField, dependencyFields, and dependencyFilterMap as compatibility inputs only. Canonical backend-driven flows should normalize through OptionSourceMetadata, mapper/normalizer specs, and runtime option-source filters.
- Do not infer
dependencyLoadOnChange, reset policy, or reload policy from dependsOn unless the canonical contract declares it.
- Keep dynamic-form and table/filter consumers aligned: the same
optionSource decision should drive form controls, inline filters, metadata-editor authoring, and CRUD/table lookup displays without host-local duplication.
- Treat Cockpit verifiers, HTTP examples, and LLM smokes as external evidence that a backend contract is reachable, not as permission to duplicate lookup semantics in Angular. If a published example demonstrates
dependencyFilterMap, by-ids order, invalid-value display, provider-backed lookup, or governed materialization, the Angular runtime still must consume the canonical OptionSourceMetadata/GenericCrudService pipeline rather than copying the example payload or translating fields locally per screen.
- When debugging an Ergon migration or another consumer, first prove whether Angular received
optionSource.dependsOn, dependencyFilterMap, filterEndpoint, byIdsEndpoint, selectedReloadPolicy, and invalidSortPolicy from /schemas/filtered. If the metadata is present but the UI does not materialize it, fix the Angular mapper/runtime. If it is absent, route to metadata/config ownership; do not add a screen-specific workaround.
- For dependent selected-value hydration, preserve the same mapped dependency context used by the filter request when calling
getOptionSourceOptionsByIds. A working smoke:llm-surface example or Cockpit reachability check does not prove edit/reopen correctness unless the Angular by-ids path also receives the contextual filter.
Entity Lookup
Use entityLookup / inlineEntityLookup for corporate entity selection when the backend publishes RESOURCE_ENTITY semantics, rich display fields, selection state, dependency requirements, create/detail affordances, or lookup filtering/sorting.
- For Resource Quick View on reference and lookup fields (
@ResourceReference, x-ui.resourceReference, optionSource.detail.resourceKey, or explicit quickView), resolve the binding via resolveFieldQuickViewBinding(field) in @praxisui/core (which protects against optionSource.valuePropertyPath: 'id' colliding with the parent entity's own 'id').
- In
view / presentation mode, FieldShellComponent binds [praxisQuickView] (hover-and-click) on .praxis-presentation__value when a single reference ID is present.
- In
edit / create mode, MaterialAsyncSelectComponent (data-testid="async-select-quick-view-action") and InlineEntityLookupComponent (data-testid="entity-lookup-quick-view-action", data-testid="entity-lookup-dialog-quick-view-action") must strictly use trigger: 'explicit-button' (openImmediate) and never hover on editable inputs, lazy-resolving ResourceQuickViewService via Injector so shell topbar mounts do not eagerly instantiate GlobalActionService.
Pair with praxis-fields-selection-lookup-controls when the task also touches select, chips, tree,
list, inline selection overlays, option identity UI, or AI control-family guidance. Keep this skill
as the owner for backend option-source semantics, cascades, by-ids reload, and selected reload
policies.
Do not replace entity lookup with a plain async select unless the canonical metadata lacks entity semantics. If metadata lacks semantics but the domain requires them, fix the backend option-source contract instead of creating a local UI convention.
Validation
Minimum focused checks:
- Core option-source contracts and metadata normalization:
npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/models/option-source.model.spec.ts --include=projects/praxis-core/src/lib/services/generic-crud.service.spec.ts --include=projects/praxis-core/src/lib/helpers/field-definition-mapper.spec.ts --include=projects/praxis-core/src/lib/helpers/metadata-normalizer.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer.service.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts
- Base option-source behavior, dependency filters,
includeIds, and selected reload:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/base/option-store.spec.ts
- Display/hydration and presentation mode:
- Add or run focused
OptionDisplayResolverService coverage for by-ids/display path behavior.
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.presentation-mode.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.select-rebind.spec.ts
- Async/searchable/autocomplete controls:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-async-select/inline-async-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-searchable-select/material-searchable-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-searchable-select/inline-searchable-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-autocomplete/material-autocomplete.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-autocomplete/inline-autocomplete.component.spec.ts
- Entity lookup and
RESOURCE_ENTITY semantics:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.spec.ts
- Editor/tooling/catalog/AI discovery when metadata/editorial claims change:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/catalog/catalog-derivation.spec.ts --include=projects/praxis-dynamic-fields/src/lib/catalog/dynamic-fields-playground.catalog.spec.ts --include=projects/praxis-dynamic-fields/src/lib/editorial/metadata-contract.spec.ts --include=projects/praxis-dynamic-fields/src/lib/editorial/metadata-i18n-contract.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/control-type-ai-catalog.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/praxis-dynamic-fields-authoring-manifest.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/inline-filter-recipes.spec.ts
- Downstream materialization: dynamic-form, metadata-editor, table/filter, or CRUD smoke only when the option-source contract changed for that consumer. Useful focused examples include:
projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-select-interaction.playwright.spec.ts
projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-cascades.playwright.spec.ts
projects/praxis-crud/test-dev/e2e/funcionarios-edit-hydration-gap.playwright.spec.ts
projects/praxis-crud/test-dev/e2e/funcionarios-modal-select-overlay.playwright.spec.ts
projects/praxis-table/test-dev/e2e/filter-inline-metadata-editor.playwright.spec.ts
npm run build:praxis-dynamic-fields when public dynamic-fields contracts or metadata claims change.
- Build/test the direct consumer when option-source normalization changes a public core contract.
Always audit reopen/edit and presentation mode for selected values. A filter request that loads a page is not proof that a saved selected ID can be displayed later.
For backend-aligned option-source work, include a negative check for fields named search, sort,
filters, or includeIds and a by-ids check that verifies missing IDs are omitted and returned
options preserve requested order.
When governed search strategies change, also prove: ambiguous multi-strategy input makes no HTTP
request; a single strategy is transported automatically; invalid digits input is blocked;
normalized-document is normalized before transport; and minSearchChars is evaluated after that
normalization.
1---2name: praxis-fields-option-sources3description: Use when implementing or reviewing @praxisui/dynamic-fields or praxis-dynamic-fields package option-source controls, async selects, searchable selects, entity lookup, `RESOURCE_ENTITY` lookup projections, selected-value reload by IDs, dependency filters, option display resolution, `GenericCrudService` option APIs, or backend `x-ui.optionSource` materialization in Angular fields.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-fields-option-sources6---78# Praxis Fields Option Sources910This `praxis-fields-*` plus `praxis-dynamic-fields-editorial` skill family is the canonical Codex skill surface for `@praxisui/dynamic-fields` and `projects/praxis-dynamic-fields`; do not create parallel dynamic-fields guidance unless this family cannot express a proven contract gap.1112Use this skill for select-like fields backed by canonical Praxis option sources. The goal is to prevent local autocomplete/select implementations when `x-ui.optionSource`, `RESOURCE_ENTITY`, `async-select`, `searchable-select`, or `entityLookup` already cover the workflow.1314## Canonical Boundary1516- Backend metadata publishes `x-ui.optionSource`.17- `@praxisui/core` owns `OptionSourceMetadata`, `GenericCrudService.filterOptionSourceOptions`, `GenericCrudService.getOptionSourceOptionsByIds`, lookup DTOs, and resource discovery contracts.18- `@praxisui/dynamic-fields` materializes option loading in `SimpleBaseSelectComponent`, `MaterialAsyncSelectComponent`, inline select variants, `InlineEntityLookupComponent`, `OptionStore`, and `OptionDisplayResolverService`.19- Backend `RESOURCE_ENTITY` semantics belong with `praxis-resource-entity-lookup-backend`; this skill owns the Angular runtime/editorial consumption.2021When backend metadata is wrong or incomplete, use `praxis-metadata-domain-option-sources` to audit `@DomainGovernance`, field access, `x-ui.optionSource`, entity lookup publication, selected reload policy, invalid sort policy, and filter/by-ids endpoints before adding Angular workarounds.2223Do not route field intent through keywords such as "customer" or "status". Use the semantic `optionSource` contract, declared resource, and resolved `controlType`.2425## Required Inventory2627First resolve the Angular workspace root. In the platform monorepo the files may live under28`praxis-ui-angular/projects/...`; in a standalone Angular checkout they may live directly under29`projects/...`. Audit the active `praxis-ui-angular` workspace, not stale issue worktrees such as30`praxis-ui-angular-issue*`, unless the user explicitly targets one of those worktrees.3132Before editing, inspect:3334- `src/lib/base/simple-base-select.component.ts`35- `src/lib/base/option-store.ts`36- `src/lib/services/option-display-resolver.service.ts`37- `src/lib/components/inline-async-select/**`38- `src/lib/components/inline-entity-lookup/**`39- `src/lib/components/material-async-select/**`40- `src/lib/components/material-searchable-select/**`41- `src/lib/components/material-autocomplete/**`42- `src/lib/components/material-select/**`43- `src/lib/directives/dynamic-field-loader.presentation-mode.spec.ts`44- `src/lib/directives/dynamic-field-loader.select-rebind.spec.ts`45- `src/lib/base/pdx-base-select-runtime-contract.json-api.md`46- `src/lib/ai/praxis-dynamic-fields-authoring-profiles.ts`47- `src/lib/ai/praxis-dynamic-fields-authoring-manifest.ts` and spec48- `src/lib/ai/inline-filter-recipes.spec.ts`49- `src/lib/catalog/dynamic-fields-playground.catalog.ts` and catalog specs50- `src/lib/editorial/wave1/entity-lookup.editorial.ts`51- `src/lib/editorial/wave1/material-select.editorial.ts`52- `src/lib/editorial/metadata-contract.spec.ts`53- `src/lib/editorial/metadata-i18n-contract.spec.ts`54- affected `material-select`, `material-searchable-select`, `material-async-select`, `inline-*select`, or `inline-entity-lookup` component and spec55- `src/lib/components/**/pdx-*.json-api.md` for public runtime claims56- `src/lib/editorial/**` when the option-source field must be discoverable57- `projects/praxis-core/src/lib/models/option-source.model.ts` and spec58- `projects/praxis-core/src/lib/services/types/options.ts`59- `projects/praxis-core/src/lib/services/generic-crud.service.ts` and spec60- `projects/praxis-core/src/lib/helpers/field-definition-mapper.ts` and spec61- `projects/praxis-core/src/lib/helpers/metadata-normalizer.ts` and spec62- `projects/praxis-core/src/lib/services/schema-normalizer.service.ts` and spec63- `projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts`64- `@praxisui/dynamic-form` submit/runtime skills when selected value shape enters form payloads65- `@praxisui/metadata-editor` cascade normalization skills when the editor authoring surface changes dependencies66- backend `x-ui.optionSource` producer when the Angular runtime lacks required data6768When the platform monorepo is available, inspect the backend option-source contract docs before69adding Angular fallbacks:7071- `praxis-metadata-starter/README.md`, especially the `/option-sources/{sourceKey}/options/filter`72 and `/options/by-ids` checklist73- `praxis-metadata-starter/docs/guides/OPTION-SOURCE-PROVIDER-SPI.md`74- `praxis-metadata-starter/docs/concepts/ui-schema.md` when `dependsOn`,75 `dependencyFilterMap`, or `x-ui.optionSource` publication changes7677## Option Source Rules7879- Prefer `optionSource.key` plus `filterOptionSourceOptions(...)` over ad hoc endpoints when the backend publishes an option source.80- Treat `filtering.searchStrategies` as governed search intent. Auto-select the only declared strategy; when two or more exist, require an explicit accessible choice and do not send a search until it is selected. Never infer code, name, or document strategy from the entered text.81- Preserve the selected key as `searchStrategy` in the option-source request. Apply its `minSearchChars` before HTTP. Honor `inputFormat=digits` with ASCII digits only; for `kind=normalized-document`, accept only digits plus spaces, periods, and hyphens, strip those visual separators, and apply the minimum to the normalized digits.82- Keep strategy validation provider-neutral and feedback safe. Do not expose the raw searched document, SQL, bindings, provider arguments, or backend exception text in UI messages, logs, metadata, or `OptionDTO.extra`.83- Treat `optionSource.filterEndpoint` and `optionSource.byIdsEndpoint`, when present in backend metadata, as execution evidence for the published contract. Angular code may route through `GenericCrudService`, but it must preserve the same source key, resource path, endpoint intent, and request envelope instead of synthesizing a different lookup route.84- Use `optionSource.resourcePath` or the canonical resource path to configure the CRUD service; do not invent local routes or derive a path from label/value names.85- Treat option labels, translated display text, visible search results, local `options` arrays, selected object labels, and `OptionStore` cached rows as presentation and hydration evidence only. Canonical identity is the selected value/id resolved through the configured value path plus the backend `optionSource`/entity lookup contract. Do not infer enum expansion, authorization, selectable policy, domain meaning, or backend validation from labels or currently loaded option rows.86- If Angular can only execute a deterministic legacy route because old metadata lacks endpoint publication, mark the path as compatibility and keep a diagnostic or test proving that backend publication is the desired fix. Do not normalize missing endpoints into a new local convention.87- Honor `optionSource.dependsOn` and `optionSource.dependencyFilterMap`. Legacy `dependencyFields` and `dependencyFilterMap` may be runtime/manual metadata, but canonical backend-driven flows should come from `optionSource`.88- Convert dependency criteria to lookup filters through the existing option-source filter pipeline; do not encode dependency routing with local text matching.89- Honor `optionSource.includeIds`. Send `includeIds` in filter requests only when the contract allows it.90- For selected-value hydration, prefer `getOptionSourceOptionsByIds(optionSource.key, ids, options)` for option sources and `getOptionsByIds(ids)` only for generic resource options.91- For contextual selected-value reload, use the option-source by-ids endpoint with the same92 structural filter context published by the backend. Do not rehydrate dependent selected IDs with93 a generic unfiltered resource lookup when `selectedReloadPolicy` says context matters.94- When `selectedReloadPolicy` is `required` or `supported`, by-ids is part of the canonical proof for reopen/edit/presentation mode. A failure in by-ids should surface as an option-source contract or execution diagnostic, not silently degrade to a broad `filter` request that can display stale or unauthorized labels.95- When `selectedReloadPolicy` is `unsupported-with-waiver` or the source lacks `capabilities.byIds`, the UI may preserve already available object labels/local options, but must label the scenario partial and avoid claiming full edit/reopen support.96- When the host `FilterDTO` has fields named `search`, `sort`, `filters`, or `includeIds`, use the97 explicit option-source request envelope (`filter`, `filters`, `search`, `sort`, `includeIds`) so98 structural resource filters do not collide with option-source execution metadata.99- `byIds` responses should contain concrete options only; missing IDs are omitted, and runtime/UI100 code must not manufacture `null` options as if the backend selected value still existed.101- Preserve the requested ID order when displaying by-ids results. Backend and executor should already102 normalize this, but Angular code should not reshuffle selected-value reloads by page/search order.103- Preserve `entityKey`, `selectionPolicy`, `capabilities`, display property paths, status/disabled fields, and rich display fields when mapping backend lookup results to select/display DTOs. Those fields are governance evidence, not optional decoration for entity lookup.104- Presentation/read-only mode still needs selected display proof. Use by-ids/display resolver coverage; a working open panel does not prove saved values render after reopen.105- Presentation mode is a separate selected-display path through `FieldShellComponent` and106 `OptionDisplayResolverService`; do not assume the async/select component's `preloadSelected()`107 proof covers read-only rendering. For dependent option sources, either prove the display resolver108 receives the same dependency context for by-ids hydration, or mark presentation/reopen support as109 partial and fix that display path instead of persisting labels locally.110- Preserve `selectedReloadPolicy`, `invalidSortPolicy`, and backend waivers in UX/tooling claims. If by-ids reload is not supported, mark the scenario partial instead of pretending edit/reopen is fully supported.111- Respect `invalidSortPolicy`: with `reject`, do not send arbitrary UI sort keys or fallback to client-side resorting as if the backend had accepted the request; with `ignore` or `unsupported`, explain the degraded sort behavior in diagnostics/tooling.112- Keep categorical buckets distinct: when the source is `CATEGORICAL_BUCKET`, default loading/search behavior may intentionally differ from free-text remote search.113- Keep legacy top-level `valueField`, `displayField`, `dependencyFields`, and `dependencyFilterMap` as compatibility inputs only. Canonical backend-driven flows should normalize through `OptionSourceMetadata`, mapper/normalizer specs, and runtime option-source filters.114- Do not infer `dependencyLoadOnChange`, reset policy, or reload policy from `dependsOn` unless the canonical contract declares it.115- Keep dynamic-form and table/filter consumers aligned: the same `optionSource` decision should drive form controls, inline filters, metadata-editor authoring, and CRUD/table lookup displays without host-local duplication.116- Treat Cockpit verifiers, HTTP examples, and LLM smokes as external evidence that a backend contract is reachable, not as permission to duplicate lookup semantics in Angular. If a published example demonstrates `dependencyFilterMap`, by-ids order, invalid-value display, provider-backed lookup, or governed materialization, the Angular runtime still must consume the canonical `OptionSourceMetadata`/`GenericCrudService` pipeline rather than copying the example payload or translating fields locally per screen.117- When debugging an Ergon migration or another consumer, first prove whether Angular received `optionSource.dependsOn`, `dependencyFilterMap`, `filterEndpoint`, `byIdsEndpoint`, `selectedReloadPolicy`, and `invalidSortPolicy` from `/schemas/filtered`. If the metadata is present but the UI does not materialize it, fix the Angular mapper/runtime. If it is absent, route to metadata/config ownership; do not add a screen-specific workaround.118- For dependent selected-value hydration, preserve the same mapped dependency context used by the filter request when calling `getOptionSourceOptionsByIds`. A working `smoke:llm-surface` example or Cockpit reachability check does not prove edit/reopen correctness unless the Angular by-ids path also receives the contextual filter.119120## Entity Lookup121122Use `entityLookup` / `inlineEntityLookup` for corporate entity selection when the backend publishes `RESOURCE_ENTITY` semantics, rich display fields, selection state, dependency requirements, create/detail affordances, or lookup filtering/sorting.123124- For **Resource Quick View** on reference and lookup fields (`@ResourceReference`, `x-ui.resourceReference`, `optionSource.detail.resourceKey`, or explicit `quickView`), resolve the binding via `resolveFieldQuickViewBinding(field)` in `@praxisui/core` (which protects against `optionSource.valuePropertyPath: 'id'` colliding with the parent entity's own `'id'`).125- In **`view` / `presentation` mode**, `FieldShellComponent` binds `[praxisQuickView]` (`hover-and-click`) on `.praxis-presentation__value` when a single reference ID is present.126- In **`edit` / `create` mode**, `MaterialAsyncSelectComponent` (`data-testid="async-select-quick-view-action"`) and `InlineEntityLookupComponent` (`data-testid="entity-lookup-quick-view-action"`, `data-testid="entity-lookup-dialog-quick-view-action"`) must strictly use `trigger: 'explicit-button'` (`openImmediate`) and never hover on editable inputs, lazy-resolving `ResourceQuickViewService` via `Injector` so shell topbar mounts do not eagerly instantiate `GlobalActionService`.127128Pair with `praxis-fields-selection-lookup-controls` when the task also touches select, chips, tree,129list, inline selection overlays, option identity UI, or AI control-family guidance. Keep this skill130as the owner for backend option-source semantics, cascades, by-ids reload, and selected reload131policies.132133Do not replace entity lookup with a plain async select unless the canonical metadata lacks entity semantics. If metadata lacks semantics but the domain requires them, fix the backend option-source contract instead of creating a local UI convention.134135## Validation136137Minimum focused checks:138139- Core option-source contracts and metadata normalization:140 - `npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/models/option-source.model.spec.ts --include=projects/praxis-core/src/lib/services/generic-crud.service.spec.ts --include=projects/praxis-core/src/lib/helpers/field-definition-mapper.spec.ts --include=projects/praxis-core/src/lib/helpers/metadata-normalizer.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer.service.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts`141- Base option-source behavior, dependency filters, `includeIds`, and selected reload:142 - `npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/base/option-store.spec.ts`143- Display/hydration and presentation mode:144 - Add or run focused `OptionDisplayResolverService` coverage for by-ids/display path behavior.145 - `npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.presentation-mode.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.select-rebind.spec.ts`146- Async/searchable/autocomplete controls:147 - `npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/material-async-select/material-async-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-async-select/inline-async-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-searchable-select/material-searchable-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-searchable-select/inline-searchable-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-autocomplete/material-autocomplete.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-autocomplete/inline-autocomplete.component.spec.ts`148- Entity lookup and `RESOURCE_ENTITY` semantics:149 - `npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.spec.ts`150- Editor/tooling/catalog/AI discovery when metadata/editorial claims change:151 - `npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/catalog/catalog-derivation.spec.ts --include=projects/praxis-dynamic-fields/src/lib/catalog/dynamic-fields-playground.catalog.spec.ts --include=projects/praxis-dynamic-fields/src/lib/editorial/metadata-contract.spec.ts --include=projects/praxis-dynamic-fields/src/lib/editorial/metadata-i18n-contract.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/control-type-ai-catalog.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/praxis-dynamic-fields-authoring-manifest.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/inline-filter-recipes.spec.ts`152- Downstream materialization: dynamic-form, metadata-editor, table/filter, or CRUD smoke only when the option-source contract changed for that consumer. Useful focused examples include:153 - `projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-select-interaction.playwright.spec.ts`154 - `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-cascades.playwright.spec.ts`155 - `projects/praxis-crud/test-dev/e2e/funcionarios-edit-hydration-gap.playwright.spec.ts`156 - `projects/praxis-crud/test-dev/e2e/funcionarios-modal-select-overlay.playwright.spec.ts`157 - `projects/praxis-table/test-dev/e2e/filter-inline-metadata-editor.playwright.spec.ts`158- `npm run build:praxis-dynamic-fields` when public dynamic-fields contracts or metadata claims change.159- Build/test the direct consumer when option-source normalization changes a public core contract.160161Always audit reopen/edit and presentation mode for selected values. A filter request that loads a page is not proof that a saved selected ID can be displayed later.162163For backend-aligned option-source work, include a negative check for fields named `search`, `sort`,164`filters`, or `includeIds` and a by-ids check that verifies missing IDs are omitted and returned165options preserve requested order.166167When governed search strategies change, also prove: ambiguous multi-strategy input makes no HTTP168request; a single strategy is transported automatically; invalid `digits` input is blocked;169`normalized-document` is normalized before transport; and `minSearchChars` is evaluated after that170normalization.