@wordpress/components 19.11.0 → 19.14.0

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

@@ -67,9 +67,8 @@ const DefaultTemplate: ComponentStory< typeof UnitControl > = ( {
 	);
 };
 
-export const Default: ComponentStory<
-	typeof UnitControl
-> = DefaultTemplate.bind( {} );
+export const Default: ComponentStory< typeof UnitControl > =
+	DefaultTemplate.bind( {} );
 Default.args = {
 	label: 'Label',
 };
@@ -79,9 +78,8 @@ Default.args = {
  * will not fire while a new value is typed in the input field (you can verify this
  * behavior by inspecting the console's output).
  */
-export const PressEnterToChange: ComponentStory<
-	typeof UnitControl
-> = DefaultTemplate.bind( {} );
+export const PressEnterToChange: ComponentStory< typeof UnitControl > =
+	DefaultTemplate.bind( {} );
 PressEnterToChange.args = {
 	...Default.args,
 	isPressEnterToChange: true,
@@ -95,9 +93,8 @@ PressEnterToChange.args = {
  * Most of `NumberControl`'s props can be passed to `UnitControl`, and they will
  * affect its numeric input field.
  */
-export const TweakingTheNumberInput: ComponentStory<
-	typeof UnitControl
-> = DefaultTemplate.bind( {} );
+export const TweakingTheNumberInput: ComponentStory< typeof UnitControl > =
+	DefaultTemplate.bind( {} );
 TweakingTheNumberInput.args = {
 	...Default.args,
 	min: 0,
@@ -109,9 +106,8 @@ TweakingTheNumberInput.args = {
 /**
  * When only one unit is available, the unit selection dropdown becomes static text.
  */
-export const WithSingleUnit: ComponentStory<
-	typeof UnitControl
-> = DefaultTemplate.bind( {} );
+export const WithSingleUnit: ComponentStory< typeof UnitControl > =
+	DefaultTemplate.bind( {} );
 WithSingleUnit.args = {
 	...Default.args,
 	units: CSS_UNITS.slice( 0, 1 ),

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

@@ -39,9 +39,8 @@ const ControlledSyncUnits = () => {
 		fieldName: 'valueA' | 'valueB',
 		newValue?: string | number
 	) => {
-		const parsedQuantityAndUnit = parseQuantityAndUnitFromRawValue(
-			newValue
-		);
+		const parsedQuantityAndUnit =
+			parseQuantityAndUnitFromRawValue( newValue );
 		const quantity = parsedQuantityAndUnit[ 0 ];
 
 		if ( ! Number.isFinite( quantity ) ) {
@@ -56,10 +55,8 @@ const ControlledSyncUnits = () => {
 		};
 
 		Object.entries( state ).forEach( ( [ stateProp, stateValue ] ) => {
-			const [
-				stateQuantity,
-				stateUnit,
-			] = parseQuantityAndUnitFromRawValue( stateValue );
+			const [ stateQuantity, stateUnit ] =
+				parseQuantityAndUnitFromRawValue( stateValue );
 
 			if ( stateProp !== fieldName && stateUnit !== newUnit ) {
 				nextState[

package/src/utils/hooks/index.js

@@ -1,6 +1,5 @@
 export { default as useControlledState } from './use-controlled-state';
 export { default as useUpdateEffect } from './use-update-effect';
-export { useCombinedRef } from './use-combined-ref';
 export { useControlledValue } from './use-controlled-value';
 export { useCx } from './use-cx';
 export { useLatestRef } from './use-latest-ref';

package/src/utils/hooks/stories/use-cx.js

@@ -33,19 +33,20 @@ const ExampleWithUseMemoWrong = ( { serializedStyles, children } ) => {
 	const cx = useCx();
 	// Wrong: using 'useMemo' without adding 'cx' to the dependency list.
 	// eslint-disable-next-line react-hooks/exhaustive-deps
-	const classes = useMemo( () => cx( serializedStyles ), [
-		serializedStyles,
-	] );
+	const classes = useMemo(
+		() => cx( serializedStyles ),
+		[ serializedStyles ]
+	);
 	return <span className={ classes }>{ children }</span>;
 };
 
 const ExampleWithUseMemoRight = ( { serializedStyles, children } ) => {
 	const cx = useCx();
 	// Right: using 'useMemo' with 'cx' listed as a dependency.
-	const classes = useMemo( () => cx( serializedStyles ), [
-		cx,
-		serializedStyles,
-	] );
+	const classes = useMemo(
+		() => cx( serializedStyles ),
+		[ cx, serializedStyles ]
+	);
 	return <span className={ classes }>{ children }</span>;
 };
 

package/src/utils/hooks/test/use-controlled-state.js

@@ -2,13 +2,14 @@
  * External dependencies
  */
 import { render, fireEvent, screen } from '@testing-library/react';
-import { noop } from 'lodash';
 
 /**
  * Internal dependencies
  */
 import useControlledState from '../use-controlled-state';
 
+const noop = () => {};
+
 describe( 'hooks', () => {
 	const getInput = () => screen.getByTestId( 'input' );
 

package/src/utils/math.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { clamp } from 'lodash';
-
 /**
  * Parses and retrieves a number value.
  *
@@ -61,6 +56,20 @@ function getPrecision( value ) {
 	return split[ 1 ] !== undefined ? split[ 1 ].length : 0;
 }
 
+/**
+ * Clamps a value based on a min/max range.
+ *
+ * @param {number} value The value.
+ * @param {number} min   The minimum range.
+ * @param {number} max   The maximum range.
+ *
+ * @return {number} The clamped value.
+ */
+export function clamp( value, min, max ) {
+	const baseValue = getNumber( value );
+	return Math.max( min, Math.min( baseValue, max ) );
+}
+
 /**
  * Clamps a value based on a min/max range with rounding
  *

package/src/utils/test/math.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { add, subtract, roundClamp } from '../math';
+import { add, clamp, subtract, roundClamp } from '../math';
 
 describe( 'add', () => {
 	it( 'should add string and number values', () => {
@@ -37,6 +37,27 @@ describe( 'subtract', () => {
 	} );
 } );
 
+describe( 'clamp', () => {
+	it( 'should clamp a value between min and max', () => {
+		expect( clamp( 10, 1, 10 ) ).toBe( 10 );
+		expect( clamp( 1, 1, 10 ) ).toBe( 1 );
+		expect( clamp( 0, 1, 10 ) ).toBe( 1 );
+
+		expect( clamp( 50, 1, 10 ) ).toBe( 10 );
+		expect( clamp( 50, -10, 10 ) ).toBe( 10 );
+		expect( clamp( -50, -10, 10 ) ).toBe( -10 );
+
+		expect( clamp( Infinity, -10, 10 ) ).toBe( 10 );
+		expect( clamp( -Infinity, -10, 10 ) ).toBe( -10 );
+	} );
+
+	it( 'should clamp number or string values', () => {
+		expect( clamp( '50', 1, 10 ) ).toBe( 10 );
+		expect( clamp( '50', -10, 10 ) ).toBe( 10 );
+		expect( clamp( -50, -10, '10' ) ).toBe( -10 );
+	} );
+} );
+
 describe( 'roundClamp', () => {
 	it( 'should clamp a value between min and max', () => {
 		expect( roundClamp( 10, 1, 10 ) ).toBe( 10 );

package/src/utils/unit-values.ts

@@ -1,4 +1,5 @@
-const UNITED_VALUE_REGEX = /^([\d.\-+]*)\s*(fr|cm|mm|Q|in|pc|pt|px|em|ex|ch|rem|lh|vw|vh|vmin|vmax|%|cap|ic|rlh|vi|vb|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?$/;
+const UNITED_VALUE_REGEX =
+	/^([\d.\-+]*)\s*(fr|cm|mm|Q|in|pc|pt|px|em|ex|ch|rem|lh|vw|vh|vmin|vmax|%|cap|ic|rlh|vi|vb|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?$/;
 
 /**
  * Parses a number and unit from a value.

package/src/utils/values.js

@@ -88,9 +88,8 @@ export function isValueNumeric( value, locale = window.navigator.language ) {
 		}
 	}
 
-	const [ delimiterRegexp, decimalRegexp ] = getDelimiterAndDecimalRegex(
-		locale
-	);
+	const [ delimiterRegexp, decimalRegexp ] =
+		getDelimiterAndDecimalRegex( locale );
 	const valueToCheck =
 		typeof value === 'string'
 			? value

package/src/v-stack/README.md

@@ -29,9 +29,7 @@ function Example() {
 
 ## Props
 
-##### alignment
-
-**Type**: `HStackAlignment`,`CSS['alignItems']`
+##### `alignment`: `HStackAlignment | CSSProperties['alignItems']`
 
 Determines how the child elements are aligned.
 
@@ -47,35 +45,25 @@ Determines how the child elements are aligned.
 -   `edge`: Aligns content to the edges of the container.
 -   `stretch`: Stretches content to the edges of the container.
 
-##### direction
-
-**Type**: `FlexDirection`
+##### `direction`: `FlexDirection`
 
 The direction flow of the children content can be adjusted with `direction`. `column` will align children vertically and `row` will align children horizontally.
 
-##### expanded
-
-**Type**: `boolean`
+##### `expanded`: `boolean`
 
 Expands to the maximum available width (if horizontal) or height (if vertical).
 
-##### justify
-
-**Type**: `CSS['justifyContent']`
+##### `justify`: `CSSProperties['justifyContent']`
 
 Horizontally aligns content if the `direction` is `row`, or vertically aligns content if the `direction` is `column`.
 In the example below, `flex-start` will align the children content to the left.
 
-##### spacing
-
-**Type**: `CSS['width']`
+##### `spacing`: `CSSProperties['width']`
 
 The amount of space between each child element. Spacing in between each child can be adjusted by using `spacing`.
 The value of `spacing` works as a multiplier to the library's grid system (base of `4px`).
 
-##### wrap
-
-**Type**: `boolean`
+##### `wrap`: `boolean`
 
 Determines if children should wrap.
 

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

@@ -1,26 +1,31 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import { useVStack } from './hook';
+import type { VStackProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function VStack( props, forwardedRef ) {
+function UnconnectedVStack(
+	props: WordPressComponentProps< VStackProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const vStackProps = useVStack( props );
 
 	return <View { ...vStackProps } ref={ forwardedRef } />;
 }
 
 /**
- * `VStack` (or Vertical Stack) is a layout component that arranges child elements in a vertical line.
+ * `VStack` (or Vertical Stack) is a layout component that arranges child
+ * elements in a vertical line.
  *
  * `VStack` can render anything inside.
  *
- * @example
  * ```jsx
  * import {
  * 	__experimentalText as Text,
@@ -38,6 +43,6 @@ function VStack( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedVStack = contextConnect( VStack, 'VStack' );
+export const VStack = contextConnect( UnconnectedVStack, 'VStack' );
 
-export default ConnectedVStack;
+export default VStack;

package/src/v-stack/{hook.js → hook.ts}

@@ -1,14 +1,13 @@
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { useHStack } from '../h-stack';
+import type { VStackProps } from './types';
 
-/**
- *
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useVStack( props ) {
+export function useVStack(
+	props: WordPressComponentProps< VStackProps, 'div' >
+) {
 	const { expanded = false, ...otherProps } = useContextSystem(
 		props,
 		'VStack'

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

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { VStack } from '..';
+
+const meta: ComponentMeta< typeof VStack > = {
+	component: VStack,
+	title: 'Components (Experimental)/VStack',
+	argTypes: {
+		alignment: { control: { type: 'text' } },
+		as: { control: { type: 'text' } },
+		direction: { control: { type: 'text' } },
+		justify: { control: { type: 'text' } },
+		spacing: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof VStack > = ( props ) => {
+	return (
+		<VStack { ...props }>
+			<View>One</View>
+			<View>Two</View>
+			<View>Three</View>
+			<View>Four</View>
+			<View>Five</View>
+		</VStack>
+	);
+};
+
+export const Default = Template.bind( {} );

package/src/v-stack/types.ts

@@ -8,7 +8,27 @@ import type { CSSProperties } from 'react';
  */
 import type { HStackAlignment, Props as HStackProps } from '../h-stack/types';
 
-export type Props = HStackProps & {
+export type VStackProps = HStackProps & {
+	/**
+	 * Determines how the child elements are aligned.
+	 *
+	 * -   `top`: Aligns content to the top.
+	 * -   `topLeft`: Aligns content to the top/left.
+	 * -   `topRight`: Aligns content to the top/right.
+	 * -   `left`: Aligns content to the left.
+	 * -   `center`: Aligns content to the center.
+	 * -   `right`: Aligns content to the right.
+	 * -   `bottom`: Aligns content to the bottom.
+	 * -   `bottomLeft`: Aligns content to the bottom/left.
+	 * -   `bottomRight`: Aligns content to the bottom/right.
+	 * -   `edge`: Aligns content to the edges of the container.
+	 * -   `stretch`: Stretches content to the edges of the container.
+	 */
 	alignment?: HStackAlignment | CSSProperties[ 'alignItems' ];
+	/**
+	 * The amount of space between each child element. Spacing in between each
+	 * child can be adjusted by using `spacing`. The value of `spacing` works as
+	 * a multiplier to the library's grid system (base of `4px`).
+	 */
 	spacing?: CSSProperties[ 'width' ];
 };

package/src/z-stack/README.md

@@ -26,16 +26,27 @@ function Example() {
 
 ### `isLayered`: `boolean`
 
-When `true`, the children are stacked on top of each other. When `false`, the children follow the normal flow of the layout. Defaults to `true`.
+Layers children elements on top of each other (first: highest z-index, last: lowest z-index).
+
+-   Required: No
+-   Default: `true`
 
 ### `isReversed`: `boolean`
 
-Reverse the layer ordering. When `true`, the first child has the lowest `z-index` and the last child has the highest `z-index`. When `false`, the first child has the highest `z-index` and the last child has the lowest `z-index`. Defaults to `false`.
+Reverse the layer ordering (first: lowest z-index, last: highest z-index).
+
+-   Required: No
+-   Default: `false`
 
 ### `offset`: `number`
 
-The amount of space between each child element. Defaults to `0`. Its value is automatically inverted (i.e. from positive to negative, and viceversa) when switching from LTR to RTL.
+The amount of space between each child element. Its value is automatically inverted (i.e. from positive to negative, and viceversa) when switching from LTR to RTL.
+
+-   Required: No
+-   Default: `0`
 
 ### `children`: `ReactNode`
 
 The children to stack.
+
+-   Required: Yes

package/src/z-stack/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ForwardedRef, ReactNode } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -13,35 +13,11 @@ import { isValidElement } from '@wordpress/element';
  */
 import { getValidChildren } from '../ui/utils/get-valid-children';
 import { contextConnect, useContextSystem } from '../ui/context';
-import type { WordPressComponentProps } from '../ui/context';
 import { ZStackView, ZStackChildView } from './styles';
+import type { ZStackProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-export interface ZStackProps {
-	/**
-	 * Layers children elements on top of each other (first: highest z-index, last: lowest z-index).
-	 *
-	 * @default true
-	 */
-	isLayered?: boolean;
-	/**
-	 * Reverse the layer ordering (first: lowest z-index, last: highest z-index).
-	 *
-	 * @default false
-	 */
-	isReversed?: boolean;
-	/**
-	 * The amount of offset between each child element. The amount of space between each child element. Defaults to `0`. Its value is automatically inverted (i.e. from positive to negative, and viceversa) when switching from LTR to RTL.
-	 *
-	 * @default 0
-	 */
-	offset?: number;
-	/**
-	 * Child elements.
-	 */
-	children: ReactNode;
-}
-
-function ZStack(
+function UnconnectedZStack(
 	props: WordPressComponentProps< ZStackProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -86,4 +62,23 @@ function ZStack(
 	);
 }
 
-export default contextConnect( ZStack, 'ZStack' );
+/**
+ * `ZStack` allows you to stack things along the Z-axis.
+ *
+ * ```jsx
+ * import { __experimentalZStack as ZStack } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <ZStack offset={ 20 } isLayered>
+ *       <ExampleImage />
+ *       <ExampleImage />
+ *       <ExampleImage />
+ *     </ZStack>
+ *   );
+ * }
+ * ```
+ */
+export const ZStack = contextConnect( UnconnectedZStack, 'ZStack' );
+
+export default ZStack;

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

@@ -0,0 +1,76 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Elevation } from '../../elevation';
+import { HStack } from '../../h-stack';
+import { View } from '../../view';
+import { ZStack } from '..';
+
+const meta: ComponentMeta< typeof ZStack > = {
+	component: ZStack,
+	title: 'Components (Experimental)/ZStack',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		children: { control: { type: null } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Avatar = ( {
+	backgroundColor,
+}: {
+	backgroundColor: CSSProperties[ 'backgroundColor' ];
+} ) => {
+	return (
+		<View>
+			<View
+				style={ {
+					border: '3px solid black',
+					borderRadius: '9999px',
+					height: '48px',
+					width: '48px',
+					backgroundColor,
+				} }
+			/>
+			<Elevation
+				borderRadius={ 9999 }
+				isInteractive={ false }
+				value={ 3 }
+			/>
+		</View>
+	);
+};
+
+const Template: ComponentStory< typeof ZStack > = ( args ) => {
+	return (
+		<View>
+			<HStack>
+				<View>
+					<ZStack { ...args }>
+						<Avatar backgroundColor="#444" />
+						<Avatar backgroundColor="#777" />
+						<Avatar backgroundColor="#aaa" />
+						<Avatar backgroundColor="#fff" />
+					</ZStack>
+				</View>
+			</HStack>
+		</View>
+	);
+};
+
+export const Default: ComponentStory< typeof ZStack > = Template.bind( {} );
+Default.args = {
+	offset: 20,
+};

package/src/z-stack/types.ts

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ZStackProps = {
+	/**
+	 * Layers children elements on top of each other (first: highest z-index,
+	 * last: lowest z-index).
+	 *
+	 * @default true
+	 */
+	isLayered?: boolean;
+	/**
+	 * Reverse the layer ordering (first: lowest z-index, last: highest
+	 * z-index).
+	 *
+	 * @default false
+	 */
+	isReversed?: boolean;
+	/**
+	 * The amount of space between each child element. Its value is
+	 * automatically inverted (i.e. from positive to negative, and viceversa)
+	 * when switching from LTR to RTL.
+	 *
+	 * @default 0
+	 */
+	offset?: number;
+	/**
+	 * The children to stack.
+	 */
+	children: ReactNode;
+};

package/tsconfig.json

@@ -6,6 +6,7 @@
 		"types": [
 			"gutenberg-env",
 			"gutenberg-test-env",
+			"dom-scroll-into-view",
 			"jest",
 			"@testing-library/jest-dom",
 			"snapshot-diff",
@@ -53,8 +54,11 @@
 		"src/dropdown/**/*",
 		"src/dropdown-menu/**/*",
 		"src/elevation/**/*",
+		"src/external-link/**/*",
 		"src/flex/**/*",
 		"src/form-group/**/*",
+		"src/form-toggle/**/*",
+		"src/form-token-field/**/*",
 		"src/grid/**/*",
 		"src/h-stack/**/*",
 		"src/heading/**/*",
@@ -69,6 +73,7 @@
 		"src/navigator/**/*",
 		"src/number-control/**/*",
 		"src/popover/**/*",
+		"src/radio-control/**/*",
 		"src/range-control/**/*",
 		"src/resizable-box/**/*",
 		"src/scroll-lock/**/*",
@@ -82,10 +87,12 @@
 		"src/surface/**/*",
 		"src/text/**/*",
 		"src/text-control/**/*",
+		"src/textarea-control/**/*",
 		"src/tip/**/*",
 		"src/toggle-group-control/**/*",
 		"src/tools-panel/**/*",
 		"src/tooltip/**/*",
+		"src/tree-select/**/*",
 		"src/truncate/**/*",
 		"src/ui/**/*",
 		"src/unit-control/**/*",