[ui] Tooltip: Default portal container to the wp compat overlay slot#78095
Merged
Conversation
|
Flaky tests detected in 0b5ab9d. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25807760468
|
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
4 times, most recently
from
51511ba to
175a123
Compare
|
Size Change: +534 B (+0.01%) Total Size: 7.96 MB 📦 View Changed
ℹ️ View Unchanged
|
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
5 times, most recently
from
9ae3d4a to
360b1fb
Compare
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
from
360b1fb to
5ddc222
Compare
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
7 times, most recently
from
271e9fb to
0b5ab9d
Compare
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
mirka
approved these changes
May 13, 2026
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
from
0b5ab9d to
1f4767d
Compare
Contributor
Author
|
All feedback addressed. |
Wire `Tooltip.Portal` to default its `container` prop to the `@wordpress/ui` compat overlay slot (when the runtime opts in via WordPress detection or the explicit window flag). A caller-supplied `container` prop continues to take precedence (props are spread after the default). Adds three integration tests in `packages/ui/src/tooltip/test` covering: popup is portaled into the slot when the gate is open; slot is not created when the gate is closed (dormant default); and caller-supplied containers override the slot default. Adds a Storybook decorator (`WithWpCompatOverlaySlot`) that opts a single story into the slot and cleans up on unmount, plus demonstration stories: per-component (`Inside WP Compat Overlay Slot`) and cross-library (`@wordpress/ui` Tooltip inside `@wordpress/components` Modal/Popover) under `Playground/WP Compat Overlay Slot`. This is a sample wiring of the prime-slot infrastructure for one leaf overlay; it doubles as the end-to-end stacking validator for the helper introduced upstream.
The decorator previously lived in `storybook/decorators/`, but per-component stories under `packages/ui/src/tooltip/stories/` imported it from there — a `packages/ui` → `storybook/` cross-package boundary violation. Move it to `packages/ui/src/utils/with-wp-compat-overlay-slot.tsx`, co-located with the helper it opts into. The Tooltip story now imports it as a same-package file. The cross-library demo under `storybook/stories/playground/` imports it via `packages/ui/src/...` which is the normal upper-level → package import direction. Drive-by: now imports `WP_COMPAT_OVERLAY_SLOT_ATTRIBUTE` from the helper module instead of hardcoding the data attribute string.
The hook landed in #77851 alongside the dormant compat overlay slot infrastructure, and goes live for end users once Tooltip starts portaling into the slot (this PR). README documentation has been intentionally deferred to this PR so the public-API copy lands alongside a real consumer. Adds a "Mixing with @wordpress/components" subsection under "Setup -> Elsewhere" — the only place a host actually needs to call the hook (standard WordPress editor screens auto-enable the slot via the window.wp.components global and don't need it).
Drops references to the underlying overlay library by name from the
three docblocks/header comments added in this PR. Rewords each to
describe the relevant behavior in library-agnostic terms ("the default
portal container", "Tooltip.Portal", "the default portal"). No code
changes.
Moves the decorator out of `@wordpress/ui` (where it had ended up to avoid a `packages/ui` → `storybook/` cross-boundary dependency for the per-component Tooltip story) and into the same directory as the only remaining consumer, the cross-library Playground story. The dedicated `Inside WP Compat Overlay Slot` Tooltip story is removed along with the move. The decorator mutates a window-level flag that's process-wide across the Storybook preview iframe, so applying it to per-component stories made the opt-in leak into every sibling story rendered on the same autodocs page. Keeping the decorator next to the single playground story that needs it confines the leak blast radius to the playground; cross-library stacking remains the end-to-end validator for the slot.
Tighten and align the JSDoc on `Portal` and `Positioner` subcomponents across `Tooltip`, `Popover`, `Select`, `Autocomplete`, `Drawer`, `Dialog`, and `AlertDialog` to a single-sentence "Used to apply custom <feature> to <Component>'s <content>" cadence. The prop listings and "Pass to X.Popup's `portal`/`positioner` prop" boilerplate are documented by the TypeScript types — the docblock no longer duplicates them.
ciampo
force-pushed
the
try/wp-compat-overlay-slot-tooltip
branch
from
1f4767d to
031f0e6
Compare
This was referenced May 15, 2026
ciampo
added a commit
that referenced
this pull request
May 15, 2026
Compresses JSDoc, inline comments, prose, and CHANGELOG/README copy added by #77851, #78095, and #78183 down to the essentials. Public API docs keep the "what / when / two opt-in paths" guidance; internal narration and implementation reasoning that the code already conveys are dropped or compressed. No behavior changes.
ciampo
added a commit
that referenced
this pull request
May 15, 2026
Compresses JSDoc, inline comments, prose, and README copy added by #77851, #78095, and #78183 down to the essentials. Public API docs keep the "what / when / two opt-in paths" guidance; internal narration and implementation reasoning that the code already conveys is dropped or compressed. No behavior changes.
ciampo
added a commit
that referenced
this pull request
May 16, 2026
Mirrors the Tooltip wiring from #78095: `Select.Portal` defaults its `container` to the `@wordpress/ui` compat overlay slot, so select popups (including `SelectControl`, which wraps `Select` internally) stack reliably above `@wordpress/components` overlays in mixed-library compositions. A caller-supplied `Select.Portal` `container` prop continues to take precedence.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Wires
Tooltip.Portal'scontainerto default to the wp compat overlay slot from #77851. End-to-end validator for the slot infrastructure: with this in place,@wordpress/uiTooltips stack reliably above@wordpress/componentsoverlays in mixed-library compositions, with no per-instance plumbing.A caller-supplied
Tooltip.Portalcontainercontinues to take precedence. No behavior change for@wordpress/ui-only consumers.Testing Instructions
Unit
npx jest --config=test/unit/jest.config.js --testPathPattern='packages/ui/src/tooltip/test/index'Expected: 8 passing (5 pre-existing + 3 new under
wp compat overlay slot).Storybook (cross-library stacking)
Open Playground / WP Compat Overlay Slot / Tooltip inside @wordpress/components Modal. Click Open Modal, hover Hover me: the
@wordpress/uiTooltip popup renders above the Modal, portaled into[data-wp-compat-overlay-slot]. Same for the Popover story.In any other (un-decorated) story — e.g. Design System / Components / Tooltip / Default — confirm the dormant baseline: the popup uses the default portal container and
[data-wp-compat-overlay-slot]is absent from the DOM.Editor (auto-detect, real consumer)
The slot auto-detects
window.wp.components, which is on the global in the WordPress editor. To exercise the wiring end-to-end against a real editor consumer, swap an existing@wordpress/componentsTooltipusage for a@wordpress/uione.Example patch — Inspector Controls tabs
Then
npm run dev, open a post in the editor, select a block (for example, the Image block), and hover the icon-only tabs at the top of the Inspector Controls sidebar (Settings / Styles / List View). The tab tooltips are now@wordpress/uiTooltips; in DevTools, confirm they portal into[data-wp-compat-overlay-slot]ondocument.body.Files touched
packages/ui/src/tooltip/portal.tsx— the wiring itself.packages/ui/src/tooltip/test/index.test.tsx— 3 new integration tests under awp compat overlay slotdescribe block. Opt-in tests render a wrapper component that callsuseEnableWpCompatOverlaySlot(), mirroring real-consumer usage rather than poking at the internal flag.packages/ui/README.md— documentsuseEnableWpCompatOverlaySlot()under a new "Mixing with@wordpress/components" subsection.storybook/stories/playground/wp-compat-overlay-slot.story.jsx— cross-library demo.storybook/stories/playground/with-wp-compat-overlay-slot.tsx— Storybook decorator that flips the gate during the playground story's lifetime. Kept private to the playground (not shared across per-component stories) because the opt-in flag is process-wide onwindow, and applying the decorator to per-component stories would leak the gate into sibling stories rendered on the same Storybook autodocs page.Next Steps
Wire the rest of
@wordpress/ui's overlays the same way in subsequent PRs..components-draggable__clonemigrates onto the slot in #78183 so an active drag stays above it.Use of AI Tools
Authored with Cursor (Claude). Author reviewed all changes.