Skip to content

Autocomplete: Throw in development when Input is inside Popup - #86674

Merged
mirka merged 9 commits into
trunkfrom
autocomplete-input-inside-popup-guard
Nov 13, 2026
Merged

mirka merged 9 commits into
trunkfrom
autocomplete-input-inside-popup-guard

Conversation

@mirka

@mirka mirka commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

What?

Follow up to #86338 and #86520

Autocomplete.Input now throws an error in development when it is rendered inside Autocomplete.Popup. The error and a new JSDoc note on Autocomplete.Popup point to the pattern of an inline Autocomplete inside a standalone Popover component.

Why?

#86338 put the search input of its special character picker inside an Autocomplete.Popup that stayed open. That inserted focus guards before the content, which shifted the block in the editor, and it caused focus trapping problems. Autocomplete.Popup is the suggestion list for an input outside it. A picker that opens from a button should render an inline Autocomplete inside a standalone Popover component, as the InlineInPopover story from #86520 shows. A development error catches this mistake when it is made, instead of relying only on docs.

I think this is worth throwing an error, because not all cases fail in a noticeable way. And like we saw in the #86338 PR, a developer may fix it in a way that is both incomplete and increases complexity unnecessarily.

How?

Base UI's internals still handle an input inside the autocomplete popup, which Combobox documents as its "Input inside popup" pattern. For Autocomplete, the docs shipped with Base UI 1.9.0 showed it only in a "Grid layout" emoji picker that opened from Autocomplete.Trigger, and mui/base-ui#5636 has since removed that example and the "command pickers" usage guideline so that they do not read as officially supported. @wordpress/ui does not export Trigger, so this check rejects a composition that neither library documents for Autocomplete.

Testing Instructions

  1. In a story or a local file, render <Autocomplete.Root open> with <Autocomplete.Input> inside <Autocomplete.Popup>.
  2. In a development build, rendering throws an error that explains what Autocomplete.Popup is for and points to an inline Autocomplete inside a standalone Popover component.
  3. Open the existing Autocomplete stories, including "Inline In Popover", and the Menu usage guidelines story. They render without errors.

Autocomplete.Popup is the suggestion list for an input outside it. A search
input inside a kept-open popup inserts focus guards before the content and
traps focus. For a picker that opens from a button, render an inline
Autocomplete inside a Popover instead.
@mirka mirka added [Type] Enhancement A suggestion for improvement. [Package] UI /packages/ui labels Nov 11, 2026
@mirka mirka self-assigned this Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +31 B (0%)

Total Size: 8.65 MB

📦 View Changed
Filename Size Change
build/modules/workflow/index.min.js 42.1 kB +31 B (+0.07%)

4930458 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 9b83b04 trunk % Change
timeToFirstByte 57.6 ms +7.2% -4.34% 55.3 ms +7.05% -3.53% 4.16%
largestContentfulPaint 92 ms +6.52% -4.35% 84 ms +11.9% -4.76% 9.52%
lcpMinusTtfb 33.75 ms +14.07% -9.04% 28.1 ms +15.84% -3.56% 20.11%
wpBeforeTemplate 30.04 ms +8.06% -2.83% 29.52 ms +8.3% -3.9% 1.76%
wpTemplate 22.64 ms +8.3% -3% 21.62 ms +5.37% -1.43% 4.72%
wpTotal 53.81 ms +6.08% -4.78% 51.42 ms +7.31% -3.35% 4.65%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 9b83b04 trunk % Change
timeToFirstByte 46.3 ms +7.67% -1.19% 45.75 ms +7.1% -2.84% 1.2%
largestContentfulPaint 82 ms +2.44% -2.44% 80 ms +5% -2.5% 2.5%
lcpMinusTtfb 34.75 ms +6.62% -2.73% 34.25 ms +2.19% -4.23% 1.46%
wpBeforeTemplate 26.46 ms +6.2% -2.04% 26.22 ms +6.29% -2.75% 0.92%
wpTemplate 16.49 ms +3.7% -2.12% 16.38 ms +4.64% -3.48% 0.67%
wpTotal 43.11 ms +7.65% -1.67% 42.57 ms +8.08% -2.37% 1.27%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 9b83b04 trunk % Change
mediaProcessingJpeg 400.78 ms +1.72% -0.93% 401.82 ms +1.35% -0.25% -0.26%
mediaProcessingAvif 6127.96 ms +0.33% -0.06% 6149.9 ms +0.28% -0.07% -0.36%
mediaProcessingJpegToAvif 4233.28 ms +0.05% -0.18% 4249.8 ms +0.22% -0.37% -0.39%

