@wordpress/components 19.5.0 → 19.6.1-next.a55ed9455a.0

package/src/tree-grid/test/index.js

@@ -13,6 +13,8 @@ import { forwardRef } from '@wordpress/element';
  * Internal dependencies
  */
 import TreeGrid from '../';
+import TreeGridRow from '../row';
+import TreeGridCell from '../cell';
 
 const TestButton = forwardRef( ( { ...props }, ref ) => (
 	<button { ...props } ref={ ref }></button>
@@ -46,9 +48,9 @@ describe( 'TreeGrid', () => {
 		it( 'renders a table, tbody and any child elements', () => {
 			const { container } = render(
 				<TreeGrid>
-					<tr>
-						<td>Test</td>
-					</tr>
+					<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 1 }>
+						<TreeGridCell withoutGridItem>Test</TreeGridCell>
+					</TreeGridRow>
 				</TreeGrid>
 			);
 
@@ -62,21 +64,36 @@ describe( 'TreeGrid', () => {
 
 			render(
 				<TreeGrid onExpandRow={ onExpandRow }>
-					<tr role="row" aria-expanded="true">
-						<td>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 1 }
+						setSize={ 3 }
+						isExpanded={ true }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 1</TestButton>
-						</td>
-					</tr>
-					<tr role="row" aria-expanded="false">
-						<td>
+						</TreeGridCell>
+					</TreeGridRow>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 2 }
+						setSize={ 3 }
+						isExpanded={ false }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 2</TestButton>
-						</td>
-					</tr>
-					<tr role="row" aria-expanded="true">
-						<td>
+						</TreeGridCell>
+					</TreeGridRow>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 3 }
+						setSize={ 3 }
+						isExpanded={ true }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 3</TestButton>
-						</td>
-					</tr>
+						</TreeGridCell>
+					</TreeGridRow>
 				</TreeGrid>
 			);
 
@@ -99,21 +116,36 @@ describe( 'TreeGrid', () => {
 
 			render(
 				<TreeGrid onCollapseRow={ onCollapseRow }>
-					<tr role="row" aria-expanded="false">
-						<td>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 1 }
+						setSize={ 3 }
+						isExpanded={ false }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 1</TestButton>
-						</td>
-					</tr>
-					<tr role="row" aria-expanded="true">
-						<td>
+						</TreeGridCell>
+					</TreeGridRow>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 2 }
+						setSize={ 3 }
+						isExpanded={ true }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 2</TestButton>
-						</td>
-					</tr>
-					<tr role="row" aria-expanded="false">
-						<td>
+						</TreeGridCell>
+					</TreeGridRow>
+					<TreeGridRow
+						level={ 1 }
+						positionInSet={ 3 }
+						setSize={ 3 }
+						isExpanded={ false }
+					>
+						<TreeGridCell withoutGridItem>
 							<TestButton>Row 3</TestButton>
-						</td>
-					</tr>
+						</TreeGridCell>
+					</TreeGridRow>
 				</TreeGrid>
 			);
 
@@ -133,21 +165,21 @@ describe( 'TreeGrid', () => {
 	describe( 'onFocusRow', () => {
 		const TestTree = ( { onFocusRow } ) => (
 			<TreeGrid onFocusRow={ onFocusRow }>
-				<tr role="row" aria-expanded="false">
-					<td>
+				<TreeGridRow level={ 1 } positionInSet={ 1 } setSize={ 3 }>
+					<TreeGridCell withoutGridItem>
 						<TestButton>Row 1</TestButton>
-					</td>
-				</tr>
-				<tr role="row" aria-expanded="true">
-					<td>
+					</TreeGridCell>
+				</TreeGridRow>
+				<TreeGridRow level={ 1 } positionInSet={ 2 } setSize={ 3 }>
+					<TreeGridCell withoutGridItem>
 						<TestButton>Row 2</TestButton>
-					</td>
-				</tr>
-				<tr role="row" aria-expanded="false">
-					<td>
+					</TreeGridCell>
+				</TreeGridRow>
+				<TreeGridRow level={ 1 } positionInSet={ 3 } setSize={ 3 }>
+					<TreeGridCell withoutGridItem>
 						<TestButton>Row 3</TestButton>
-					</td>
-				</tr>
+					</TreeGridCell>
+				</TreeGridRow>
 			</TreeGrid>
 		);
 

package/src/truncate/utils.js

@@ -34,7 +34,7 @@ export function truncateMiddle( word, headLength, tailLength, ellipsis ) {
 	const wordLength = word.length;
 	// Setting default values
 	// eslint-disable-next-line no-bitwise
-	const frontLength = ~~headLength; // will cast to integer
+	const frontLength = ~~headLength; // Will cast to integer
 	// eslint-disable-next-line no-bitwise
 	const backLength = ~~tailLength;
 	/* istanbul ignore next */

package/src/ui/context/{context-connect.js → context-connect.ts}

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { uniq } from 'lodash';
+import type { ForwardedRef, ReactChild, ReactNode } from 'react';
 
 /**
  * WordPress dependencies
@@ -14,8 +15,13 @@ import warn from '@wordpress/warning';
  */
 import { CONNECT_STATIC_NAMESPACE } from './constants';
 import { getStyledClassNameFromKey } from './get-styled-class-name-from-key';
+import type { WordPressComponentFromProps } from '.';
+
+type ContextConnectOptions = {
+	/** Defaults to `false`. */
+	memo?: boolean;
+};
 
-/* eslint-disable jsdoc/valid-types */
 /**
  * Forwards ref (React.ForwardRef) and "Connects" (or registers) a component
  * within the Context system under a specified namespace.
@@ -24,15 +30,16 @@ import { getStyledClassNameFromKey } from './get-styled-class-name-from-key';
  * The hope is that we can improve render performance by removing functional
  * component wrappers.
  *
- * @template {import('./wordpress-component').WordPressComponentProps<{}, any, any>} P
- * @param {(props: P, ref: import('react').Ref<any>) => JSX.Element | null} Component            The component to register into the Context system.
- * @param {string}                                                          namespace            The namespace to register the component under.
- * @param {Object}                                                          options
- * @param {boolean}                                                         [options.memo=false]
- * @return {import('./wordpress-component').WordPressComponentFromProps<P>} The connected WordPressComponent
+ * @param  Component The component to register into the Context system.
+ * @param  namespace The namespace to register the component under.
+ * @param  options
+ * @return The connected WordPressComponent
  */
-export function contextConnect( Component, namespace, options = {} ) {
-	/* eslint-enable jsdoc/valid-types */
+export function contextConnect< P >(
+	Component: ( props: P, ref: ForwardedRef< any > ) => JSX.Element | null,
+	namespace: string,
+	options: ContextConnectOptions = {}
+): WordPressComponentFromProps< P > {
 	const { memo: memoProp = false } = options;
 
 	let WrappedComponent = forwardRef( Component );
@@ -75,10 +82,12 @@ export function contextConnect( Component, namespace, options = {} ) {
 /**
  * Attempts to retrieve the connected namespace from a component.
  *
- * @param {import('react').ReactChild | undefined | {}} Component The component to retrieve a namespace from.
- * @return {Array<string>} The connected namespaces.
+ * @param  Component The component to retrieve a namespace from.
+ * @return The connected namespaces.
  */
-export function getConnectNamespace( Component ) {
+export function getConnectNamespace(
+	Component: ReactChild | undefined | {}
+): string[] {
 	if ( ! Component ) return [];
 
 	let namespaces = [];
@@ -101,11 +110,13 @@ export function getConnectNamespace( Component ) {
 /**
  * Checks to see if a component is connected within the Context system.
  *
- * @param {import('react').ReactNode} Component The component to retrieve a namespace from.
- * @param {Array<string>|string}      match     The namespace to check.
- * @return {boolean} The result.
+ * @param  Component The component to retrieve a namespace from.
+ * @param  match     The namespace to check.
  */
-export function hasConnectNamespace( Component, match ) {
+export function hasConnectNamespace(
+	Component: ReactNode,
+	match: string[] | string
+): boolean {
 	if ( ! Component ) return false;
 
 	if ( typeof match === 'string' ) {

package/src/ui/context/context-system-provider.js

@@ -54,9 +54,9 @@ function useContextSystemBridge( { value } ) {
 
 	useUpdateEffect( () => {
 		if (
-			// objects are equivalent
+			// Objects are equivalent.
 			isEqual( valueRef.current, value ) &&
-			// but not the same reference
+			// But not the same reference.
 			valueRef.current !== value
 		) {
 			warn( `Please memoize your context: ${ JSON.stringify( value ) }` );

package/src/ui/context/wordpress-component.ts

@@ -18,6 +18,7 @@ export type WordPressComponentProps<
 	Omit< React.ComponentPropsWithRef< T >, 'as' | keyof P | 'children' > &
 	( IsPolymorphic extends true
 		? {
+				/** The HTML element or React component to render the component as. */
 				as?: T | keyof JSX.IntrinsicElements;
 		  }
 		: {} );

package/src/ui/tooltip/test/index.js

@@ -41,11 +41,11 @@ describe( 'props', () => {
 		const invisibleTooltipTrigger = screen.getByText(
 			invisibleTooltipTriggerContent
 		);
-		// The invisible tooltip should not render
+		// The invisible tooltip should not render.
 		expect( tooltips ).toHaveLength( 1 );
-		// Assert that the rendered tooltip is indeed the base tooltip
+		// Assert that the rendered tooltip is indeed the base tooltip.
 		expect( tooltips[ 0 ].id ).toBe( baseTooltipId );
-		// But the invisible tooltip's trigger still should have rendered
+		// But the invisible tooltip's trigger still should have rendered.
 		expect( invisibleTooltipTrigger ).not.toBeUndefined();
 	} );
 
@@ -71,7 +71,7 @@ describe( 'props', () => {
 			</Tooltip>
 		);
 		const tooltips = screen.getAllByRole( /tooltip/ );
-		// assert only the base tooltip rendered
+		// Assert only the base tooltip rendered.
 		expect( tooltips ).toHaveLength( 1 );
 		expect( tooltips[ 0 ].id ).toBe( baseTooltipId );
 	} );

package/src/ui/utils/colors.js

@@ -61,9 +61,9 @@ function _getComputedBackgroundColor( backgroundColor ) {
 	if ( ! el ) return '';
 
 	el.style.background = backgroundColor;
-	// Grab the style
+	// Grab the style.
 	const computedColor = window?.getComputedStyle( el ).background;
-	// Reset
+	// Reset.
 	el.style.background = '';
 
 	return computedColor || '';

package/src/ui/utils/space.ts

@@ -21,14 +21,14 @@ export function space( value?: SpaceInput ): string | undefined {
 		return undefined;
 	}
 
-	// handle empty strings, if it's the number 0 this still works
+	// Handle empty strings, if it's the number 0 this still works.
 	if ( ! value ) {
 		return '0';
 	}
 
 	const asInt = typeof value === 'number' ? value : Number( value );
 
-	// test if the input has a unit, was NaN, or was one of the named CSS values (like `auto`), in which case just use that value
+	// Test if the input has a unit, was NaN, or was one of the named CSS values (like `auto`), in which case just use that value.
 	if (
 		( typeof window !== 'undefined' &&
 			window.CSS?.supports?.( 'margin', value.toString() ) ) ||

package/src/unit-control/README.md

@@ -96,7 +96,7 @@ Example:
 
 -   Required: No
 
-### `units`: `WPUnitControlUnitList`
+### `units`: `WPUnitControlUnit[]`
 
 Collection of available units.
 

package/src/unit-control/index.native.js

@@ -16,7 +16,7 @@ import RangeCell from '../mobile/bottom-sheet/range-cell';
 import StepperCell from '../mobile/bottom-sheet/stepper-cell';
 import Picker from '../mobile/picker';
 import styles from './style.scss';
-import { CSS_UNITS, hasUnits, parseA11yLabelForUnit } from './utils';
+import { CSS_UNITS, hasUnits, getAccessibleLabelForUnit } from './utils';
 
 /**
  * WordPress dependencies
@@ -116,6 +116,8 @@ function UnitControl( {
 	};
 
 	const renderUnitPicker = useCallback( () => {
+		// Keeping for legacy reasons, although `false` should not be a valid
+		// value for the `units` prop anymore.
 		if ( units === false ) {
 			return null;
 		}
@@ -164,7 +166,7 @@ function UnitControl( {
 					shouldDisplayTextInput
 					decimalNum={ decimalNum }
 					openUnitPicker={ onPickerPresent }
-					unitLabel={ parseA11yLabelForUnit( unit ) }
+					unitLabel={ getAccessibleLabelForUnit( unit ) }
 					{ ...props }
 				>
 					{ renderUnitPicker() }
@@ -182,7 +184,7 @@ function UnitControl( {
 					separatorType={ separatorType }
 					decimalNum={ decimalNum }
 					openUnitPicker={ onPickerPresent }
-					unitLabel={ parseA11yLabelForUnit( unit ) }
+					unitLabel={ getAccessibleLabelForUnit( unit ) }
 					{ ...props }
 				>
 					{ renderUnitPicker() }

package/src/unit-control/index.tsx

@@ -6,6 +6,7 @@ import type {
 	KeyboardEvent,
 	ForwardedRef,
 	SyntheticEvent,
+	ChangeEvent,
 } from 'react';
 import { noop, omit } from 'lodash';
 import classnames from 'classnames';
@@ -13,7 +14,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { forwardRef, useMemo, useRef } from '@wordpress/element';
+import { forwardRef, useMemo, useRef, useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { ENTER } from '@wordpress/keycodes';
 
@@ -27,9 +28,9 @@ import { Root, ValueInput } from './styles/unit-control-styles';
 import UnitSelectControl from './unit-select-control';
 import {
 	CSS_UNITS,
-	getParsedValue,
+	getParsedQuantityAndUnit,
 	getUnitsWithCurrentUnit,
-	getValidParsedUnit,
+	getValidParsedQuantityAndUnit,
 } from './utils';
 import { useControlledState } from '../utils/hooks';
 import type { UnitControlProps, UnitControlOnChangeCallback } from './types';
@@ -57,29 +58,46 @@ function UnitControl(
 	}: WordPressComponentProps< UnitControlProps, 'input', false >,
 	forwardedRef: ForwardedRef< any >
 ) {
+	// The `value` prop, in theory, should not be `null`, but the following line
+	// ensures it fallback to `undefined` in case a consumer of `UnitControl`
+	// still passes `null` as a `value`.
+	const nonNullValueProp = valueProp ?? undefined;
 	const units = useMemo(
-		() => getUnitsWithCurrentUnit( valueProp, unitProp, unitsProp ),
-		[ valueProp, unitProp, unitsProp ]
+		() => getUnitsWithCurrentUnit( nonNullValueProp, unitProp, unitsProp ),
+		[ nonNullValueProp, unitProp, unitsProp ]
 	);
-	const [ value, initialUnit ] = getParsedValue( valueProp, unitProp, units );
+	const [ parsedQuantity, parsedUnit ] = getParsedQuantityAndUnit(
+		nonNullValueProp,
+		unitProp,
+		units
+	);
+
 	const [ unit, setUnit ] = useControlledState< string | undefined >(
 		unitProp,
 		{
-			initial: initialUnit,
+			initial: parsedUnit,
 			fallback: '',
 		}
 	);
 
-	// Stores parsed value for hand-off in state reducer
-	const refParsedValue = useRef< string | null >( null );
+	useEffect( () => {
+		setUnit( parsedUnit );
+	}, [ parsedUnit ] );
+
+	// Stores parsed value for hand-off in state reducer.
+	const refParsedQuantity = useRef< number | undefined >( undefined );
 
 	const classes = classnames( 'components-unit-control', className );
 
-	const handleOnChange: UnitControlOnChangeCallback = (
-		next,
-		changeProps
+	const handleOnQuantityChange = (
+		nextQuantityValue: number | string | undefined,
+		changeProps: { event: ChangeEvent< HTMLInputElement > }
 	) => {
-		if ( next === '' ) {
+		if (
+			nextQuantityValue === '' ||
+			typeof nextQuantityValue === 'undefined' ||
+			nextQuantityValue === null
+		) {
 			onChange( '', changeProps );
 			return;
 		}
@@ -88,53 +106,64 @@ function UnitControl(
 		 * Customizing the onChange callback.
 		 * This allows as to broadcast a combined value+unit to onChange.
 		 */
-		next = getValidParsedUnit( next, units, value, unit ).join( '' );
+		const onChangeValue = getValidParsedQuantityAndUnit(
+			nextQuantityValue,
+			units,
+			parsedQuantity,
+			unit
+		).join( '' );
 
-		onChange( next, changeProps );
+		onChange( onChangeValue, changeProps );
 	};
 
 	const handleOnUnitChange: UnitControlOnChangeCallback = (
-		next,
+		nextUnitValue,
 		changeProps
 	) => {
 		const { data } = changeProps;
 
-		let nextValue = `${ value }${ next }`;
+		let nextValue = `${ parsedQuantity ?? '' }${ nextUnitValue }`;
 
 		if ( isResetValueOnUnitChange && data?.default !== undefined ) {
-			nextValue = `${ data.default }${ next }`;
+			nextValue = `${ data.default }${ nextUnitValue }`;
 		}
 
 		onChange( nextValue, changeProps );
-		onUnitChange( next, changeProps );
+		onUnitChange( nextUnitValue, changeProps );
 
-		setUnit( next );
+		setUnit( nextUnitValue );
 	};
 
 	const mayUpdateUnit = ( event: SyntheticEvent< HTMLInputElement > ) => {
 		if ( ! isNaN( Number( event.currentTarget.value ) ) ) {
-			refParsedValue.current = null;
+			refParsedQuantity.current = undefined;
 			return;
 		}
-		const [ parsedValue, parsedUnit ] = getValidParsedUnit(
+		const [
+			validParsedQuantity,
+			validParsedUnit,
+		] = getValidParsedQuantityAndUnit(
 			event.currentTarget.value,
 			units,
-			value,
+			parsedQuantity,
 			unit
 		);
 
-		refParsedValue.current = parsedValue.toString();
+		refParsedQuantity.current = validParsedQuantity;
 
-		if ( isPressEnterToChange && parsedUnit !== unit ) {
+		if ( isPressEnterToChange && validParsedUnit !== unit ) {
 			const data = Array.isArray( units )
-				? units.find( ( option ) => option.value === parsedUnit )
+				? units.find( ( option ) => option.value === validParsedUnit )
 				: undefined;
 			const changeProps = { event, data };
 
-			onChange( `${ parsedValue }${ parsedUnit }`, changeProps );
-			onUnitChange( parsedUnit, changeProps );
+			onChange(
+				`${ validParsedQuantity ?? '' }${ validParsedUnit }`,
+				changeProps
+			);
+			onUnitChange( validParsedUnit, changeProps );
 
-			setUnit( parsedUnit );
+			setUnit( validParsedUnit );
 		}
 	};
 
@@ -163,9 +192,9 @@ function UnitControl(
 		 * then use that result to update the state.
 		 */
 		if ( action.type === inputControlActionTypes.COMMIT ) {
-			if ( refParsedValue.current !== null ) {
-				state.value = refParsedValue.current;
-				refParsedValue.current = null;
+			if ( refParsedQuantity.current !== undefined ) {
+				state.value = ( refParsedQuantity.current ?? '' ).toString();
+				refParsedQuantity.current = undefined;
 			}
 		}
 
@@ -209,11 +238,11 @@ function UnitControl(
 				label={ label }
 				onBlur={ handleOnBlur }
 				onKeyDown={ handleOnKeyDown }
-				onChange={ handleOnChange }
+				onChange={ handleOnQuantityChange }
 				ref={ forwardedRef }
 				size={ size }
 				suffix={ inputSuffix }
-				value={ value }
+				value={ parsedQuantity ?? '' }
 				step={ step }
 				__unstableStateReducer={ composeStateReducers(
 					unitControlStateReducer,
@@ -242,5 +271,5 @@ function UnitControl(
  */
 const ForwardedUnitControl = forwardRef( UnitControl );
 
-export { parseUnit, useCustomUnits } from './utils';
+export { parseQuantityAndUnitFromRawValue, useCustomUnits } from './utils';
 export default ForwardedUnitControl;