@wordpress/components 20.0.2-next.957ca95e4c.0 → 21.0.0

package/src/ui/context/context-connect.ts

@@ -6,7 +6,7 @@ import type { ForwardedRef, ReactChild, ReactNode } from 'react';
 /**
  * WordPress dependencies
  */
-import { forwardRef, memo } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 import warn from '@wordpress/warning';
 
 /**
@@ -16,42 +16,74 @@ import { CONNECT_STATIC_NAMESPACE } from './constants';
 import { getStyledClassNameFromKey } from './get-styled-class-name-from-key';
 import type { WordPressComponentFromProps } from '.';
 
+type AcceptsTwoArgs<
+	F extends ( ...args: any ) => any,
+	ErrorMessage = never
+> = Parameters< F >[ 'length' ] extends 2 ? {} : ErrorMessage;
+
 type ContextConnectOptions = {
-	/** Defaults to `false`. */
-	memo?: boolean;
+	forwardsRef?: boolean;
 };
 
 /**
  * Forwards ref (React.ForwardRef) and "Connects" (or registers) a component
  * within the Context system under a specified namespace.
  *
- * This is an (experimental) evolution of the initial connect() HOC.
- * The hope is that we can improve render performance by removing functional
- * component wrappers.
+ * @param  Component The component to register into the Context system.
+ * @param  namespace The namespace to register the component under.
+ * @return The connected WordPressComponent
+ */
+export function contextConnect<
+	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null
+>(
+	Component: C &
+		AcceptsTwoArgs<
+			C,
+			'Warning: Your component function does not take a ref as the second argument. Did you mean to use `contextConnectWithoutRef`?'
+		>,
+	namespace: string
+) {
+	return _contextConnect( Component, namespace, { forwardsRef: true } );
+}
+
+/**
+ * "Connects" (or registers) a component within the Context system under a specified namespace.
+ * Does not forward a ref.
  *
  * @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< P >(
-	Component: ( props: P, ref: ForwardedRef< any > ) => JSX.Element | null,
-	namespace: string,
-	options: ContextConnectOptions = {}
-): WordPressComponentFromProps< P > {
-	const { memo: memoProp = false } = options;
+export function contextConnectWithoutRef< P >(
+	Component: ( props: P ) => JSX.Element | null,
+	namespace: string
+) {
+	return _contextConnect( Component, namespace );
+}
 
-	let WrappedComponent = forwardRef( Component );
-	if ( memoProp ) {
-		// @ts-ignore
-		WrappedComponent = memo( WrappedComponent );
-	}
+// This is an (experimental) evolution of the initial connect() HOC.
+// The hope is that we can improve render performance by removing functional
+// component wrappers.
+function _contextConnect<
+	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
+	O extends ContextConnectOptions
+>(
+	Component: C,
+	namespace: string,
+	options?: O
+): WordPressComponentFromProps<
+	Parameters< C >[ 0 ],
+	O[ 'forwardsRef' ] extends true ? true : false
+> {
+	const WrappedComponent = options?.forwardsRef
+		? forwardRef< any, Parameters< C >[ 0 ] >( Component )
+		: Component;
 
 	if ( typeof namespace === 'undefined' ) {
 		warn( 'contextConnect: Please provide a namespace' );
 	}
 
-	// @ts-ignore internal property
+	// @ts-expect-error internal property
 	let mergedNamespace = WrappedComponent[ CONNECT_STATIC_NAMESPACE ] || [
 		namespace,
 	];
@@ -66,18 +98,13 @@ export function contextConnect< P >(
 		mergedNamespace = [ ...mergedNamespace, namespace ];
 	}
 
-	WrappedComponent.displayName = namespace;
-
-	// @ts-ignore internal property
-	WrappedComponent[ CONNECT_STATIC_NAMESPACE ] = [
-		...new Set( mergedNamespace ),
-	];
-
-	// @ts-ignore WordPressComponent property
-	WrappedComponent.selector = `.${ getStyledClassNameFromKey( namespace ) }`;
-
-	// @ts-ignore
-	return WrappedComponent;
+	// @ts-expect-error We can't rely on inferred types here because of the
+	// `as` prop polymorphism we're handling in https://github.com/WordPress/gutenberg/blob/9620bae6fef4fde7cc2b7833f416e240207cda29/packages/components/src/ui/context/wordpress-component.ts#L32-L33
+	return Object.assign( WrappedComponent, {
+		[ CONNECT_STATIC_NAMESPACE ]: [ ...new Set( mergedNamespace ) ],
+		displayName: namespace,
+		selector: `.${ getStyledClassNameFromKey( namespace ) }`,
+	} );
 }
 
 /**

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { isEqual, merge, cloneDeep } from 'lodash';
+import { isEqual, merge } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -66,7 +66,7 @@ function useContextSystemBridge( { value } ) {
 	// `parentContext` will always be memoized (i.e., the result of this hook itself)
 	// or the default value from when the `ComponentsContext` was originally
 	// initialized (which will never change, it's a static variable)
-	// so this memoization will prevent `merge` and `cloneDeep` from rerunning unless
+	// so this memoization will prevent `merge` and `JSON.parse/stringify` from rerunning unless
 	// the references to `value` change OR the `parentContext` has an actual material change
 	// (because again, it's guaranteed to be memoized or a static reference to the empty object
 	// so we know that the only changes for `parentContext` are material ones... i.e., why we
@@ -74,9 +74,10 @@ function useContextSystemBridge( { value } ) {
 	// need to bother with the `value`). The `useUpdateEffect` above will ensure that we are
 	// correctly warning when the `value` isn't being properly memoized. All of that to say
 	// that this should be super safe to assume that `useMemo` will only run on actual
-	// changes to the two dependencies, therefore saving us calls to `merge` and `cloneDeep`!
+	// changes to the two dependencies, therefore saving us calls to `merge` and `JSON.parse/stringify`!
 	const config = useMemo( () => {
-		return merge( cloneDeep( parentContext ), value );
+		// Deep clone `parentContext` to avoid mutating it later.
+		return merge( JSON.parse( JSON.stringify( parentContext ) ), value );
 	}, [ parentContext, value ] );
 
 	return config;

package/src/ui/context/test/context-connect.tsx

@@ -0,0 +1,55 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, contextConnectWithoutRef } from '../context-connect';
+import type { WordPressComponentProps } from '../wordpress-component';
+
+// Static TypeScript tests
+describe( 'ref forwarding', () => {
+	const ComponentWithRef = (
+		props: WordPressComponentProps< {}, 'div' >,
+		ref: ForwardedRef< any >
+	) => <div { ...props } ref={ ref } />;
+	const ComponentWithoutRef = (
+		props: WordPressComponentProps< {}, 'div' >
+	) => <div { ...props } />;
+
+	it( 'should not trigger a TS error if components are passed to the correct connect* functions', () => {
+		contextConnect( ComponentWithRef, 'Foo' );
+		contextConnectWithoutRef( ComponentWithoutRef, 'Foo' );
+	} );
+
+	it( 'should trigger a TS error if components are passed to the wrong connect* functions', () => {
+		// Wrapped in a thunk because React.forwardRef() will throw a console warning if this is executed
+		// eslint-disable-next-line no-unused-expressions
+		() => {
+			// @ts-expect-error This should error
+			contextConnect( ComponentWithoutRef, 'Foo' );
+		};
+
+		// @ts-expect-error This should error
+		contextConnectWithoutRef( ComponentWithRef, 'Foo' );
+	} );
+
+	it( 'should result in a component with the correct prop types', () => {
+		const AcceptsRef = contextConnect( ComponentWithRef, 'Foo' );
+
+		<AcceptsRef ref={ null } />;
+
+		// @ts-expect-error An unaccepted prop should trigger an error
+		<AcceptsRef foo={ null } />;
+
+		const NoRef = contextConnectWithoutRef( ComponentWithoutRef, 'Foo' );
+
+		// @ts-expect-error The ref prop should trigger an error
+		<NoRef ref={ null } />;
+
+		// @ts-expect-error An unaccepted prop should trigger an error
+		<NoRef foo={ null } />;
+	} );
+} );

package/src/ui/context/test/wordpress-component.tsx

@@ -0,0 +1,36 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../wordpress-component';
+
+// Static TypeScript checks
+describe( 'WordPressComponentProps', () => {
+	it( 'should not accept a ref', () => {
+		const Foo = ( props: WordPressComponentProps< {}, 'div' > ) => (
+			<div { ...props } />
+		);
+
+		// @ts-expect-error The ref prop should trigger an error.
+		<Foo ref={ null } />;
+	} );
+
+	it( 'should accept a ref if wrapped by a forwardRef()', () => {
+		const Foo = (
+			props: WordPressComponentProps< {}, 'div' >,
+			ref: ForwardedRef< any >
+		) => <div { ...props } ref={ ref } />;
+		const ForwardedFoo = forwardRef( Foo );
+
+		<ForwardedFoo ref={ null } />;
+	} );
+} );

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

@@ -3,19 +3,19 @@
  */
 import type * as React from 'react';
 