media-upload

Metric 9b83b04 trunk % Change
jpegUploadProcessing 1760.51 ms +13.66% -14.27% 1530.21 ms +29.21% -2.07% 15.05%
pngUploadProcessing 271.1 ms +3.91% -5.27% 279.71 ms +1.73% -2.85% -3.08%
largeJpegUploadProcessing 1967.01 ms +1.07% -23.79% 1974.99 ms +1.25% -23.88% -0.4%
multipleImageUploadProcessing 2083.66 ms +0.05% -1.75% 2109.32 ms +3.94% -0.34% -1.22%

post-editor

Metric 9b83b04 trunk % Change
serverResponse 489.11 ms +1.94% -9.42% 452.14 ms +7.52% -1.15% 8.18%
firstPaint 441.78 ms +8.51% -9.53% 394.14 ms +12.4% -9.62% 12.09%
domContentLoaded 830.25 ms +7.76% -2.69% 809.91 ms +1.04% -0.86% 2.51%
loaded 831.32 ms +7.76% -2.68% 810.9 ms +1.1% -0.86% 2.52%
firstContentfulPaint 477.17 ms +10.34% -4.8% 453.84 ms +1.8% -1.44% 5.14%
firstBlock 2216.88 ms +2.61% -2.35% 2199.46 ms +0.59% -1.22% 0.79%
type 17.57 ms +6.26% -7.23% 16.85 ms +4.99% -5.1% 4.27%
typeWithoutInspector 16.86 ms +4.86% -9.13% 16.91 ms +4.14% -8.57% -0.3%
typeWithTopToolbar 22.8 ms +9.61% -14.04% 23.21 ms +2.37% -16.5% -1.77%
typeContainer 8.89 ms +1.57% -16.42% 8.34 ms +5.04% -5.64% 6.59%
focus 123.22 ms +10.35% -9.13% 112.3 ms +5.63% -2.83% 9.72%
firstFocus 252.61 ms +0% -0% 237.17 ms +0% -0% 6.51%
selectAll 422.41 ms +2.67% -1.35% 400.89 ms +1.95% -0.33% 5.37%
undo 29.08 ms +8.98% -7.02% 28.27 ms +6.79% -3.68% 2.87%
listViewOpen 76.38 ms +13.46% -4.41% 77.35 ms +9.46% -5.31% -1.25%
inserterOpen 43.85 ms +7.62% -4.2% 42.79 ms +8.93% -4.35% 2.48%
inserterHover 11.55 ms +8.05% -7.97% 11.45 ms +6.2% -8.12% 0.87%
inserterSearch 8.09 ms +6.43% -7.42% 8.42 ms +7.6% -7.96% -3.92%
loadPatterns 665.73 ms +4% -2.7% 650.05 ms +7.47% -5.16% 2.41%
wpTotal 478.77 ms +1.67% -9.46% 442.44 ms +7.68% -1.19% 8.21%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 9b83b04 trunk % Change
serverResponse 488.57 ms +0.88% -8.25% 476.52 ms +2.41% -7.26% 2.53%
firstPaint 454.55 ms +7.01% -9.35% 446.89 ms +6.74% -14.81% 1.71%
domContentLoaded 865.98 ms +1.89% -1.17% 852.19 ms +0.63% -0.56% 1.62%
loaded 867.26 ms +1.87% -1.19% 853.75 ms +0.6% -0.6% 1.58%
firstContentfulPaint 490.44 ms +1.97% -2.41% 477.66 ms +2.77% -1.12% 2.68%
firstBlock 2701.96 ms +0.41% -0.53% 2621.18 ms +1.38% -0.79% 3.08%
type 19.97 ms +2.95% -12.87% 20.3 ms +3.3% -14.78% -1.63%
navigate 131.11 ms +1.87% -1.11% 120.68 ms +5.59% -4.22% 8.64%
loadPatterns 1443.29 ms +12.15% -4.91% 1544.41 ms +5.04% -15.65% -6.55%
loadPages 979.01 ms +2.04% -0.8% 974.74 ms +5.26% -1.87% 0.44%
wpTotal 479 ms +0.86% -8.45% 466.58 ms +2.54% -7.34% 2.66%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

