@wordpress/components 19.13.0 → 19.16.0

package/src/range-control/utils.ts

@@ -0,0 +1,135 @@
+/**
+ * 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: floatClamp( initial ?? null, min, max ),
+			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/utils.ts

@@ -4,7 +4,6 @@
 import { useEffect, useRef, useState } from '@wordpress/element';
 import { useResizeObserver } from '@wordpress/compose';
 
-const { clearTimeout, setTimeout } = window;
 const noop = () => {};
 
 export type Axis = 'x' | 'y';
@@ -97,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/sandbox/index.native.js

@@ -1,13 +1,14 @@
 /**
  * External dependencies
  */
-import { Dimensions, Platform } from 'react-native';
+import { Dimensions, StyleSheet } from 'react-native';
 import { WebView } from 'react-native-webview';
 
 /**
  * WordPress dependencies
  */
 import {
+	Platform,
 	renderToString,
 	memo,
 	useRef,
@@ -307,6 +308,7 @@ function Sandbox( {
 			style={ [
 				sandboxStyles[ 'sandbox-webview__content' ],
 				getSizeStyle(),
+				Platform.isAndroid && workaroundStyles.webView,
 			] }
 			onMessage={ checkMessageForResize }
 			scrollEnabled={ false }
@@ -317,4 +319,15 @@ function Sandbox( {
 	);
 }
 
+const workaroundStyles = StyleSheet.create( {
+	webView: {
+		/**
+		 * The slight opacity below is a workaround for an Android crash caused from combining Android
+		 * 12's new scroll overflow behavior and webviews.
+		 * https://github.com/react-native-webview/react-native-webview/issues/1915#issuecomment-808869253
+		 */
+		opacity: 0.99,
+	},
+} );
+
 export default memo( Sandbox );

package/src/scroll-lock/README.md

@@ -7,7 +7,7 @@ ScrollLock is a content-free React component for declaratively preventing scroll
 Declare scroll locking as part of modal UI.
 
 ```jsx
-import { ScrollLock } from '@wordpress/components';
+import { ScrollLock, Button } from '@wordpress/components';
 import { useState } from '@wordpress/element';
 
 const MyScrollLock = () => {

package/src/scroll-lock/{index.js → index.tsx}

@@ -12,10 +12,7 @@ import { useEffect } from '@wordpress/element';
  */
 let previousScrollTop = 0;
 
-/**
- * @param {boolean} locked
- */
-function setLocked( locked ) {
+function setLocked( locked: boolean ) {
 	const scrollingElement = document.scrollingElement || document.body;
 
 	if ( locked ) {
@@ -36,11 +33,39 @@ function setLocked( locked ) {
 let lockCounter = 0;
 
 /**
- * A component that will lock scrolling when it is mounted and unlock scrolling when it is unmounted.
+ * ScrollLock is a content-free React component for declaratively preventing
+ * scroll bleed from modal UI to the page body. This component applies a
+ * `lockscroll` class to the `document.documentElement` and
+ * `document.scrollingElement` elements to stop the body from scrolling. When it
+ * is present, the lock is applied.
+ *
+ * ```jsx
+ * import { ScrollLock, Button } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
  *
- * @return {null} Render nothing.
+ * const MyScrollLock = () => {
+ *   const [ isScrollLocked, setIsScrollLocked ] = useState( false );
+ *
+ *   const toggleLock = () => {
+ *     setIsScrollLocked( ( locked ) => ! locked ) );
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Button variant="secondary" onClick={ toggleLock }>
+ *         Toggle scroll lock
+ *       </Button>
+ *       { isScrollLocked && <ScrollLock /> }
+ *       <p>
+ *         Scroll locked:
+ *         <strong>{ isScrollLocked ? 'Yes' : 'No' }</strong>
+ *       </p>
+ *     </div>
+ *   );
+ * };
+ * ```
  */
-export default function ScrollLock() {
+export function ScrollLock(): null {
 	useEffect( () => {
 		if ( lockCounter === 0 ) {
 			setLocked( true );
@@ -59,3 +84,5 @@ export default function ScrollLock() {
 
 	return null;
 }
+
+export default ScrollLock;

package/src/scroll-lock/stories/index.tsx

@@ -0,0 +1,96 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import ScrollLock from '..';
+
+const meta: ComponentMeta< typeof ScrollLock > = {
+	component: ScrollLock,
+	title: 'Components/ScrollLock',
+	parameters: {
+		controls: { hideNoControlsWarning: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+function StripedBackground( props: { children: ReactNode } ) {
+	return (
+		<div
+			style={ {
+				backgroundColor: '#fff',
+				backgroundImage:
+					'linear-gradient(transparent 50%, rgba(0, 0, 0, 0.05) 50%)',
+				backgroundSize: '50px 50px',
+				height: 3000,
+				position: 'relative',
+			} }
+			{ ...props }
+		/>
+	);
+}
+
+function ToggleContainer( props: { children: ReactNode } ) {
+	const { children } = props;
+	return (
+		<div
+			style={ {
+				position: 'sticky',
+				top: 0,
+				padding: 40,
+				display: 'flex',
+				justifyContent: 'center',
+				textAlign: 'center',
+			} }
+		>
+			<div>{ children }</div>
+		</div>
+	);
+}
+
+export const Default: ComponentStory< typeof ScrollLock > = () => {
+	const [ isScrollLocked, setScrollLocked ] = useState( false );
+	const toggleLock = () => setScrollLocked( ! isScrollLocked );
+
+	return (
+		<div style={ { height: 1000 } }>
+			<div
+				style={ {
+					overflow: 'auto',
+					height: 240,
+					border: '1px solid lightgray',
+				} }
+			>
+				<StripedBackground>
+					<div>
+						Start scrolling down. Once you scroll to the end of this
+						container with the stripes, the rest of the page will
+						continue scrolling. <code>ScrollLock</code> prevents
+						this &quot;scroll bleed&quot; from happening.
+					</div>
+					<ToggleContainer>
+						<Button variant="primary" onClick={ toggleLock }>
+							Toggle Scroll Lock
+						</Button>
+						{ isScrollLocked && <ScrollLock /> }
+						<p>
+							Scroll locked:{ ' ' }
+							<strong>{ isScrollLocked ? 'Yes' : 'No' }</strong>
+						</p>
+					</ToggleContainer>
+				</StripedBackground>
+			</div>
+		</div>
+	);
+};

package/src/scroll-lock/test/index.tsx

@@ -0,0 +1,26 @@
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import ScrollLock from '..';
+
+describe( 'scroll-lock', () => {
+	const lockingClassName = 'lockscroll';
+
+	it( 'locks when mounted', () => {
+		expect( document.documentElement ).not.toHaveClass( lockingClassName );
+		render( <ScrollLock /> );
+		expect( document.documentElement ).toHaveClass( lockingClassName );
+	} );
+
+	it( 'unlocks when unmounted', () => {
+		const { unmount } = render( <ScrollLock /> );
+		expect( document.documentElement ).toHaveClass( lockingClassName );
+		unmount();
+		expect( document.documentElement ).not.toHaveClass( lockingClassName );
+	} );
+} );

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;
 };