@wordpress/components 17.0.0 → 19.0.2

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

@@ -0,0 +1,129 @@
+/**
+ * WordPress dependencies
+ */
+import { usePrevious } from '@wordpress/compose';
+import { useCallback, useEffect, useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+import { useToolsPanelContext } from '../context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import { useCx } from '../../utils/hooks/use-cx';
+import type { ToolsPanelItemProps } from '../types';
+
+export function useToolsPanelItem(
+	props: WordPressComponentProps< ToolsPanelItemProps, 'div' >
+) {
+	const {
+		className,
+		hasValue,
+		isShownByDefault,
+		label,
+		panelId,
+		resetAllFilter,
+		onDeselect,
+		onSelect,
+		...otherProps
+	} = useContextSystem( props, 'ToolsPanelItem' );
+
+	const {
+		panelId: currentPanelId,
+		menuItems,
+		registerPanelItem,
+		deregisterPanelItem,
+		flagItemCustomization,
+		isResetting,
+		shouldRenderPlaceholderItems: shouldRenderPlaceholder,
+	} = useToolsPanelContext();
+
+	const hasValueCallback = useCallback( hasValue, [ panelId ] );
+	const resetAllFilterCallback = useCallback( resetAllFilter, [ panelId ] );
+
+	// Registering the panel item allows the panel to include it in its
+	// automatically generated menu and determine its initial checked status.
+	useEffect( () => {
+		if ( currentPanelId === panelId ) {
+			registerPanelItem( {
+				hasValue: hasValueCallback,
+				isShownByDefault,
+				label,
+				resetAllFilter: resetAllFilterCallback,
+				panelId,
+			} );
+		}
+
+		return () => deregisterPanelItem( label );
+	}, [
+		currentPanelId,
+		panelId,
+		isShownByDefault,
+		label,
+		hasValueCallback,
+		resetAllFilterCallback,
+	] );
+
+	const isValueSet = hasValue();
+	const wasValueSet = usePrevious( isValueSet );
+
+	// If this item represents a default control it will need to notify the
+	// panel when a custom value has been set.
+	useEffect( () => {
+		if ( isShownByDefault && isValueSet && ! wasValueSet ) {
+			flagItemCustomization( label );
+		}
+	}, [ isValueSet, wasValueSet, isShownByDefault, label ] );
+
+	// Note: `label` is used as a key when building menu item state in
+	// `ToolsPanel`.
+	const menuGroup = isShownByDefault ? 'default' : 'optional';
+	const isMenuItemChecked = menuItems?.[ menuGroup ]?.[ label ];
+	const wasMenuItemChecked = usePrevious( isMenuItemChecked );
+
+	// Determine if the panel item's corresponding menu is being toggled and
+	// trigger appropriate callback if it is.
+	useEffect( () => {
+		if ( isResetting || currentPanelId !== panelId ) {
+			return;
+		}
+
+		if ( isMenuItemChecked && ! isValueSet && ! wasMenuItemChecked ) {
+			onSelect?.();
+		}
+
+		if ( ! isMenuItemChecked && wasMenuItemChecked ) {
+			onDeselect?.();
+		}
+	}, [
+		currentPanelId,
+		isMenuItemChecked,
+		isResetting,
+		isValueSet,
+		panelId,
+		wasMenuItemChecked,
+	] );
+
+	// The item is shown if it is a default control regardless of whether it
+	// has a value. Optional items are shown when they are checked or have
+	// a value.
+	const isShown = isShownByDefault
+		? menuItems?.[ menuGroup ]?.[ label ] !== undefined
+		: isMenuItemChecked;
+
+	const cx = useCx();
+	const classes = useMemo( () => {
+		const placeholderStyle =
+			shouldRenderPlaceholder &&
+			! isShown &&
+			styles.ToolsPanelItemPlaceholder;
+		return cx( styles.ToolsPanelItem, placeholderStyle, className );
+	}, [ isShown, shouldRenderPlaceholder, className ] );
+
+	return {
+		...otherProps,
+		isShown,
+		shouldRenderPlaceholder,
+		className: classes,
+	};
+}

package/src/tools-panel/types.ts

@@ -0,0 +1,142 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { ReactNode } from 'react';
+
+type ResetAllFilter = () => void;
+type ResetAll = ( filters?: ResetAllFilter[] ) => void;
+
+export type ToolsPanelProps = {
+	/**
+	 * The child elements.
+	 */
+	children: ReactNode;
+	/**
+	 * Flags that the items in this ToolsPanel will be contained within an inner
+	 * wrapper element allowing the panel to lay them out accordingly.
+	 */
+	hasInnerWrapper: boolean;
+	/**
+	 * Text to be displayed within the panel's header and as the `aria-label`
+	 * for the panel's dropdown menu.
+	 */
+	label: string;
+	/**
+	 * If a `panelId` is set, it is passed through the `ToolsPanelContext` and
+	 * used to restrict panel items. Only items with a matching `panelId` will
+	 * be able to register themselves with this panel.
+	 */
+	panelId: string;
+	/**
+	 * A function to call when the `Reset all` menu option is selected. This is
+	 * passed through to the panel's header component.
+	 */
+	resetAll: ResetAll;
+	/**
+	 * Advises the `ToolsPanel` that its child `ToolsPanelItem`s should render
+	 * placeholder content instead of null when they are toggled off and hidden.
+	 */
+	shouldRenderPlaceholderItems: boolean;
+};
+
+export type ToolsPanelHeaderProps = {
+	/**
+	 * Text to be displayed within the panel header. It is also passed along as
+	 * the `label` for the panel header's `DropdownMenu`.
+	 */
+	label: string;
+	/**
+	 * The `resetAll` prop provides the callback to execute when the "Reset all"
+	 * menu item is selected. Its purpose is to facilitate resetting any control
+	 * values for items contained within this header's panel.
+	 */
+	resetAll: ResetAll;
+	/**
+	 * This is executed when an individual control's menu item is toggled. It
+	 * will update the panel's menu item state and call the panel item's
+	 * `onSelect` or `onDeselect` callbacks as appropriate.
+	 */
+	toggleItem: ( label: string ) => void;
+};
+
+export type ToolsPanelItem = {
+	/**
+	 * This is called when building the `ToolsPanel` menu to determine the
+	 * item's initial checked state.
+	 */
+	hasValue: () => boolean;
+	/**
+	 * This prop identifies the current item as being displayed by default. This
+	 * means it will show regardless of whether it has a value set or is toggled
+	 * on in the panel's menu.
+	 */
+	isShownByDefault: boolean;
+	/**
+	 * The supplied label is dual purpose. It is used as:
+	 * 1. the human-readable label for the panel's dropdown menu
+	 * 2. a key to locate the corresponding item in the panel's menu context to
+	 * determine if the panel item should be displayed.
+	 * A panel item's `label` should be unique among all items within a single
+	 * panel.
+	 */
+	label: string;
+	/**
+	 * Panel items will ensure they are only registering with their intended
+	 * panel by comparing the `panelId` props set on both the item and the panel
+	 * itself. This allows items to be injected from a shared source.
+	 */
+	panelId: string;
+	/**
+	 * A `ToolsPanel` will collect each item's `resetAllFilter` and pass an
+	 * array of these functions through to the panel's `resetAll` callback. They
+	 * can then be iterated over to perform additional tasks.
+	 */
+	resetAllFilter: ResetAllFilter;
+};
+
+export type ToolsPanelItemProps = ToolsPanelItem & {
+	/**
+	 * The child elements.
+	 */
+	children?: ReactNode;
+	/**
+	 * Called when this item is deselected in the `ToolsPanel` menu. This is
+	 * normally used to reset the panel item control's value.
+	 */
+	onDeselect?: () => void;
+	/**
+	 * A callback to take action when this item is selected in the `ToolsPanel`
+	 * menu.
+	 */
+	onSelect?: () => void;
+};
+
+export type ToolsPanelMenuItemKey = 'default' | 'optional';
+
+export type ToolsPanelMenuItems = {
+	[ menuItemKey in ToolsPanelMenuItemKey ]: { [ key: string ]: boolean };
+};
+
+export type ToolsPanelContext = {
+	panelId?: string;
+	menuItems: ToolsPanelMenuItems;
+	hasMenuItems: boolean;
+	registerPanelItem: ( item: ToolsPanelItem ) => void;
+	deregisterPanelItem: ( label: string ) => void;
+	flagItemCustomization: ( label: string ) => void;
+	isResetting: boolean;
+	shouldRenderPlaceholderItems: boolean;
+	areAllOptionalControlsHidden: boolean;
+};
+
+export type ToolsPanelControlsGroupProps = {
+	items: [ string, boolean ][];
+	onClose: () => void;
+	toggleItem: ( label: string ) => void;
+};
+
+export type ToolsPanelMenuItemsConfig = {
+	panelItems: ToolsPanelItem[];
+	shouldReset: boolean;
+};

package/src/tooltip/README.md

@@ -46,6 +46,14 @@ The tooltip text to show on focus or hover.
 -   Type: `String`
 -   Required: No
 
+### delay (web only)
+
+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.
+
+-   Type: `Number`
+-   Required: No
+-   Default: 700
+
 ### visible (native only)
 
 Whether the tooltip should be displayed on initial render. This prop is currently only available for the native mobile app built with React Native.

package/src/tooltip/index.js

@@ -38,7 +38,6 @@ const getDisabledElement = ( { eventHandlers, child, childrenWithPopover } ) =>
 			{ cloneElement( child, {
 				children: childrenWithPopover,
 			} ) }
-			,
 		</span>,
 		eventHandlers
 	);
