@wordpress/components 19.13.0 → 19.16.0

package/src/elevation/README.md

@@ -33,46 +33,45 @@ function Example() {
 
 Size of the shadow value when active (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `borderRadius`: `CSSProperties[ 'borderRadius' ]`
 
 Renders the border-radius of the shadow.
 
-- Required: No
-- Default: `inherit`
+-   Required: No
+-   Default: `inherit`
 
 ### `focus`: `number`
 
-Size of the shadow value when focused (see the `value` and `isInteractive` props).
+Size of the shadow value when focused (see the `value` and `isInteractive`props).
 
-- Required: No
+-   Required: No
 
 ### `hover`: `number`
 
-Size of the shadow value when hovered  (see the `value` and `isInteractive` props).
+Size of the shadow value when hovered (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `isInteractive`: `boolean`
 
 Determines if `hover`, `active`, and `focus` shadow values should be automatically calculated and rendered.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 ### `offset`: `number`
 
 Dimensional offsets (margin) for the shadow.
 
-- Required: No
-- Default: `0`
+-   Required: No
+-   Default: `0`
 
-### `value`
-
-**Type**: `number`
+### `value`: `number`
 
 Size of the shadow, based on the Style system's elevation system. The `value` determines the strength of the shadow, which sense of depth.
+
 In the example below, `isInteractive` is activated to give a better sense of depth.
 
 ```jsx
@@ -86,3 +85,6 @@ function Example() {
 	);
 }
 ```
+
+-   Required: No
+-   Default: `0`

package/src/elevation/component.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../ui/context';
+import { View } from '../view';
+import { useElevation } from './hook';
+import type { ElevationProps } from './types';
+
+function UnconnectedElevation(
+	props: WordPressComponentProps< ElevationProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const elevationProps = useElevation( props );
+
+	return <View { ...elevationProps } ref={ forwardedRef } />;
+}
+
+/**
+ * `Elevation` is a core component that renders shadow, using the component
+ * system's shadow system.
+ *
+ * The shadow effect is generated using the `value` prop.
+ *
+ * ```jsx
+ * import {
+ *	__experimentalElevation as Elevation,
+ *	__experimentalSurface as Surface,
+ *	__experimentalText as Text,
+ * } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Surface>
+ *       <Text>Code is Poetry</Text>
+ *       <Elevation value={ 5 } />
+ *     </Surface>
+ *   );
+ * }
+ * ```
+ */
+export const Elevation = contextConnect( UnconnectedElevation, 'Elevation' );
+
+export default Elevation;

package/src/elevation/{hook.js → hook.ts}

@@ -1,8 +1,7 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
-import { isNil } from 'lodash';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * WordPress dependencies
@@ -12,27 +11,24 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import * as styles from './styles';
 import { CONFIG, reduceMotion } from '../utils';
 import { useCx } from '../utils/hooks/use-cx';
+import { isValueDefined } from '../utils/values';
+import type { ElevationProps } from './types';
 
-/**
- * @param {number} value
- * @return {string} The box shadow value.
- */
-export function getBoxShadow( value ) {
-	const boxShadowColor = `rgba(0 ,0, 0, ${ value / 20 })`;
+export function getBoxShadow( value: number ) {
+	const boxShadowColor = `rgba(0, 0, 0, ${ value / 20 })`;
 	const boxShadow = `0 ${ value }px ${ value * 2 }px 0
 	${ boxShadowColor }`;
 
 	return boxShadow;
 }
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useElevation( props ) {
+export function useElevation(
+	props: WordPressComponentProps< ElevationProps, 'div' >
+) {
 	const {
 		active,
 		borderRadius = 'inherit',
@@ -48,19 +44,26 @@ export function useElevation( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		/** @type {number | undefined} */
-		let hoverValue = ! isNil( hover ) ? hover : value * 2;
-		/** @type {number | undefined} */
-		let activeValue = ! isNil( active ) ? active : value / 2;
+		let hoverValue: number | undefined = isValueDefined( hover )
+			? hover
+			: value * 2;
+		let activeValue: number | undefined = isValueDefined( active )
+			? active
+			: value / 2;
 
 		if ( ! isInteractive ) {
-			hoverValue = ! isNil( hover ) ? hover : undefined;
-			activeValue = ! isNil( active ) ? active : undefined;
+			hoverValue = isValueDefined( hover ) ? hover : undefined;
+			activeValue = isValueDefined( active ) ? active : undefined;
 		}
 
 		const transition = `box-shadow ${ CONFIG.transitionDuration } ${ CONFIG.transitionTimingFunction }`;
 
-		const sx = {};
+		const sx: {
+			Base?: SerializedStyles;
+			hover?: SerializedStyles;
+			active?: SerializedStyles;
+			focus?: SerializedStyles;
+		} = {};
 
 		sx.Base = css(
 			{
@@ -76,7 +79,7 @@ export function useElevation( props ) {
 			reduceMotion( 'transition' )
 		);
 
-		if ( ! isNil( hoverValue ) ) {
+		if ( isValueDefined( hoverValue ) ) {
 			sx.hover = css`
 				*:hover > & {
 					box-shadow: ${ getBoxShadow( hoverValue ) };
@@ -84,7 +87,7 @@ export function useElevation( props ) {
 			`;
 		}
 
-		if ( ! isNil( activeValue ) ) {
+		if ( isValueDefined( activeValue ) ) {
 			sx.active = css`
 				*:active > & {
 					box-shadow: ${ getBoxShadow( activeValue ) };
@@ -92,7 +95,7 @@ export function useElevation( props ) {
 			`;
 		}
 
-		if ( ! isNil( focus ) ) {
+		if ( isValueDefined( focus ) ) {
 			sx.focus = css`
 				*:focus > & {
 					box-shadow: ${ getBoxShadow( focus ) };
@@ -103,9 +106,9 @@ export function useElevation( props ) {
 		return cx(
 			styles.Elevation,
 			sx.Base,
-			sx.hover && sx.hover,
-			sx.focus && sx.focus,
-			sx.active && sx.active,
+			sx.hover,
+			sx.focus,
+			sx.active,
 			className
 		);
 	}, [

package/src/elevation/stories/index.tsx

@@ -0,0 +1,85 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Elevation } from '..';
+
+const meta: ComponentMeta< typeof Elevation > = {
+	component: Elevation,
+	title: 'Components (Experimental)/Elevation',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		borderRadius: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Elevation > = ( args ) => {
+	return (
+		<div
+			style={ {
+				width: 150,
+				height: 150,
+				position: 'relative',
+			} }
+		>
+			<Elevation { ...args } />
+		</div>
+	);
+};
+
+const InteractiveTemplate: ComponentStory< typeof Elevation > = ( args ) => {
+	return (
+		<button
+			style={ {
+				border: 0,
+				background: 'transparent',
+				width: 150,
+				height: 150,
+				position: 'relative',
+			} }
+		>
+			Click me
+			<Elevation { ...args } />
+		</button>
+	);
+};
+
+export const Default: ComponentStory< typeof Elevation > = Template.bind( {} );
+Default.args = {
+	value: 5,
+};
+
+/**
+ * Enable the `isInteractive` prop to automatically generate values
+ * for the hover/active/focus states.
+ */
+export const WithInteractive: ComponentStory< typeof Elevation > =
+	InteractiveTemplate.bind( {} );
+WithInteractive.args = {
+	...Default.args,
+	isInteractive: true,
+};
+
+/**
+ * You can also provide custom values for the hover/active/focus states
+ * instead of using the `isInteractive` prop.
+ */
+export const WithCustomInteractive: ComponentStory< typeof Elevation > =
+	InteractiveTemplate.bind( {} );
+WithCustomInteractive.args = {
+	...Default.args,
+	hover: 7,
+	active: 1,
+	focus: 10,
+};

package/src/elevation/test/__snapshots__/{index.js.snap → index.tsx.snap}

@@ -10,7 +10,7 @@ exports[`props should render active 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: 0;
-  box-shadow: 0 7px 14px 0 rgba(0 ,0, 0, 0.35);
+  box-shadow: 0 7px 14px 0 rgba(0, 0, 0, 0.35);
   opacity: 1;
   left: 0;
   right: 0;
@@ -26,16 +26,17 @@ exports[`props should render active 1`] = `
 }
 
 *:hover>.emotion-0 {
-  box-shadow: 0 14px 28px 0 rgba(0 ,0, 0, 0.7);
+  box-shadow: 0 14px 28px 0 rgba(0, 0, 0, 0.7);
 }
 
 *:active>.emotion-0 {
-  box-shadow: 0 5px 10px 0 rgba(0 ,0, 0, 0.25);
+  box-shadow: 0 5px 10px 0 rgba(0, 0, 0, 0.25);
 }
 
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />
@@ -51,7 +52,7 @@ exports[`props should render correctly 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: 0;
-  box-shadow: 0 0px 0px 0 rgba(0 ,0, 0, 0);
+  box-shadow: 0 0px 0px 0 rgba(0, 0, 0, 0);
   opacity: 1;
   left: 0;
   right: 0;
@@ -69,6 +70,7 @@ exports[`props should render correctly 1`] = `
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />
@@ -84,7 +86,7 @@ exports[`props should render hover 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: 0;
-  box-shadow: 0 7px 14px 0 rgba(0 ,0, 0, 0.35);
+  box-shadow: 0 7px 14px 0 rgba(0, 0, 0, 0.35);
   opacity: 1;
   left: 0;
   right: 0;
@@ -100,12 +102,13 @@ exports[`props should render hover 1`] = `
 }
 
 *:hover>.emotion-0 {
-  box-shadow: 0 14px 28px 0 rgba(0 ,0, 0, 0.7);
+  box-shadow: 0 14px 28px 0 rgba(0, 0, 0, 0.7);
 }
 
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />
@@ -121,7 +124,7 @@ exports[`props should render isInteractive 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: 0;
-  box-shadow: 0 0px 0px 0 rgba(0 ,0, 0, 0);
+  box-shadow: 0 0px 0px 0 rgba(0, 0, 0, 0);
   opacity: 1;
   left: 0;
   right: 0;
@@ -137,16 +140,17 @@ exports[`props should render isInteractive 1`] = `
 }
 
 *:hover>.emotion-0 {
-  box-shadow: 0 0px 0px 0 rgba(0 ,0, 0, 0);
+  box-shadow: 0 0px 0px 0 rgba(0, 0, 0, 0);
 }
 
 *:active>.emotion-0 {
-  box-shadow: 0 0px 0px 0 rgba(0 ,0, 0, 0);
+  box-shadow: 0 0px 0px 0 rgba(0, 0, 0, 0);
 }
 
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />
@@ -162,7 +166,7 @@ exports[`props should render offset 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: -2px;
-  box-shadow: 0 7px 14px 0 rgba(0 ,0, 0, 0.35);
+  box-shadow: 0 7px 14px 0 rgba(0, 0, 0, 0.35);
   opacity: 1;
   left: -2px;
   right: -2px;
@@ -178,16 +182,17 @@ exports[`props should render offset 1`] = `
 }
 
 *:hover>.emotion-0 {
-  box-shadow: 0 14px 28px 0 rgba(0 ,0, 0, 0.7);
+  box-shadow: 0 14px 28px 0 rgba(0, 0, 0, 0.7);
 }
 
 *:active>.emotion-0 {
-  box-shadow: 0 5px 10px 0 rgba(0 ,0, 0, 0.25);
+  box-shadow: 0 5px 10px 0 rgba(0, 0, 0, 0.25);
 }
 
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />
@@ -203,7 +208,7 @@ exports[`props should render value 1`] = `
   will-change: box-shadow;
   border-radius: inherit;
   bottom: 0;
-  box-shadow: 0 7px 14px 0 rgba(0 ,0, 0, 0.35);
+  box-shadow: 0 7px 14px 0 rgba(0, 0, 0, 0.35);
   opacity: 1;
   left: 0;
   right: 0;
@@ -221,6 +226,7 @@ exports[`props should render value 1`] = `
 <div
   aria-hidden="true"
   class="components-elevation emotion-0 emotion-1"
+  data-testid="elevation"
   data-wp-c16t="true"
   data-wp-component="Elevation"
 />

package/src/elevation/test/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Elevation } from '..';
+
+describe( 'props', () => {
+	test( 'should render correctly', () => {
+		render( <Elevation data-testid="elevation" /> );
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render isInteractive', () => {
+		render( <Elevation isInteractive data-testid="elevation" /> );
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render value', () => {
+		render( <Elevation value={ 7 } data-testid="elevation" /> );
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render hover', () => {
+		render(
+			<Elevation hover={ 14 } value={ 7 } data-testid="elevation" />
+		);
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render active', () => {
+		render(
+			<Elevation
+				active={ 5 }
+				hover={ 14 }
+				value={ 7 }
+				data-testid="elevation"
+			/>
+		);
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render offset', () => {
+		render(
+			<Elevation
+				active={ 5 }
+				hover={ 14 }
+				offset={ -2 }
+				value={ 7 }
+				data-testid="elevation"
+			/>
+		);
+
+		expect( screen.getByTestId( 'elevation' ) ).toMatchSnapshot();
+	} );
+} );

package/src/elevation/types.ts

@@ -3,9 +3,10 @@
  */
 import type { CSSProperties } from 'react';
 
-export type Props = {
+export type ElevationProps = {
 	/**
-	 * Size of the shadow value when active (see the `value` and `isInteractive` props).
+	 * Size of the shadow value when active (see the `value` and `isInteractive`
+	 * props).
 	 */
 	active?: number;
 	/**
@@ -15,15 +16,18 @@ export type Props = {
 	 */
 	borderRadius?: CSSProperties[ 'borderRadius' ];
 	/**
-	 * Size of the shadow value when focused (see the `value` and `isInteractive` props).
+	 * Size of the shadow value when focused (see the `value` and
+	 * `isInteractive` props).
 	 */
 	focus?: number;
 	/**
-	 * Size of the shadow value when hovered  (see the `value` and `isInteractive` props).
+	 * Size of the shadow value when hovered (see the `value` and
+	 * `isInteractive` props).
 	 */
 	hover?: number;
 	/**
-	 * Determines if hover, active, and focus shadow values should be automatically calculated and rendered.
+	 * Determines if `hover`, `active`, and `focus` shadow values should be
+	 * automatically calculated and rendered.
 	 *
 	 * @default false
 	 */
@@ -35,20 +39,9 @@ export type Props = {
 	 */
 	offset?: number;
 	/**
-	 * Size of the shadow, based on the Style system's elevation system. The `value` determines the strength of the shadow, which sense of depth.
-	 * In the example below, `isInteractive` is activated to give a better sense of depth.
-	 *
-	 * @example
-	 * ```jsx
-	 * import { __experimentalElevation as Elevation } from '@wordpress/components';
-	 * 	* function Example() {
-	 * 	return (
-	 * 		<div>
-	 * 			<Elevation isInteractive value={ 200 } />
-	 * 		</div>
-	 * 	);
-	 * }
-	 * ```
+	 * Size of the shadow, based on the Style system's elevation system. The
+	 * `value` determines the strength of the shadow, which creates the sense of
+	 * depth.
 	 *
 	 * @default 0
 	 */

package/src/external-link/index.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { compact, uniq } from 'lodash';
 import type { ForwardedRef } from 'react';
 
 /**
@@ -28,9 +27,16 @@ function UnforwardedExternalLink(
 	ref: ForwardedRef< HTMLAnchorElement >
 ) {
 	const { href, children, className, rel = '', ...additionalProps } = props;
-	const optimizedRel = uniq(
-		compact( [ ...rel.split( ' ' ), 'external', 'noreferrer', 'noopener' ] )
-	).join( ' ' );
+	const optimizedRel = [
+		...new Set(
+			[
+				...rel.split( ' ' ),
+				'external',
+				'noreferrer',
+				'noopener',
+			].filter( Boolean )
+		),
+	].join( ' ' );
 	const classes = classnames( 'components-external-link', className );
 	return (
 		/* eslint-disable react/jsx-no-target-blank */

package/src/flex/flex/README.md

@@ -1,9 +1,5 @@
 # Flex
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 `Flex` is a primitive layout component that adaptively aligns child content horizontally or vertically. `Flex` powers components like `HStack` and `VStack`.
 
 ## Usage
@@ -11,21 +7,16 @@ This feature is still experimental. “Experimental” means this is an early im
 `Flex` is used with any of it's two sub-components, `FlexItem` and `FlexBlock`.
 
 ```jsx
-import {
-	__experimentalFlex as Flex,
-	__experimentalFlexBlock as FlexBlock,
-	__experimentalFlexItem as FlexItem,
-	__experimentalText as Text,
-} from '@wordpress/components';
+import { Flex, FlexBlock, FlexItem } from '@wordpress/components';
 
 function Example() {
 	return (
 		<Flex>
 			<FlexItem>
-				<Text>Code</Text>
+				<p>Code</p>
 			</FlexItem>
 			<FlexBlock>
-				<Text>Poetry</Text>
+				<p>Poetry</p>
 			</FlexBlock>
 		</Flex>
 	);

package/src/flex/flex/component.js

@@ -33,27 +33,21 @@ function Flex( props, forwardedRef ) {
  *
  * @example
  * ```jsx
- * import {
- * 	__experimentalFlex as Flex,
- * 	__experimentalFlexBlock as FlexBlock,
- * 	__experimentalFlexItem as FlexItem,
- * 	__experimentalText as Text
- * } from `@wordpress/components`;
+ * import { Flex, FlexBlock, FlexItem } from '@wordpress/components';
  *
  * function Example() {
- * 	return (
- * 		<Flex>
- * 			<FlexItem>
- * 				<Text>Code</Text>
- * 			</FlexItem>
- * 			<FlexBlock>
- * 				<Text>Poetry</Text>
- * 			</FlexBlock>
- * 		</Flex>
- * 	);
+ *   return (
+ *     <Flex>
+ *       <FlexItem>
+ *         <p>Code</p>
+ *       </FlexItem>
+ *       <FlexBlock>
+ *         <p>Poetry</p>
+ *       </FlexBlock>
+ *     </Flex>
+ *   );
  * }
  * ```
- *
  */
 const ConnectedFlex = contextConnect( Flex, 'Flex' );