4930458 Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Undo restores the post selection when another synced entity is loaded in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 2,
+   "offset": 2,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
page-list submenu user interactions in /test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js, passed after 1 failed attempt.
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for getByRole('region', { name: 'Editor top bar' }).getByRole('button', { name: 'Save', exact: true })
    - locator resolved to <button type="button" aria-disabled="true" class="components-button editor-post-publish-button editor-post-publish-button__button is-primary is-compact">Save</button>
  - attempting click action
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
    - waiting 20ms
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
      - waiting 100ms
    15 × waiting for element to be visible, enabled and stable
       - element is not enabled
     - retrying click action
       - waiting 500ms

    at Editor.saveSiteEditorEntities (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/editor/site-editor.ts:39:22)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js:598:4
should reset a named font size using input field in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"small"} -->
+ <!-- wp:paragraph {"fontSize":"tiny"} -->
- <p class="has-small-font-size">Paragraph with font size reset using input field</p>
+ <p class="has-tiny-font-size">Paragraph with font size reset using input field</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:216:6
should reset a named font size using the tools panel menu in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"medium"} -->
+ <!-- wp:paragraph {"fontSize":"small"} -->
- <p class="has-medium-font-size">Paragraph with font size reset using tools panel menu</p>
+ <p class="has-small-font-size">Paragraph with font size reset using tools panel menu</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:178:6
submenu click on the arrow interactions in /test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js, passed after 1 failed attempt.
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for getByRole('region', { name: 'Editor top bar' }).getByRole('button', { name: 'Save', exact: true })
    - locator resolved to <button type="button" aria-disabled="true" class="components-button editor-post-publish-button editor-post-publish-button__button is-primary is-compact">Save</button>
  - attempting click action
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
    - waiting 20ms
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
      - waiting 100ms
    15 × waiting for element to be visible, enabled and stable
       - element is not enabled
     - retrying click action
       - waiting 500ms

    at Editor.saveSiteEditorEntities (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/editor/site-editor.ts:39:22)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js:506:4

4930458 Run

Reset the popup context in Root, so the check applies only to the input of
the autocomplete that owns the popup. Group the test with the other
composition checks and assert the full message.
@mirka
mirka marked this pull request as ready for review November 12, 2026 15:24
@mirka
mirka requested a review from a team as a code owner November 12, 2026 15:24

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regenerating the Storybook snapshot removes Autocomplete.Root>Autocomplete.Popup from storybook/prop-description-allowlist.json. Could you include that one-line deletion so the snapshot check passes?

@mirka
mirka requested a review from ciampo November 13, 2026 09:36

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🚀

@mirka
mirka enabled auto-merge (squash) November 13, 2026 09:53
# Conflicts:
#	packages/ui/CHANGELOG.md
@mirka
mirka merged commit 4d5f966 into trunk Nov 13, 2026
84 checks passed
@mirka
mirka deleted the autocomplete-input-inside-popup-guard branch November 13, 2026 10:14
@github-actions github-actions Bot added this to the Gutenberg 24.5 milestone Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] UI /packages/ui [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants