@wordpress/components 17.0.0 → 19.0.2

package/src/navigator/test/index.js

@@ -0,0 +1,218 @@
+/**
+ * External dependencies
+ */
+import { render, screen, fireEvent } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { NavigatorProvider, NavigatorScreen, useNavigator } from '../';
+
+jest.mock( 'framer-motion', () => {
+	const actual = jest.requireActual( 'framer-motion' );
+	return {
+		__esModule: true,
+		...actual,
+		AnimatePresence: ( { children } ) => <div>{ children }</div>,
+		motion: {
+			...actual.motion,
+			div: require( 'react' ).forwardRef( ( { children }, ref ) => (
+				<div ref={ ref }>{ children }</div>
+			) ),
+		},
+	};
+} );
+
+const PATHS = {
+	HOME: '/',
+	CHILD: '/child',
+	NOT_FOUND: '/not-found',
+};
+
+function NavigatorButton( { path, isBack = false, onClick, ...props } ) {
+	const navigator = useNavigator();
+	return (
+		<button
+			onClick={ () => {
+				navigator.push( path, { isBack } );
+				// Used to spy on the values passed to `navigator.push`
+				onClick?.( { path, isBack } );
+			} }
+			{ ...props }
+		/>
+	);
+}
+
+const MyNavigation = ( {
+	initialPath = PATHS.HOME,
+	onNavigatorButtonClick,
+} ) => (
+	<NavigatorProvider initialPath={ initialPath }>
+		<NavigatorScreen path={ PATHS.HOME }>
+			<p>This is the home screen.</p>
+			<NavigatorButton
+				path={ PATHS.CHILD }
+				onClick={ onNavigatorButtonClick }
+			>
+				Navigate to child screen.
+			</NavigatorButton>
+			<NavigatorButton
+				path={ PATHS.NOT_FOUND }
+				onClick={ onNavigatorButtonClick }
+			>
+				Navigate to non-existing screen.
+			</NavigatorButton>
+		</NavigatorScreen>
+
+		<NavigatorScreen path={ PATHS.CHILD }>
+			<p>This is the child screen.</p>
+			<NavigatorButton
+				path={ PATHS.HOME }
+				isBack
+				onClick={ onNavigatorButtonClick }
+			>
+				Go back
+			</NavigatorButton>
+		</NavigatorScreen>
+
+		{ /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included */ }
+	</NavigatorProvider>
+);
+
+const getNavigationScreenByText = ( text, { throwIfNotFound = true } = {} ) => {
+	const fnName = throwIfNotFound ? 'getByText' : 'queryByText';
+	return screen[ fnName ]( text );
+};
+const getHomeScreen = ( { throwIfNotFound } = {} ) =>
+	getNavigationScreenByText( 'This is the home screen.', {
+		throwIfNotFound,
+	} );
+const getChildScreen = ( { throwIfNotFound } = {} ) =>
+	getNavigationScreenByText( 'This is the child screen.', {
+		throwIfNotFound,
+	} );
+
+const getNavigationButtonByText = ( text, { throwIfNotFound = true } = {} ) => {
+	const fnName = throwIfNotFound ? 'getByRole' : 'queryByRole';
+	return screen[ fnName ]( 'button', { name: text } );
+};
+const getToNonExistingScreenButton = ( { throwIfNotFound } = {} ) =>
+	getNavigationButtonByText( 'Navigate to non-existing screen.', {
+		throwIfNotFound,
+	} );
+const getToChildScreenButton = ( { throwIfNotFound } = {} ) =>
+	getNavigationButtonByText( 'Navigate to child screen.', {
+		throwIfNotFound,
+	} );
+const getToHomeScreenButton = ( { throwIfNotFound } = {} ) =>
+	getNavigationButtonByText( 'Go back', {
+		throwIfNotFound,
+	} );
+
+describe( 'Navigator', () => {
+	it( 'should render', () => {
+		render( <MyNavigation /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'should show a different screen on the first render depending on the value of `initialPath`', () => {
+		render( <MyNavigation initialPath={ PATHS.CHILD } /> );
+
+		expect(
+			getHomeScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+		expect( getChildScreen() ).toBeInTheDocument();
+	} );
+
+	it( 'should ignore changes to `initialPath` after the first render', () => {
+		const { rerender } = render( <MyNavigation /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+
+		rerender( <MyNavigation initialPath={ PATHS.CHILD } /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'should not rended anything if the `initialPath` does not match any available screen', () => {
+		render( <MyNavigation initialPath={ PATHS.NOT_FOUND } /> );
+
+		expect(
+			getHomeScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'should navigate across screens', () => {
+		const spy = jest.fn();
+
+		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
+
+		expect( getToChildScreenButton() ).toBeInTheDocument();
+
+		// Navigate to child screen
+		fireEvent.click( getToChildScreenButton() );
+
+		expect(
+			getHomeScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+		expect( getChildScreen() ).toBeInTheDocument();
+		expect( getToHomeScreenButton() ).toBeInTheDocument();
+
+		// Navigate back to home screen
+		fireEvent.click( getToHomeScreenButton() );
+
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+		expect( getHomeScreen() ).toBeInTheDocument();
+
+		// Check the values passed to `navigator.push()`
+		expect( spy ).toHaveBeenCalledTimes( 2 );
+		expect( spy ).toHaveBeenNthCalledWith( 1, {
+			path: PATHS.CHILD,
+			isBack: false,
+		} );
+		expect( spy ).toHaveBeenNthCalledWith( 2, {
+			path: PATHS.HOME,
+			isBack: true,
+		} );
+	} );
+
+	it( 'should not rended anything if the path does not match any available screen', () => {
+		const spy = jest.fn();
+
+		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
+
+		expect( getToChildScreenButton() ).toBeInTheDocument();
+
+		// Attempt to navigate to non-existing screen. No screens get rendered.
+		fireEvent.click( getToNonExistingScreenButton() );
+
+		expect(
+			getHomeScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+		expect(
+			getChildScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
+
+		// Check the values passed to `navigator.push()`
+		expect( spy ).toHaveBeenCalledTimes( 1 );
+		expect( spy ).toHaveBeenNthCalledWith( 1, {
+			path: PATHS.NOT_FOUND,
+			isBack: false,
+		} );
+	} );
+} );

package/src/navigator/types.ts

@@ -0,0 +1,45 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { ReactNode } from 'react';
+
+type NavigatorPathOptions = {
+	isBack?: boolean;
+};
+
+export type NavigatorPath = NavigatorPathOptions & {
+	path?: string;
+};
+
+export type NavigatorContext = [
+	NavigatorPath,
+	( path: NavigatorPath ) => void
+];
+
+// Returned by the `useNavigator` hook
+export type Navigator = {
+	push: ( path: string, options: NavigatorPathOptions ) => void;
+};
+
+export type NavigatorProviderProps = {
+	/**
+	 * The initial active path.
+	 */
+	initialPath: string;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+};
+
+export type NavigatorScreenProps = {
+	/**
+	 * The screen's path, matched against the current path stored in the navigator.
+	 */
+	path: string;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+};

package/src/navigator/use-navigator.ts

@@ -0,0 +1,25 @@
+/**
+ * WordPress dependencies
+ */
+import { useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { NavigatorContext } from './context';
+import type { Navigator } from './types';
+
+/**
+ * Retrieves a `navigator` instance.
+ */
+function useNavigator(): Navigator {
+	const [ , setPath ] = useContext( NavigatorContext );
+
+	return {
+		push( path, options ) {
+			setPath( { path, ...options } );
+		},
+	};
+}
+
+export default useNavigator;

package/src/notice/stories/index.js

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

package/src/number-control/README.md

@@ -81,6 +81,22 @@ The position of the label (`top`, `side`, `bottom`, or `edge`).
 -   Type: `String`
 -   Required: No
 
+### max
+
+The maximum `value` allowed.
+
+-   Type: `Number`
+-   Required: No
+-   Default: `Infinity`
+
+### min
+
+The minimum `value` allowed.
+
+-   Type: `Number`
+-   Required: No
+-   Default: `-Infinity`
+
 ### required
 
 If `true` enforces a valid number within the control's min/max range. If `false` allows an empty string as a valid value.
@@ -99,8 +115,8 @@ Amount to increment by when the `SHIFT` key is held down. This shift value is a
 
 ### step
 
-Amount to increment by when incrementing/decrementing.
+Amount by which the `value` is changed when incrementing/decrementing. It is also a factor in validation as `value` must be a multiple of `step` (offset by `min`, if specified) to be valid. Accepts the special string value `any` that voids the validation constraint and causes stepping actions to increment/decrement by `1`.
 
--   Type: `Number`
+-   Type: `Number | "any"`
 -   Required: No
 -   Default: `1`

package/src/number-control/index.js

@@ -17,7 +17,6 @@ import { Input } from './styles/number-control-styles';
 import * as inputControlActionTypes from '../input-control/reducer/actions';
 import { composeStateReducers } from '../input-control/reducer/reducer';
 import { add, subtract, roundClamp } from '../utils/math';
-import { useJumpStep } from '../utils/hooks';
 import { isValueEmpty } from '../utils/values';
 
 export function NumberControl(
@@ -40,13 +39,15 @@ export function NumberControl(
 	},
 	ref
 ) {
-	const baseValue = roundClamp( 0, min, max, step );
-
-	const jumpStep = useJumpStep( {
-		step,
-		shiftStep,
-		isShiftStepEnabled,
-	} );
+	const isStepAny = step === 'any';
+	const baseStep = isStepAny ? 1 : parseFloat( step );
+	const baseValue = roundClamp( 0, min, max, baseStep );
+	const constrainValue = ( value, stepOverride ) => {
+		// When step is "any" clamp the value, otherwise round and clamp it
+		return isStepAny
+			? Math.min( max, Math.max( min, value ) )
+			: roundClamp( value, min, max, stepOverride ?? baseStep );
+	};
 
 	const autoComplete = typeProp === 'number' ? 'off' : null;
 	const classes = classNames( 'components-number-control', className );
@@ -75,8 +76,8 @@ export function NumberControl(
 			const enableShift = event.shiftKey && isShiftStepEnabled;
 
 			const incrementalValue = enableShift
-				? parseFloat( shiftStep ) * parseFloat( step )
-				: parseFloat( step );
+				? parseFloat( shiftStep ) * baseStep
+				: baseStep;
 			let nextValue = isValueEmpty( currentValue )
 				? baseValue
 				: currentValue;
@@ -93,58 +94,55 @@ export function NumberControl(
 				nextValue = subtract( nextValue, incrementalValue );
 			}
 
-			nextValue = roundClamp( nextValue, min, max, incrementalValue );
-
-			state.value = nextValue;
+			state.value = constrainValue(
+				nextValue,
+				enableShift ? incrementalValue : null
+			);
 		}
 
 		/**
 		 * Handles drag to update events
 		 */
 		if ( type === inputControlActionTypes.DRAG && isDragEnabled ) {
-			const { delta, shiftKey } = payload;
-			const [ x, y ] = delta;
-			const modifier = shiftKey
-				? parseFloat( shiftStep ) * parseFloat( step )
-				: parseFloat( step );
+			const [ x, y ] = payload.delta;
+			const enableShift = payload.shiftKey && isShiftStepEnabled;
+			const modifier = enableShift
+				? parseFloat( shiftStep ) * baseStep
+				: baseStep;
 
 			let directionModifier;
-			let directionBaseValue;
+			let delta;
 
 			switch ( dragDirection ) {
 				case 'n':
-					directionBaseValue = y;
+					delta = y;
 					directionModifier = -1;
 					break;
 
 				case 'e':
-					directionBaseValue = x;
+					delta = x;
 					directionModifier = isRTL() ? -1 : 1;
 					break;
 
 				case 's':
-					directionBaseValue = y;
+					delta = y;
 					directionModifier = 1;
 					break;
 
 				case 'w':
-					directionBaseValue = x;
+					delta = x;
 					directionModifier = isRTL() ? 1 : -1;
 					break;
 			}
 
-			const distance = directionBaseValue * modifier * directionModifier;
-			let nextValue;
+			if ( delta !== 0 ) {
+				delta = Math.ceil( Math.abs( delta ) ) * Math.sign( delta );
+				const distance = delta * modifier * directionModifier;
 
-			if ( distance !== 0 ) {
-				nextValue = roundClamp(
+				state.value = constrainValue(
 					add( currentValue, distance ),
-					min,
-					max,
-					modifier
+					enableShift ? modifier : null
 				);
-
-				state.value = nextValue;
 			}
 		}
 
@@ -159,7 +157,7 @@ export function NumberControl(
 
 			state.value = applyEmptyValue
 				? currentValue
-				: roundClamp( currentValue, min, max, step );
+				: constrainValue( currentValue );
 		}
 
 		return state;
@@ -179,7 +177,7 @@ export function NumberControl(
 			min={ min }
 			ref={ ref }
 			required={ required }
-			step={ jumpStep }
+			step={ step }
 			type={ typeProp }
 			value={ valueProp }
 			__unstableStateReducer={ composeStateReducers(

package/src/number-control/stories/index.js

@@ -16,6 +16,9 @@ import NumberControl from '../';
 export default {
 	title: 'Components/NumberControl',
 	component: NumberControl,
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 function Example() {
@@ -32,7 +35,7 @@ function Example() {
 		placeholder: text( 'placeholder', 0 ),
 		required: boolean( 'required', false ),
 		shiftStep: number( 'shiftStep', 10 ),
-		step: number( 'step', 1 ),
+		step: text( 'step', 1 ),
 	};
 
 	return (

package/src/number-control/test/index.js

@@ -170,6 +170,16 @@ describe( 'NumberControl', () => {
 			expect( input.value ).toBe( '-4' );
 		} );
 
+		it( 'should increment while preserving the decimal value when `step` is “any”', () => {
+			render( <StatefulNumberControl value={ 866.5309 } step="any" /> );
+
+			const input = getInput();
+			input.focus();
+			fireKeyDown( { keyCode: UP } );
+
+			expect( input.value ).toBe( '867.5309' );
+		} );
+
 		it( 'should increment by shiftStep on key UP + shift press', () => {
 			render( <StatefulNumberControl value={ 5 } shiftStep={ 10 } /> );
 
@@ -180,6 +190,16 @@ describe( 'NumberControl', () => {
 			expect( input.value ).toBe( '20' );
 		} );
 
+		it( 'should increment by shiftStep while preserving the decimal value when `step` is “any”', () => {
+			render( <StatefulNumberControl value={ 857.5309 } step="any" /> );
+
+			const input = getInput();
+			input.focus();
+			fireKeyDown( { keyCode: UP, shiftKey: true } );
+
+			expect( input.value ).toBe( '867.5309' );
+		} );
+
 		it( 'should increment by custom shiftStep on key UP + shift press', () => {
 			render( <StatefulNumberControl value={ 5 } shiftStep={ 100 } /> );
 
@@ -254,6 +274,16 @@ describe( 'NumberControl', () => {
 			expect( input.value ).toBe( '-6' );
 		} );
 
+		it( 'should decrement while preserving the decimal value when `step` is “any”', () => {
+			render( <StatefulNumberControl value={ 868.5309 } step="any" /> );
+
+			const input = getInput();
+			input.focus();
+			fireKeyDown( { keyCode: DOWN } );
+
+			expect( input.value ).toBe( '867.5309' );
+		} );
+
 		it( 'should decrement by shiftStep on key DOWN + shift press', () => {
 			render( <StatefulNumberControl value={ 5 } /> );
 
@@ -264,6 +294,16 @@ describe( 'NumberControl', () => {
 			expect( input.value ).toBe( '0' );
 		} );
 
+		it( 'should decrement by shiftStep while preserving the decimal value when `step` is “any”', () => {
+			render( <StatefulNumberControl value={ 877.5309 } step="any" /> );
+
+			const input = getInput();
+			input.focus();
+			fireKeyDown( { keyCode: DOWN, shiftKey: true } );
+
+			expect( input.value ).toBe( '867.5309' );
+		} );
+
 		it( 'should decrement by custom shiftStep on key DOWN + shift press', () => {
 			render( <StatefulNumberControl value={ 5 } shiftStep={ 100 } /> );
 

package/src/panel/stories/index.js

@@ -10,7 +10,18 @@ import Panel from '../';
 import PanelRow from '../row';
 import PanelBody from '../body';
 
-export default { title: 'Components/Panel', component: Panel };
+/**
+ * WordPress dependencies
+ */
+import { wordpress } from '@wordpress/icons';
+
+export default {
+	title: 'Components/Panel',
+	component: Panel,
+	parameters: {
+		knobs: { disabled: false },
+	},
+};
 
 export const _default = () => {
 	const bodyTitle = text( 'Body Title', 'My Block Settings' );
@@ -62,7 +73,7 @@ export const multipleBodies = () => {
 export const withIcon = () => {
 	const bodyTitle = text( 'Body Title', 'My Block Settings' );
 	const rowText = text( 'Row Text', 'My Panel Inputs and Labels' );
-	const icon = text( 'Icon', 'wordpress' );
+	const icon = boolean( 'Icon', true ) ? wordpress : undefined;
 	const opened = boolean( 'Opened', true );
 	return (
 		<Panel header="My Panel">

package/src/panel/style.scss

@@ -36,7 +36,6 @@
 	align-items: center;
 	padding: 0 $grid-unit-20;
 	height: $grid-unit-60;
-	border-top: $border-width solid $gray-300;
 	border-bottom: $border-width solid $gray-300;
 
 	h2 {
@@ -50,7 +49,7 @@
 .components-panel__body + .components-panel__header,
 .components-panel__header + .components-panel__body,
 .components-panel__header + .components-panel__header {
-	margin-top: -1px;
+	margin-top: -$border-width;
 }
 
 .components-panel__body > .components-panel__body-title {

package/src/placeholder/stories/index.js

@@ -9,7 +9,13 @@ import { boolean, text } from '@storybook/addon-knobs';
 import Placeholder from '../';
 import TextControl from '../../text-control';
 
-export default { title: 'Components/Placeholder', component: Placeholder };
+export default {
+	title: 'Components/Placeholder',
+	component: Placeholder,
+	parameters: {
+		knobs: { disabled: false },
+	},
+};
 
 export const _default = () => {
 	const icon = text( 'Icon', 'smiley' );