@wordpress/components 25.13.0 → 25.15.1-next.79a6196f.0

package/src/toggle-group-control/toggle-group-control-option-icon/README.md

@@ -4,7 +4,7 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-`ToggleGroupControlOptionIcon` is a form component which is meant to be used as a child of [`ToggleGroupControl`] and displays an icon(<(/packages/components/src/toggle-group-control/toggle-group-control/README.md)>).
+`ToggleGroupControlOptionIcon` is a form component which is meant to be used as a child of [`ToggleGroupControl`](/packages/components/src/toggle-group-control/toggle-group-control/README.md) and displays an icon.
 
 ## Usage
 

package/src/toolbar/toolbar/README.md

@@ -4,12 +4,6 @@ Toolbar can be used to group related options. To emphasize groups of related ico
 
 ![Toolbar component above an image block](https://wordpress.org/gutenberg/files/2019/01/s_96EC471FE9C9D91A996770229947AAB54A03351BDE98F444FD3C1BF0CED365EA_1541782974545_ButtonGroup.png)
 
-## Table of contents
-
-1. [Design guidelines](#design-guidelines)
-2. [Development guidelines](#development-guidelines)
-3. [Related components](#related-components)
-
 ## Design guidelines
 
 ### Usage

package/src/tools-panel/test/index.tsx

@@ -455,8 +455,8 @@ describe( 'ToolsPanel', () => {
 
 			const menuGroups = screen.getAllByRole( 'group' );
 
-			// Groups should be: default controls, optional controls & reset all.
-			expect( menuGroups.length ).toEqual( 3 );
+			// There are now only two groups controls & reset all.
+			expect( menuGroups.length ).toEqual( 2 );
 		} );
 
 		it( 'should not render contents of items when in placeholder state', () => {
@@ -517,15 +517,11 @@ describe( 'ToolsPanel', () => {
 
 			await openDropdownMenu();
 
-			// The linked control should initially appear in the optional controls
-			// menu group. There should be three menu groups: default controls,
-			// optional controls, and the group to reset all options.
 			let menuGroups = screen.getAllByRole( 'group' );
-			expect( menuGroups.length ).toEqual( 3 );
 
-			// The linked control should be in the second group, of optional controls.
+			// The linked control should be in the first group of controls.
 			expect(
-				within( menuGroups[ 1 ] ).getByText( 'Linked' )
+				within( menuGroups[ 0 ] ).getByText( 'Linked' )
 			).toBeInTheDocument();
 
 			// Simulate the main control having a value set which should
@@ -540,22 +536,18 @@ describe( 'ToolsPanel', () => {
 			linkedItem = screen.getByText( 'Linked control' );
 			expect( linkedItem ).toBeInTheDocument();
 
-			// The linked control should now appear in the default controls
-			// menu group and have been removed from the optional group.
+			// The linked control should still appear in the controls
+			// menu group but as a default control.
 			menuGroups = screen.getAllByRole( 'group' );
 
-			// There should now only be two groups. The default controls and
-			// and the group for the reset all option.
-			expect( menuGroups.length ).toEqual( 2 );
-
-			// The new default control item for the Linked control should be
-			// within the first menu group.
+			// The new default control item for the Linked control should still
+			// be within the first menu group.
 			const defaultItem = within( menuGroups[ 0 ] ).getByText( 'Linked' );
 			expect( defaultItem ).toBeInTheDocument();
 
 			// Optional controls have an additional aria-label. This can be used
-			// to confirm the conditional default control has been removed from
-			// the optional menu item group.
+			// to confirm the conditional default control is now being treated
+			// as default control.
 			expect(
 				screen.queryByRole( 'menuitemcheckbox', {
 					name: 'Show Linked',
@@ -599,7 +591,7 @@ describe( 'ToolsPanel', () => {
 			let conditionalItem = screen.queryByText( 'Conditional control' );
 			expect( conditionalItem ).not.toBeInTheDocument();
 
-			// The conditional control should not yet appear in the default controls
+			// The conditional control should not yet appear in the controls
 			// menu group.
 			await openDropdownMenu();
 			let menuGroups = screen.getAllByRole( 'group' );
@@ -619,7 +611,7 @@ describe( 'ToolsPanel', () => {
 			conditionalItem = screen.getByText( 'Conditional control' );
 			expect( conditionalItem ).toBeInTheDocument();
 
-			// The conditional control should now appear in the default controls
+			// The conditional control should now appear in the controls
 			// menu group.
 			menuGroups = screen.getAllByRole( 'group' );
 

package/src/tools-panel/tools-panel/README.md

@@ -157,6 +157,13 @@ wrapper element allowing the panel to lay them out accordingly.
 - Required: No
 - Default: `false`
 
+### `dropdownMenuProps`: `{}`
+
+The popover props to configure panel's `DropdownMenu`.
+
+-   Type: `DropdownMenuProps`
+-   Required: No
+
 ### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
 The heading level of the panel's header.

package/src/tools-panel/tools-panel/component.tsx

@@ -25,6 +25,7 @@ const UnconnectedToolsPanel = (
 		resetAllItems,
 		toggleItem,
 		headingLevel,
+		dropdownMenuProps,
 		...toolsPanelProps
 	} = useToolsPanel( props );
 
@@ -36,6 +37,7 @@ const UnconnectedToolsPanel = (
 					resetAll={ resetAllItems }
 					toggleItem={ toggleItem }
 					headingLevel={ headingLevel }
+					dropdownMenuProps={ dropdownMenuProps }
 				/>
 				{ children }
 			</ToolsPanelContext.Provider>

package/src/tools-panel/tools-panel-header/README.md

@@ -18,6 +18,13 @@ This component is generated automatically by its parent
 
 ## Props
 
+### `dropdownMenuProps`: `{}`
+
+The dropdown menu props to configure the panel's `DropdownMenu`.
+
+-   Type: `DropdownMenuProps`
+-   Required: No
+
 ### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
 The heading level of the panel's header.

package/src/tools-panel/tools-panel-header/component.tsx

@@ -39,7 +39,7 @@ const DefaultControlsGroup = ( {
 	const resetSuffix = <ResetLabel aria-hidden>{ __( 'Reset' ) }</ResetLabel>;
 
 	return (
-		<MenuGroup label={ __( 'Defaults' ) }>
+		<>
 			{ items.map( ( [ label, hasValue ] ) => {
 				if ( hasValue ) {
 					return (
@@ -73,6 +73,7 @@ const DefaultControlsGroup = ( {
 				return (
 					<MenuItem
 						key={ label }
+						icon={ check }
 						className={ itemClassName }
 						role="menuitemcheckbox"
 						isSelected
@@ -82,7 +83,7 @@ const DefaultControlsGroup = ( {
 					</MenuItem>
 				);
 			} ) }
-		</MenuGroup>
+		</>
 	);
 };
 
@@ -95,7 +96,7 @@ const OptionalControlsGroup = ( {
 	}
 
 	return (
-		<MenuGroup label={ __( 'Tools' ) }>
+		<>
 			{ items.map( ( [ label, isSelected ] ) => {
 				const itemLabel = isSelected
 					? sprintf(
@@ -143,7 +144,7 @@ const OptionalControlsGroup = ( {
 					</MenuItem>
 				);
 			} ) }
-		</MenuGroup>
+		</>
 	);
 };
 
@@ -162,6 +163,7 @@ const ToolsPanelHeader = (
 		menuItems,
 		resetAll,
 		toggleItem,
+		dropdownMenuProps,
 		...headerProps
 	} = useToolsPanelHeader( props );
 
@@ -192,6 +194,7 @@ const ToolsPanelHeader = (
 			</Heading>
 			{ hasMenuItems && (
 				<DropdownMenu
+					{ ...dropdownMenuProps }
 					icon={ dropDownMenuIcon }
 					label={ dropDownMenuLabelText }
 					menuProps={ { className: dropdownMenuClassName } }
@@ -202,15 +205,19 @@ const ToolsPanelHeader = (
 				>
 					{ () => (
 						<>
-							<DefaultControlsGroup
-								items={ defaultItems }
-								toggleItem={ toggleItem }
-								itemClassName={ defaultControlsItemClassName }
-							/>
-							<OptionalControlsGroup
-								items={ optionalItems }
-								toggleItem={ toggleItem }
-							/>
+							<MenuGroup label={ labelText }>
+								<DefaultControlsGroup
+									items={ defaultItems }
+									toggleItem={ toggleItem }
+									itemClassName={
+										defaultControlsItemClassName
+									}
+								/>
+								<OptionalControlsGroup
+									items={ optionalItems }
+									toggleItem={ toggleItem }
+								/>
+							</MenuGroup>
 							<MenuGroup>
 								<MenuItem
 									aria-disabled={ ! canResetAll }

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

@@ -52,11 +52,14 @@ export function useToolsPanelItem(
 		__experimentalLastVisibleItemClass,
 	} = useToolsPanelContext();
 
-	const hasValueCallback = useCallback( hasValue, [ panelId, hasValue ] );
-	const resetAllFilterCallback = useCallback( resetAllFilter, [
-		panelId,
-		resetAllFilter,
-	] );
+	// hasValue is a new function on every render, so do not add it as a
+	// dependency to the useCallback hook! If needed, we should use a ref.
+	// eslint-disable-next-line react-hooks/exhaustive-deps
+	const hasValueCallback = useCallback( hasValue, [ panelId ] );
+	// resetAllFilter is a new function on every render, so do not add it as a
+	// dependency to the useCallback hook! If needed, we should use a ref.
+	// eslint-disable-next-line react-hooks/exhaustive-deps
+	const resetAllFilterCallback = useCallback( resetAllFilter, [ panelId ] );
 	const previousPanelId = usePrevious( currentPanelId );
 
 	const hasMatchingPanel =
@@ -126,27 +129,13 @@ export function useToolsPanelItem(
 	const newValueSet = isValueSet && ! wasValueSet;
 
 	// Notify the panel when an item's value has been set.
-	//
-	// 1. For default controls, this is so "reset" appears beside its menu item.
-	// 2. For optional controls, when the panel ID is `null`, it allows the
-	// panel to ensure the item is toggled on for display in the menu, given the
-	// value has been set external to the control.
 	useEffect( () => {
 		if ( ! newValueSet ) {
 			return;
 		}
 
-		if ( isShownByDefault || currentPanelId === null ) {
-			flagItemCustomization( label, menuGroup );
-		}
-	}, [
-		currentPanelId,
-		newValueSet,
-		isShownByDefault,
-		menuGroup,
-		label,
-		flagItemCustomization,
-	] );
+		flagItemCustomization( label, menuGroup );
+	}, [ newValueSet, menuGroup, label, flagItemCustomization ] );
 
 	// Determine if the panel item's corresponding menu is being toggled and
 	// trigger appropriate callback if it is.

package/src/tools-panel/types.ts

@@ -7,6 +7,7 @@ import type { ReactNode } from 'react';
  * Internal dependencies
  */
 import type { HeadingSize } from '../heading/types';
+import type { DropdownMenu } from '../dropdown-menu';
 
 export type ResetAllFilter = ( attributes?: any ) => any;
 type ResetAll = ( filters?: ResetAllFilter[] ) => void;
@@ -16,6 +17,10 @@ export type ToolsPanelProps = {
 	 * The child elements.
 	 */
 	children: ReactNode;
+	/**
+	 * The dropdown menu props to configure the panel's `DropdownMenu`.
+	 */
+	dropdownMenuProps?: React.ComponentProps< typeof DropdownMenu >;
 	/**
 	 * Flags that the items in this ToolsPanel will be contained within an inner
 	 * wrapper element allowing the panel to lay them out accordingly.
@@ -69,6 +74,10 @@ export type ToolsPanelProps = {
 };
 
 export type ToolsPanelHeaderProps = {
+	/**
+	 * The dropdown menu props to configure the panel's `DropdownMenu`.
+	 */
+	dropdownMenuProps?: React.ComponentProps< typeof DropdownMenu >;
 	/**
 	 * The heading level of the panel's header.
 	 *

package/src/tooltip/README.md

@@ -16,6 +16,10 @@ const MyTooltip = () => (
 );
 ```
 
+### Nested tooltips
+
+In case one or more `Tooltip` components are rendered inside another `Tooltip` component, only the tooltip associated to the outermost `Tooltip` component will be rendered in the browser and shown to the user appropriately. The rest of the nested `Tooltip` components will simply no-op and pass-through their anchor.
+
 ## Props
 
 The component accepts the following props:

package/src/tooltip/index.tsx

@@ -8,22 +8,37 @@ import * as Ariakit from '@ariakit/react';
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { Children } from '@wordpress/element';
+import { Children, cloneElement } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
  */
-import type { TooltipProps } from './types';
+import type { TooltipProps, TooltipInternalContext } from './types';
 import Shortcut from '../shortcut';
 import { positionToPlacement } from '../popover/utils';
+import {
+	contextConnect,
+	useContextSystem,
+	ContextSystemProvider,
+} from '../context';
+import type { WordPressComponentProps } from '../context';
 
 /**
  * Time over anchor to wait before showing tooltip
  */
 export const TOOLTIP_DELAY = 700;
 
-function Tooltip( props: TooltipProps ) {
+const CONTEXT_VALUE = {
+	Tooltip: {
+		isNestedInTooltip: true,
+	},
+};
+
+function UnconnectedTooltip(
+	props: WordPressComponentProps< TooltipProps, 'div', false >,
+	ref: React.ForwardedRef< any >
+) {
 	const {
 		children,
 		delay = TOOLTIP_DELAY,
@@ -32,7 +47,15 @@ function Tooltip( props: TooltipProps ) {
 		position,
 		shortcut,
 		text,
-	} = props;
+
+		// From Internal Context system
+		isNestedInTooltip,
+
+		...restProps
+	} = useContextSystem< typeof props & TooltipInternalContext >(
+		props,
+		'Tooltip'
+	);
 
 	const baseId = useInstanceId( Tooltip, 'tooltip' );
 	const describedById = text || shortcut ? baseId : undefined;
@@ -43,7 +66,7 @@ function Tooltip( props: TooltipProps ) {
 		if ( 'development' === process.env.NODE_ENV ) {
 			// eslint-disable-next-line no-console
 			console.error(
-				'Tooltip should be called with only a single child element.'
+				'wp-components.Tooltip should be called with only a single child element.'
 			);
 		}
 	}
@@ -64,24 +87,37 @@ function Tooltip( props: TooltipProps ) {
 	}
 	computedPlacement = computedPlacement || 'bottom';
 
-	const tooltipStore = Ariakit.useTooltipStore( {
+	// Removing the `Ariakit` namespace from the hook name allows ESLint to
+	// properly identify the hook, and apply the correct linting rules.
+	const useAriakitTooltipStore = Ariakit.useTooltipStore;
+	const tooltipStore = useAriakitTooltipStore( {
 		placement: computedPlacement,
-		timeout: delay,
+		showTimeout: delay,
 	} );
 
+	if ( isNestedInTooltip ) {
+		return isOnlyChild
+			? cloneElement( children, {
+					...restProps,
+					ref,
+			  } )
+			: children;
+	}
+
 	return (
-		<>
+		<ContextSystemProvider value={ CONTEXT_VALUE }>
 			<Ariakit.TooltipAnchor
 				onClick={ hideOnClick ? tooltipStore.hide : undefined }
 				store={ tooltipStore }
 				render={ isOnlyChild ? children : undefined }
+				ref={ ref }
 			>
 				{ isOnlyChild ? undefined : children }
 			</Ariakit.TooltipAnchor>
 			{ isOnlyChild && ( text || shortcut ) && (
 				<Ariakit.Tooltip
+					{ ...restProps }
 					unmountOnHide
-					className="components-tooltip"
 					gutter={ 4 }
 					id={ describedById }
 					overflowPadding={ 0.5 }
@@ -98,8 +134,10 @@ function Tooltip( props: TooltipProps ) {
 					) }
 				</Ariakit.Tooltip>
 			) }
-		</>
+		</ContextSystemProvider>
 	);
 }
 
+export const Tooltip = contextConnect( UnconnectedTooltip, 'Tooltip' );
+
 export default Tooltip;

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

@@ -30,7 +30,7 @@ const meta: Meta< typeof Tooltip > = {
 				'bottom right',
 			],
 		},
-		shortcut: { control: { type: 'text' } },
+		shortcut: { control: { type: 'object' } },
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -57,3 +57,20 @@ KeyboardShortcut.args = {
 		ariaLabel: shortcutAriaLabel.primaryShift( ',' ),
 	},
 };
+
+/**
+ * In case one or more `Tooltip` components are rendered inside another
+ * `Tooltip` component, only the tooltip associated to the outermost `Tooltip`
+ * component will be rendered in the browser and shown to the user
+ * appropriately. The rest of the nested `Tooltip` components will simply no-op
+ * and pass-through their anchor.
+ */
+export const Nested: StoryFn< typeof Tooltip > = Template.bind( {} );
+Nested.args = {
+	children: (
+		<Tooltip text="Nested tooltip text (that will never show)">
+			<Button variant="primary">Tooltip Anchor</Button>
+		</Tooltip>
+	),
+	text: 'Outer tooltip text',
+};