feat(context-selector): default topLayer to true for portal-safe rendering

[chdefrene]

Component Development

Type

• Feature

Reference to assignment

Refs equinor/fusion-core-tasks#1428
Refs equinor/fusion-web-components#2368 (coordinated PR adding the underlying topLayer property to @equinor/fusion-wc-searchable-dropdown)

Description of assignment

Context selector results are portal-owned UI that must render above whatever stacking context a hosting Fusion app happens to create, without app teams having to manage z-index themselves. equinor/fusion-web-components#2368 adds an opt-in, boolean topLayer property (default false, reflected as top-layer) to @equinor/fusion-wc-searchable-dropdown that renders the dropdown popover via the native Popover API / browser top layer, falling back to current behavior when unsupported. This PR is the React/shared-component half: it makes @equinor/fusion-react-context-selector enable that behavior by default, while leaving the generic @equinor/fusion-react-searchable-dropdown package's default unchanged.

Description of Proposed Changes

• @equinor/fusion-react-context-selector: ContextSelector (and, transitively, ContextSearch, which forwards unrecognized props) now defaults topLayer to true. Consumers can still explicitly pass topLayer={false} to opt back out — the existing prop surface already supports overriding it, no new API was introduced for this.
• @equinor/fusion-react-searchable-dropdown: no behavioral change. Dropdown/SearchableDropdown keep their generic default (topLayer unset/false), only gaining typed pass-through support for the new prop.
• Temporary ambient type augmentation (wc-searchable-dropdown.d.ts in both packages/searchable-dropdown/src and packages/context-selector/src — duplicated because this monorepo's TS project references don't propagate ambient augmentations across referenced projects): types topLayer on SearchableDropdownProps/SearchableDropdownElement today, ahead of the real upstream release. Heavily documented as temporary and safe to delete once the real dependency ships.
• Dependency: @equinor/fusion-wc-searchable-dropdown's changeset in fusion-web-components#2368 is minor from the current published 4.1.3, so the expected next release is 4.2.0 — not yet published (verified via npm view @equinor/fusion-wc-searchable-dropdown versions). The dependency range in both package.json files is intentionally left at ^4.1.1, which already permits 4.2.0 once published; explicitly bumping to ^4.2.0 today breaks bun install for the whole workspace since that version doesn't exist yet (verified). No bun.lock changes were needed as a result.
  • Runtime behavior today: @equinor/fusion-wc-searchable-dropdown prop-forwarding (extractElementProps in packages/utils) inspects the actual runtime prototype of the installed custom element class, not TypeScript types. Against the currently-installed 4.1.3 (which lacks topLayer), setting topLayer is a harmless no-op — it's treated as an unrecognized attribute. Once 4.2.0+ is installed, the exact same code starts rendering via the top layer with no further code changes required — only delete the two temporary .d.ts files.
• Docs: updated packages/context-selector/README.md and packages/searchable-dropdown/README.md with new sections explaining the default/opt-in behavior, override syntax, and the no-op caveat.
• Storybook: added a ContextHeaderTopLayerDisabled story and docs section. The story mirrors fusion-web-components#2368 with a transformed stacking-context container and a z-index: 999 overlay directly below the input, so toggling topLayer in Controls visibly demonstrates the result list moving above the overlay.
• Changesets: added minor changesets for both @equinor/fusion-react-context-selector and @equinor/fusion-react-searchable-dropdown.

Validation

• bun run build — full monorepo (21 packages) builds cleanly, including both touched packages.
• bun run storybook:build — Storybook production bundle builds successfully with the overlay story.
• bunx biome check — clean on all new/changed .ts/.tsx files covered by the repository Biome configuration.
• bunx changeset status — correctly reports minor bumps for both packages.
• Storybook tsc -b has pre-existing, unrelated TS errors across several packages; confirmed via git stash comparison that the exact same error set exists with and without this change (zero new errors introduced).
• bun run lint (biome, whole repo) — the ~40 warnings surfaced are all in pre-existing, unrelated files (e.g. scripts/publish.js); zero warnings in files touched by this change.

Known blocker / follow-up

• Upstream dependency: this draft PR is held until fusion-web-components#2368 publishes @equinor/fusion-wc-searchable-dropdown@4.2.0, so the temporary ambient augmentations can be removed, the real dependency explicitly installed, and top-layer behavior validated against the published package.

Checklist

Development

• Describe the component
• Code functional requirements
• Create stories
• Remove unused imports and commented code
• Lint code with Biome

Create Pull Request

• Assign relevant reviewers in Github and Cromatic
• Inform colleagues of pending reviews (Teams, fusion-frontend Code review channel)

Publish Code

• Increment version number
• Merge PR

---

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[changeset-bot]

🦋 Changeset detected

Latest commit: 9929fd3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@equinor/fusion-react-context-selector	Minor
@equinor/fusion-react-searchable-dropdown	Minor
@equinor/fusion-react-components-stories	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR