@wordpress/components 25.6.1 → 25.8.0

package/src/toolbar/toolbar-group/{toolbar-group-collapsed.js → toolbar-group-collapsed.tsx}

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 /**
  * WordPress dependencies
  */
@@ -11,13 +9,21 @@ import { useContext } from '@wordpress/element';
 import DropdownMenu from '../../dropdown-menu';
 import ToolbarContext from '../toolbar-context';
 import ToolbarItem from '../toolbar-item';
+import type { ToolbarGroupCollapsedProps } from './types';
+import type { DropdownMenuProps } from '../../dropdown-menu/types';
 
-function ToolbarGroupCollapsed( { controls = [], toggleProps, ...props } ) {
+function ToolbarGroupCollapsed( {
+	controls = [],
+	toggleProps,
+	...props
+}: ToolbarGroupCollapsedProps ) {
 	// It'll contain state if `ToolbarGroup` is being used within
 	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
-	const renderDropdownMenu = ( internalToggleProps ) => (
+	const renderDropdownMenu = (
+		internalToggleProps?: DropdownMenuProps[ 'toggleProps' ]
+	) => (
 		<DropdownMenu
 			controls={ controls }
 			toggleProps={ {

package/src/toolbar/toolbar-group/toolbar-group-container.tsx

@@ -0,0 +1,16 @@
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../../ui/context';
+import type { ToolbarGroupContainerProps } from './types';
+
+const ToolbarGroupContainer = ( {
+	className,
+	children,
+	...props
+}: WordPressComponentProps< ToolbarGroupContainerProps, 'div', false > ) => (
+	<div className={ className } { ...props }>
+		{ children }
+	</div>
+);
+export default ToolbarGroupContainer;

package/src/toolbar/toolbar-group/types.ts

@@ -0,0 +1,92 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	DropdownMenuProps,
+	DropdownOption,
+} from '../../dropdown-menu/types';
+
+/**
+ * WordPress dependencies
+ */
+import type { Props as IconProps } from '../../icon';
+
+export type ToolbarGroupControls = DropdownOption & {
+	/**
+	 * An optional subscript associated to the control.
+	 */
+	subscript?: string;
+};
+
+type ToolbarGroupPropsBase = {
+	/**
+	 * The controls to render in this toolbar.
+	 */
+	controls?: ToolbarGroupControls[] | ToolbarGroupControls[][];
+
+	/**
+	 * Class to set on the container div.
+	 */
+	className?: string;
+
+	/**
+	 * Any other things to render inside the toolbar besides the controls.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * The Dashicon icon slug to be shown for the option.
+	 */
+	icon?: IconProps[ 'icon' ];
+};
+
+export type ToolbarGroupProps = ToolbarGroupPropsBase &
+	(
+		| {
+				/**
+				 * When true, turns `ToolbarGroup` into a dropdown menu.
+				 */
+				isCollapsed?: false;
+				/**
+				 * Any other things to render inside the toolbar besides the controls.
+				 */
+				children?: ReactNode;
+				title?: never;
+		  }
+		| {
+				/**
+				 * When true, turns `ToolbarGroup` into a dropdown menu.
+				 */
+				isCollapsed: true;
+				/**
+				 * Any other things to render inside the toolbar besides the controls.
+				 */
+				children?: ToolbarGroupCollapsedProps[ 'children' ];
+				/**
+				 * ARIA label for dropdown menu if is collapsed.
+				 */
+				title: string;
+		  }
+	);
+
+export type ToolbarGroupCollapsedProps = DropdownMenuProps;
+
+export type ToolbarGroupContainerProps = {
+	/**
+	 * Children to be rendered inside the toolbar.
+	 */
+	children?: ReactNode;
+	/**
+	 * Class to set on the container div.
+	 */
+	className?: string;
+	/**
+	 * Props to be passed.
+	 */
+	props?: any;
+};

package/src/toolbar/toolbar-item/index.tsx

@@ -43,7 +43,9 @@ function ToolbarItem(
 		return children( allProps );
 	}
 
-	const render = isRenderProp ? children : Component && <Component />;
+	const render = isRenderProp
+		? children
+		: Component && <Component>{ children }</Component>;
 
 	return (
 		<BaseToolbarItem

package/src/tools-panel/stories/index.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 import styled from '@emotion/styled';
 
 /**
@@ -25,9 +25,11 @@ import Panel from '../../panel';
 import UnitControl from '../../unit-control';
 import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
 
-const meta: ComponentMeta< typeof ToolsPanel > = {
+const meta: Meta< typeof ToolsPanel > = {
 	title: 'Components (Experimental)/ToolsPanel',
 	component: ToolsPanel,
+	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+	subcomponents: { ToolsPanelItem },
 	argTypes: {
 		as: { control: { type: null } },
 		children: { control: { type: null } },
@@ -44,7 +46,7 @@ const meta: ComponentMeta< typeof ToolsPanel > = {
 };
 export default meta;
 
-export const Default: ComponentStory< typeof ToolsPanel > = ( {
+export const Default: StoryFn< typeof ToolsPanel > = ( {
 	resetAll: resetAllProp,
 	...props
 } ) => {
@@ -136,7 +138,7 @@ Default.args = {
 	label: 'Tools Panel (default example)',
 };
 
-export const WithNonToolsPanelItems: ComponentStory< typeof ToolsPanel > = ( {
+export const WithNonToolsPanelItems: StoryFn< typeof ToolsPanel > = ( {
 	resetAll: resetAllProp,
 	...props
 } ) => {
@@ -191,9 +193,10 @@ WithNonToolsPanelItems.args = {
 	label: 'ToolsPanel (with non-menu items)',
 };
 
-export const WithOptionalItemsPlusIcon: ComponentStory<
-	typeof ToolsPanel
-> = ( { resetAll: resetAllProp, ...props } ) => {
+export const WithOptionalItemsPlusIcon: StoryFn< typeof ToolsPanel > = ( {
+	resetAll: resetAllProp,
+	...props
+} ) => {
 	const [
 		isFirstToolsPanelItemShownByDefault,
 		setIsFirstToolsPanelItemShownByDefault,
@@ -294,7 +297,7 @@ WithOptionalItemsPlusIcon.args = {
 
 const { Fill: ToolsPanelItems, Slot } = createSlotFill( 'ToolsPanelSlot' );
 
-export const WithSlotFillItems: ComponentStory< typeof ToolsPanel > = ( {
+export const WithSlotFillItems: StoryFn< typeof ToolsPanel > = ( {
 	resetAll: resetAllProp,
 	panelId,
 	...props
@@ -392,9 +395,11 @@ WithSlotFillItems.args = {
 	panelId: 'unique-tools-panel-id',
 };
 
-export const WithConditionalDefaultControl: ComponentStory<
-	typeof ToolsPanel
-> = ( { resetAll: resetAllProp, panelId, ...props } ) => {
+export const WithConditionalDefaultControl: StoryFn< typeof ToolsPanel > = ( {
+	resetAll: resetAllProp,
+	panelId,
+	...props
+} ) => {
 	const [ attributes, setAttributes ] = useState< {
 		height?: string;
 		scale?: React.ReactText;
@@ -488,7 +493,7 @@ WithConditionalDefaultControl.args = {
 	panelId: 'unique-tools-panel-id',
 };
 
-export const WithConditionallyRenderedControl: ComponentStory<
+export const WithConditionallyRenderedControl: StoryFn<
 	typeof ToolsPanel
 > = ( { resetAll: resetAllProp, panelId, ...props } ) => {
 	const [ attributes, setAttributes ] = useState< {

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

@@ -48,7 +48,6 @@ const UnconnectedToolsPanel = (
  * by a header. The header includes a dropdown menu which is automatically
  * generated from the panel's inner `ToolsPanelItems`.
  *
- * @example
  * ```jsx
  * import { __ } from '@wordpress/i18n';
  * import {

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

@@ -214,6 +214,9 @@ const ToolsPanelHeader = (
 							<MenuGroup>
 								<MenuItem
 									aria-disabled={ ! canResetAll }
+									// @ts-expect-error - TODO: If this "tertiary" style is something we really want to allow on MenuItem,
+									// we should rename it and explicitly allow it as an official API. All the other Button variants
+									// don't make sense in a MenuItem context, and should be disallowed.
 									variant={ 'tertiary' }
 									onClick={ () => {
 										if ( canResetAll ) {

package/src/tooltip/README.md

@@ -1,8 +1,6 @@
-# Tooltip
+# ToolTip
 
-Tooltip is a React component to render floating help text relative to a node when it receives focus or when the user places the mouse cursor atop it. If the tooltip exceeds the bounds of the page in the direction it opens, its position will be flipped automatically.
-
-Accessibility note: the tooltip text is hidden from screen readers and assistive technologies that understand ARIA. To make it accessible, use an `aria-label` attribute on the same element the tooltip is applied to, preferably using the same text used for the tooltip.
+Tooltip is a React component to render floating help text relative to a node when it receives focus or it is hovered upon by a mouse. If the tooltip exceeds the bounds of the page in the direction it opens, its position will be flipped automatically.
 
 ## Usage
 
@@ -22,49 +20,54 @@ const MyTooltip = () => (
 
 The component accepts the following props:
 
-### position
+#### `children`: `React.ReactElement`
 
-The direction in which the tooltip should open relative to its parent node. Specify y- and x-axis as a space-separated string. Supports `"top"`, `"bottom"` y axis, and `"left"`, `"center"`, `"right"` x axis.
+The element to which the tooltip should anchor.
 
--   Type: `String`
--   Required: No
--   Default: `"bottom"`
+**NOTE:** Accepts only one child element.
 
-### children
+-   Required: Yes
 
-The element to which the tooltip should anchor.
+#### `delay`: `number`
 
-**NOTE:** You must pass only a single child. Tooltip renders itself as a clone of `children` with a [`Popover`](/packages/components/src/popover/README.md) added as an additional child.
+The amount of time in milliseconds to wait before showing the tooltip.
 
--   Type: `Element`
--   Required: Yes
+-   Required: No
+-   Default: `700`
 
-### text
+#### `hideOnClick`: `boolean`
 
-The tooltip text to show on focus or hover.
+Option to hide the tooltip when the anchor is clicked.
 
--   Type: `String`
 -   Required: No
+-   Default: `true`
+
+#### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+
+Used to specify the tooltip's placement with respect to its anchor.
+
+-   Required: No
+-   Default: `'bottom'`
+
+#### `position`: `string`
+
+_Note: use the `placement` prop instead when possible._
 
-### shortcut (web only)
+Legacy way to specify the popover's position with respect to its anchor. Specify y- and x-axis as a space-separated string. Supports `'top'`, `'middle'`, `'bottom'` y axis, and `'left'`, `'center'`, `'right'` x axis.
 
--   Type: `string` or `object`
 -   Required: No
+-   Default: `'bottom'`
 
-If shortcut is a string, it is expecting the display text. If shortcut is an object, it will accept the properties of `display` (string) and `ariaLabel` (string).
+#### `shortcut`: `string` | `object`
 
-### delay (web only)
+An option for adding accessible keyboard shortcuts.
 
-Time in milliseconds to wait before showing tooltip after the tooltip's visibility is toggled. This prop is currently only available for the web platforms.
+If shortcut is a string, it is expecting the display text. If shortcut is an object, it will accept the properties of `display`: `string` and `ariaLabel`: `string`.
 
--   Type: `Number`
 -   Required: No
--   Default: 700
 
-### visible (native only)
+#### `text`: `string`
 
-Whether the tooltip should be displayed on initial render. This prop is currently only available for the native mobile app built with React Native.
+The text shown in the tooltip when anchor element is focused or hovered.
 
--   Type: `Boolean`
 -   Required: No
--   Default: `false`

package/src/tooltip/index.tsx

@@ -0,0 +1,106 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react/tooltip';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { Children } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
+
+/**
+ * Internal dependencies
+ */
+import type { TooltipProps } from './types';
+import Shortcut from '../shortcut';
+import { positionToPlacement } from '../popover/utils';
+
+/**
+ * Time over anchor to wait before showing tooltip
+ */
+export const TOOLTIP_DELAY = 700;
+
+function Tooltip( props: TooltipProps ) {
+	const {
+		children,
+		delay = TOOLTIP_DELAY,
+		hideOnClick = true,
+		placement,
+		position,
+		shortcut,
+		text,
+	} = props;
+
+	const baseId = useInstanceId( Tooltip, 'tooltip' );
+	const describedById = text || shortcut ? baseId : undefined;
+
+	const isOnlyChild = Children.count( children ) === 1;
+	// console error if more than one child element is added
+	if ( ! isOnlyChild ) {
+		if ( 'development' === process.env.NODE_ENV ) {
+			// eslint-disable-next-line no-console
+			console.error(
+				'Tooltip should be called with only a single child element.'
+			);
+		}
+	}
+
+	// Compute tooltip's placement:
+	// - give priority to `placement` prop, if defined
+	// - otherwise, compute it from the legacy `position` prop (if defined)
+	// - finally, fallback to the default placement: 'bottom'
+	let computedPlacement;
+	if ( placement !== undefined ) {
+		computedPlacement = placement;
+	} else if ( position !== undefined ) {
+		computedPlacement = positionToPlacement( position );
+		deprecated( '`position` prop in wp.components.tooltip', {
+			since: '6.4',
+			alternative: '`placement` prop',
+		} );
+	}
+	computedPlacement = computedPlacement || 'bottom';
+
+	const tooltipStore = Ariakit.useTooltipStore( {
+		placement: computedPlacement,
+		timeout: delay,
+	} );
+
+	const isTooltipOpen = tooltipStore.useState( 'open' );
+
+	return (
+		<>
+			<Ariakit.TooltipAnchor
+				onBlur={ tooltipStore.hide }
+				onClick={ hideOnClick ? tooltipStore.hide : undefined }
+				store={ tooltipStore }
+				render={ isOnlyChild ? children : undefined }
+			>
+				{ isOnlyChild ? undefined : children }
+			</Ariakit.TooltipAnchor>
+			{ isOnlyChild && ( text || shortcut ) && isTooltipOpen && (
+				<Ariakit.Tooltip
+					className="components-tooltip"
+					gutter={ 4 }
+					id={ describedById }
+					overflowPadding={ 0.5 }
+					store={ tooltipStore }
+				>
+					{ text }
+					{ shortcut && (
+						<Shortcut
+							className={
+								text ? 'components-tooltip__shortcut' : ''
+							}
+							shortcut={ shortcut }
+						/>
+					) }
+				</Ariakit.Tooltip>
+			) }
+		</>
+	);
+}
+
+export default Tooltip;

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

@@ -0,0 +1,59 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { shortcutAriaLabel } from '@wordpress/keycodes';
+
+/**
+ * Internal dependencies
+ */
+import Tooltip from '..';
+import Button from '../../button';
+
+const meta: Meta< typeof Tooltip > = {
+	title: 'Components/Tooltip',
+	component: Tooltip,
+	argTypes: {
+		children: { control: { type: null } },
+		position: {
+			control: { type: 'select' },
+			options: [
+				'top left',
+				'top center',
+				'top right',
+				'bottom left',
+				'bottom center',
+				'bottom right',
+			],
+		},
+		shortcut: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+};
+export default meta;
+
+const Template: StoryFn< typeof Tooltip > = ( props ) => (
+	<Tooltip { ...props } />
+);
+
+export const Default: StoryFn< typeof Tooltip > = Template.bind( {} );
+Default.args = {
+	children: <Button variant="primary">Tooltip Anchor</Button>,
+	text: 'Tooltip Text',
+};
+
+export const KeyboardShortcut = Template.bind( {} );
+KeyboardShortcut.args = {
+	children: <Button variant="secondary">Keyboard Shortcut</Button>,
+	shortcut: {
+		display: '⇧⌘,',
+		ariaLabel: shortcutAriaLabel.primaryShift( ',' ),
+	},
+};

package/src/tooltip/style.scss

@@ -1,40 +1,15 @@
-.components-tooltip.components-popover {
-	z-index: z-index(".components-tooltip");
-
-	.components-popover__content {
-		min-width: min-content;
-	}
-}
-
-.components-tooltip .components-popover__content {
+.components-tooltip {
 	background: $black; // TODO: Discuss with designers.
 	border-radius: $radius-block-ui;
-	border-width: 0;
-	outline: none;
 	color: $gray-100;
-	white-space: nowrap;
 	text-align: center;
 	line-height: 1.4;
 	font-size: 12px;
-	box-shadow: none;
 	padding: $grid-unit-05 $grid-unit-10;
+	z-index: z-index(".components-tooltip");
 }
 
 .components-tooltip__shortcut {
-	display: inline-block;
 	margin-left: $grid-unit-10;
 }
 
-.disabled-element-wrapper {
-	position: relative;
-	.event-catcher {
-		z-index: z-index(".components-tooltip .event-catcher");
-		position: absolute;
-		width: 100%;
-		height: 100%;
-		top: 0;
-		left: 0;
-		bottom: 0;
-		right: 0;
-	}
-}