@@ -82,12 +81,24 @@ const emitToChild = ( children, eventName, event ) => {
 	}
 
 	const child = Children.only( children );
+
+	// If the underlying element is disabled, do not emit the event.
+	if ( child.props.disabled ) {
+		return;
+	}
+
 	if ( typeof child.props[ eventName ] === 'function' ) {
 		child.props[ eventName ]( event );
 	}
 };
 
-function Tooltip( { children, position, text, shortcut } ) {
+function Tooltip( {
+	children,
+	position,
+	text,
+	shortcut,
+	delay = TOOLTIP_DELAY,
+} ) {
 	/**
 	 * Whether a mouse is currently pressed, used in determining whether
 	 * to handle a focus event as displaying the tooltip immediately.
@@ -96,7 +107,7 @@ function Tooltip( { children, position, text, shortcut } ) {
 	 */
 	const [ isMouseDown, setIsMouseDown ] = useState( false );
 	const [ isOver, setIsOver ] = useState( false );
-	const delayedSetIsOver = useDebounce( setIsOver, TOOLTIP_DELAY );
+	const delayedSetIsOver = useDebounce( setIsOver, delay );
 
 	const createMouseDown = ( event ) => {
 		// Preserve original child callback behavior

package/src/tooltip/index.native.js

@@ -273,6 +273,7 @@ const TooltipSlot = ( { children, ...rest } ) => {
 				}
 				pointerEvents="box-none"
 				style={ StyleSheet.absoluteFill }
+				testID="tooltip-overlay"
 			>
 				{ children }
 				<Slot { ...rest } />

package/src/tooltip/stories/index.js

@@ -1,7 +1,13 @@
 /**
  * External dependencies
  */
-import { text, select } from '@storybook/addon-knobs';
+import styled from '@emotion/styled';
+import { text, select, number } from '@storybook/addon-knobs';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -11,6 +17,9 @@ import Tooltip from '../';
 export default {
 	title: 'Components/ToolTip',
 	component: Tooltip,
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 export const _default = () => {
@@ -24,8 +33,9 @@ export const _default = () => {
 	};
 	const tooltipText = text( 'Text', 'More information' );
 	const position = select( 'Position', positionOptions, 'top center' );
+	const delay = number( 'Delay', 700 );
 	return (
-		<Tooltip text={ tooltipText } position={ position }>
+		<Tooltip text={ tooltipText } position={ position } delay={ delay }>
 			<div
 				style={ {
 					margin: '50px auto',
@@ -40,3 +50,31 @@ export const _default = () => {
 		</Tooltip>
 	);
 };
+
+const Button = styled.button`
+	margin: 0 10px;
+`;
+
+export const DisabledElement = () => {
+	const [ showMessage, toggleMessage ] = useState( false );
+
+	return (
+		<>
+			<Tooltip text="Hey, I am tooltip" position="bottom center">
+				<Button onClick={ () => toggleMessage( ! showMessage ) }>
+					Hover me!
+				</Button>
+			</Tooltip>
+			<Tooltip text="Hey, I am tooltip" position="bottom center">
+				<Button
+					disabled
+					onClick={ () => toggleMessage( ! showMessage ) }
+				>
+					Hover me, but I am disabled
+				</Button>
+			</Tooltip>
+			<br />
+			{ showMessage ? <p>Hello World!</p> : null }
+		</>
+	);
+};

package/src/tooltip/test/index.js

@@ -152,6 +152,40 @@ describe( 'Tooltip', () => {
 			}, TOOLTIP_DELAY );
 		} );
 
+		it( 'should respect custom delay prop when showing popover', () => {
+			const originalMouseEnter = jest.fn();
+			jest.useFakeTimers();
+			const wrapper = mount(
+				<Tooltip text="Help text" delay={ 2000 }>
+					<button
+						onMouseEnter={ originalMouseEnter }
+						onFocus={ originalMouseEnter }
+					>
+						<span>Hover Me!</span>
+					</button>
+				</Tooltip>
+			);
+
+			const button = wrapper.find( 'button' );
+			button.simulate( 'mouseenter', { type: 'mouseenter' } );
+
+			const popoverBeforeTimeout = wrapper.find( 'Popover' );
+			expect( popoverBeforeTimeout ).toHaveLength( 0 );
+			expect( originalMouseEnter ).toHaveBeenCalledTimes( 1 );
+
+			// Popover does not yet exist after default delay, because custom delay is passed.
+			setTimeout( () => {
+				const popoverBetweenTimeout = wrapper.find( 'Popover' );
+				expect( popoverBetweenTimeout ).toHaveLength( 0 );
+			}, TOOLTIP_DELAY );
+
+			// Popover appears after custom delay.
+			setTimeout( () => {
+				const popoverAfterTimeout = wrapper.find( 'Popover' );
+				expect( popoverAfterTimeout ).toHaveLength( 1 );
+			}, 2000 );
+		} );
+
 		it( 'should show tooltip when an element is disabled', () => {
 			const wrapper = mount(
 				<Tooltip text="Show helpful text here">
@@ -177,6 +211,26 @@ describe( 'Tooltip', () => {
 			}, TOOLTIP_DELAY );
 		} );
 
+		it( 'should not emit events back to children when they are disabled', () => {
+			const handleClick = jest.fn();
+
+			const wrapper = mount(
+				<Tooltip text="Show helpful text here">
+					<button disabled onClick={ handleClick }>
+						Click me
+					</button>
+				</Tooltip>
+			);
+
+			const eventCatcher = wrapper.find( '.event-catcher' );
+			eventCatcher.simulate( 'click', {
+				type: 'click',
+				currentTarget: {},
+			} );
+
+			expect( handleClick ).toHaveBeenCalledTimes( 0 );
+		} );
+
 		it( 'should cancel pending setIsOver on mouseleave', () => {
 			// Mount: Issues with using `setState` asynchronously with shallow-
 			// rendered components: https://github.com/airbnb/enzyme/issues/450

package/src/tooltip/test/index.native.js

@@ -0,0 +1,103 @@
+/**
+ * External dependencies
+ */
+import { act } from 'react-test-renderer';
+import { fireEvent, render } from 'test/helpers';
+import { Keyboard, Text } from 'react-native';
+
+/**
+ * WordPress dependencies
+ */
+import { SlotFillProvider } from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import Tooltip from '../index';
+
+// Minimal tree to render tooltip
+const TooltipSlot = ( { children } ) => (
+	<SlotFillProvider>
+		<Tooltip.Slot>{ children }</Tooltip.Slot>
+	</SlotFillProvider>
+);
+
+let keyboardAddListenerSpy;
+const keyboardHandlers = [];
+
+beforeAll( () => {
+	keyboardAddListenerSpy = jest
+		.spyOn( Keyboard, 'addListener' )
+		.mockImplementation( ( event, handler ) => {
+			const length = keyboardHandlers.push( [ event, handler ] );
+			return {
+				remove: () => {
+					keyboardHandlers.splice( length - 1 );
+				},
+			};
+		} );
+} );
+
+afterAll( () => {
+	keyboardAddListenerSpy.mockRestore();
+} );
+
+it( 'displays the message', () => {
+	const screen = render(
+		<TooltipSlot>
+			<Tooltip visible={ true } text="A helpful message">
+				<Text>I need help</Text>
+			</Tooltip>
+		</TooltipSlot>
+	);
+
+	expect( screen.getByText( 'A helpful message' ) ).toBeTruthy();
+} );
+
+it( 'dismisses when the screen is tapped', () => {
+	const screen = render(
+		<TooltipSlot>
+			<Tooltip visible={ true } text="A helpful message">
+				<Text>I need help</Text>
+			</Tooltip>
+		</TooltipSlot>
+	);
+
+	expect( screen.getByText( 'A helpful message' ) ).toBeTruthy();
+
+	fireEvent( screen.getByTestId( 'tooltip-overlay' ), 'touchStart' );
+
+	expect( screen.queryByText( 'A helpful message' ) ).toBeNull();
+} );
+
+it( 'dismisses when the keyboard closes', () => {
+	const screen = render(
+		<TooltipSlot>
+			<Tooltip visible={ true } text="A helpful message">
+				<Text>I need help</Text>
+			</Tooltip>
+		</TooltipSlot>
+	);
+
+	// Show keyboard
+	act( () => {
+		keyboardHandlers.forEach( ( [ event, handler ] ) => {
+			if ( event === 'keyboardDidShow' ) {
+				handler();
+			}
+		} );
+	} );
+
+	expect( screen.getByText( 'A helpful message' ) ).toBeTruthy();
+
+	// Hide keyboard
+	act( () => {
+		keyboardHandlers.forEach( ( [ event, handler ] ) => {
+			if ( event === 'keyboardDidHide' ) {
+				handler();
+			}
+		} );
+	} );
+
+	expect( screen.queryByText( 'A helpful message' ) ).toBeNull();
+} );

package/src/tree-grid/index.js

@@ -24,7 +24,9 @@ import RovingTabIndexContainer from './roving-tab-index';
  * @return {?Array} The array of focusables in the row.
  */
 function getRowFocusables( rowElement ) {
-	const focusablesInRow = focus.focusable.find( rowElement );
+	const focusablesInRow = focus.focusable.find( rowElement, {
+		sequential: true,
+	} );
 
 	if ( ! focusablesInRow || ! focusablesInRow.length ) {
 		return;

package/src/tree-select/stories/index.js

@@ -16,6 +16,9 @@ import TreeSelect from '../';
 export default {
 	title: 'Components/TreeSelect',
 	component: TreeSelect,
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 const TreeSelectWithState = ( props ) => {

package/src/truncate/component.js

@@ -1,9 +1,20 @@
 /**
  * Internal dependencies
  */
-import { createComponent } from '../ui/utils';
+import { contextConnect } from '../ui/context';
+import { View } from '../view';
 import useTruncate from './hook';
 
+/**
+ * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
+ * @param {import('react').Ref<any>}                                                         forwardedRef
+ */
+function Truncate( props, forwardedRef ) {
+	const truncateProps = useTruncate( props );
+
+	return <View as="span" { ...truncateProps } ref={ forwardedRef } />;
+}
+
 /**
  * `Truncate` is a typography primitive that trims text content.
  * For almost all cases, it is recommended that `Text`, `Heading`, or
@@ -25,10 +36,6 @@ import useTruncate from './hook';
  * }
  * ```
  */
-const Truncate = createComponent( {
-	as: 'span',
-	useHook: useTruncate,
-	name: 'Truncate',
-} );
+const ConnectedTruncate = contextConnect( Truncate, 'Truncate' );
 
-export default Truncate;
+export default ConnectedTruncate;

package/src/truncate/stories/index.js

@@ -10,7 +10,10 @@ import { Truncate } from '..';
 
 export default {
 	component: Truncate,
-	title: 'G2 Components (Experimental)/Truncate',
+	title: 'Components (Experimental)/Truncate',
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 export const _default = () => {

package/src/ui/context/stories/ComponentsProvider.stories.js

@@ -16,7 +16,7 @@ const useSomeContext = () => useContext( SomeContext );
 
 export default {
 	component: ContextSystemProvider,
-	title: 'G2 Components (Experimental)/ContextSystemProvider',
+	title: 'Components (Experimental)/ContextSystemProvider',
 };
 
 const outerContext = {

package/src/ui/context/use-context-system.js

@@ -13,7 +13,7 @@ import { useCx } from '../../utils/hooks/use-cx';
 
 /**
  * @template TProps
- * @typedef {TProps & { className: string; }} ConnectedProps
+ * @typedef {TProps & { className: string }} ConnectedProps
  */
 
 /**