@wordpress/components 19.12.0 → 19.15.0

package/src/range-control/utils.ts

@@ -0,0 +1,132 @@
+/**
+ * External dependencies
+ */
+import type { MouseEventHandler } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useRef, useEffect, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useControlledState } from '../utils/hooks';
+import { clamp } from '../utils/math';
+
+import type {
+	UseControlledRangeValueArgs,
+	UseDebouncedHoverInteractionArgs,
+} from './types';
+
+const noop = () => {};
+
+/**
+ * A float supported clamp function for a specific value.
+ *
+ * @param  value The value to clamp.
+ * @param  min   The minimum value.
+ * @param  max   The maximum value.
+ *
+ * @return A (float) number
+ */
+export function floatClamp( value: number | null, min: number, max: number ) {
+	if ( typeof value !== 'number' ) {
+		return null;
+	}
+
+	return parseFloat( `${ clamp( value, min, max ) }` );
+}
+
+/**
+ * Hook to store a clamped value, derived from props.
+ *
+ * @param  settings
+ * @return The controlled value and the value setter.
+ */
+export function useControlledRangeValue(
+	settings: UseControlledRangeValueArgs
+) {
+	const { min, max, value: valueProp, initial } = settings;
+	const [ state, setInternalState ] = useControlledState(
+		floatClamp( valueProp, min, max ),
+		{ initial, fallback: null }
+	);
+
+	const setState = useCallback(
+		( nextValue: number | null ) => {
+			if ( nextValue === null ) {
+				setInternalState( null );
+			} else {
+				setInternalState( floatClamp( nextValue, min, max ) );
+			}
+		},
+		[ min, max ]
+	);
+
+	// `state` can't be an empty string because we specified a fallback value of
+	// `null` in `useControlledState`
+	return [ state as Exclude< typeof state, '' >, setState ] as const;
+}
+
+/**
+ * Hook to encapsulate the debouncing "hover" to better handle the showing
+ * and hiding of the Tooltip.
+ *
+ * @param  settings
+ * @return Bound properties for use on a React.Node.
+ */
+export function useDebouncedHoverInteraction(
+	settings: UseDebouncedHoverInteractionArgs
+) {
+	const {
+		onHide = noop,
+		onMouseLeave = noop as MouseEventHandler,
+		onMouseMove = noop as MouseEventHandler,
+		onShow = noop,
+		timeout = 300,
+	} = settings;
+
+	const [ show, setShow ] = useState( false );
+	const timeoutRef = useRef< number | undefined >();
+
+	const setDebouncedTimeout = useCallback(
+		( callback ) => {
+			window.clearTimeout( timeoutRef.current );
+
+			timeoutRef.current = window.setTimeout( callback, timeout );
+		},
+		[ timeout ]
+	);
+
+	const handleOnMouseMove = useCallback( ( event ) => {
+		onMouseMove( event );
+
+		setDebouncedTimeout( () => {
+			if ( ! show ) {
+				setShow( true );
+				onShow();
+			}
+		} );
+	}, [] );
+
+	const handleOnMouseLeave = useCallback( ( event ) => {
+		onMouseLeave( event );
+
+		setDebouncedTimeout( () => {
+			setShow( false );
+			onHide();
+		} );
+	}, [] );
+
+	useEffect( () => {
+		return () => {
+			window.clearTimeout( timeoutRef.current );
+		};
+	} );
+
+	return {
+		onMouseMove: handleOnMouseMove,
+		onMouseLeave: handleOnMouseLeave,
+	};
+}

package/src/resizable-box/resize-tooltip/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { noop } from 'lodash';
 import classnames from 'classnames';
 import type { Ref, ForwardedRef } from 'react';
 
@@ -30,6 +29,8 @@ type ResizeTooltipProps = React.ComponentProps< typeof Root > & {
 	zIndex?: number;
 };
 
