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

package/src/alert-dialog/test/index.test.tsx

@@ -1453,8 +1453,8 @@ describe( 'AlertDialog', () => {
 		} );
 	} );
 
-	describe( 'container', () => {
-		it( 'should render inside the container when provided', async () => {
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
 			const user = userEvent.setup();
 			const containerRef = createRef< HTMLDivElement >();
 
@@ -1468,7 +1468,11 @@ describe( 'AlertDialog', () => {
 						/>
 						<AlertDialog.Popup
 							title="Confirm"
-							container={ containerRef }
+							portal={
+								<AlertDialog.Portal
+									container={ containerRef }
+								/>
+							}
 						/>
 					</AlertDialog.Root>
 				</div>
@@ -1506,4 +1510,326 @@ describe( 'AlertDialog', () => {
 			);
 		} );
 	} );
+
+	describe( 'overlay scroll container', () => {
+		// AlertDialog's scroll container is a library-internal `<div>` with
+		// no role or testid — a `querySelector` is the only way to reach
+		// it from a test. The Testing Library rule is disabled for this
+		// helper because that's exactly what it's flagging.
+		const findScroller = ( popup: HTMLElement | null ): HTMLDivElement => {
+			if ( ! popup ) {
+				throw new Error(
+					'Popup ref not attached — did AlertDialog.Popup render?'
+				);
+			}
+			// eslint-disable-next-line testing-library/no-node-access
+			const el = popup.querySelector(
+				'[data-wp-ui-overlay-scroll-container]'
+			);
+			if ( ! ( el instanceof HTMLDivElement ) ) {
+				throw new Error(
+					'Scroll container not found inside AlertDialog popup'
+				);
+			}
+			return el;
+		};
+
+		it( 'renders an internal scroll container with data-wp-ui-overlay-scroll-container', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			expect( findScroller( popupRef.current ) ).toBeInstanceOf(
+				HTMLDivElement
+			);
+		} );
+
+		it( 'is always modal (data-wp-ui-overlay-modal present on popup)', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			expect( popupRef.current ).toHaveAttribute(
+				'data-wp-ui-overlay-modal'
+			);
+		} );
+
+		it( 'pins header and footer outside the scroller when sticky props are true (default)', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+			const title = screen.getByRole( 'heading', { name: 'Title' } );
+			const ok = screen.getByRole( 'button', { name: 'OK' } );
+
+			// Default: chrome sits outside the scroll container.
+			expect( scroller ).not.toContainElement( title );
+			expect( scroller ).not.toContainElement( ok );
+		} );
+
+		it( 'nests header and footer inside the scroller when stickyHeader and stickyFooter are false', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup
+						ref={ popupRef }
+						title="Title"
+						stickyHeader={ false }
+						stickyFooter={ false }
+					>
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+			const title = screen.getByRole( 'heading', { name: 'Title' } );
+			const ok = screen.getByRole( 'button', { name: 'OK' } );
+
+			expect( scroller ).toContainElement( title );
+			expect( scroller ).toContainElement( ok );
+		} );
+
+		it( 'toggles tabindex="0" on the scroller based on overflow', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 500,
+			} );
+			Object.defineProperty( scroller, 'clientHeight', {
+				configurable: true,
+				value: 100,
+			} );
+			Object.defineProperty( scroller, 'scrollTop', {
+				configurable: true,
+				value: 0,
+			} );
+
+			act( () => {
+				scroller.dispatchEvent(
+					new Event( 'scroll', { bubbles: true } )
+				);
+			} );
+
+			expect( scroller ).toHaveAttribute( 'tabindex', '0' );
+
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 100,
+			} );
+
+			act( () => {
+				scroller.dispatchEvent(
+					new Event( 'scroll', { bubbles: true } )
+				);
+			} );
+
+			expect( scroller ).not.toHaveAttribute( 'tabindex' );
+		} );
+
+		it( 'toggles data-wp-ui-overlay-scrolled-from-* on the scroller based on scroll position', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			// JSDOM doesn't lay out elements, so we simulate an
+			// overflowing scroll container by stubbing layout metrics
+			// per scenario and dispatching a scroll event.
+			const scroller = findScroller( popupRef.current );
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 500,
+			} );
+			Object.defineProperty( scroller, 'clientHeight', {
+				configurable: true,
+				value: 100,
+			} );
+
+			const setScrollTop = ( value: number ) => {
+				Object.defineProperty( scroller, 'scrollTop', {
+					configurable: true,
+					value,
+				} );
+				act( () => {
+					scroller.dispatchEvent(
+						new Event( 'scroll', { bubbles: true } )
+					);
+				} );
+			};
+
+			setScrollTop( 0 );
+			expect( scroller ).not.toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+
+			setScrollTop( 200 );
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+
+			setScrollTop( 400 );
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).not.toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+		} );
+
+		it( 'does not focus the scroll container on open even when it is keyboard-tabbable', async () => {
+			// JSDOM reports `scrollHeight`/`clientHeight` as 0 by default,
+			// so the scroll container would never overflow on its own and
+			// would never become `tabindex="0"`. Forcing both prototype
+			// getters to overflow values here makes the scroller
+			// keyboard-reachable at the moment Base UI resolves
+			// `initialFocus` — exactly the configuration that, without
+			// `useDeprioritizedInitialFocus` wired up, lets the scroller
+			// steal focus from the action buttons.
+			const originalScrollHeight = Object.getOwnPropertyDescriptor(
+				Element.prototype,
+				'scrollHeight'
+			);
+			const originalClientHeight = Object.getOwnPropertyDescriptor(
+				Element.prototype,
+				'clientHeight'
+			);
+			Object.defineProperty( Element.prototype, 'scrollHeight', {
+				configurable: true,
+				get() {
+					return 500;
+				},
+			} );
+			Object.defineProperty( Element.prototype, 'clientHeight', {
+				configurable: true,
+				get() {
+					return 100;
+				},
+			} );
+
+			try {
+				const user = userEvent.setup();
+				const popupRef = createRef< HTMLDivElement >();
+
+				render(
+					<AlertDialog.Root>
+						<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+						<AlertDialog.Popup ref={ popupRef } title="Title">
+							Body that overflows
+						</AlertDialog.Popup>
+					</AlertDialog.Root>
+				);
+
+				await user.click(
+					screen.getByRole( 'button', { name: 'Open' } )
+				);
+
+				await waitFor( () => {
+					expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+				} );
+
+				// The scroll container (overflow forced via the
+				// prototype stubs above) must not steal focus from the
+				// action buttons — that's exactly what the
+				// `useDeprioritizedInitialFocus` wiring on
+				// `AlertDialog.Popup` is there to prevent. The Cancel
+				// button is the first non-deprioritized tabbable, so
+				// focus should settle on it.
+				const scroller = findScroller( popupRef.current );
+				await waitFor( () => {
+					expect(
+						screen.getByRole( 'button', { name: 'Cancel' } )
+					).toHaveFocus();
+				} );
+				expect( scroller ).not.toHaveFocus();
+			} finally {
+				if ( originalScrollHeight ) {
+					Object.defineProperty(
+						Element.prototype,
+						'scrollHeight',
+						originalScrollHeight
+					);
+				}
+				if ( originalClientHeight ) {
+					Object.defineProperty(
+						Element.prototype,
+						'clientHeight',
+						originalClientHeight
+					);
+				}
+			}
+		} );
+	} );
 } );

