Praxis Fields Inline Overlay Runtime
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 compact inline filter controls in @praxisui/dynamic-fields. Inline controls are package-owned compact field renderers with a runtime/filter contract; they are not default form controls unless the authoring context is explicitly filter-focused.
Pair it with:
praxis-fields-runtime-loaderfor registry, loader, selector, and hot metadata behavior.praxis-dynamic-fields-editorialandpraxis-fields-editorial-discoveryfor inline catalog, descriptors, docs, and tooling discovery.praxis-fields-control-profile-aiwhen AI profiles or inline recipes need to understand overlay behavior.praxis-fields-text-number-time-controlsfor text, numeric, currency, date, time, period, and range value shapes.praxis-fields-selection-lookup-controlsfor select, async select, autocomplete, entity lookup, multi-select, tree, and chips behavior.praxis-table-runtime-dataor table/filter skills when the issue ispraxis-filterpromotion or emitted filter payloads.
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-inline-filter-runtime-contract.mddocs/dynamic-fields-inline-components-guide.mddocs/dynamic-fields-inline-filter-custom-component-guide.mddocs/dynamic-fields-inline-filter-catalog.mddocs/dynamic-fields-inline-filter-inventory.mddocs/dynamic-fields-inline-filter-selection-guide.mddocs/dynamic-fields-inline-filter-troubleshooting.mdsrc/lib/components/inline-*/**src/lib/components/collection-overlay/**src/lib/components/collection-search/**src/lib/components/material-date-range/date-range-shortcuts-overlay.component.tssrc/lib/utils/inline-display-mask.util.tsand specsrc/lib/i18n/dynamic-fields.i18n.tssrc/lib/i18n/dynamic-fields.en-US.tssrc/lib/i18n/dynamic-fields.pt-BR.tssrc/lib/catalog/dynamic-fields-playground.catalog.tssrc/lib/catalog/dynamic-fields-playground.recipes.tssrc/lib/catalog/catalog-derivation.spec.tssrc/lib/catalog/dynamic-fields-playground.catalog.spec.tssrc/lib/ai/inline-filter-recipes.spec.tssrc/lib/ai/control-type-ai-catalog.tsand specsrc/lib/services/component-registry/component-registry.service.tssrc/lib/directives/dynamic-field-loader.directive.tssrc/lib/directives/dynamic-field-loader.presentation-mode.spec.tssrc/lib/directives/dynamic-field-loader-global-states.spec.tssrc/lib/directives/dynamic-field-loader.metadata-refresh.spec.tssrc/lib/directives/dynamic-field-loader.select-rebind.spec.tssrc/lib/directives/dynamic-field-loader.skip-snapshot.spec.tsprojects/praxis-core/src/lib/utils/inline-filter-controls.util.tsand its specprojects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.tsand its promotion specsprojects/praxis-core/src/lib/tokens/layer-scale.token.tsprojects/praxis-core/src/lib/tokens/layer-scale.token.spec.tsprojects/praxis-metadata-editor/src/lib/ai/praxis-metadata-editor-authoring-manifest.tsprojects/praxis-metadata-editor/src/lib/ai/praxis-metadata-editor-authoring-manifest.spec.ts- affected
projects/praxis-metadata-editor/src/lib/config/*.config.tsfiles wheninlineOverlay.applyMode,inlineOverlay.actions.*, orclearButton.*metadata changes - focused inline component specs and
test-dev/e2e/*.playwright.spec.tswhen visual overlay behavior changes
Canonical Boundary
Dynamic Fields owns:
- canonical
inline*control types and runtime components; - package-owned
--pdx-inline-field-*and--pdx-inline-panel-*tokens; - inline field density, pill states, clear button behavior, context tooltip behavior, and component-level value shape;
inlineOverlay.applyModeand action metadata consumed by inline panels.- overlay action labels, aria labels, and shared inline copy through dynamic-fields i18n catalogs.
praxis-filter owns when generic controls are promoted to inline variants in filter toolbars. Backend metadata/range normalizers own the final HTTP payload shape.
Numeric Range Versus Period Identity
inlineYearRange and inlineMonthRange are numeric wrappers of
InlineRangeSliderComponent: they accept numeric { start, end } values or
numeric tuples and commit the numeric range shape. They are distinct canonical
control IDs, not aliases for inlinePeriodRange with injected granularity.
inlinePeriodRange owns its separate [string, string] period-value projection
and explicit granularity; date ranges also keep their own value contract.
Table's shared inline resolution/promotion preserves those IDs: generic year/month range controls in range mode become the matching numeric wrapper when inline-range promotion is enabled. Promotion must not replace them with period strings, fabricate granularity or change the backend DTO. Prove aliases, registry identity and Table metadata promotion against the existing components before updating fixtures or documenting a value shape.
Inline Overlay Rules
- Use
inlineOverlay.applyMode: "auto"for simple, reversible, single-step interactions. - Use
inlineOverlay.applyMode: "explicit"when a panel has draft state: ranges, multi-selection, presets, sliders, exploratory visual choices, or complex remote lookup. - In explicit mode, Apply commits, Cancel/Escape/outside close restores the last committed value, and Clear is distinct from Cancel.
- Closing an explicit overlay is not proof of commit. Audit the full cycle: open from the committed value, mutate draft state, close by Cancel/Escape/outside click, reopen with the committed value restored, then Apply and verify only the applied value emits.
- Draft state must be component-local and disposable. Do not let
FormControl/CVAonChange, filter payload emission, selected token display, or table filter promotion observe draft values before Apply in explicit mode. - Clear is a committed reset action only when invoked through the clear action. It must not be implemented as "cancel plus empty draft"; after Clear, reopen should reflect the cleared committed value and downstream filter payloads should receive the canonical empty value.
- Do not add local
confirm,commitPolicy, or per-component Apply/Cancel contracts wheninlineOverlay.actions.apply|cancel|clearcan represent the workflow. - Keep
clearButtonas rendering/runtime metadata. It is not backend payload. - Keep overlay labels and aria strings in dynamic-fields i18n catalogs; do not hardcode Apply/Cancel/Clear per inline component.
- Use
inline-display-maskfor display-only compact summaries. It must not mutate the committed value shape. - For inline selection/lookup overlays, combine explicit apply semantics with the option identity rules from
praxis-fields-selection-lookup-controls: draft tokens may be rendered in-panel, but committed chip text, selected display, and removal actions must remain based on canonical committed identity until Apply. - For inline multi-select panels, keep selected values available to the underlying selection control so Material/CDK can retain selection state, but exclude the same selected values from the regular unselected option list to avoid duplicate visible rows. Do not "fix" duplicate rows by dropping selected identities from the control option set.
- Presentation mode, skip snapshot, metadata refresh, select rebind, and global disabled/readonly/loading states must remain compatible with inline overlays.
- Metadata refresh or select rebind while an explicit overlay is open must either rebase draft state from the new committed metadata or close/cancel deterministically. Do not preserve stale draft option IDs after metadata/resource changes.
- Do not document component internal value shape as the final HTTP DTO; range normalization may happen later in host/backend contracts.
- Fix blocked overlays through shared layer/token contracts before adding host-only z-index or color overrides.
- Selection overlays must use the shared connected-overlay shell: trigger ownership, a sibling
header/search slot, one scrollable options region, and a sibling footer/action slot. Footer
content must be created only while the overlay is open; it must never be projected into a
MatSelecttrigger or option list. - Use the standard transparent CDK backdrop for deterministic outside-close semantics and keep the panel connected to the trigger with below-then-above positions, viewport push, and a viewport margin. Do not emulate outside close with competing document click handlers.
- Keep overflow inside the options region. Header and footer stay visible, short collections must
not gain a forced scrollbar, and long collections must have measurable
scrollHeight > clientHeight. Usescrollbar-gutter: autofor the shared options region unless a specific stable layout contract proves otherwise. - Prove focus and keyboard activation of footer actions while the panel remains open. Also prove
trigger/panel geometry at desktop and narrow widths; a unit test that only toggles
openedis not sufficient evidence for connected-overlay placement. - CDK stacking is owned by
@praxisui/corelayer scale tokens. Connected overlay panes must remain above CDK backdrops throughPRAXIS_LAYER_SCALE_*; do not patch individual inline components with one-off z-index values unless the shared layer contract is already correct and the issue is truly local. - Metadata-editor authoring for
inlineOverlay.applyModeandinlineOverlay.actions.*is part of the same contract. When runtime overlay behavior changes, verify the metadata-editor config and AI manifest can still author the same shared metadata instead of introducing component-local flags.
Inventory Before New Contract
ja-suportado-so-ux: the inline component or overlay contract exists but the chip, panel, tooltip, action, or docs do not make it clear.ja-suportado-mal-nomeado-ou-mal-materializado: a component uses local Apply/Cancel flags, local z-indexes, or host CSS whereinlineOverlay, tokens, or shared CDK layers already carry the semantics.suportado-parcialmente: runtime works but filter promotion, value shape docs, e2e overlay behavior, AI profile, or catalog discovery is incomplete.lacuna-real-de-contrato: noinline*control, overlay action contract, token, value shape, promotion rule, or docs/catalog path can represent the needed compact interaction.
Only real gaps justify new public metadata. Prefer completing inlineOverlay support before creating per-control contracts.
Validation
Use focused gates:
- Inline scalar/temporal/range component changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/inline-input/inline-input.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-number/inline-number.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-currency/inline-currency.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-currency-range/inline-currency-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-range-slider/inline-range-slider.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-date/inline-date.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-date-range/inline-date-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-time/inline-time.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-time-range/inline-time-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-period-range/inline-period-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-month-range/inline-month-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-year-range/inline-year-range.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-relative-period/inline-relative-period.component.spec.ts
- Inline selection/lookup component changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --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 --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/inline-tree-select/inline-tree-select.component.spec.ts
- Inline visual/status component changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-sentiment/inline-sentiment.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-pipeline-status/inline-pipeline-status.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-rating/inline-rating.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-distance-radius/inline-distance-radius.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-score-priority/inline-score-priority.component.spec.ts --include=projects/praxis-dynamic-fields/src/lib/components/inline-toggle/inline-toggle.component.spec.ts
- Shared display mask, registry, loader, metadata refresh, presentation mode, global states, or rebind behavior:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/utils/inline-display-mask.util.spec.ts --include=projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.spec.ts --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-global-states.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.metadata-refresh.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.select-rebind.spec.ts --include=projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.skip-snapshot.spec.ts
- Inline docs/catalog/AI/profile discovery changes:
npx ng test praxis-dynamic-fields --watch=false --progress=false --include=projects/praxis-dynamic-fields/src/lib/ai/inline-filter-recipes.spec.ts --include=projects/praxis-dynamic-fields/src/lib/ai/control-type-ai-catalog.spec.ts --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
- I18n/action label changes:
- Pair affected inline component specs with
metadata-i18n-contract.spec.tswhen catalog/editorial text changes.
- Pair affected inline component specs with
- Core layer scale changes:
- Add
projects/praxis-core/src/lib/tokens/layer-scale.token.spec.tswhen overlay clickability, backdrop ordering, or CDK z-index behavior changes.
- Add
- Shared collection overlay changes:
- include the focused
collection-overlay.component.spec.tsand affected selection component specs; - run
node tools/check-mat-select-content-model.mjs; - use
inline-searchable-select-panel-ux.playwright.spec.tsfor header/options/footer lifecycle, short/long overflow, theme tokens, keyboard load-more, and open-panel persistence; - use
inline-layout-overflow.playwright.spec.tsfor desktop/narrow trigger-panel geometry.
- include the focused
- Metadata-editor authoring changes:
- Add focused metadata-editor config/manifest specs when
inlineOverlay.applyMode,inlineOverlay.actions.*, orclearButton.*metadata is added, renamed, or reinterpreted.
- Add focused metadata-editor config/manifest specs when
- Playwright/e2e for overlay clickability, close behavior, Apply/Cancel/Clear, responsive layout, and theme contrast:
projects/praxis-dynamic-fields/test-dev/e2e/inline-all-components-smoke.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-date-range-visual.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-date-range-business-shortcuts.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-searchable-select-panel-ux.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-layout-overflow.playwright.spec.tsprojects/praxis-dynamic-fields/test-dev/e2e/inline-visual-states-design.playwright.spec.ts
- Table/filter payload validation when promotion or submitted filter DTO changes. For year/month/period distinctions, pair inline-filter-controls.util.spec.ts, the year/month/period component specs and PraxisFilter promotion specs. Assert canonical IDs, preserved metadata and numeric-versus-period values; do not repair stale fixtures by changing runtime/DTO semantics.
npm run build:praxis-dynamic-fieldsfor public API, metadata, token, i18n, or exported contract changes.
State which overlay behavior, visual contrast, registry, docs/catalog, and payload checks were run.