-/**
- * Based on https://github.com/reakit/reakit/blob/master/packages/reakit-utils/src/types.ts
- *
- * The `children` prop is being explicitely omitted since it is otherwise implicitly added
- * by `ComponentPropsWithRef`. The context is that components should require the `children`
- * prop explicitely when needed (see https://github.com/WordPress/gutenberg/pull/31817).
- */
+// Based on https://github.com/reakit/reakit/blob/master/packages/reakit-utils/src/types.ts
 export type WordPressComponentProps<
+	/** Prop types. */
 	P,
+	/** The HTML element to inherit props from. */
 	T extends React.ElementType,
+	/** Supports polymorphism through the `as` prop. */
 	IsPolymorphic extends boolean = true
 > = P &
-	Omit< React.ComponentPropsWithRef< T >, 'as' | keyof P | 'children' > &
+	// The `children` prop is being explicitly omitted since it is otherwise implicitly added
+	// by `ComponentPropsWithRef`. The context is that components should require the `children`
+	// prop explicitely when needed (see https://github.com/WordPress/gutenberg/pull/31817).
+	Omit< React.ComponentPropsWithoutRef< T >, 'as' | keyof P | 'children' > &
 	( IsPolymorphic extends true
 		? {
 				/** The HTML element or React component to render the component as. */
@@ -47,7 +47,13 @@ export type WordPressComponent<
 	selector: `.${ string }`;
 };
 
-export type WordPressComponentFromProps< Props > =
-	Props extends WordPressComponentProps< infer P, infer T, infer I >
-		? WordPressComponent< T, P, I >
-		: never;
+export type WordPressComponentFromProps<
+	Props,
+	ForwardsRef extends boolean = true
+> = Props extends WordPressComponentProps< infer P, infer T, infer I >
+	? WordPressComponent<
+			T,
+			P & ( ForwardsRef extends true ? React.RefAttributes< any > : {} ),
+			I
+	  >
+	: never;

package/src/ui/control-group/test/__snapshots__/index.js.snap

@@ -13,16 +13,13 @@ exports[`props should render correctly 1`] = `
   -webkit-flex-direction: row;
   -ms-flex-direction: row;
   flex-direction: row;
+  gap: -1px;
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
   width: 100%;
 }
 
-.emotion-0>*+*:not( marquee ) {
-  margin-left: -1px;
-}
-
 .emotion-0>* {
   min-width: 0;
 }

package/src/unit-control/index.tsx

@@ -46,6 +46,7 @@ function UnforwardedUnitControl(
 	const {
 		__unstableStateReducer: stateReducerProp,
 		autoComplete = 'off',
+		// @ts-expect-error Ensure that children is omitted from restProps
 		children,
 		className,
 		disabled = false,
@@ -259,7 +260,6 @@ function UnforwardedUnitControl(
 	return (
 		<Root className="components-unit-control-wrapper" style={ style }>
 			<ValueInput
-				aria-label={ label }
 				type={ isPressEnterToChange ? 'text' : 'number' }
 				{ ...props }
 				autoComplete={ autoComplete }

package/src/unit-control/stories/index.tsx

@@ -18,24 +18,15 @@ const meta: ComponentMeta< typeof UnitControl > = {
 	component: UnitControl,
 	title: 'Components (Experimental)/UnitControl',
 	argTypes: {
-		__unstableInputWidth: {
-			control: { type: 'text' },
-		},
-		__unstableStateReducer: {
-			control: { type: null },
-		},
-		onChange: {
-			action: 'onChange',
-			control: { type: null },
-		},
-		onUnitChange: {
-			control: { type: null },
-		},
-		value: {
-			control: { type: null },
-		},
+		__unstableInputWidth: { control: { type: 'text' } },
+		__unstableStateReducer: { control: { type: null } },
+		onChange: { control: { type: null } },
+		onUnitChange: { control: { type: null } },
+		prefix: { control: { type: 'text' } },
+		value: { control: { type: null } },
 	},
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: {
 			expanded: true,
 		},

package/src/unit-control/styles/unit-control-styles.ts

@@ -66,7 +66,7 @@ const baseUnitLabelStyles = ( { selectSize }: SelectProps ) => {
 			box-sizing: border-box;
 			padding: 2px 1px;
 			width: 20px;
-			color: ${ COLORS.darkGray[ 500 ] };
+			color: ${ COLORS.gray[ 800 ] };
 			font-size: 8px;
 			line-height: 1;
 			letter-spacing: -0.5px;
@@ -113,7 +113,7 @@ const unitSelectSizes = ( { selectSize = 'default' }: SelectProps ) => {
 			${ rtl( { borderTopLeftRadius: 0, borderBottomLeftRadius: 0 } )() }
 
 			&:not(:disabled):hover {
-				background-color: ${ COLORS.lightGray[ 300 ] };
+				background-color: ${ COLORS.gray[ 100 ] };
 			}
 
 			&:focus {

package/src/unit-control/test/__snapshots__/index.tsx.snap

@@ -5,20 +5,18 @@ Snapshot Diff:
 - First value
 + Second value
 
-@@ -1,10 +1,10 @@
+@@ -1,20 +1,20 @@
   <div
     class="components-unit-control-wrapper css-zi0c81-Root e1bagdl33"
   >
     <div
--     class="components-flex components-input-control components-number-control components-unit-control e1bagdl32 ep48uk90 em5sgkm7 css-1njfmeu-View-Flex-sx-Base-sx-Items-ItemsColumn-Root-rootLabelPositionStyles-Input-ValueInput-arrowStyles em57xhy0"
-+     class="components-flex components-input-control components-number-control components-unit-control hello e1bagdl32 ep48uk90 em5sgkm7 css-1njfmeu-View-Flex-sx-Base-sx-Items-ItemsColumn-Root-rootLabelPositionStyles-Input-ValueInput-arrowStyles em57xhy0"
+-     class="components-flex components-input-control components-number-control components-unit-control e1bagdl32 ep48uk90 em5sgkm7 css-x6mixa-View-Flex-base-ItemsColumn-Root-Input-ValueInput-arrowStyles e19lxcc00"
++     class="components-flex components-input-control components-number-control components-unit-control hello e1bagdl32 ep48uk90 em5sgkm7 css-x6mixa-View-Flex-base-ItemsColumn-Root-Input-ValueInput-arrowStyles e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="Flex"
     >
       <div
-        class="components-flex-item em5sgkm3 css-1fmchc6-View-Item-sx-Base-LabelWrapper em57xhy0"
-@@ -15,11 +15,11 @@
-        class="components-input-control__container css-1sy20aj-Container-containerDisabledStyles-containerMarginStyles-containerWidthStyles em5sgkm6"
+        class="components-input-control__container css-1o1a8cj-Container-containerDisabledStyles-containerWidthStyles em5sgkm6"
       >
         <input
           autocomplete="off"

package/src/unit-control/types.ts

@@ -1,22 +1,17 @@
 /**
  * External dependencies
  */
-import type {
-	CSSProperties,
-	FocusEventHandler,
-	ReactNode,
-	SyntheticEvent,
-} from 'react';
+import type { FocusEventHandler, SyntheticEvent } from 'react';
 
 /**
  * Internal dependencies
  */
-import type { StateReducer } from '../input-control/reducer/state';
 import type {
 	InputChangeCallback,
 	InputControlProps,
 	Size as InputSize,
 } from '../input-control/types';
+import type { NumberControlProps } from '../number-control/types';
 
 export type SelectSize = InputSize;
 
@@ -71,31 +66,14 @@ export type UnitSelectControlProps = Pick< InputControlProps, 'size' > & {
 	units?: WPUnitControlUnit[];
 };
 
-// TODO: when available, should (partially) extend `NumberControl` props.
 export type UnitControlProps = Omit< UnitSelectControlProps, 'unit' > &
-	Pick<
-		InputControlProps,
-		'hideLabelFromVision' | 'prefix' | '__next36pxDefaultSize'
-	> & {
-		__unstableStateReducer?: StateReducer;
-		__unstableInputWidth?: CSSProperties[ 'width' ];
-		/**
-		 * The children elements.
-		 */
-		children?: ReactNode;
+	Omit< NumberControlProps, 'hideHTMLArrows' | 'suffix' | 'type' > & {
 		/**
 		 * If `true`, the unit `<select>` is hidden.
 		 *
 		 * @default false
 		 */
 		disableUnits?: boolean;
-		/**
-		 * If `true`, the `ENTER` key press is required in order to trigger an `onChange`.
-		 * If enabled, a change is also triggered when tabbing away (`onBlur`).
-		 *
-		 * @default false
-		 */
-		isPressEnterToChange?: boolean;
 		/**
 		 * If `true`, and the selected unit provides a `default` value, this value is set
 		 * when changing units.
@@ -103,10 +81,6 @@ export type UnitControlProps = Omit< UnitSelectControlProps, 'unit' > &
 		 * @default false
 		 */
 		isResetValueOnUnitChange?: boolean;
-		/**
-		 * If this property is added, a label will be generated using label property as the content.
-		 */
-		label?: string;
 		/**
 		 * Callback when the `unit` changes.
 		 */
@@ -122,21 +96,6 @@ export type UnitControlProps = Omit< UnitSelectControlProps, 'unit' > &
 		 * For example, a `value` of "50%" will set the current unit to `%`.
 		 */
 		value?: string | number;
-		/**
-		 * If true, pressing `UP` or `DOWN` along with the `SHIFT` key will increment
-		 * the value by the `shiftStep` value.
-		 *
-		 * @default true
-		 */
-		isShiftStepEnabled?: boolean;
-		/**
-		 * Amount to increment by when the `SHIFT` key is held down. This shift value
-		 * is a multiplier to the `step` value. For example, if the `step` value is `5`,
-		 * and `shiftStep` is `10`, each jump would increment/decrement by `50`.
-		 *
-		 * @default 10
-		 */
-		shiftStep?: number;
 		/**
 		 * Callback when either the quantity or the unit inputs lose focus.
 		 */

package/src/utils/colors-values.js

@@ -22,20 +22,6 @@ const GRAY = {
 	100: '#f0f0f0',
 };
 
-const DARK_GRAY = {
-	500: '#555d66', // Use this most of the time for dark items.
-	300: '#6c7781', // Lightest gray that can be used for AA text contrast.
-	150: '#8d96a0', // Lightest gray that can be used for AA non-text contrast.
-};
-
-const LIGHT_GRAY = {
-	800: '#b5bcc2',
-	600: '#d7dade',
-	400: '#e8eaeb', // Good for "readonly" input fields and special text selection.
-	300: '#edeff0',
-	200: '#f3f4f5',
-};
-
 // Matches @wordpress/base-styles
 const ALERT = {
 	yellow: '#f0b849',
@@ -52,12 +38,12 @@ const ADMIN = {
 const UI = {
 	theme: ADMIN.theme,
 	background: white,
-	backgroundDisabled: LIGHT_GRAY[ 200 ], // TODO: Replace with WordPress gray
+	backgroundDisabled: GRAY[ 100 ],
 	border: GRAY[ 700 ],
 	borderHover: GRAY[ 700 ],
 	borderFocus: ADMIN.themeDark10,
 	borderDisabled: GRAY[ 400 ],
-	textDisabled: DARK_GRAY[ 150 ], // TODO: Replace with WordPress gray
+	textDisabled: GRAY[ 600 ],
 	textDark: white,
 
 	// Matches @wordpress/base-styles
@@ -66,18 +52,10 @@ const UI = {
 };
 
 export const COLORS = Object.freeze( {
-	/**
-	 * @deprecated Try to use `gray` instead.
-	 */
-	darkGray: DARK_GRAY,
 	/**
 	 * The main gray color object.
 	 */
 	gray: GRAY,
-	/**
-	 * @deprecated Try to use `gray` instead.
-	 */
-	lightGray: LIGHT_GRAY,
 	white,
 	alert: ALERT,
 	ui: UI,

package/src/utils/math.js

@@ -73,10 +73,10 @@ export function clamp( value, min, max ) {
 /**
  * Clamps a value based on a min/max range with rounding
  *
- * @param {number} value The value.
- * @param {number} min   The minimum range.
- * @param {number} max   The maximum range.
- * @param {number} step  A multiplier for the value.
+ * @param {number | string} value The value.
+ * @param {number}          min   The minimum range.
+ * @param {number}          max   The maximum range.
+ * @param {number}          step  A multiplier for the value.
  *
  * @return {number} The rounded and clamped value.
  */

package/src/utils/values.js

@@ -4,8 +4,8 @@
  *
  * @template T
  *
- * @param {T | null | undefined} value The value to check.
- * @return {value is T} Whether value is not null or undefined.
+ * @param {T} value The value to check.
+ * @return {value is Exclude<T, null | undefined>} Whether value is not null or undefined.
  */
 export function isValueDefined( value ) {
 	return value !== undefined && value !== null;
@@ -16,10 +16,8 @@ export function isValueDefined( value ) {
 /**
  * Determines if a value is empty, null, or undefined.
  *
- * @template T
- *
- * @param {T | "" | null | undefined} value The value to check.
- * @return {value is T} Whether value is empty.
+ * @param {string | number | null | undefined} value The value to check.
+ * @return {value is ("" | null | undefined)} Whether value is empty.
  */
 export function isValueEmpty( value ) {
 	const isEmptyString = value === '';
@@ -99,3 +97,47 @@ export function isValueNumeric( value, locale = window.navigator.language ) {
 			: value;
 	return ! isNaN( parseFloat( valueToCheck ) ) && isFinite( valueToCheck );
 }
+
+/**
+ * Converts a string to a number.
+ *
+ * @param {string} value
+ * @return {number} String as a number.
+ */
+export const stringToNumber = ( value ) => {
+	return parseFloat( value );
+};
+
+/**
+ * Converts a number to a string.
+ *
+ * @param {number} value
+ * @return {string} Number as a string.
+ */
+export const numberToString = ( value ) => {
+	return `${ value }`;
+};
+
+/**
+ * Regardless of the input being a string or a number, returns a number.
+ *
+ * Returns `undefined` in case the string is `undefined` or not a valid numeric value.
+ *
+ * @param {string | number} value
+ * @return {number} The parsed number.
+ */
+export const ensureNumber = ( value ) => {
+	return typeof value === 'string' ? stringToNumber( value ) : value;
+};
+
+/**
+ * Regardless of the input being a string or a number, returns a number.
+ *
+ * Returns `undefined` in case the string is `undefined` or not a valid numeric value.
+ *
+ * @param {string | number} value
+ * @return {string} The converted string, or `undefined` in case the input is `undefined` or `NaN`.
+ */
+export const ensureString = ( value ) => {
+	return typeof value === 'string' ? value : numberToString( value );
+};