@wordpress/ui 0.12.1-next.v.202604201441.0 → 0.13.0

package/src/utils/css/item-popup.module.css

@@ -1,17 +1,5 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
-/*
- * Temporary workaround for a Base UI tabbability regression with
- * checkVisibility() and display: contents.
- * See: https://github.com/mui/base-ui/issues/4622
- *
- * This must stay outside the CSS layers to override ThemeProvider's
- * unlayered display: contents.
- */
-[data-wpds-theme-provider-id]:has(> .popup) {
-	display: block;
-}
-
 @layer wp-ui-utilities {
 	.popup {
 		composes: dropdown-motion from "./dropdown-motion.module.css";
@@ -25,7 +13,7 @@
 		min-width: var(--anchor-width);
 		max-width: var(--available-width);
 		border-radius: var(--wpds-border-radius-md);
-		border: 1px solid var(--wpds-color-stroke-surface-neutral);
+		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		box-shadow: var(--wpds-elevation-md);
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
 		font-family: var(--wpds-typography-font-family-body);
@@ -57,7 +45,7 @@
 		padding-block: var(--wp-ui-popup-padding);
 
 		.list-scrollable-container:not(:empty) + & {
-			border-block-start: 1px solid var(--wpds-color-stroke-surface-neutral);
+			border-block-start: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		}
 	}
 
@@ -67,12 +55,10 @@
 		--wp-ui-popup-item-padding-inline: 12px;
 		--wp-ui-popup-item-padding-block: 4px;
 
-		display: grid;
-		grid-template-columns: 24px 1fr;
+		display: flex;
 		align-items: center;
 		justify-content: flex-start;
 		gap: var(--wpds-dimension-gap-xs);
-		cursor: var(--wpds-cursor-control);
 		min-height: var(--wp-ui-popup-item-height);
 		border-radius: var(--wpds-border-radius-sm);
 		user-select: none;
@@ -83,6 +69,10 @@
 		padding-inline-start: calc(var(--wp-ui-popup-item-padding-inline) - 4px);
 		padding-inline-end: var(--wp-ui-popup-item-padding-inline);
 
+		&:not([data-disabled]) {
+			cursor: var(--wpds-cursor-control);
+		}
+
 		&.is-size-compact {
 			--wp-ui-popup-item-height: 32px;
 			--wp-ui-popup-item-padding-inline: 8px;
@@ -103,6 +93,7 @@
 		&[data-highlighted]:not([aria-disabled="true"]) {
 			background-color: var(--wpds-color-bg-interactive-brand-weak-active);
 			color: var(--wpds-color-fg-interactive-neutral);
+			outline: none; /* Disable user agent focus ring */
 
 			@media ( forced-colors: active ) {
 				outline: 1px solid Highlight;
@@ -118,23 +109,22 @@
 		}
 	}
 
-	.item-indicator {
-		justify-self: center;
+	.item-indicator-icon {
+		flex-shrink: 0;
 	}
 
-	.empty {
+	/* Only style when there is content, because otherwise the element would block clicks
+	on the .list beneath it (both share grid-area: main and overlap). */
+	.empty:not(:empty) {
 		--wp-ui-popup-empty-min-height: 40px;
 		--wp-ui-popup-empty-padding-inline: 12px;
 
 		grid-area: main;
 		display: flex;
 		align-items: center;
+		min-height: var(--wp-ui-popup-empty-min-height);
 		padding-inline: var(--wp-ui-popup-empty-padding-inline);
 		color: var(--wpds-color-fg-content-neutral-weak);
-
-		&:not(:empty) {
-			min-height: var(--wp-ui-popup-empty-min-height);
-		}
 	}
 
 }

package/src/utils/css/overlay-chrome.module.css

@@ -0,0 +1,239 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	/*
+	 * Shared chrome + scroll-container primitives for overlay popups
+	 * (Dialog, AlertDialog, Drawer).
+	 *
+	 * Layout model: the popup is a vertical flex column with three regions
+	 * — `.header`, `.content`, `.footer`. Only `.content` scrolls; the
+	 * chrome sits at the popup's block-axis edges as natural flex siblings.
+	 *
+	 * Sticky opt-out for `Dialog` / `Drawer` is expressed in the DOM by
+	 * placing `Dialog.Header` / `Dialog.Footer` (or the Drawer equivalents)
+	 * inside `Dialog.Content` / `Drawer.Content` so they scroll with the
+	 * body; AlertDialog exposes the same choice via `stickyHeader` /
+	 * `stickyFooter` props, since it owns its internal DOM.
+	 */
+
+	/*
+	 * Chrome: flex row, no background (the popup already paints it), no
+	 * sticky positioning. Block-axis padding is asymmetric: the outer
+	 * side (popup edge) uses `padding-2xl` to match the inset that used
+	 * to live on the popup; the inner side (toward `.content`) uses the
+	 * tokenized `gap-lg` in full.
+	 *
+	 * No separator border here — the base chrome has none. The pinned
+	 * case (where a separator is needed) adds a `border-block-*: 1px
+	 * solid transparent` on the inner side and subtracts 1px from that
+	 * same padding so the chrome's overall border-box height stays
+	 * identical to the non-pinned case. See the `:has(~ .content)` /
+	 * `.content ~` rules below.
+	 *
+	 * `min-height` on `.header` keeps the header footprint stable whether
+	 * or not a close icon is rendered (notably the AlertDialog case, which
+	 * has no close button).
+	 */
+	.header {
+		display: flex;
+		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
+		padding-block: var(--wpds-dimension-padding-2xl) var(--wpds-dimension-gap-lg);
+		padding-inline: var(--wpds-dimension-padding-2xl);
+		/* TODO: refactor to a DS element size token when available. */
+		min-height: 32px;
+	}
+
+	.footer {
+		display: flex;
+		justify-content: flex-end;
+		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
+		padding-block: var(--wpds-dimension-gap-lg) var(--wpds-dimension-padding-2xl);
+		padding-inline: var(--wpds-dimension-padding-2xl);
+	}
+
+	/*
+	 * Overlay heading defaults: anchor the title to the inline start and
+	 * set the neutral text color explicitly. `--_gcd-heading-color` and
+	 * `--_gcd-heading-margin` defend against the heading-reset rules in
+	 * `global-css-defense.module.css`, which would otherwise take over a
+	 * `<h2>` rendered via `Text`.
+	 */
+	.title {
+		color: var(--wpds-color-fg-content-neutral);
+		--_gcd-heading-color: var(--wpds-color-fg-content-neutral);
+
+		margin-inline-end: auto;
+		--_gcd-heading-margin: 0 auto 0 0;
+
+		&:dir(rtl) {
+			--_gcd-heading-margin: 0 0 0 auto;
+		}
+	}
+
+	/*
+	 * Scroll container. `flex: 1 1 auto` + `min-block-size: 0` lets it
+	 * shrink below its content size so `overflow-block: auto` can actually
+	 * show a scrollbar when content exceeds the available space. Default
+	 * padding is `padding-2xl` on all sides; the yield rules below strip
+	 * block padding when chrome occupies that edge.
+	 *
+	 * Scrolling is intentionally block-axis-only. `overflow-inline: hidden`
+	 * clips wide content instead of introducing a horizontal scrollbar:
+	 * the sibling chrome doesn't scroll inline, the popup edge already
+	 * clips, and `useOverlayScrollStateAttributes` only tracks block-axis
+	 * overflow (tabindex + separator state). Overlay consumers should
+	 * constrain content width rather than rely on horizontal scroll.
+	 */
+	.content {
+		flex: 1 1 auto;
+		min-block-size: 0;
+		overflow-block: auto;
+		overflow-inline: hidden;
+		padding: var(--wpds-dimension-padding-2xl);
+
+		/*
+		 * The shared `outset-ring--focus-visible` utility (composed by
+		 * the Content components) uses an `outline-offset` of `+1px`,
+		 * which for this scroll container would put the ring outside
+		 * the popup's rounded corners and have it clipped by the
+		 * popup's `overflow: hidden`. Inset the ring by the focus
+		 * width instead, so it sits flush inside the content box.
+		 *
+		 * The shared utility's transition shorthand (`transition:
+		 * outline …`) only animates outline-color and outline-width,
+		 * not outline-offset, so the negative offset applied here is
+		 * static — visually, the ring still fades in/out via color
+		 * change while the offset stays put.
+		 */
+		&:focus-visible {
+			outline-offset: calc(var(--wpds-border-width-focus) * -1);
+		}
+	}
+
+	/*
+	 * Pinned chrome: reserve 1px on the inner side for the separator
+	 * border and subtract that same 1px from the adjacent padding. Net
+	 * effect on block-axis height is zero — the chrome's overall
+	 * border-box matches the non-pinned case — while the border provides
+	 * a fixed slot that the scroll-state rules below colorize.
+	 *
+	 * `.content` then drops its matching block-axis padding on that
+	 * edge, because the chrome already supplies the popup-edge
+	 * `padding-2xl` + inner `gap-lg`.
+	 *
+	 * Sibling relationships intentionally use the general-sibling
+	 * combinator (`~`) and `:has(~ …)` instead of the adjacent
+	 * combinator, so an extra element between header / content / footer
+	 * (custom wrappers, an a11y live region, etc.) doesn't silently
+	 * break the pinned layout. The expected DOM shape is still
+	 * header → content → footer; additional siblings in between are
+	 * tolerated.
+	 */
+	.header:has(~ .content) {
+		padding-block-end: calc(var(--wpds-dimension-gap-lg) - 1px);
+		border-block-end: 1px solid transparent;
+	}
+
+	.header ~ .content {
+		padding-block-start: 0;
+	}
+
+	.content ~ .footer {
+		padding-block-start: calc(var(--wpds-dimension-gap-lg) - 1px);
+		border-block-start: 1px solid transparent;
+	}
+
+	.content:has(~ .footer) {
+		padding-block-end: 0;
+	}
+
+	/*
+	 * Non-pinned case: when `.header` / `.footer` live inside `.content`
+	 * (scrolls with body). The scroll container already supplies the
+	 * inline popup-edge padding, so nested chrome always collapses its
+	 * own `padding-inline` regardless of its position inside `.content`
+	 * (no `:first-child` / `:last-child` guard). Block-axis padding is
+	 * only collapsed at the scroll edges — the `:first-child` /
+	 * `:last-child` rules keep the body's `gap-lg` visual separation
+	 * between the chrome and any preceding / following siblings inside
+	 * `.content`. No border — the separator is specific to the pinned
+	 * case.
+	 *
+	 * Each rule is duplicated with `> [data-drawer-content] >` so it
+	 * also fires for `Drawer`, where `Drawer.Content` renders an outer
+	 * wrapper around Base UI's `_Drawer.Content` marker (so the popup-
+	 * edge gutter falls outside `[data-drawer-content]` and stays
+	 * mouse-draggable for swipe-dismiss). The marker is a transparent
+	 * one-level wrapper, so mirroring each direct-child rule one level
+	 * deeper through it preserves the same intent: chrome sitting at
+	 * the scroll body's true visual edge collapses its popup-edge
+	 * padding; chrome wrapped in arbitrary consumer-supplied
+	 * intermediate elements keeps its own padding. `Dialog` and
+	 * `AlertDialog` have no such wrapper, so the `[data-drawer-content]`
+	 * variants never match for them.
+	 */
+	.content > .header,
+	.content > [data-drawer-content] > .header {
+		padding-inline: 0;
+	}
+
+	.content > .header:first-child,
+	.content > [data-drawer-content] > .header:first-child {
+		padding-block-start: 0;
+	}
+
+	.content > .footer,
+	.content > [data-drawer-content] > .footer {
+		padding-inline: 0;
+	}
+
+	.content > .footer:last-child,
+	.content > [data-drawer-content] > .footer:last-child {
+		padding-block-end: 0;
+	}
+
+	/*
+	 * Separator coloring. The transparent border on the pinned chrome is
+	 * colorized when the adjacent scroll container reports off-screen
+	 * content in that direction. Toggling the color (not the border's
+	 * existence) means no layout shift on scroll.
+	 *
+	 * `useOverlayScrollStateAttributes` owns the
+	 * `data-wp-ui-overlay-scrolled-from-*` toggles, so CSS handles the
+	 * visual state without React re-rendering on scroll.
+	 *
+	 * Forced-colors note: `border-color: transparent` is preserved as-is
+	 * in forced-colors mode per spec, so the default (non-scrolled)
+	 * state stays invisible. When the color toggles to a token value
+	 * below, the UA substitutes a system color (typically `CanvasText`),
+	 * so the separator remains visible in forced-colors mode without
+	 * any additional rules.
+	 */
+	.header:has(~ [data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-top]) {
+		border-block-end-color: var(--wpds-color-stroke-surface-neutral);
+	}
+
+	[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-bottom] ~ .footer {
+		border-block-start-color: var(--wpds-color-stroke-surface-neutral);
+	}
+
+	/*
+	 * `overscroll-behavior: contain` stops scroll chaining from the overlay
+	 * to whatever sits behind it. We only want that when the overlay is
+	 * modal: a non-modal overlay lets the page underneath remain
+	 * interactive, and chaining scroll to the page there is the intuitive
+	 * behavior.
+	 *
+	 * `data-wp-ui-overlay-modal` is toggled on the popup by each component
+	 * (Dialog / Drawer mirror their `modal` prop; AlertDialog is always
+	 * modal). The scroll container always lives inside the popup —
+	 * `Dialog.Content` / `Drawer.Content` for the public API, or an
+	 * internal container for AlertDialog — so a single descendant
+	 * selector anchored at the modal popup covers all three.
+	 */
+	[data-wp-ui-overlay-modal] [data-wp-ui-overlay-scroll-container] {
+		overscroll-behavior: contain;
+	}
+}

package/src/utils/css/select-trigger.module.css

@@ -26,9 +26,12 @@
 		font-size: inherit;
 		line-height: 1.4;
 		text-align: start;
-		cursor: var(--wpds-cursor-control);
 		user-select: none;
 
+		&:not([data-disabled]) {
+			cursor: var(--wpds-cursor-control);
+		}
+
 		&.is-minimal {
 			width: auto;
 		}
@@ -48,7 +51,7 @@
 		text-overflow: ellipsis;
 		white-space: nowrap;
 
-		&.is-placeholder {
+		&[data-placeholder] {
 			color: var(--wpds-color-fg-interactive-neutral-disabled);
 		}
 	}

package/src/utils/render-slot-with-children.ts

@@ -0,0 +1,31 @@
+import { cloneElement } from '@wordpress/element';
+import type { ReactElement, ReactNode } from 'react';
+
+/**
+ * Fills an optional "slot" element prop with content by cloning it and
+ * injecting the given `children`. When `slot` is undefined, the provided
+ * `defaultSlot` is used in its place.
+ *
+ * Shared by overlay `Popup` components for their slot-shaped customization
+ * props (e.g. `portal`, `positioner`), so the merge behavior — defaults,
+ * children injection — stays consistent across all of them.
+ *
+ * Callers should type the slot prop as `ReactElement<Omit<Props, 'children'>>`:
+ * any subtree passed on the slot element is overwritten by `children`.
+ *
+ * @param slot        Optional element from the slot prop (e.g. `<Tooltip.Portal … />`
+ *                    or `<Tooltip.Positioner … />`). When omitted, `defaultSlot`
+ *                    is used. Injected `children` replace any subtree the caller
+ *                    may have passed on the slot element.
+ * @param defaultSlot Unpopulated default element used when `slot` is omitted
+ *                    (e.g. `<Tooltip.Portal />`).
+ * @param children    Content to inject as the slot's children (backdrop,
+ *                    positioner, popup subtree, etc.).
+ */
+export function renderSlotWithChildren(
+	slot: ReactElement | undefined,
+	defaultSlot: ReactElement,
+	children: ReactNode
+): ReactElement {
+	return cloneElement( slot ?? defaultSlot, { children } );
+}

package/src/utils/test/use-deprioritized-initial-focus.test.tsx

@@ -17,7 +17,7 @@ function TestHarness( {
 } ) {
 	const result = useDeprioritizedInitialFocus( {
 		initialFocus,
-		deprioritizedAttribute: ATTR,
+		deprioritizedAttributes: [ ATTR ],
 	} );
 
 	useEffect( () => {
@@ -156,7 +156,7 @@ describe( 'useDeprioritizedInitialFocus', () => {
 			} ) {
 				const result = useDeprioritizedInitialFocus( {
 					initialFocus: undefined,
-					deprioritizedAttribute: ATTR,
+					deprioritizedAttributes: [ ATTR ],
 				} );
 
 				useEffect( () => {
@@ -200,7 +200,7 @@ describe( 'useDeprioritizedInitialFocus', () => {
 			} ) {
 				const result = useDeprioritizedInitialFocus( {
 					initialFocus: undefined,
-					deprioritizedAttribute: ATTR,
+					deprioritizedAttributes: [ ATTR ],
 				} );
 
 				useEffect( () => {

package/src/utils/use-deprioritized-initial-focus.ts

@@ -1,5 +1,5 @@
 import type { Popover as _Popover } from '@base-ui/react/popover';
-import { useMemo, useRef } from '@wordpress/element';
+import { useRef } from '@wordpress/element';
 import { tabbable } from 'tabbable';
 
 /**
@@ -24,39 +24,43 @@ const getTabbableOptions = () => ( {
 
 /**
  * Returns a resolved `initialFocus` value that deprioritizes elements
- * marked with a given data attribute (e.g. a close icon), and an internal
- * ref that must be merged onto the popup element.
+ * marked with any of the given data attributes (e.g. a close icon, a
+ * library-managed scroll container), and an internal ref that must be
+ * merged onto the popup element.
  *
  * When `initialFocus` is `undefined` or `true` (the default behavior),
  * the hook replaces it with a callback that:
  * 1. On touch interactions — focuses the popup element itself (preventing
  *    the virtual keyboard on Android), matching Base UI's default.
  * 2. On other interactions — returns the first tabbable element that does
- *    *not* carry `deprioritizedAttribute`. Falls back to Base UI's default
- *    when the deprioritized element is the only tabbable element.
+ *    *not* carry any of `deprioritizedAttributes`. Falls back to Base
+ *    UI's default when every tabbable element is deprioritized.
  *
  * All other `initialFocus` values (`false`, `RefObject`, callback) pass
  * through unchanged.
  *
  * @param props
- * @param props.initialFocus           The consumer-provided `initialFocus` value.
- * @param props.deprioritizedAttribute The data attribute whose elements should be deprioritized.
+ * @param props.initialFocus            The consumer-provided `initialFocus` value.
+ * @param props.deprioritizedAttributes The data attributes whose elements should be deprioritized.
  */
 export function useDeprioritizedInitialFocus( {
 	initialFocus,
-	deprioritizedAttribute,
+	deprioritizedAttributes,
 }: {
 	initialFocus: InitialFocus;
-	deprioritizedAttribute: string;
+	deprioritizedAttributes: string[];
 } ) {
 	const popupRef = useRef< HTMLDivElement >( null );
 
-	const resolvedInitialFocus = useMemo( (): InitialFocus => {
-		if ( initialFocus !== undefined && initialFocus !== true ) {
-			return initialFocus;
-		}
-
-		return ( interactionType ): HTMLElement | boolean | null => {
+	// Returning a fresh callback on every render is intentional. Base UI
+	// stores `initialFocus` via `useValueAsRef` (see its FloatingFocusManager
+	// source) and reads it through `ref.current` only at open time, so
+	// reference identity doesn't affect behavior. Skipping `useMemo` also
+	// avoids either forcing callers to memoize their attributes array or
+	// fighting the React Compiler with a stringified dep key.
+	let resolvedInitialFocus: InitialFocus = initialFocus;
+	if ( initialFocus === undefined || initialFocus === true ) {
+		resolvedInitialFocus = ( interactionType ) => {
 			if ( interactionType === 'touch' ) {
 				return popupRef.current ?? true;
 			}
@@ -70,7 +74,9 @@ export function useDeprioritizedInitialFocus( {
 			for ( const el of tabbables ) {
 				if (
 					el instanceof HTMLElement &&
-					! el.hasAttribute( deprioritizedAttribute )
+					! deprioritizedAttributes.some( ( attr ) =>
+						el.hasAttribute( attr )
+					)
 				) {
 					return el;
 				}
@@ -78,7 +84,7 @@ export function useDeprioritizedInitialFocus( {
 
 			return true;
 		};
-	}, [ initialFocus, deprioritizedAttribute ] );
+	}
 
 	return { resolvedInitialFocus, popupRef };
 }