@wordpress/components 25.12.0 → 25.13.0

package/src/private-apis.ts

@@ -32,11 +32,12 @@ import {
 import {
 	DropdownMenu as DropdownMenuV2Ariakit,
 	DropdownMenuGroup as DropdownMenuGroupV2Ariakit,
-	DropdownMenuGroupLabel as DropdownMenuGroupLabelV2Ariakit,
 	DropdownMenuItem as DropdownMenuItemV2Ariakit,
 	DropdownMenuCheckboxItem as DropdownMenuCheckboxItemV2Ariakit,
 	DropdownMenuRadioItem as DropdownMenuRadioItemV2Ariakit,
 	DropdownMenuSeparator as DropdownMenuSeparatorV2Ariakit,
+	DropdownMenuItemLabel as DropdownMenuItemLabelV2Ariakit,
+	DropdownMenuItemHelpText as DropdownMenuItemHelpTextV2Ariakit,
 } from './dropdown-menu-v2-ariakit';
 import { ComponentsContext } from './context/context-system-provider';
 import Theme from './theme';
@@ -74,9 +75,10 @@ lock( privateApis, {
 	Theme,
 	DropdownMenuV2Ariakit,
 	DropdownMenuGroupV2Ariakit,
-	DropdownMenuGroupLabelV2Ariakit,
 	DropdownMenuItemV2Ariakit,
 	DropdownMenuCheckboxItemV2Ariakit,
 	DropdownMenuRadioItemV2Ariakit,
 	DropdownMenuSeparatorV2Ariakit,
+	DropdownMenuItemLabelV2Ariakit,
+	DropdownMenuItemHelpTextV2Ariakit,
 } );

package/src/slot-fill/README.md

@@ -68,7 +68,7 @@ Both `Slot` and `Fill` accept a `name` string prop, where a `Slot` with a given
 -   By default, events will bubble to their parents on the DOM hierarchy (native event bubbling)
 -   If `bubblesVirtually` is set to true, events will bubble to their virtual parent in the React elements hierarchy instead.
 
-`Slot` with `bubblesVirtually` set to true also accept an optional `className` to add to the slot container.
+`Slot` with `bubblesVirtually` set to true also accept optional `className` and `style` props to add to the slot container.
 
 `Slot` **without** `bubblesVirtually` accepts an optional `children` function prop, which takes `fills` as a param. It allows you to perform additional processing and wrap `fills` conditionally.
 

package/src/slot-fill/types.ts

@@ -36,15 +36,21 @@ export type SlotComponentProps =
 
 			/**
 			 * A function that returns nodes to be rendered.
-			 * Not supported when `bubblesVirtually` is true.
+			 * Supported only when `bubblesVirtually` is `false`.
 			 */
 			children?: never;
 
 			/**
-			 * className.
-			 * Not supported when `bubblesVirtually` is true.
+			 * Additional className for the `Slot` component.
+			 * Supported only when `bubblesVirtually` is `true`.
 			 */
 			className?: string;
+
+			/**
+			 * Additional styles for the `Slot` component.
+			 * Supported only when `bubblesVirtually` is `true`.
+			 */
+			style?: React.CSSProperties;
 	  } )
 	| ( SlotPropBase & {
 			/**
@@ -56,15 +62,21 @@ export type SlotComponentProps =
 
 			/**
 			 * A function that returns nodes to be rendered.
-			 * Not supported when `bubblesVirtually` is true.
+			 * Supported only when `bubblesVirtually` is `false`.
 			 */
 			children?: ( fills: ReactNode ) => ReactNode;
 
 			/**
-			 * className.
-			 * Not supported when `bubblesVirtually` is false.
+			 * Additional className for the `Slot` component.
+			 * Supported only when `bubblesVirtually` is `true`.
 			 */
 			className?: never;
+
+			/**
+			 * Additional styles for the `Slot` component.
+			 * Supported only when `bubblesVirtually` is `true`.
+			 */
+			style?: never;
 	  } );
 
 export type FillComponentProps = {

package/src/tabs/index.tsx

@@ -8,7 +8,7 @@ import * as Ariakit from '@ariakit/react';
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { useLayoutEffect, useRef } from '@wordpress/element';
+import { useLayoutEffect, useMemo, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -154,8 +154,16 @@ function Tabs( {
 		setSelectedId,
 	] );
 
+	const contextValue = useMemo(
+		() => ( {
+			store,
+			instanceId,
+		} ),
+		[ store, instanceId ]
+	);
+
 	return (
-		<TabsContext.Provider value={ { store, instanceId } }>
+		<TabsContext.Provider value={ contextValue }>
 			{ children }
 		</TabsContext.Provider>
 	);
@@ -164,4 +172,6 @@ function Tabs( {
 Tabs.TabList = TabList;
 Tabs.Tab = Tab;
 Tabs.TabPanel = TabPanel;
+Tabs.Context = TabsContext;
+
 export default Tabs;

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

@@ -20,6 +20,14 @@ import Button from '../../button';
 const meta: Meta< typeof Tabs > = {
 	title: 'Components (Experimental)/Tabs',
 	component: Tabs,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.TabList': Tabs.TabList,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.Tab': Tabs.Tab,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.TabPanel': Tabs.TabPanel,
+	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },

package/src/tabs/tab.tsx

@@ -2,14 +2,14 @@
  * WordPress dependencies
  */
 
-import { useContext, forwardRef } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import type { TabProps } from './types';
 import warning from '@wordpress/warning';
-import { TabsContext } from './context';
+import { useTabsContext } from './context';
 import { Tab as StyledTab } from './styles';
 import type { WordPressComponentProps } from '../context';
 
@@ -17,9 +17,9 @@ export const Tab = forwardRef<
 	HTMLButtonElement,
 	WordPressComponentProps< TabProps, 'button', false >
 >( function Tab( { children, id, disabled, render, ...otherProps }, ref ) {
-	const context = useContext( TabsContext );
+	const context = useTabsContext();
 	if ( ! context ) {
-		warning( '`Tabs.TabList` must be wrapped in a `Tabs` component.' );
+		warning( '`Tabs.Tab` must be wrapped in a `Tabs` component.' );
 		return null;
 	}
 	const { store, instanceId } = context;

package/src/tabs/tabpanel.tsx

@@ -6,7 +6,7 @@
  * WordPress dependencies
  */
 
-import { forwardRef, useContext } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -15,14 +15,14 @@ import type { TabPanelProps } from './types';
 import { TabPanel as StyledTabPanel } from './styles';
 
 import warning from '@wordpress/warning';
-import { TabsContext } from './context';
+import { useTabsContext } from './context';
 import type { WordPressComponentProps } from '../context';
 
 export const TabPanel = forwardRef<
 	HTMLDivElement,
 	WordPressComponentProps< TabPanelProps, 'div', false >
 >( function TabPanel( { children, id, focusable = true, ...otherProps }, ref ) {
-	const context = useContext( TabsContext );
+	const context = useTabsContext();
 	if ( ! context ) {
 		warning( '`Tabs.TabPanel` must be wrapped in a `Tabs` component.' );
 		return null;

package/src/tabs/test/index.tsx

@@ -524,6 +524,15 @@ describe( 'Tabs', () => {
 				await screen.findByRole( 'tab', { name: 'Alpha' } )
 			).toHaveFocus();
 
+			// This assertion ensures the component has had time to fully
+			// render, preventing flakiness.
+			// see https://github.com/WordPress/gutenberg/pull/55950
+			await waitFor( () =>
+				expect(
+					screen.getByRole( 'tab', { name: 'Beta' } )
+				).toHaveAttribute( 'tabindex', '-1' )
+			);
+
 			// Because all other tabs should have `tabindex=-1`, pressing Tab
 			// should NOT move the focus to the next tab, which is Beta.
 			// Instead, focus should go to the currently selected tabpanel (alpha).
@@ -847,6 +856,16 @@ describe( 'Tabs', () => {
 				// onSelect should not be called since the disabled tab is
 				// highlighted, but not selected.
 				await user.keyboard( '[Tab]' );
+
+				// This assertion ensures focus has time to move to the first
+				// tab before the test proceeds, preventing flakiness.
+				// see https://github.com/WordPress/gutenberg/pull/55950
+				await waitFor( () =>
+					expect(
+						screen.getByRole( 'tab', { name: 'Alpha' } )
+					).toHaveFocus()
+				);
+
 				await user.keyboard( '[ArrowLeft]' );
 				expect( mockOnSelect ).toHaveBeenCalledTimes( 1 );
 

package/src/text/README.md

@@ -132,6 +132,8 @@ function Example() {
 
 Sets `Text` to have `display: block`.
 
+Note: text truncation only works when `isBlock` is `false`.
+
 ### isDestructive
 
 **Type**: `boolean`
@@ -196,7 +198,9 @@ function Example() {
 
 **Type**: `boolean`
 
-Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways.
+
+Note: text truncation won't work if the `isBlock` property is set to `true`
 
 ```jsx
 import { __experimentalText as Text } from '@wordpress/components';

package/src/text/types.ts

@@ -46,10 +46,14 @@ export interface Props extends TruncateProps {
 	isDestructive?: boolean;
 	/**
 	 * Escape characters in `highlightWords` which are meaningful in regular expressions.
+	 *
+	 * @default false
 	 */
 	highlightEscape?: boolean;
 	/**
 	 * Determines if `highlightWords` should be case sensitive.
+	 *
+	 * @default false
 	 */
 	highlightCaseSensitive?: boolean;
 	/**
@@ -57,7 +61,10 @@ export interface Props extends TruncateProps {
 	 */
 	highlightSanitize?: FindAllArgs[ 'sanitize' ];
 	/**
-	 * Sets `Text` to have `display: block`.
+	 * Sets `Text` to have `display: block`. Note: text truncation only works
+	 * when `isBlock` is `false`.
+	 *
+	 * @default false
 	 */
 	isBlock?: boolean;
 	/**
@@ -73,11 +80,15 @@ export interface Props extends TruncateProps {
 	 */
 	size?: CSSProperties[ 'fontSize' ] | TextSize;
 	/**
-	 * Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+	 * Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways. Note: text truncation won't work if the `isBlock` property is set to `true`
+	 *
+	 * @default false
 	 */
 	truncate?: boolean;
 	/**
 	 * Uppercases the text content.
+	 *
+	 * @default false
 	 */
 	upperCase?: boolean;
 	/**
@@ -86,6 +97,8 @@ export interface Props extends TruncateProps {
 	variant?: TextVariant;
 	/**
 	 * Adjusts font-weight of the text.
+	 *
+	 * @default 'normal'
 	 */
 	weight?: CSSProperties[ 'fontWeight' ] | TextWeight;
 	/**

package/src/toggle-control/README.md

@@ -22,8 +22,8 @@ const MyToggleControl = () => {
 					: 'No fixed background.'
 			}
 			checked={ hasFixedBackground }
-			onChange={ () => {
-				setHasFixedBackground( ( state ) => ! state );
+			onChange={ (newValue) => {
+				setHasFixedBackground( newValue );
 			} }
 		/>
 	);

package/src/tools-panel/tools-panel-item/hook.ts

@@ -2,7 +2,12 @@
  * WordPress dependencies
  */
 import { usePrevious } from '@wordpress/compose';
-import { useCallback, useEffect, useMemo } from '@wordpress/element';
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+} from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -59,7 +64,11 @@ export function useToolsPanelItem(
 
 	// Registering the panel item allows the panel to include it in its
 	// automatically generated menu and determine its initial checked status.
-	useEffect( () => {
+	//
+	// This is performed in a layout effect to ensure that the panel item
+	// is registered before it is rendered preventing a rendering glitch.
+	// See: https://github.com/WordPress/gutenberg/issues/56470
+	useLayoutEffect( () => {
 		if ( hasMatchingPanel && previousPanelId !== null ) {
 			registerPanelItem( {
 				hasValue: hasValueCallback,