CustomSelectControlV2: fix popover styles

[ciampo]

What?

Extracted from #62424

Fix popover styles of CustomSelectControlV2 component

Why?

• To fix bugs related to the popover size and z stacking
• To match more closely behavior and look of V1 component

How?

• Adding max-height and overflow styles (in addition to the --popover-available-height Ariakit CSS variable) to make sure that the popover doesn't get too tall
• Adding a z-index matching the V1 component (and the legacy Popover)
• Switch to display: flex (it feels more appropriate for the layout we want to implement, and it handles better extra white space)

Testing Instructions

In the editor

To test in the editor, apply this patch

Click to expand

diff --git a/packages/block-editor/src/components/font-appearance-control/index.js b/packages/block-editor/src/components/font-appearance-control/index.js
index 18e814ad23..1340396c86 100644
--- a/packages/block-editor/src/components/font-appearance-control/index.js
+++ b/packages/block-editor/src/components/font-appearance-control/index.js
@@ -1,10 +1,20 @@
 /**
  * WordPress dependencies
  */
-import { CustomSelectControl } from '@wordpress/components';
+import {
+	CustomSelectControl,
+	privateApis as componentsPrivateApis,
+} from '@wordpress/components';
 import { useMemo } from '@wordpress/element';
 import { __, _x, sprintf } from '@wordpress/i18n';
 
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+const { CustomSelectControlV2Legacy } = unlock( componentsPrivateApis );
+
 const FONT_STYLES = [
 	{
 		name: _x( 'Regular', 'font style' ),
@@ -205,7 +215,7 @@ export default function FontAppearanceControl( props ) {
 
 	return (
 		hasStylesOrWeights && (
-			<CustomSelectControl
+			<CustomSelectControlV2Legacy
 				{ ...otherProps }
 				className="components-font-appearance-control"
 				label={ label }
diff --git a/packages/components/src/private-apis.ts b/packages/components/src/private-apis.ts
index f55373664e..9a26b7c7e3 100644
--- a/packages/components/src/private-apis.ts
+++ b/packages/components/src/private-apis.ts
@@ -14,6 +14,7 @@ import {
 	useCompositeStore as useCompositeStoreV2,
 } from './composite/v2';
 import { default as CustomSelectControl } from './custom-select-control';
+import { default as CustomSelectControlV2Legacy } from './custom-select-control-v2/legacy-component';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
 import { createPrivateSlotFill } from './slot-fill';
 import {
@@ -40,6 +41,7 @@ lock( privateApis, {
 	CompositeRowV2,
 	useCompositeStoreV2,
 	CustomSelectControl,
+	CustomSelectControlV2Legacy,
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
 	ComponentsContext,

2. Load the post editor
3. Select the block, and in the block toolbar, add the "Appearance" controls in the typography section
4. Open the select popover

Before (trunk)	After applying height + overflow fixees	After applying z-index fix

Known issues

The V2 version of the component automatically "flips" the popover to render on top of the trigger if there isn't enough space below it. In the specific example of the block toolbar, this causes a small visual glitch when the browser's viewport is short enough to cause the flip:

This glitch happens because the block toolbar's header has position: sticky, which causes it to render on top of the select popover despite a lower z-index. I haven't looked too much into it, but this feels like an issue that shouldn't be solved at the CustomSelectControl level (should we leverage popover slots?)

[github-actions]

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 props-bot label.

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: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

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

[github-actions]

Flaky tests detected in 540a0ee.
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.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/9680963724
📝 Reported issues:

• [Flaky Test] Redirection after template creation #60678 in /test/e2e/specs/site-editor/site-editor-url-navigation.spec.js

[mirka]

This is fine for legacy (and for the purposes of this PR), but I think we will also need a way for consumers to override this (#49110).

[ciampo]

That's a good point — not necessarily part of the tweaks to V2 legacy, but important to keep in mind for future work. It's also tracked in #55023