+const noop = () => {};
+
 function ResizeTooltip(
 	{
 		axis,

package/src/resizable-box/resize-tooltip/utils.ts

@@ -1,15 +1,10 @@
-/**
- * External dependencies
- */
-import { noop } from 'lodash';
-
 /**
  * WordPress dependencies
  */
 import { useEffect, useRef, useState } from '@wordpress/element';
 import { useResizeObserver } from '@wordpress/compose';
 
-const { clearTimeout, setTimeout } = window;
+const noop = () => {};
 
 export type Axis = 'x' | 'y';
 
@@ -101,10 +96,10 @@ export function useResizeLabel( {
 
 	const debounceUnsetMoveXY = () => {
 		if ( moveTimeoutRef.current ) {
-			clearTimeout( moveTimeoutRef.current );
+			window.clearTimeout( moveTimeoutRef.current );
 		}
 
-		moveTimeoutRef.current = setTimeout( unsetMoveXY, fadeTimeout );
+		moveTimeoutRef.current = window.setTimeout( unsetMoveXY, fadeTimeout );
 	};
 
 	useEffect( () => {

package/src/responsive-wrapper/index.js

@@ -15,10 +15,8 @@ function ResponsiveWrapper( {
 	children,
 	isInline = false,
 } ) {
-	const [
-		containerResizeListener,
-		{ width: containerWidth },
-	] = useResizeObserver();
+	const [ containerResizeListener, { width: containerWidth } ] =
+		useResizeObserver();
 	if ( Children.count( children ) !== 1 ) {
 		return null;
 	}

package/src/sandbox/test/index.js

@@ -46,9 +46,8 @@ describe( 'Sandbox', () => {
 
 		const iframe = result.container.querySelector( '.components-sandbox' );
 
-		let sandboxedIframe = iframe.contentWindow.document.body.querySelector(
-			'.mock-iframe'
-		);
+		let sandboxedIframe =
+			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
 
 		expect( sandboxedIframe.getAttribute( 'src' ) ).toBe(
 			'https://super.embed'
@@ -58,9 +57,8 @@ describe( 'Sandbox', () => {
 			fireEvent.click( result.getByRole( 'button' ) );
 		} );
 
-		sandboxedIframe = iframe.contentWindow.document.body.querySelector(
-			'.mock-iframe'
-		);
+		sandboxedIframe =
+			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
 
 		expect( sandboxedIframe.getAttribute( 'src' ) ).toBe(
 			'https://another.super.embed'

package/src/scrollable/README.md

@@ -9,7 +9,7 @@ This feature is still experimental. “Experimental” means this is an early im
 ## Usage
 
 ```jsx
-import {__experimentalScrollable as Scrollable } from '@wordpress/components';
+import { __experimentalScrollable as Scrollable } from '@wordpress/components';
 
 function Example() {
 	return (
@@ -22,17 +22,23 @@ function Example() {
 
 ## Props
 
-### `scrollDirection`: `string`
+### `children`: `ReactNode`
+
+The children elements.
 
-- Required: No
-- Default: `y`
-- Allowed values: `x`, `y`, `auto`
+-   Required: Yes
+
+### `scrollDirection`: `string`
 
 Renders a scrollbar for a specific axis when content overflows.
 
-### `smoothScroll`: `boolean`
+-   Required: No
+-   Default: `y`
+-   Allowed values: `x`, `y`, `auto`
 
-- Required: No
-- Default: `false`
+### `smoothScroll`: `boolean`
 
 Enables (CSS) smooth scrolling.
+
+-   Required: No
+-   Default: `false`

package/src/scrollable/{component.js → component.tsx}

@@ -1,15 +1,20 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import { useScrollable } from './hook';
+import type { ScrollableProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function Scrollable( props, forwardedRef ) {
+function UnconnectedScrollable(
+	props: WordPressComponentProps< ScrollableProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const scrollableProps = useScrollable( props );
 
 	return <View { ...scrollableProps } ref={ forwardedRef } />;
@@ -18,7 +23,6 @@ function Scrollable( props, forwardedRef ) {
 /**
  * `Scrollable` is a layout component that content in a scrollable container.
  *
- * @example
  * ```jsx
  * import { __experimentalScrollable as Scrollable } from `@wordpress/components`;
  *
@@ -31,7 +35,6 @@ function Scrollable( props, forwardedRef ) {
  * }
  * ```
  */
+export const Scrollable = contextConnect( UnconnectedScrollable, 'Scrollable' );
 
-const ConnectedScrollable = contextConnect( Scrollable, 'Scrollable' );
-
-export default ConnectedScrollable;
+export default Scrollable;

package/src/scrollable/{hook.js → hook.ts}

@@ -6,16 +6,14 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
+import type { ScrollableProps } from './types';
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-/* eslint-enable jsdoc/valid-types */
-export function useScrollable( props ) {
+export function useScrollable(
+	props: WordPressComponentProps< ScrollableProps, 'div' >
+) {
 	const {
 		className,
 		scrollDirection = 'y',

package/src/scrollable/stories/{index.js → index.tsx}

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { boolean, select } from '@storybook/addon-knobs';
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -12,58 +12,49 @@ import { useRef } from '@wordpress/element';
  * Internal dependencies
  */
 import { View } from '../../view';
-import { Scrollable } from '../';
+import { Scrollable } from '..';
 
-export default {
+const meta: ComponentMeta< typeof Scrollable > = {
 	component: Scrollable,
 	title: 'Components (Experimental)/Scrollable',
+	argTypes: {
+		as: {
+			control: { type: 'text' },
+		},
+		children: {
+			control: { type: null },
+		},
+	},
 	parameters: {
-		knobs: { disable: false },
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-export const _default = () => {
-	const targetRef = useRef( null );
+const Template: ComponentStory< typeof Scrollable > = ( { ...args } ) => {
+	const targetRef = useRef< HTMLInputElement >( null );
 
 	const onButtonClick = () => {
 		targetRef.current?.focus();
 	};
 
-	const otherProps = {
-		smoothScroll: boolean(
-			'Scrollable: smoothScroll (hint: move focus in the scrollable container)',
-			false
-		),
-		scrollDirection: select(
-			'Scrollable: scrollDirection',
-			{
-				x: 'x',
-				y: 'y',
-				auto: 'auto',
-			},
-			'y'
-		),
-	};
-
 	const containerWidth = 300;
 	const containerHeight = 400;
 
 	return (
 		<Scrollable
 			style={ { height: containerHeight, width: containerWidth } }
-			{ ...otherProps }
+			{ ...args }
 		>
 			<View
 				style={ {
 					backgroundColor: '#eee',
 					height:
-						otherProps.scrollDirection === 'x'
-							? containerHeight
-							: 1000,
-					width:
-						otherProps.scrollDirection === 'y'
-							? containerWidth
-							: 1000,
+						args.scrollDirection === 'x' ? containerHeight : 1000,
+					width: args.scrollDirection === 'y' ? containerWidth : 1000,
 					position: 'relative',
 				} }
 			>
@@ -74,10 +65,8 @@ export const _default = () => {
 					ref={ targetRef }
 					style={ {
 						position: 'absolute',
-						bottom:
-							otherProps.scrollDirection === 'x' ? 'initial' : 0,
-						right:
-							otherProps.scrollDirection === 'y' ? 'initial' : 0,
+						bottom: args.scrollDirection === 'x' ? 'initial' : 0,
+						right: 0,
 					} }
 					type="text"
 					value="Focus me"
@@ -86,3 +75,9 @@ export const _default = () => {
 		</Scrollable>
 	);
 };
+
+export const Default: ComponentStory< typeof Scrollable > = Template.bind( {} );
+Default.args = {
+	smoothScroll: false,
+	scrollDirection: 'y',
+};

package/src/scrollable/test/__snapshots__/{index.js.snap → index.tsx.snap}

@@ -37,6 +37,7 @@ exports[`props should render correctly 1`] = `
 
 <div
   class="components-scrollable emotion-0 emotion-1"
+  data-testid="scrollable"
   data-wp-c16t="true"
   data-wp-component="Scrollable"
 >

package/src/scrollable/test/index.tsx

@@ -0,0 +1,34 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Scrollable } from '../index';
+
+describe( 'props', () => {
+	beforeEach( () => {
+		render(
+			<Scrollable data-testid="scrollable">
+				WordPress.org - Code is Poetry
+			</Scrollable>
+		);
+	} );
+
+	test( 'should render correctly', () => {
+		expect( screen.getByTestId( 'scrollable' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render smoothScroll', () => {
+		render(
+			<Scrollable smoothScroll data-testid="smooth-scrollable">
+				WordPress.org - Code is Poetry
+			</Scrollable>
+		);
+		expect(
+			screen.getByTestId( 'smooth-scrollable' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'scrollable' ) );
+	} );
+} );

package/src/scrollable/types.ts

@@ -1,6 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
 export type ScrollableDirection = 'x' | 'y' | 'auto';
 
-export type Props = {
+export type ScrollableProps = {
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
 	/**
 	 * Renders a scrollbar for a specific axis when content overflows.
 	 *
@@ -13,8 +22,4 @@ export type Props = {
 	 * @default false
 	 */
 	smoothScroll?: boolean;
-	/**
-	 * The children elements.
-	 */
-	children: React.ReactNode;
 };

package/src/select-control/index.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { isEmpty, noop } from 'lodash';
+import { isEmpty } from 'lodash';
 import classNames from 'classnames';
 import type { ChangeEvent, FocusEvent, ForwardedRef } from 'react';
 
@@ -21,6 +21,8 @@ import { Select, DownArrowWrapper } from './styles/select-control-styles';
 import type { WordPressComponentProps } from '../ui/context';
 import type { SelectControlProps } from './types';
 
+const noop = () => {};
+
 function useUniqueId( idProp?: string ) {
 	const instanceId = useInstanceId( SelectControl );
 	const id = `inspector-select-control-${ instanceId }`;

package/src/select-control/stories/index.tsx

@@ -12,7 +12,7 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import SelectControl from '..';
+import SelectControl from '../';
 
 const meta: ComponentMeta< typeof SelectControl > = {
 	title: 'Components/SelectControl',
@@ -34,9 +34,8 @@ export default meta;
 const SelectControlWithState: ComponentStory< typeof SelectControl > = (
 	args
 ) => {
-	const [ selection, setSelection ] = useState<
-		ComponentProps< typeof SelectControl >[ 'value' ]
-	>();
+	const [ selection, setSelection ] =
+		useState< ComponentProps< typeof SelectControl >[ 'value' ] >();
 
 	return (
 		<SelectControl

package/src/select-control/test/select-control.tsx

@@ -1,21 +1,29 @@
 /**
  * External dependencies
  */
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * Internal dependencies
  */
 import SelectControl from '..';
 
+const setupUser = () =>
+	userEvent.setup( {
+		advanceTimers: jest.advanceTimersByTime,
+	} );
+
 describe( 'SelectControl', () => {
 	it( 'should not render when no options or children are provided', () => {
-		const { container } = render( <SelectControl /> );
+		render( <SelectControl /> );
 
-		expect( container.firstChild ).toBeNull();
+		// use `queryByRole` to avoid throwing an error with `getByRole`
+		expect( screen.queryByRole( 'combobox' ) ).not.toBeInTheDocument();
 	} );
 
 	it( 'should not render its children', async () => {
+		const user = setupUser();
 		const handleChangeMock = jest.fn();
 
 		render(
@@ -30,13 +38,12 @@ describe( 'SelectControl', () => {
 			</SelectControl>
 		);
 
-		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
+		expect(
+			screen.getByRole( 'option', { name: 'Option 1' } )
+		).toBeInTheDocument();
 
-		const selectElement = screen.getByLabelText( 'Select' );
-
-		fireEvent.change( selectElement, {
-			target: { value: 'option-group-option-1' },
-		} );
+		const selectElement = screen.getByRole( 'combobox' );
+		await user.selectOptions( selectElement, 'option-group-option-1' );
 
 		expect( handleChangeMock ).toHaveBeenCalledWith(
 			'option-group-option-1',
@@ -45,6 +52,7 @@ describe( 'SelectControl', () => {
 	} );
 
 	it( 'should not render its options', async () => {
+		const user = setupUser();
 		const handleChangeMock = jest.fn();
 
 		render(
@@ -66,13 +74,12 @@ describe( 'SelectControl', () => {
 			/>
 		);
 
-		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
-
-		const selectElement = screen.getByLabelText( 'Select' );
+		expect(
+			screen.getByRole( 'option', { name: 'Option 1' } )
+		).toBeInTheDocument();
 
-		fireEvent.change( selectElement, {
-			target: { value: 'option-2' },
-		} );
+		const selectElement = screen.getByRole( 'combobox' );
+		await user.selectOptions( selectElement, 'option-2' );
 
 		expect( handleChangeMock ).toHaveBeenCalledWith(
 			'option-2',

package/src/shortcut/index.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { isString, isObject } from 'lodash';
-
 /** @typedef {string | { display: string, ariaLabel: string }} Shortcut */
 /**
  * @typedef Props
@@ -22,11 +17,11 @@ function Shortcut( { shortcut, className } ) {
 	let displayText;
 	let ariaLabel;
 
-	if ( isString( shortcut ) ) {
+	if ( typeof shortcut === 'string' ) {
 		displayText = shortcut;
 	}
 
-	if ( isObject( shortcut ) ) {
+	if ( shortcut !== null && typeof shortcut === 'object' ) {
 		displayText = shortcut.display;
 		ariaLabel = shortcut.ariaLabel;
 	}

package/src/slot-fill/fill.js

@@ -1,8 +1,4 @@
 // @ts-nocheck
-/**
- * External dependencies
- */
-import { isFunction } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -50,7 +46,7 @@ function FillComponent( { name, children, registerFill, unregisterFill } ) {
 	}
 
 	// If a function is passed as a child, provide it with the fillProps.
-	if ( isFunction( children ) ) {
+	if ( typeof children === 'function' ) {
 		children = children( slot.props.fillProps );
 	}