Praxis Fields Selection Lookup Controls
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 option-bearing and lookup controls in @praxisui/dynamic-fields. These controls are grounded by option identity and source semantics; they must not be reduced to labels, local arrays, or host-only search widgets.
Pair it with:
praxis-fields-option-sourcesfor backend option sources,RESOURCE_ENTITY, cascades, by-ids reload, dependency maps, and selected reload policies.praxis-fields-runtime-loaderfor runtime registration and loader behavior.praxis-fields-editorial-discoveryfor metadata, catalog, descriptors, JSON API docs, and selection guidance.praxis-fields-inline-overlay-runtimefor compact inline select/multi-select/autocomplete/lookup overlay behavior.praxis-fields-control-profile-aifor AI profiles such as select, entity lookup, tree select, list transfer, toggle, and chips-related capabilities.praxis-resource-entity-lookup-backendwhen backend entity lookup contracts change.
Source Audit
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.
Inspect:
projects/praxis-dynamic-fields/AGENTS.mdREADME.mddocs/dynamic-fields-field-catalog.mddocs/dynamic-fields-field-selection-guide.mddocs/dynamic-fields-inline-filter-runtime-contract.md- selection component folders under
src/lib/components/** src/lib/components/collection-overlay/**andsrc/lib/components/collection-search/**- selection
*.metadata.tsand*.json-api.md src/lib/base/option-store.tssrc/lib/base/simple-base-select.component.tssrc/lib/services/option-display-resolver.service.tssrc/lib/components/inline-entity-lookup/**src/lib/components/material-select/**src/lib/components/material-searchable-select/**src/lib/components/material-async-select/**src/lib/components/material-autocomplete/**src/lib/directives/autocomplete-layout.directive.tsand its mounted spec for Material autocomplete positioningsrc/lib/components/material-multi-select/**src/lib/components/material-multi-select-tree/**src/lib/components/material-tree-select/**src/lib/components/material-selection-list/**src/lib/components/material-transfer-list/**src/lib/components/material-chips/**src/lib/components/material-checkbox-group/**src/lib/components/material-radio-group/**src/lib/components/material-slide-toggle/**src/lib/components/material-button-toggle/**- inline selection folders such as
inline-select,inline-searchable-select,inline-async-select,inline-autocomplete,inline-multi-select, andinline-tree-select src/lib/ai/select-controls-ai-capabilities.tssrc/lib/ai/chips-controls-ai-capabilities.tssrc/lib/ai/list-controls-ai-capabilities.tssrc/lib/ai/tree-controls-ai-capabilities.tssrc/lib/ai/toggle-controls-ai-capabilities.tssrc/lib/ai/control-type-ai-catalog.tssrc/lib/ai/praxis-dynamic-fields-authoring-manifest.tsand specsrc/lib/editorial/wave1/material-select.editorial.tssrc/lib/editorial/wave1/entity-lookup.editorial.tssrc/lib/editorial/wave1/material-slide-toggle.editorial.tssrc/lib/editorial/metadata-contract.spec.tssrc/lib/editorial/metadata-i18n-contract.spec.tssrc/lib/catalog/dynamic-fields-playground.catalog.tsand catalog specsprojects/praxis-core/src/lib/helpers/field-definition-mapper.tsand spec when optionSource metadata is normalized from backend/schemaprojects/praxis-core/src/lib/tokens/collection-search.token.tsand spec when shared collection-search theming changesprojects/praxis-core/src/lib/services/schema-normalizer.service.tsand spec whenx-uioptionSource, value/display fields, cascades, or entity lookup contracts changeprojects/praxis-metadata-editor/src/lib/config/entity-lookup.config.tsprojects/praxis-metadata-editor/src/lib/config/inline-editor-coverage.spec.tswhen entity lookup, tree/list, selection policy, display, detail, or create affordance coverage changes- option-source and component specs
Canonical Families
- Simple selection:
select,radio,checkbox,buttonToggle,toggle. - Search/remote:
searchable-select,async-select,autoComplete,entityLookup. - Multiple/list/tree:
multiSelect,multiSelectTree,treeSelect,selectionList,transferList,chipInput,chipList. - Inline selection:
inlineSelect,inlineSearchableSelect,inlineAsyncSelect,inlineEntityLookup,inlineAutocomplete,inlineMultiSelect,inlineTreeSelect, plus specialized inline status/sentiment/color label controls when used as selections.
Runtime Rules
- Preserve value identity. Display labels are not persisted identity unless the canonical option contract says so.
- Treat value arrival and option arrival as independent asynchronous streams. A non-empty selected value that is not yet present in local options is a pending selection, not proof that the value is invalid. The control must preserve identity without emitting a synthetic change, repeatedly rewriting the CVA control, opening an overlay, or starting an unbounded reload loop.
- For genuinely local
metadata.options, hosts should keep a persisted/default value pending until the matching option is available. If the component accepts the value first, it must expose a deterministic unresolved state and reconcile exactly once when options arrive. Do not render a stale label from a previous context. - For remote or entity-backed sources, a selected ID absent from the current page must use the canonical by-ids/display rehydration path. Do not wait for the search page to happen to contain the selected ID, and do not clear the value while rehydration is in flight.
- Context changes must invalidate option display evidence from the previous context while
preserving only identities allowed by
selectionPolicy. Cancel or ignore stale async responses; a late response from company, tenant, dependency, or parent A must not resolve a pending selection under context B. - Prefer
optionSourcefor remote/entity-backed data and localoptionsonly for genuinely local lists. entityLookupshould use canonicalRESOURCE_ENTITYsemantics, stable value/display paths, by-ids rehydration when required, dependency maps, and selection policy.- For entity lookup, keep selection state (
selectable,blocked,legacy) distinct from generic disabled UI state.blockedprevents new selection;legacymay preserve an already selected invalid value only whenselectionPolicy.allowRetainInvalidExistingValueor equivalent backend evidence allows it. - Do not collapse
OptionDTO.extra.selectable,disabledReason,status,statusTone,badges,richFields, detail/create affordances, orselectionPolicyinto a plain{label,value,disabled}option unless the target control truly cannot express entity lookup semantics. Loss of those fields is a governance regression. - Payload shape is canonical. Use
payloadModeplus single/multiple semantics (id,ids,entityRef,entityRefs) consistently through display, edit, form submit, chips, dialogs, and table/filter consumers; do not infer payload shape from the current JavaScript value alone. - Selected-value reload must use by-ids/display paths when the source requires it; do not fake hydration with generic filter calls.
- Selected display outside the open panel should route through
OptionDisplayResolverService,OptionStore, or the owning select component path; do not persist labels as a shortcut for display. - Treat
OptionStoreby-id entries, including ephemeral selected options, as visibility/hydration evidence only. They may keep selected values visible until a page load replaces the display row, but they must not become persisted labels, local options, or a second source of lookup identity. - For dependent option sources, selected display/reopen must preserve the same structural filter
context used by the option-source runtime. If the component uses
filterCriteriafor loading, verify the by-ids path also receives that contextual filter. - Contextual selected reload is a first-class by-ids contract.
GenericCrudService.getOptionSourceOptionsByIds(...)posts{ filter, ids }when a filter is provided, and async selectpreloadSelected()must pass the same dependency context throughoptionSourceByIdsOptions(). A broadfilterOptionSourceOptionsrequest withincludeIdscan be compatibility evidence for option-source search, but it is not equivalent proof of edit/reopen selected hydration for dependent lookups. - A visible option while the panel is open is not proof of selected identity support. Prove closed display, presentation/read-only mode, edit/reopen, missing-ID behavior, and requested ID order.
- Legacy
valueField/displayFieldmust be normalized toward canonical option identity/display keys through the core mapper/normalizer; do not create a second alias layer in the component. searchable-select,async-select, and autocomplete need explicit search/load policy and clear value shape.- Governed lookup search is deterministic: auto-select one declared
searchStrategy; require an accessible chooser for multiple strategies and block HTTP while ambiguous. Apply strategy-specific minimum and input format before loading options; never guess intent from the typed term. - Tree controls require stable node identity and parent/children semantics.
- Chips/list/transfer controls must preserve array value shape, order policy, and max-selection rules. For remote/entity-backed chips, render labels from the canonical selected-display/by-ids path and preserve option identity even when the option is not present in the currently filtered page.
- Multi-select and chip removal must operate on canonical identity, not label text or object reference equality. If values can be
EntityRef, normalize comparison through the same identity extraction used by the payload serializer. - Toggle/radio/checkbox/button-toggle controls are still option-bearing when labels, values, disabled states, or i18n are derived from metadata; do not treat them as plain booleans unless the control contract is boolean.
- Inline selection overlays use
inlineOverlaywhen selections are drafted before commit. - Search, option rows, empty/loading states, and pagination actions must not be projected as
interactive descendants of
MatSelect. Use the shared collection overlay composition with sibling header, scrollable option region, and footer. KeepMatSelectonly where its panel owns actual Material option rows and every auxiliary action remains outside its trigger/content model. - Search UX shared by Dynamic Fields and Table must consume the canonical collection-search
variables/builders from
@praxisui/coreand the publicPdxCollectionSearchComponent; do not recreate radius, surface, foreground, border, focus, or placeholder tokens per consumer. - A remote
loadMoreaction is panel footer state, not an option. Render it only while the owning overlay is open and only when the loaded-page contract proves another page exists. Static option arrays and fully loaded first pages must not expose the action. - Dynamic Form, metadata-editor, table filters, CRUD dialogs, and host projects should consume the same identity/source contract. Do not fork lookup behavior per consumer.
- Treat Cockpit verifiers, HTTP examples, and LLM smokes as external evidence that lookup endpoints are reachable, not as proof that a generic select can replace
entityLookup. If the backend publishesRESOURCE_ENTITY, the Angular control must preserveentityKey,selectionPolicy,capabilities,selectable,disabledReason,status,statusTone, rich display fields, detail/create affordances, and retained-invalid-value semantics through open panel, closed display, edit/reopen, and presentation mode. - Do not use LLM operational examples or published HTTP payloads as a local shape contract for Ergon or another host. They can help diagnose the backend response, but the runtime shape must still flow through
OptionSourceMetadata,OptionDTO.extra,OptionDisplayResolverService,OptionStore, and the entity lookup component's view model. If those fields are not reaching the control, fix mapper/normalizer/runtime wiring before inventing a consumer adapter. - For dependent entity lookup, verify both the search path and selected-display path. A successful dependent filter example proves the lookup can search; it does not prove that already selected blocked/legacy values render correctly after reopen unless by-ids hydration also receives the mapped dependency context and preserves disabled reason/order.
Material Autocomplete During Layout Motion
For a misplaced autocomplete panel, inspect the installed Material/CDK version and actual connected origin, panel and ancestors before patching CSS. CDK can use a native popover outside the usual OverlayContainer; measure the actual DOM. Reuse the internal autocomplete-layout directive for Material async-select, autocomplete and inline-autocomplete inputs; it is not a new metadata flag or public API and does not replace the separate collection-overlay owner.
updatePosition() alone does not refresh width in the inspected Material version.
While the panel is already open, the public openPanel() path refreshes origin
and width without detaching, followed by public updatePosition(). Keep that
behavior covered by mounted tests when upgrading Material. Observe the declared
connected origin or form-field origin, not only the narrower input. Coalesce
origin resize and ancestor CSS transition/animation end or cancellation into one
animation frame; translations alone do not trigger ResizeObserver. Ignore unrelated
motion, guard browser capabilities and cancel observers/listeners/queued work on
close and destruction. Never reopen a closed panel from a queued callback or use
private overlay references, synthetic window resize, host offsets or polling.
Prove width and position change with the origin while value/CVA, active option and opened/closed counts remain stable. Include an external connected origin and missing ResizeObserver. Browser proof must also open during a tab transition plus viewport resize, then check desktop and narrow geometry, search/no-match, clear and keyboard selection; opening only after layout settles does not cover the race.
Inventory Before New Contract
ja-suportado-so-ux: options/source identity exists but UI, labels, selected display, empty state, or docs are weak.ja-suportado-mal-nomeado-ou-mal-materializado: host-local option arrays, display labels, aliases, or search endpoints duplicate canonicaloptionSource, value/display fields, or entity lookup semantics.suportado-parcialmente: runtime renders but selected reload, cascade dependency, metadata-editor coverage, AI profile, catalog, or inline overlay behavior is incomplete.lacuna-real-de-contrato: no current control type, option source contract, value identity, by-ids reload path, metadata path, profile, or validator can express the selection decision.
Only real gaps justify new metadata or backend contracts. Most select/lookup bugs should complete the existing option-source and profile chain.
Use praxis-angular-accessibility-governance for searchable-panel focus,
loading announcements, option naming, keyboard selection, and localized
calendar/lookup accessibility.
Validation
Use focused gates:
- Base option loading, display, selected reload, or identity changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/base/option-store.spec.ts --include=projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.spec.ts- Add the focused spec for
OptionDisplayResolverServicewhen one exists or create it with the behavior change; selected display/rehydration should not remain untested.
- Simple/search/remote/entity selection controls:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/material-select/material-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/material-async-select/material-async-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-select/inline-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/inline-async-select/inline-async-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-autocomplete/inline-autocomplete.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-entity-lookup/inline-entity-lookup.component.spec.ts
- Material autocomplete layout changes:
- Include
projects/praxis-dynamic-fields/src/lib/directives/autocomplete-layout.directive.spec.tsplus the affected Material async-select, autocomplete and inline-autocomplete component specs; mounted geometry tests complement the temporal browser proof above.
- Include
- Multi/list/tree/chips controls:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/material-multi-select/material-multi-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-multi-select-tree/material-multi-select-tree.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-tree-select/material-tree-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-tree-select/inline-tree-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-multi-select/inline-multi-select.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-selection-list/material-selection-list.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-transfer-list/material-transfer-list.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-chips/material-chips.component.spec.ts
- Toggle/radio/checkbox/button toggle controls:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/material-checkbox-group/material-checkbox-group.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-radio-group/material-radio-group.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-slide-toggle/material-slide-toggle.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/material-button-toggle/material-button-toggle.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-toggle/inline-toggle.component.spec.ts
- Registry/loader changes:
- Run the focused gates from
praxis-fields-runtime-loader, especiallycomponent-registry.service.spec.tswhen a selectioncontrolTypeis added or remapped.
- Run the focused gates from
- Core metadata normalization, optionSource,
RESOURCE_ENTITY, cascades, value/display fields, or by-ids changes:npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/helpers/field-definition-mapper.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
- Metadata/editorial/catalog discovery changes:
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
- AI profile/catalog changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --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
- Selected reload/reopen tests for remote/entity options:
- Include the relevant component spec plus
option-store/display resolver proof; add regression coverage before relying on manual QA.
- Include the relevant component spec plus
- Bootstrap-order regression tests for every changed option-bearing control:
- Cover value-before-options, options-before-value, selected ID absent after load, context change during load, and component destruction during load.
- Assert bounded calls/effects, no emitted user change during reconciliation, stable CVA value, deterministic unresolved display, and successful resolution when the matching option arrives.
- For shell/global-context usage, add a browser test with heartbeat,
requestAnimationFrame, DOM snapshot, open/select interaction, and a timeout that distinguishes locator/accessibility failure from a blocked main thread.
- Playwright for inline selection overlays, multi-select draft behavior, lookup UX, and contrast:
projects/praxis-dynamic-fields/test-dev/e2e/entity-lookup-procurement.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/entity-lookup-funcionarios.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-searchable-select-panel-ux.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-all-components-smoke.playwright.spec.ts
- Shared collection content model and search tokens:
- run the focused specs under
components/collection-overlayandcomponents/collection-search; - run
node tools/check-mat-select-content-model.mjsand keep the debt baseline empty; - prove square, intermediate, and pill search radii in Dynamic Fields and at least one direct consumer, including a narrow viewport at the shared-consumer level.
- run the focused specs under
- Direct consumer checks when a selection control is exposed through dynamic-form, metadata-editor, table filter, CRUD, or a host example.
- Metadata-editor coverage for entity lookup/selection controls:
- Add or run
projects/praxis-metadata-editor/src/lib/config/inline-editor-coverage.spec.tswhen metadata foroptionSource.display.*,selectionPolicy.*,capabilities.*,detail.*,create.*,payloadMode,multiple, or max-selection behavior changes.
- Add or run
npm run build:praxis-dynamic-fieldswhen public exports, metadata contracts, AI profiles, or package-owned control coverage changes.
State which runtime, option identity, selected reload, editor/tooling, AI profile, and overlay checks were run.