package/src/alert-dialog/types.ts

@@ -1,8 +1,12 @@
 import type { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
-import type { ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 
 import type { ComponentProps } from '../utils/types';
 
+export type PortalProps = ComponentPropsWithoutRef<
+	typeof _AlertDialog.Portal
+>;
+
 /**
  * The return type of `onConfirm`. Return `void` (or nothing) to auto-close
  * the dialog after the confirm handler completes. Return `{ close: false }`
@@ -63,9 +67,15 @@ export interface PopupProps
 	extends ComponentProps< 'div' >,
 		Pick< _AlertDialog.Popup.Props, 'initialFocus' | 'finalFocus' > {
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<AlertDialog.Portal />` with
+	 * custom `container`, `className`, or `style`. Overlay content is
+	 * rendered as this portal's children (do not pass `children` on the portal
+	 * element; they would be ignored).
+	 *
+	 * When omitted, `AlertDialog.Popup` uses `AlertDialog.Portal` with default
+	 * props.
 	 */
-	container?: _AlertDialog.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 
 	/**
 	 * The semantic intent of the dialog, which determines its styling.
@@ -116,4 +126,21 @@ export interface PopupProps
 	 * @default 'Cancel'
 	 */
 	cancelButtonText?: string;
+
+	/**
+	 * When `true`, the dialog's title stays pinned to the top of the popup
+	 * as the body scrolls. When `false`, the title scrolls with the body.
+	 *
+	 * @default true
+	 */
+	stickyHeader?: boolean;
+
+	/**
+	 * When `true`, the dialog's action buttons (and error message, if any)
+	 * stay pinned to the bottom of the popup as the body scrolls. When
+	 * `false`, they scroll with the body.
+	 *
+	 * @default true
+	 */
+	stickyFooter?: boolean;
 }

package/src/badge/stories/index.story.tsx

@@ -6,6 +6,12 @@ const meta: Meta< typeof Badge > = {
 	tags: [ 'manifest' ],
 	title: 'Design System/Components/Badge',
 	component: Badge,
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/button/button.tsx

@@ -9,6 +9,9 @@ import resetStyles from '../utils/css/resets.module.css';
 import focusStyles from '../utils/css/focus.module.css';
 import defenseStyles from '../utils/css/global-css-defense.module.css';
 
+/**
+ * A versatile button component with multiple variants, tones, and sizes.
+ */
 export const Button = forwardRef< HTMLButtonElement, ButtonProps >(
 	function Button(
 		{

package/src/button/icon.tsx

@@ -1,14 +1,7 @@
 import { forwardRef } from '@wordpress/element';
-import { type IconProps } from '../icon/types';
+import { type ButtonIconProps } from './types';
 import { Icon } from '../icon';
 
-interface ButtonIconProps extends IconProps {
-	/**
-	 * The icon to display, from the `@wordpress/icons` package.
-	 */
-	icon: IconProps[ 'icon' ];
-}
-
 export const ButtonIcon = forwardRef< SVGSVGElement, ButtonIconProps >(
 	function ButtonIcon( { icon, ...props }, ref ) {
 		return (

package/src/button/index.ts

@@ -1,16 +1,15 @@
-import { Button as ButtonButton } from './button';
+import { Button as _Button } from './button';
 import { ButtonIcon } from './icon';
 
+ButtonIcon.displayName = 'Button.Icon';
+
 /**
  * A versatile button component with multiple variants, tones, and sizes.
- * Built on design tokens for consistent theming and accessibility.
  */
-export const Button = Object.assign( ButtonButton, {
+export const Button = Object.assign( _Button, {
 	/**
 	 * An icon component specifically designed to work well when rendered inside
 	 * a `Button` component.
 	 */
 	Icon: ButtonIcon,
-} ) as typeof ButtonButton & {
-	Icon: typeof ButtonIcon;
-};
+} );

package/src/button/stories/index.story.tsx

@@ -6,11 +6,21 @@ import { Button } from '../index';
 const meta: Meta< typeof Button > = {
 	title: 'Design System/Components/Button',
 	component: Button,
+	subcomponents: {
+		'Button.Icon': Button.Icon,
+	},
 	argTypes: {
 		'aria-pressed': {
 			control: { type: 'boolean' },
 		},
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and text overflow behavior. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/button/types.ts

@@ -1,5 +1,6 @@
 import { type ReactNode, type HTMLAttributes } from 'react';
 import type { Button as _Button } from '@base-ui/react/button';
+import { type IconProps } from '../icon/types';
 import type { ComponentProps } from '../utils/types';
 
 type _ButtonProps = ComponentProps< typeof _Button >;
@@ -70,3 +71,10 @@ export interface ButtonProps
 	 */
 	loadingAnnouncement?: string;
 }
+
+export interface ButtonIconProps extends IconProps {
+	/**
+	 * The icon to display, from the `@wordpress/icons` package.
+	 */
+	icon: IconProps[ 'icon' ];
+}

package/src/card/stories/index.story.tsx

@@ -24,6 +24,7 @@ function Text( { children }: { children: React.ReactNode } ) {
 }
 
 const meta: Meta< typeof Card.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Card',
 	component: Card.Root,
 	subcomponents: {
@@ -32,6 +33,12 @@ const meta: Meta< typeof Card.Root > = {
 		'Card.FullBleed': Card.FullBleed,
 		'Card.Title': Card.Title,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/collapsible/stories/index.story.tsx

@@ -3,12 +3,19 @@ import { useState } from '@wordpress/element';
 import * as Collapsible from '../index';
 
 const meta: Meta< typeof Collapsible.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Collapsible',
 	component: Collapsible.Root,
 	subcomponents: {
 		'Collapsible.Trigger': Collapsible.Trigger,
 		'Collapsible.Panel': Collapsible.Panel,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/collapsible-card/content.tsx

@@ -17,7 +17,18 @@ export const Content = forwardRef< HTMLDivElement, ContentProps >(
 		return (
 			<Collapsible.Panel
 				ref={ ref }
-				className={ clsx( styles.content, className ) }
+				// @ts-expect-error Base UI supports the callback-style
+				// version of the `className` prop, but we're purposefully
+				// not advertising it in our `@wordpress/ui` re-export.
+				className={ ( state ) =>
+					clsx(
+						styles.content,
+						state.open &&
+							state.transitionStatus === 'idle' &&
+							styles.overflowVisible,
+						className
+					)
+				}
 				hiddenUntilFound={ hiddenUntilFound }
 				{ ...restProps }
 			>

package/src/collapsible-card/header.tsx

@@ -1,3 +1,4 @@
+import { mergeProps, useRender } from '@base-ui/react';
 import clsx from 'clsx';
 import { forwardRef, useMemo, useState } from '@wordpress/element';
 import { chevronDown } from '@wordpress/icons';
@@ -15,6 +16,12 @@ import type { HeaderProps } from './types';
  * toggle trigger — clicking anywhere on it expands or collapses the
  * card's content.
  *
+ * Defaults to a `<div>` wrapper around the trigger. Since the right heading
+ * level depends on the surrounding document outline, the consumer is
+ * expected to opt in to heading semantics. Pass `render` to wrap the
+ * trigger in a heading (e.g. `render={ <h2 /> }`), following the W3C APG
+ * accordion pattern (heading wraps button).
+ *
  * Avoid placing interactive elements (buttons, links, inputs) inside the
  * header, since the entire area is clickable and their events will bubble
  * to trigger the collapse toggle.
@@ -31,48 +38,54 @@ export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 			[ setDescriptionId ]
 		);
 
-		return (
-			<HeaderDescriptionIdContext.Provider value={ contextValue }>
-				<Collapsible.Trigger
-					className={ clsx( styles.header, className ) }
-					render={
-						<Card.Header
-							ref={ ref }
-							render={ render }
-							{ ...restProps }
-						/>
-					}
-					nativeButton={ false }
-					aria-describedby={ descriptionId }
-				>
-					<div className={ styles[ 'header-content' ] }>
-						{ children }
-					</div>
-					<div
-						className={ clsx(
-							styles[ 'header-trigger-positioner' ]
-						) }
-					>
-						<div
-							className={ clsx(
-								styles[ 'header-trigger-wrapper' ],
-								defenseStyles.div,
-								// While the interactive trigger element is the whole header,
-								// the focus ring will be displayed only on the icon to visually
-								// emulate it being the button.
-								focusStyles[
-									'outset-ring--focus-parent-visible'
-								]
-							) }
+		return useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( restProps, {
+				className: clsx(
+					defenseStyles.heading,
+					styles[ 'heading-wrapper' ],
+					className
+				),
+				children: (
+					<HeaderDescriptionIdContext.Provider value={ contextValue }>
+						<Collapsible.Trigger
+							className={ styles.header }
+							render={ <Card.Header /> }
+							nativeButton={ false }
+							aria-describedby={ descriptionId }
 						>
-							<Icon
-								icon={ chevronDown }
-								className={ styles[ 'header-trigger' ] }
-							/>
-						</div>
-					</div>
-				</Collapsible.Trigger>
-			</HeaderDescriptionIdContext.Provider>
-		);
+							<div className={ styles[ 'header-content' ] }>
+								{ children }
+							</div>
+							<div
+								className={ clsx(
+									styles[ 'header-trigger-positioner' ]
+								) }
+							>
+								<div
+									className={ clsx(
+										styles[ 'header-trigger-wrapper' ],
+										defenseStyles.div,
+										// While the interactive trigger element is the whole header,
+										// the focus ring will be displayed only on the icon to visually
+										// emulate it being the button.
+										focusStyles[
+											'outset-ring--focus-parent-visible'
+										]
+									) }
+								>
+									<Icon
+										icon={ chevronDown }
+										className={ styles[ 'header-trigger' ] }
+									/>
+								</div>
+							</div>
+						</Collapsible.Trigger>
+					</HeaderDescriptionIdContext.Provider>
+				),
+			} ),
+		} );
 	}
 );