# Praxis Fields Inline Overlay Runtime

> Praxis Fields Inline Overlay Runtime

- Skill: `codexrodrigues/praxis-fields-inline-overlay-runtime` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-fields-inline-overlay-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-fields-inline-overlay-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-fields-inline-overlay-runtime

---


# 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-loader` for registry, loader, selector, and hot metadata behavior.
- `praxis-dynamic-fields-editorial` and `praxis-fields-editorial-discovery` for inline catalog, descriptors, docs, and tooling discovery.
- `praxis-fields-control-profile-ai` when AI profiles or inline recipes need to understand overlay behavior.
- `praxis-fields-text-number-time-controls` for text, numeric, currency, date, time, period, and range value shapes.
- `praxis-fields-selection-lookup-controls` for select, async select, autocomplete, entity lookup, multi-select, tree, and chips behavior.
- `praxis-table-runtime-data` or table/filter skills when the issue is `praxis-filter` promotion 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.md`
- `README.md`
- `docs/dynamic-fields-inline-filter-runtime-contract.md`
- `docs/dynamic-fields-inline-components-guide.md`
- `docs/dynamic-fields-inline-filter-custom-component-guide.md`
- `docs/dynamic-fields-inline-filter-catalog.md`
- `docs/dynamic-fields-inline-filter-inventory.md`
- `docs/dynamic-fields-inline-filter-selection-guide.md`
- `docs/dynamic-fields-inline-filter-troubleshooting.md`
- `src/lib/components/inline-*/**`
- `src/lib/components/collection-overlay/**`
- `src/lib/components/collection-search/**`
- `src/lib/components/material-date-range/date-range-shortcuts-overlay.component.ts`
- `src/lib/utils/inline-display-mask.util.ts` and spec
- `src/lib/i18n/dynamic-fields.i18n.ts`
- `src/lib/i18n/dynamic-fields.en-US.ts`
- `src/lib/i18n/dynamic-fields.pt-BR.ts`
- `src/lib/catalog/dynamic-fields-playground.catalog.ts`
- `src/lib/catalog/dynamic-fields-playground.recipes.ts`
- `src/lib/catalog/catalog-derivation.spec.ts`
- `src/lib/catalog/dynamic-fields-playground.catalog.spec.ts`
- `src/lib/ai/inline-filter-recipes.spec.ts`
- `src/lib/ai/control-type-ai-catalog.ts` and spec
- `src/lib/services/component-registry/component-registry.service.ts`
- `src/lib/directives/dynamic-field-loader.directive.ts`
- `src/lib/directives/dynamic-field-loader.presentation-mode.spec.ts`
- `src/lib/directives/dynamic-field-loader-global-states.spec.ts`
- `src/lib/directives/dynamic-field-loader.metadata-refresh.spec.ts`
- `src/lib/directives/dynamic-field-loader.select-rebind.spec.ts`
- `src/lib/directives/dynamic-field-loader.skip-snapshot.spec.ts`
- `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts` and its spec
- `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts` and its promotion specs
- `projects/praxis-core/src/lib/tokens/layer-scale.token.ts`
- `projects/praxis-core/src/lib/tokens/layer-scale.token.spec.ts`
- `projects/praxis-metadata-editor/src/lib/ai/praxis-metadata-editor-authoring-manifest.ts`
- `projects/praxis-metadata-editor/src/lib/ai/praxis-metadata-editor-authoring-manifest.spec.ts`
- affected `projects/praxis-metadata-editor/src/lib/config/*.config.ts` files when
  `inlineOverlay.applyMode`, `inlineOverlay.actions.*`, or `clearButton.*` metadata changes
- focused inline component specs and `test-dev/e2e/*.playwright.spec.ts` when 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.applyMode` and 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`/CVA `onChange`, 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 when `inlineOverlay.actions.apply|cancel|clear` can represent the workflow.
- Keep `clearButton` as 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-mask` for 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
  `MatSelect` trigger 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`. Use `scrollbar-gutter: auto` for 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 `opened` is not
  sufficient evidence for connected-overlay placement.
- CDK stacking is owned by `@praxisui/core` layer scale tokens. Connected overlay panes must remain
  above CDK backdrops through `PRAXIS_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.applyMode` and `inlineOverlay.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 where `inlineOverlay`, 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`: no `inline*` control, overlay action contract, token, value shape, promotion rule, or docs/cata­log 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.ts` when catalog/editorial text changes.
- Core layer scale changes:
  - Add `projects/praxis-core/src/lib/tokens/layer-scale.token.spec.ts` when overlay clickability,
    backdrop ordering, or CDK z-index behavior changes.
- Shared collection overlay changes:
  - include the focused `collection-overlay.component.spec.ts` and affected selection component specs;
  - run `node tools/check-mat-select-content-model.mjs`;
  - use `inline-searchable-select-panel-ux.playwright.spec.ts` for header/options/footer lifecycle,
    short/long overflow, theme tokens, keyboard load-more, and open-panel persistence;
  - use `inline-layout-overflow.playwright.spec.ts` for desktop/narrow trigger-panel geometry.
- Metadata-editor authoring changes:
  - Add focused metadata-editor config/manifest specs when `inlineOverlay.applyMode`,
    `inlineOverlay.actions.*`, or `clearButton.*` metadata is added, renamed, or reinterpreted.
- 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.ts`
  - `projects/praxis-dynamic-fields/test-dev/e2e/inline-date-range-visual.playwright.spec.ts`
  - `projects/praxis-dynamic-fields/test-dev/e2e/inline-date-range-business-shortcuts.playwright.spec.ts`
  - `projects/praxis-dynamic-fields/test-dev/e2e/inline-searchable-select-panel-ux.playwright.spec.ts`
  - `projects/praxis-dynamic-fields/test-dev/e2e/inline-layout-overflow.playwright.spec.ts`
  - `projects/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-fields` for public API, metadata, token, i18n, or exported contract changes.

State which overlay behavior, visual contrast, registry, docs/catalog, and payload checks were run.

