@wordpress/components 19.14.0 → 19.15.0

package/src/grid/types.ts

@@ -1,9 +1,12 @@
 /**
  * External dependencies
  */
-import type { CSSProperties } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
-type ResponsiveCSSValue< T > = Array< T | undefined > | T;
+/**
+ * Internal dependencies
+ */
+import type { ResponsiveCSSValue } from '../ui/utils/types';
 
 type GridAlignment =
 	| 'bottom'
@@ -18,11 +21,7 @@ type GridAlignment =
 	| 'topLeft'
 	| 'topRight';
 
-type GridColumns = ResponsiveCSSValue< number >;
-
-type GridRows = ResponsiveCSSValue< number >;
-
-export type Props = {
+export type GridProps = {
 	/**
 	 * Adjusts the block alignment of children.
 	 */
@@ -31,26 +30,30 @@ export type Props = {
 	 * Adjusts the horizontal and vertical alignment of children.
 	 */
 	alignment?: GridAlignment;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
 	/**
 	 * Adjusts the number of columns of the `Grid`.
 	 *
 	 * @default 2
 	 */
-	columns?: GridColumns;
+	columns?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the `grid-column-gap`.
 	 */
 	columnGap?: CSSProperties[ 'gridColumnGap' ];
-	/**
-	 * Changes the CSS display from `grid` to `inline-grid`.
-	 */
-	isInline?: boolean;
 	/**
 	 * Gap between each child.
 	 *
 	 * @default 3
 	 */
 	gap?: number;
+	/**
+	 * Changes the CSS display from `grid` to `inline-grid`.
+	 */
+	isInline?: boolean;
 	/**
 	 * Adjusts the inline alignment of children.
 	 */
@@ -62,7 +65,7 @@ export type Props = {
 	/**
 	 * Adjusts the number of rows of the `Grid`.
 	 */
-	rows?: GridRows;
+	rows?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the CSS grid `template-columns`.
 	 */
@@ -71,8 +74,4 @@ export type Props = {
 	 * Adjusts the CSS grid `template-rows`.
 	 */
 	templateRows?: CSSProperties[ 'gridTemplateRows' ];
-	/**
-	 * The children elements.
-	 */
-	children: React.ReactNode;
 };

package/src/grid/{utils.js → utils.ts}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
 const ALIGNMENTS = {
 	bottom: { alignItems: 'flex-end', justifyContent: 'center' },
 	bottomLeft: { alignItems: 'flex-start', justifyContent: 'flex-end' },
@@ -12,14 +17,11 @@ const ALIGNMENTS = {
 	topRight: { alignItems: 'flex-start', justifyContent: 'flex-end' },
 };
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {keyof typeof ALIGNMENTS | undefined} alignment
- * @return {{ alignItems?: import('react').CSSProperties['alignItems'], justifyContent?: import('react').CSSProperties['justifyContent']}} CSS props for alignment
- */
-export function getAlignmentProps( alignment ) {
+export function getAlignmentProps( alignment?: keyof typeof ALIGNMENTS ): {
+	alignItems?: CSSProperties[ 'alignItems' ];
+	justifyContent?: CSSProperties[ 'justifyContent' ];
+} {
 	const alignmentProps = alignment ? ALIGNMENTS[ alignment ] : {};
 
 	return alignmentProps;
 }
-/* eslint-enable jsdoc/valid-types */

package/src/guide/style.scss

@@ -20,6 +20,7 @@
 		border-bottom: none;
 		padding: 0;
 		position: sticky;
+		height: $header-height;
 
 		.components-button {
 			align-self: flex-start;

package/src/h-stack/{component.js → component.tsx}

@@ -1,15 +1,15 @@
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import { useHStack } from './hook';
+import type { Props } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function HStack( props, forwardedRef ) {
+function UnconnectedHStack(
+	props: WordPressComponentProps< Props, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) {
 	const hStackProps = useHStack( props );
 
 	return <View { ...hStackProps } ref={ forwardedRef } />;
@@ -38,6 +38,6 @@ function HStack( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedHStack = contextConnect( HStack, 'HStack' );
+export const HStack = contextConnect( UnconnectedHStack, 'HStack' );
 
-export default ConnectedHStack;
+export default HStack;

package/src/h-stack/{hook.js → hook.tsx}

@@ -1,16 +1,22 @@
+/**
+ * External dependencies
+ */
+import type { ReactElement } from 'react';
+
 /**
  * Internal dependencies
  */
-import { hasConnectNamespace, useContextSystem } from '../ui/context';
+import {
+	hasConnectNamespace,
+	useContextSystem,
+	WordPressComponentProps,
+} from '../ui/context';
 import { FlexItem, useFlex } from '../flex';
 import { getAlignmentProps } from './utils';
 import { getValidChildren } from '../ui/utils/get-valid-children';
+import type { Props } from './types';
 
-/**
- *
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useHStack( props ) {
+export function useHStack( props: WordPressComponentProps< Props, 'div' > ) {
 	const {
 		alignment = 'edge',
 		children,
@@ -22,19 +28,18 @@ export function useHStack( props ) {
 	const align = getAlignmentProps( alignment, direction );
 
 	const validChildren = getValidChildren( children );
-	const clonedChildren = validChildren.map(
-		// @ts-ignore
-		( /** @type {import('react').ReactElement} */ child, index ) => {
-			const _key = child.key || `hstack-${ index }`;
-			const _isSpacer = hasConnectNamespace( child, [ 'Spacer' ] );
+	const clonedChildren = validChildren.map( ( child, index ) => {
+		const _isSpacer = hasConnectNamespace( child, [ 'Spacer' ] );
 
-			if ( _isSpacer ) {
-				return <FlexItem isBlock key={ _key } { ...child.props } />;
-			}
+		if ( _isSpacer ) {
+			const childElement = child as ReactElement;
+			const _key = childElement.key || `hstack-${ index }`;
 
-			return child;
+			return <FlexItem isBlock key={ _key } { ...childElement.props } />;
 		}
-	);
+
+		return child;
+	} );
 
 	const propsForFlex = {
 		children: clonedChildren,

package/src/h-stack/stories/index.tsx

@@ -0,0 +1,92 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { HStack } from '..';
+
+const ALIGNMENTS = {
+	top: 'top',
+	topLeft: 'topLeft',
+	topRight: 'topRight',
+	left: 'left',
+	center: 'center',
+	right: 'right',
+	bottom: 'bottom',
+	bottomLeft: 'bottomLeft',
+	bottomRight: 'bottomRight',
+	edge: 'edge',
+	stretch: 'stretch',
+};
+
+const DIRECTIONS = {
+	row: 'row',
+	column: 'column',
+	responsive: [ 'column', 'row' ],
+};
+
+const JUSTIFICATIONS = {
+	'space-around': 'space-around',
+	'space-between': 'space-between',
+	'space-evenly': 'space-evenly',
+	stretch: 'stretch',
+	center: 'center',
+	end: 'end',
+	'flex-end': 'flex-end',
+	'flex-start': 'flex-start',
+	start: 'start',
+};
+
+const meta: ComponentMeta< typeof HStack > = {
+	component: HStack,
+	title: 'Components (Experimental)/HStack',
+	argTypes: {
+		as: {
+			control: { type: null },
+		},
+		children: {
+			control: { type: null },
+		},
+		alignment: {
+			control: { type: 'select' },
+			options: Object.keys( ALIGNMENTS ),
+			mapping: ALIGNMENTS,
+		},
+		direction: {
+			control: { type: 'select' },
+			options: Object.keys( DIRECTIONS ),
+			mapping: DIRECTIONS,
+		},
+		justify: {
+			control: { type: 'select' },
+			options: Object.keys( JUSTIFICATIONS ),
+			mapping: JUSTIFICATIONS,
+		},
+		spacing: {
+			control: { type: 'text' },
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof HStack > = ( args ) => (
+	<HStack { ...args } style={ { background: '#eee', minHeight: '3rem' } }>
+		{ [ 'One', 'Two', 'Three', 'Four', 'Five' ].map( ( text ) => (
+			<View key={ text } style={ { background: '#b9f9ff' } }>
+				{ text }
+			</View>
+		) ) }
+	</HStack>
+);
+
+export const Default: ComponentStory< typeof HStack > = Template.bind( {} );
+Default.args = {
+	spacing: '3',
+};

package/src/h-stack/{utils.js → utils.ts}

@@ -1,10 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
 /**
  * Internal dependencies
  */
+import type { FlexDirection } from '../flex/types';
+import type { HStackAlignment, AlignmentProps, Alignments } from './types';
 import { isValueDefined } from '../utils/values';
 
-/** @type {import('./types').Alignments} */
-const ALIGNMENTS = {
+const H_ALIGNMENTS: Alignments = {
 	bottom: { align: 'flex-end', justify: 'center' },
 	bottomLeft: { align: 'flex-start', justify: 'flex-end' },
 	bottomRight: { align: 'flex-end', justify: 'flex-end' },
@@ -18,8 +23,7 @@ const ALIGNMENTS = {
 	topRight: { align: 'flex-start', justify: 'flex-end' },
 };
 
-/** @type {import('./types').Alignments} */
-const V_ALIGNMENTS = {
+const V_ALIGNMENTS: Alignments = {
 	bottom: { justify: 'flex-end', align: 'center' },
 	bottomLeft: { justify: 'flex-start', align: 'flex-end' },
 	bottomRight: { justify: 'flex-end', align: 'flex-end' },
@@ -33,23 +37,19 @@ const V_ALIGNMENTS = {
 	topRight: { justify: 'flex-start', align: 'flex-end' },
 };
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {import('./types').HStackAlignment | import('react').CSSProperties[ 'alignItems' ]} alignment         Where to align.
- * @param {import('../flex/types').FlexDirection}                                             [direction='row'] Direction to align.
- * @return {import('./types').AlignmentProps} Alignment props.
- */
-/* eslint-enable jsdoc/valid-types */
-export function getAlignmentProps( alignment, direction = 'row' ) {
+export function getAlignmentProps(
+	alignment: HStackAlignment | CSSProperties[ 'alignItems' ],
+	direction: FlexDirection = 'row'
+): AlignmentProps {
 	if ( ! isValueDefined( alignment ) ) {
 		return {};
 	}
 	const isVertical = direction === 'column';
-	const props = isVertical ? V_ALIGNMENTS : ALIGNMENTS;
+	const props = isVertical ? V_ALIGNMENTS : H_ALIGNMENTS;
 
 	const alignmentProps =
 		alignment in props
-			? props[ /** @type {keyof typeof ALIGNMENTS} */ ( alignment ) ]
+			? props[ alignment as keyof typeof props ]
 			: { align: alignment };
 
 	return alignmentProps;

package/src/higher-order/navigate-regions/README.md

@@ -1,6 +1,6 @@
 # navigateRegions
 
-`navigateRegions` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) adding keyboard navigation to switch between the different DOM elements marked as "regions" (role="region"). These regions should be focusable (By adding a tabIndex attribute for example). For better accessibility, these elements must be properly labelled to briefly describe the purpose of the content in the region. For more details, see "ARIA landmarks" in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria/).
+`navigateRegions` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) adding keyboard navigation to switch between the different DOM elements marked as "regions" (role="region"). These regions should be focusable (By adding a tabIndex attribute for example). For better accessibility, these elements must be properly labelled to briefly describe the purpose of the content in the region. For more details, see "Landmark Roles" in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria/) and "Landmark Regions" in the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/).
 
 ## Example:
 
@@ -21,3 +21,6 @@ const MyComponentWithNavigateRegions = navigateRegions( () => (
 	</div>
 ) );
 ```
+
+## Notes:
+It's important to note that an ARIA `role="region"` is an ARIA landmark role. It should be reserved for sections of content sufficiently important to have it listed in a summary of the page. Only use this ARIA role for the main sections of a page. All perceivable content should reside in a semantically meaningful landmark in order that content is not missed by the user.

package/src/icon/index.tsx

@@ -20,7 +20,7 @@ import { SVG } from '@wordpress/primitives';
 import Dashicon from '../dashicon';
 import type { IconKey as DashiconIconKey } from '../dashicon/types';
 
-type IconType< P > = DashiconIconKey | ComponentType< P > | JSX.Element;
+export type IconType< P > = DashiconIconKey | ComponentType< P > | JSX.Element;
 
 interface BaseProps< P > {
 	/**

package/src/menu-item/index.js

@@ -3,7 +3,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { isString } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -41,7 +40,7 @@ export function MenuItem( props, ref ) {
 		);
 	}
 
-	if ( icon && ! isString( icon ) ) {
+	if ( icon && typeof icon !== 'string' ) {
 		icon = cloneElement( icon, {
 			className: classnames( 'components-menu-items__item-icon', {
 				'has-icon-right': iconPosition === 'right',

package/src/mobile/focal-point-settings-panel/index.native.js

@@ -8,7 +8,7 @@ import { useRoute, useNavigation } from '@react-navigation/native';
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { memo, useContext, useState } from '@wordpress/element';
+import { memo, useContext, useState, useCallback } from '@wordpress/element';
 import { BottomSheetContext, FocalPointPicker } from '@wordpress/components';
 
 /**
@@ -56,7 +56,7 @@ const FocalPointSettingsPanelMemo = memo(
 				</NavBar>
 				<FocalPointPicker
 					focalPoint={ draftFocalPoint }
-					onChange={ setPosition }
+					onChange={ useCallback( setPosition, [] ) }
 					shouldEnableBottomSheetScroll={
 						shouldEnableBottomSheetScroll
 					}

package/src/mobile/image/index.native.js

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { Image, Text, View } from 'react-native';
+import FastImage from 'react-native-fast-image';
 
 /**
  * WordPress dependencies
@@ -210,7 +211,7 @@ const ImageComponent = ( {
 					</View>
 				) : (
 					<View style={ focalPoint && styles.focalPointContent }>
-						<Image
+						<FastImage
 							{ ...( ! resizeMode && {
 								aspectRatio: imageData?.aspectRatio,
 							} ) }
@@ -219,7 +220,7 @@ const ImageComponent = ( {
 							{ ...( ! focalPoint && {
 								resizeMethod: 'scale',
 							} ) }
-							resizeMode={ resizeMode }
+							resizeMode={ FastImage.resizeMode[ resizeMode ] }
 						/>
 					</View>
 				) }

package/src/modal/index.js

@@ -10,8 +10,10 @@ import classnames from 'classnames';
  */
 import {
 	createPortal,
+	useCallback,
 	useEffect,
 	useRef,
+	useState,
 	forwardRef,
 } from '@wordpress/element';
 import {
@@ -24,7 +26,7 @@ import {
 } from '@wordpress/compose';
 import { ESCAPE } from '@wordpress/keycodes';
 import { __ } from '@wordpress/i18n';
-import { closeSmall } from '@wordpress/icons';
+import { close } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -73,6 +75,8 @@ function Modal( props, forwardedRef ) {
 	const focusReturnRef = useFocusReturn();
 	const focusOutsideProps = useFocusOutside( onRequestClose );
 
+	const [ hasScrolledContent, setHasScrolledContent ] = useState( false );
+
 	useEffect( () => {
 		openModalCount++;
 
@@ -104,6 +108,19 @@ function Modal( props, forwardedRef ) {
 		}
 	}
 
+	const onContentContainerScroll = useCallback(
+		( e ) => {
+			const scrollY = e?.target?.scrollTop ?? -1;
+
+			if ( ! hasScrolledContent && scrollY > 0 ) {
+				setHasScrolledContent( true );
+			} else if ( hasScrolledContent && scrollY <= 0 ) {
+				setHasScrolledContent( false );
+			}
+		},
+		[ hasScrolledContent ]
+	);
+
 	return createPortal(
 		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
 		<div
@@ -142,8 +159,10 @@ function Modal( props, forwardedRef ) {
 					<div
 						className={ classnames( 'components-modal__content', {
 							'hide-header': __experimentalHideHeader,
+							'has-scrolled-content': hasScrolledContent,
 						} ) }
 						role="document"
+						onScroll={ onContentContainerScroll }
 					>
 						{ ! __experimentalHideHeader && (
 							<div className="components-modal__header">
@@ -168,7 +187,7 @@ function Modal( props, forwardedRef ) {
 								{ isDismissible && (
 									<Button
 										onClick={ onRequestClose }
-										icon={ closeSmall }
+										icon={ close }
 										label={
 											closeButtonLabel ||
 											__( 'Close dialog' )

package/src/modal/stories/index.js

@@ -35,7 +35,23 @@ const ModalExample = ( props ) => {
 				Open Modal
 			</Button>
 			{ isOpen && (
-				<Modal { ...props } onRequestClose={ closeModal }>
+				<Modal
+					{ ...props }
+					onRequestClose={ closeModal }
+					style={ { maxWidth: '600px' } }
+				>
+					<p>
+						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+						sed do eiusmod tempor incididunt ut labore et magna
+						aliqua. Ut enim ad minim veniam, quis nostrud
+						exercitation ullamco laboris nisi ut aliquip ex ea ea
+						commodo consequat. Duis aute irure dolor in
+						reprehenderit in voluptate velit esse cillum dolore eu
+						fugiat nulla pariatur. Excepteur sint occaecat cupidatat
+						non proident, sunt in culpa qui officia deserunt mollit
+						anim id est laborum.
+					</p>
+
 					<Button variant="secondary" onClick={ closeModal }>
 						Close Modal
 					</Button>

package/src/modal/style.scss

@@ -8,6 +8,7 @@
 	background-color: rgba($black, 0.35);
 	z-index: z-index(".components-modal__screen-overlay");
 	display: flex;
+	backdrop-filter: blur($grid-unit);
 
 	// This animates the appearance of the white background.
 	@include edit-post__fade-in-animation();
@@ -63,13 +64,13 @@
 // modal screen).
 .components-modal__header {
 	box-sizing: border-box;
-	border-bottom: $border-width solid $gray-300;
+	border-bottom: $border-width solid transparent;
 	padding: 0 $grid-unit-40;
 	display: flex;
 	flex-direction: row;
 	justify-content: space-between;
 	align-items: center;
-	height: $header-height;
+	height: $header-height + $grid-unit-20;
 	width: 100%;
 	z-index: z-index(".components-modal__header");
 	position: absolute;
@@ -77,7 +78,7 @@
 	left: 0;
 
 	.components-modal__header-heading {
-		font-size: 1rem;
+		font-size: 1.2rem;
 		font-weight: 600;
 	}
 
@@ -90,6 +91,10 @@
 		position: relative;
 		left: $grid-unit-10;
 	}
+
+	.components-modal__content.has-scrolled-content:not(.hide-header) & {
+		border-bottom-color: $gray-300;
+	}
 }
 
 .components-modal__header-heading-container {
@@ -113,26 +118,12 @@
 // Modal contents.
 .components-modal__content {
 	flex: 1;
-	margin-top: $header-height;
+	margin-top: $header-height + $grid-unit-20;
 	padding: 0 $grid-unit-40 $grid-unit-30;
 	overflow: auto;
 
-	// Emulate margin-bottom for the header. Uses a pseudo-element since the
-	// absolutely positioned header’s margins wouldn’t effect siblings and
-	// padding-top on the content element would effect positioning of any
-	// sticky elements within.
-	&::before {
-		content: "";
-		display: block;
-		margin-bottom: $grid-unit-30;
-	}
-
 	&.hide-header {
 		margin-top: 0;
 		padding-top: $grid-unit-30;
-
-		&::before {
-			content: none;
-		}
 	}
 }

package/src/navigation/index.js

@@ -54,6 +54,9 @@ export default function Navigation( {
 		if ( activeMenu !== menu ) {
 			setActiveMenu( activeMenu );
 		}
+		// Ignore exhaustive-deps here, as it would require either a larger refactor or some questionable workarounds.
+		// See https://github.com/WordPress/gutenberg/pull/41612 for context.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ activeMenu ] );
 
 	const context = {

package/src/navigation/item/base.js

@@ -18,7 +18,8 @@ import { ItemBaseUI } from '../styles/navigation-styles';
 let uniqueId = 0;
 
 export default function NavigationItemBase( props ) {
-	const { children, className, ...restProps } = props;
+	// Also avoid to pass the `title` and `href` props to the ItemBaseUI styled component.
+	const { children, className, title, href, ...restProps } = props;
 
 	const [ itemId ] = useState( `item-${ ++uniqueId }` );
 

package/src/popover/README.md

@@ -61,7 +61,7 @@ Set this prop to `false` to disable focus changing entirely. This should only be
 
 ### placement
 
-The direction in which the popover should open relative to its parent node or anchor node. 
+The direction in which the popover should open relative to its parent node or anchor node.
 
 The available base placements are 'top', 'right', 'bottom', 'left'.
 
@@ -137,7 +137,7 @@ A callback function which is used to override the anchor value computation algor
 
 If you need the `DOMRect` object i.e., the position of popover to be calculated on every time, the popover re-renders, then use `getAnchorRect`.
 
-`getAnchorRect` callback function receives a reference to the popover anchor element as a function parameter and it should return a `DOMRect` object.
+`getAnchorRect` callback function receives a reference to the popover anchor element as a function parameter and it should return a `DOMRect` object. Noting that `getAnchorRect` can be called with `null`.
 
 -   Type: `Function`
 -   Required: No