@wordpress/components 19.4.1 → 19.7.0-next.e230fbab09.0

package/src/mobile/keyboard-aware-flat-list/index.ios.js

@@ -44,7 +44,7 @@ export const KeyboardAwareFlatList = ( {
 					this.latestContentOffsetY !== undefined &&
 					! shouldPreventAutomaticScroll()
 				) {
-					// Reset the content position if keyboard is still closed
+					// Reset the content position if keyboard is still closed.
 					if ( this.scrollViewRef ) {
 						this.scrollViewRef.scrollToPosition(
 							0,
@@ -74,7 +74,7 @@ KeyboardAwareFlatList.handleCaretVerticalPositionChange = (
 	previousCaretY
 ) => {
 	if ( previousCaretY ) {
-		//if this is not the first tap
+		// If this is not the first tap.
 		scrollView.refreshScrollForField( targetId );
 	}
 };

package/src/mobile/link-picker/index.native.js

@@ -22,7 +22,7 @@ import LinkPickerResults from './link-picker-results';
 import NavBar from '../bottom-sheet/nav-bar';
 import styles from './styles.scss';
 
-// this creates a search suggestion for adding a url directly
+// This creates a search suggestion for adding a url directly.
 export const createDirectEntry = ( value ) => {
 	let type = 'URL';
 
@@ -64,8 +64,8 @@ export const LinkPicker = ( {
 	} );
 	const directEntry = createDirectEntry( value );
 
-	// the title of a direct entry is displayed as the raw input value, but if we
-	// are replacing empty text, we want to use the generated url
+	// The title of a direct entry is displayed as the raw input value, but if we
+	// are replacing empty text, we want to use the generated url.
 	const pickLink = ( { title, url, isDirectEntry } ) => {
 		onLinkPicked( { title: isDirectEntry ? url : title, url } );
 	};

package/src/mobile/link-picker/link-picker-results.native.js

@@ -34,7 +34,7 @@ export default function LinkPickerResults( {
 		pendingRequest.current = null;
 	};
 
-	// a stable debounced function to fetch suggestions and append
+	// A stable debounced function to fetch suggestions and append.
 	const { fetchMoreSuggestions } = useSelect( ( select ) => {
 		const { getSettings } = select( 'core/block-editor' );
 		const fetchLinkSuggestions = async ( { search } ) => {
@@ -49,8 +49,8 @@ export default function LinkPickerResults( {
 			query: search,
 			links: currentSuggestions,
 		} ) => {
-			// return early if we've already detected the end of data or we are
-			// already awaiting a response
+			// Return early if we've already detected the end of data or we are
+			// already awaiting a response.
 			if ( hasAllSuggestions || pendingRequest.current ) {
 				return;
 			}
@@ -58,10 +58,10 @@ export default function LinkPickerResults( {
 			pendingRequest.current = request;
 			const suggestions = await request;
 
-			// only update links for the most recent request
+			// Only update links for the most recent request.
 			if ( suggestions && request === pendingRequest.current ) {
-				// since we don't have the response header, we check if the results
-				// are truncated to determine we've reached the end
+				// Since we don't have the response header, we check if the results
+				// are truncated to determine we've reached the end.
 				if ( suggestions.length < PER_PAGE ) {
 					setHasAllSuggestions( true );
 				}
@@ -76,10 +76,10 @@ export default function LinkPickerResults( {
 		};
 	}, [] );
 
-	// prevent setting state when unmounted
+	// Prevent setting state when unmounted.
 	useEffect( () => clearRequest, [] );
 
-	// any time the query changes, we reset pagination
+	// Any time the query changes, we reset pagination.
 	useEffect( () => {
 		clearRequest();
 		nextPage.current = 1;

package/src/mobile/link-settings/image-link-destinations-screen.native.js

@@ -86,9 +86,9 @@ function ImageLinkDestinationsScreen( props ) {
 		navigation.navigate( blockSettingsScreens.settings, {
 			// The `inputValue` name is reused from LinkPicker, as it helps avoid
 			// bugs from stale values remaining in the React Navigation route
-			// parameters
+			// parameters.
 			inputValue: newUrl,
-			// Clear link text value that may be set from LinkPicker
+			// Clear link text value that may be set from LinkPicker.
 			text: '',
 		} );
 	};

package/src/mobile/link-settings/index.native.js

@@ -33,7 +33,6 @@ import LinkRelIcon from './link-rel';
 import styles from './style.scss';
 
 const NEW_TAB_REL = 'noreferrer noopener';
-
 function LinkSettings( {
 	// Control link settings `BottomSheet` visibility
 	isVisible,
@@ -222,7 +221,7 @@ function LinkSettings( {
 		if ( ! clipboardText ) {
 			return;
 		}
-		// Check if pasted text is URL
+		// Check if pasted text is URL.
 		if ( ! isURL( clipboardText ) ) {
 			return;
 		}

package/src/mobile/link-settings/test/edit.native.js

@@ -70,12 +70,12 @@ describe.each( [
 	 * WHEN the USER selects the SETTINGS BUTTON on the EDIT IMAGE BLOCK or EDIT BUTTON BLOCK;
 	 */
 	it( 'should display the LINK SETTINGS with an EMPTY LINK TO field.', async () => {
-		// Arrange
+		// Arrange.
 		const url = 'https://tonytahmouchtest.files.wordpress.com';
 		const subject = await initializeEditor( { initialHtml } );
 		Clipboard.getString.mockReturnValue( url );
 
-		// Act
+		// Act.
 		const block = await waitFor( () =>
 			subject.getByA11yLabel(
 				type === 'core/image' ? /Image Block/ : /Button Block/
@@ -87,7 +87,7 @@ describe.each( [
 			await waitFor( () => subject.getByA11yLabel( 'Open Settings' ) )
 		);
 
-		// Assert
+		// Assert.
 		const linkToField = await waitFor( () =>
 			subject.getByA11yLabel(
 				`Link to, ${
@@ -107,12 +107,12 @@ describe.each( [
 			 * WHEN the USER selects the LINK TO cell;
 			 */
 			it( 'should display the LINK PICKER with NO FROM CLIPBOARD CELL.', async () => {
-				// Arrange
+				// Arrange.
 				const url = 'tonytahmouchtest.files.wordpress.com';
 				const subject = await initializeEditor( { initialHtml } );
 				Clipboard.getString.mockReturnValue( url );
 
-				// Act
+				// Act.
 				const block = await waitFor( () =>
 					subject.getByA11yLabel(
 						type === 'core/image' ? /Image Block/ : /Button Block/
@@ -145,7 +145,7 @@ describe.each( [
 				}
 				await waitFor( () => subject.getByA11yLabel( 'Apply' ) );
 
-				// Assert
+				// Assert.
 				expect(
 					subject.queryByA11yLabel( /Copy URL from the clipboard[,]/ )
 				).toBeNull();
@@ -160,12 +160,12 @@ describe.each( [
 			 * WHEN the USER selects the LINK TO cell;
 			 */
 			it( 'should display the LINK PICKER with NO FROM CLIPBOARD CELL.', async () => {
-				// Arrange
+				// Arrange.
 				const url = 'https://tonytahmouchtest.files.wordpress.com';
 				const subject = await initializeEditor( { initialHtml } );
 				Clipboard.getString.mockReturnValue( url );
 
-				// Act
+				// Act.
 				const block = await waitFor( () =>
 					subject.getByA11yLabel(
 						type === 'core/image' ? /Image Block/ : /Button Block/
@@ -221,7 +221,7 @@ describe.each( [
 				}
 				await waitFor( () => subject.getByA11yLabel( 'Apply' ) );
 
-				// Assert
+				// Assert.
 				expect(
 					subject.queryByA11yLabel( /Copy URL from the clipboard[,]/ )
 				).toBeNull();
@@ -239,12 +239,12 @@ describe.each( [
 				'should display the LINK PICKER with the FROM CLIPBOARD CELL populated' +
 					' with the URL from the CLIPBOARD.',
 				async () => {
-					// Arrange
+					// Arrange.
 					const url = 'https://tonytahmouchtest.files.wordpress.com';
 					const subject = await initializeEditor( { initialHtml } );
 					Clipboard.getString.mockReturnValue( url );
 
-					// Act
+					// Act.
 					const block = await waitFor( () =>
 						subject.getByA11yLabel(
 							type === 'core/image'
@@ -283,7 +283,7 @@ describe.each( [
 						)
 					);
 
-					// Assert
+					// Assert.
 					const clipboardUrl = await waitFor( () =>
 						subject.getByText( url )
 					);
@@ -306,12 +306,12 @@ describe.each( [
 				'should display the LINK SETTINGS with the URL from the CLIPBOARD' +
 					' populated in the LINK TO field.',
 				async () => {
-					// Arrange
+					// Arrange.
 					const url = 'https://tonytahmouchtest.files.wordpress.com';
 					const subject = await initializeEditor( { initialHtml } );
 					Clipboard.getString.mockReturnValue( url );
 
-					// Act
+					// Act.
 					const block = await waitFor( () =>
 						subject.getByA11yLabel(
 							type === 'core/image'
@@ -352,7 +352,7 @@ describe.each( [
 						)
 					);
 
-					// Assert
+					// Assert.
 					const linkToField = await waitFor( () =>
 						subject.getByA11yLabel(
 							`Link to, ${

package/src/modal/aria-helper.js

@@ -1,4 +1,4 @@
-//@ts-nocheck
+// @ts-nocheck
 
 /**
  * External dependencies

package/src/modal/index.js

@@ -1,4 +1,4 @@
-//@ts-nocheck
+// @ts-nocheck
 
 /**
  * External dependencies
@@ -45,7 +45,7 @@ function Modal( props, forwardedRef ) {
 		shouldCloseOnEsc = true,
 		shouldCloseOnClickOutside = true,
 		isDismissible = true,
-		/* accessibility */
+		/* Accessibility. */
 		aria = {
 			labelledby: null,
 			describedby: null,

package/src/navigable-container/container.js

@@ -93,9 +93,9 @@ class NavigableContainer extends Component {
 
 		const offset = eventToOffset( event );
 
-		// eventToOffset returns undefined if the event is not handled by the component
+		// eventToOffset returns undefined if the event is not handled by the component.
 		if ( offset !== undefined && stopNavigationEvents ) {
-			// Prevents arrow key handlers bound to the document directly interfering
+			// Prevents arrow key handlers bound to the document directly interfering.
 			event.stopImmediatePropagation();
 
 			// When navigating a collection of items, prevent scroll containers

package/src/navigable-container/tabbable.js

@@ -27,7 +27,7 @@ export function TabbableContainer( { eventToOffset, ...props }, ref ) {
 		// - +1: move focus forward
 		// - -1: move focus backward
 		// -  0: don't move focus, but acknowledge event and thus stop it
-		// - undefined: do nothing, let the event propagate
+		// - undefined: do nothing, let the event propagate.
 		if ( eventToOffset ) {
 			return eventToOffset( evt );
 		}

package/src/navigable-container/test/menu.js

@@ -75,7 +75,7 @@ describe( 'NavigableMenu', () => {
 
 		container.querySelector( '#btn1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown( keyCode, expectedActiveIndex, expectedStop ) {
 			const interaction = fireKeyDown(
 				getByRole( 'menu' ),
@@ -129,7 +129,7 @@ describe( 'NavigableMenu', () => {
 
 		container.querySelector( '#btn1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown( keyCode, expectedActiveIndex, expectedStop ) {
 			const interaction = fireKeyDown(
 				getByRole( 'menu' ),
@@ -185,7 +185,7 @@ describe( 'NavigableMenu', () => {
 
 		container.querySelector( '#btn1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown( keyCode, expectedActiveIndex, expectedStop ) {
 			const interaction = fireKeyDown(
 				getByRole( 'menu' ),
@@ -239,7 +239,7 @@ describe( 'NavigableMenu', () => {
 
 		container.querySelector( '#btn1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown( keyCode, expectedActiveIndex, expectedStop ) {
 			const interaction = fireKeyDown(
 				getByRole( 'menu' ),
@@ -284,7 +284,7 @@ describe( 'NavigableMenu', () => {
 
 		container.querySelector( '#btn1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown( keyCode, expectedActiveIndex, expectedStop ) {
 			const interaction = fireKeyDown( getByRole( 'menu' ), keyCode );
 			expect( currentIndex ).toBe( expectedActiveIndex );

package/src/navigable-container/test/tabbable.js

@@ -75,7 +75,7 @@ describe( 'TabbableContainer', () => {
 
 		container.querySelector( '#section1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown(
 			keyCode,
 			shiftKey,
@@ -132,7 +132,7 @@ describe( 'TabbableContainer', () => {
 
 		container.querySelector( '#section1' ).focus();
 
-		// Navigate options
+		// Navigate options.
 		function assertKeyDown(
 			keyCode,
 			shiftKey,

package/src/navigation/item/index.js

@@ -43,7 +43,7 @@ export default function NavigationItem( props ) {
 
 	// If hideIfTargetMenuEmpty prop is true
 	// And the menu we are supposed to navigate to
-	// Is marked as empty, then we skip rendering the item
+	// Is marked as empty, then we skip rendering the item.
 	if (
 		hideIfTargetMenuEmpty &&
 		navigateToMenu &&

package/src/navigation/menu/index.js

@@ -45,7 +45,7 @@ export default function NavigationMenu( props ) {
 		search: uncontrolledSearch,
 	};
 
-	// Keep the children rendered to make sure invisible items are included in the navigation tree
+	// Keep the children rendered to make sure invisible items are included in the navigation tree.
 	if ( activeMenu !== menu ) {
 		return (
 			<NavigationMenuContext.Provider value={ context }>

package/src/navigation/stories/controlled-state.js

@@ -15,11 +15,11 @@ export function ControlledStateStory() {
 	const [ activeItem, setActiveItem ] = useState( 'item-1' );
 	const [ activeMenu, setActiveMenu ] = useState( 'root' );
 
-	// Mock navigation link
+	// Mock navigation link.
 	const MockLink = ( { href, children } ) => (
 		<Button
 			href={ href }
-			// Since we're not actually navigating pages, simulate it with on onClick
+			// Since we're not actually navigating pages, simulate it with on onClick.
 			onClick={ ( event ) => {
 				event.preventDefault();
 				const item = href.replace( 'https://example.com/', '' );

package/src/navigation/stories/index.js

@@ -15,7 +15,7 @@ import { HideIfEmptyStory } from './hide-if-empty';
 import './style.css';
 
 export default {
-	title: 'Components/Navigation',
+	title: 'Components (Experimental)/Navigation',
 	component: Navigation,
 	subcomponents: {
 		NavigationBackButton,

package/src/navigator/index.ts

@@ -1,3 +1,5 @@
 export { default as NavigatorProvider } from './navigator-provider';
 export { default as NavigatorScreen } from './navigator-screen';
+export { default as NavigatorButton } from './navigator-button';
+export { default as NavigatorBackButton } from './navigator-back-button';
 export { default as useNavigator } from './use-navigator';

package/src/navigator/navigator-back-button/README.md

@@ -0,0 +1,31 @@
+# `NavigatorBackButton`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+The `NavigatorBackButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook).
+
+## Usage
+
+Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
+
+## Props
+
+The component accepts the following props:
+
+### `onClick`: `React.MouseEventHandler< HTMLElement >`
+
+The callback called in response to a `click` event.
+
+-   Required: No
+
+### `path`: `string`
+
+The path of the screen to navigate to.
+
+-   Required: Yes
+
+### Inherited props
+
+`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.

package/src/navigator/navigator-back-button/component.tsx

@@ -0,0 +1,62 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useNavigatorBackButton } from './hook';
+import type { NavigatorBackButtonProps } from '../types';
+
+function NavigatorBackButton(
+	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const navigatorBackButtonProps = useNavigatorBackButton( props );
+
+	return <View ref={ forwardedRef } { ...navigatorBackButtonProps } />;
+}
+
+/**
+ * The `NavigatorBackButton` component can be used to navigate to a screen and
+ * should be used in combination with the `NavigatorProvider`, the
+ * `NavigatorScreen` and the `NavigatorButton` components (or the `useNavigator`
+ * hook).
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalNavigatorProvider as NavigatorProvider,
+ *   __experimentalNavigatorScreen as NavigatorScreen,
+ *   __experimentalNavigatorButton as NavigatorButton,
+ *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ * } from '@wordpress/components';
+ *
+ * const MyNavigation = () => (
+ *   <NavigatorProvider initialPath="/">
+ *     <NavigatorScreen path="/">
+ *       <p>This is the home screen.</p>
+ *        <NavigatorButton path="/child">
+ *          Navigate to child screen.
+ *       </NavigatorButton>
+ *     </NavigatorScreen>
+ *
+ *     <NavigatorScreen path="/child">
+ *       <p>This is the child screen.</p>
+ *       <NavigatorBackButton>
+ *         Go back
+ *       </NavigatorBackButton>
+ *     </NavigatorScreen>
+ *   </NavigatorProvider>
+ * );
+ * ```
+ */
+const ConnectedNavigatorBackButton = contextConnect(
+	NavigatorBackButton,
+	'NavigatorBackButton'
+);
+
+export default ConnectedNavigatorBackButton;

package/src/navigator/navigator-back-button/hook.ts

@@ -0,0 +1,40 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+/**
+ * Internal dependencies
+ */
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import Button from '../../button';
+import useNavigator from '../use-navigator';
+import type { NavigatorBackButtonProps } from '../types';
+
+export function useNavigatorBackButton(
+	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >
+) {
+	const { onClick, as = Button, ...otherProps } = useContextSystem(
+		props,
+		'NavigatorBackButton'
+	);
+
+	const { goBack } = useNavigator();
+	const handleClick: React.MouseEventHandler< HTMLButtonElement > = useCallback(
+		( e ) => {
+			e.preventDefault();
+			goBack();
+			onClick?.( e );
+		},
+		[ goBack, onClick ]
+	);
+
+	return {
+		as,
+		onClick: handleClick,
+		...otherProps,
+	};
+}

package/src/navigator/navigator-back-button/index.ts

@@ -0,0 +1 @@
+export { default } from './component';

package/src/navigator/navigator-button/README.md

@@ -0,0 +1,38 @@
+# `NavigatorButton`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+The `NavigatorButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components (or the `useNavigator` hook).
+
+## Usage
+
+Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
+
+## Props
+
+The component accepts the following props:
+
+### `attributeName`: `string`
+
+The HTML attribute used to identify the `NavigatorButton`, which is used by `Navigator` to restore focus.
+
+-   Required: No
+-   Default: `id`
+
+### `onClick`: `React.MouseEventHandler< HTMLElement >`
+
+The callback called in response to a `click` event.
+
+-   Required: No
+
+### `path`: `string`
+
+The path of the screen to navigate to. The value of this prop needs to be [a valid value for an HTML attribute](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2).
+
+-   Required: Yes
+
+### Inherited props
+
+`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.

package/src/navigator/navigator-button/component.tsx

@@ -0,0 +1,61 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useNavigatorButton } from './hook';
+import type { NavigatorButtonProps } from '../types';
+
+function NavigatorButton(
+	props: WordPressComponentProps< NavigatorButtonProps, 'button' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const navigatorButtonProps = useNavigatorButton( props );
+
+	return <View ref={ forwardedRef } { ...navigatorButtonProps } />;
+}
+
+/**
+ * The `NavigatorButton` component can be used to navigate to a screen and should
+ * be used in combination with the `NavigatorProvider`, the `NavigatorScreen`
+ * and the `NavigatorBackButton` components (or the `useNavigator` hook).
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalNavigatorProvider as NavigatorProvider,
+ *   __experimentalNavigatorScreen as NavigatorScreen,
+ *   __experimentalNavigatorButton as NavigatorButton,
+ *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ * } from '@wordpress/components';
+ *
+ * const MyNavigation = () => (
+ *   <NavigatorProvider initialPath="/">
+ *     <NavigatorScreen path="/">
+ *       <p>This is the home screen.</p>
+ *        <NavigatorButton path="/child">
+ *          Navigate to child screen.
+ *       </NavigatorButton>
+ *     </NavigatorScreen>
+ *
+ *     <NavigatorScreen path="/child">
+ *       <p>This is the child screen.</p>
+ *       <NavigatorBackButton>
+ *         Go back
+ *       </NavigatorBackButton>
+ *     </NavigatorScreen>
+ *   </NavigatorProvider>
+ * );
+ * ```
+ */
+const ConnectedNavigatorButton = contextConnect(
+	NavigatorButton,
+	'NavigatorButton'
+);
+
+export default ConnectedNavigatorButton;