@wordpress/components 20.0.0 → 21.0.0

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/strings.ts

@@ -70,3 +70,14 @@ export const normalizeTextString = ( value: string ): string => {
 		.toLocaleLowerCase()
 		.replace( ALL_UNICODE_DASH_CHARACTERS, '-' );
 };
+
+/**
+ * Escapes the RegExp special characters.
+ *
+ * @param {string} string Input string.
+ *
+ * @return {string} Regex-escaped string.
+ */
+export function escapeRegExp( string: string ): string {
+	return string.replace( /[\\^$.*+?()[\]{}|]/g, '\\$&' );
+}

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 );
+};

package/src/v-stack/test/__snapshots__/index.tsx.snap

@@ -13,16 +13,13 @@ exports[`props should render alignment 1`] = `
   -webkit-flex-direction: column;
   -ms-flex-direction: column;
   flex-direction: column;
+  gap: calc(4px * 2);
   -webkit-box-pack: center;
   -ms-flex-pack: center;
   -webkit-justify-content: center;
   justify-content: center;
 }
 
-.emotion-0>*+*:not( marquee ) {
-  margin-top: calc(4px * 2);
-}
-
 .emotion-0>* {
   min-height: 0;
 }
@@ -54,15 +51,12 @@ exports[`props should render correctly 1`] = `
   -webkit-flex-direction: column;
   -ms-flex-direction: column;
   flex-direction: column;
+  gap: calc(4px * 2);
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
 }
 
-.emotion-0>*+*:not( marquee ) {
-  margin-top: calc(4px * 2);
-}
-
 .emotion-0>* {
   min-height: 0;
 }
@@ -94,15 +88,12 @@ exports[`props should render spacing 1`] = `
   -webkit-flex-direction: column;
   -ms-flex-direction: column;
   flex-direction: column;
+  gap: calc(4px * 5);
   -webkit-box-pack: justify;
   -webkit-justify-content: space-between;
   justify-content: space-between;
 }
 
-.emotion-0>*+*:not( marquee ) {
-  margin-top: calc(4px * 5);
-}
-
 .emotion-0>* {
   min-height: 0;
 }

package/src/view/{component.js → component.tsx}

@@ -2,6 +2,13 @@
  * External dependencies
  */
 import styled from '@emotion/styled';
+import type { RefAttributes } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponent } from '../ui/context/wordpress-component';
+import type { ViewProps } from './types';
 
 /**
  * `View` is a core component that renders everything in the library.
@@ -19,11 +26,13 @@ import styled from '@emotion/styled';
  * 	);
  * }
  * ```
- *
- * @type {import('../ui/context').WordPressComponent<'div', { children?: import('react').ReactNode }, true>}
  */
-// @ts-ignore
-const View = styled.div``;
+// @ts-expect-error
+export const View: WordPressComponent<
+	'div',
+	ViewProps & RefAttributes< any >
+> = styled.div``;
+
 View.selector = '.components-view';
 View.displayName = 'View';
 

package/src/view/stories/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '..';
+
+const meta: ComponentMeta< typeof View > = {
+	component: View,
+	title: 'Components (Experimental)/View',
+	argTypes: {
+		as: { control: { type: null } },
+		children: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof View > = ( args ) => {
+	return <View { ...args } />;
+};
+
+export const Default: ComponentStory< typeof View > = Template.bind( {} );
+Default.args = {
+	children: 'An example tip',
+};

package/src/view/types.ts

@@ -0,0 +1,6 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ViewProps = { children?: ReactNode };