@wordpress/components 19.14.0 → 19.17.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,7 +1,7 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * WordPress dependencies
@@ -11,28 +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,10 +44,12 @@ export function useElevation( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		/** @type {number | undefined} */
-		let hoverValue = isValueDefined( hover ) ? hover : value * 2;
-		/** @type {number | undefined} */
-		let activeValue = isValueDefined( 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 = isValueDefined( hover ) ? hover : undefined;
@@ -60,7 +58,12 @@ export function useElevation( props ) {
 
 		const transition = `box-shadow ${ CONFIG.transitionDuration } ${ CONFIG.transitionTimingFunction }`;
 
-		const sx = {};
+		const sx: {
+			Base?: SerializedStyles;
+			hover?: SerializedStyles;
+			active?: SerializedStyles;
+			focus?: SerializedStyles;
+		} = {};
 
 		sx.Base = css(
 			{
@@ -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,16 +27,33 @@ 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 );
+	/* Anchor links are percieved as external links.
+	This constant helps check for on page anchor links,
+	to prevent them from being opened in the editor. */
+	const isInternalAnchor = !! href?.startsWith( '#' );
+
 	return (
 		/* eslint-disable react/jsx-no-target-blank */
 		<a
 			{ ...additionalProps }
 			className={ classes }
 			href={ href }
+			onClick={
+				isInternalAnchor
+					? ( event ) => event.preventDefault()
+					: undefined
+			}
 			target="_blank"
 			rel={ optimizedRel }
 			ref={ ref }

package/src/flex/flex/README.md

@@ -7,11 +7,7 @@
 `Flex` is used with any of it's two sub-components, `FlexItem` and `FlexBlock`.
 
 ```jsx
-import {
-	Flex,
-	FlexBlock,
-	FlexItem,
-} from '@wordpress/components';
+import { Flex, FlexBlock, FlexItem } from '@wordpress/components';
 
 function Example() {
 	return (
@@ -29,38 +25,44 @@ function Example() {
 
 ## Props
 
-##### align
-
-**Type**: `CSSProperties['alignItems']`
+### `align`: `CSSProperties['alignItems']`
 
 Aligns children using CSS Flexbox `align-items`. Vertically aligns content if the `direction` is `row`, or horizontally aligns content if the `direction` is `column`.
 
-##### direction
+-   Required: No
+-   Default: `center`
 
-**Type**: `[ResponsiveCSSValue<CSSProperties['flexDirection']>]`
+### `direction`: `ResponsiveCSSValue<CSSProperties['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
+-   Required: No
+-   Default: `row`
 
-**Type**: `[boolean]`
+### `expanded`: `boolean`
 
 Expands to the maximum available width (if horizontal) or height (if vertical).
 
-##### gap
+-   Required: No
+-   Default: `true`
 
-**Type**: `[number | string]`
+### `gap`: `number`
 
 Spacing in between each child can be adjusted by using `gap`. The value of `gap` works as a multiplier to the library's grid system (base of `4px`).
 
-##### justify
+-   Required: No
+-   Default: `2`
 
-**Type**: `[CSSProperties['justifyContent']]`
+##### `justify`: `CSSProperties['justifyContent']`
 
 Horizontally aligns content if the `direction` is `row`, or vertically aligns content if the `direction` is `column`.
 
-##### wrap
+-   Required: No
+-   Default: `space-between`
 
-**Type**: `[boolean]`
+##### `wrap`: `boolean`
 
 Determines if children should wrap.
+
+-   Required: No
+-   Default: `false`

package/src/flex/flex/component.tsx

@@ -0,0 +1,59 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { useFlex } from './hook';
+import { FlexContext } from './../context';
+import { View } from '../../view';
+import type { FlexProps } from '../types';
+
+function UnconnectedFlex(
+	props: WordPressComponentProps< FlexProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const { children, isColumn, ...otherProps } = useFlex( props );
+
+	return (
+		<FlexContext.Provider
+			value={ { flexItemDisplay: isColumn ? 'block' : undefined } }
+		>
+			<View { ...otherProps } ref={ forwardedRef }>
+				{ children }
+			</View>
+		</FlexContext.Provider>
+	);
+}
+
+/**
+ * `Flex` is a primitive layout component that adaptively aligns child content
+ * horizontally or vertically. `Flex` powers components like `HStack` and
+ * `VStack`.
+ *
+ * `Flex` is used with any of its two sub-components, `FlexItem` and
+ * `FlexBlock`.
+ *
+ * ```jsx
+ * import { Flex, FlexBlock, FlexItem } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Flex>
+ *       <FlexItem>
+ *         <p>Code</p>
+ *       </FlexItem>
+ *       <FlexBlock>
+ *         <p>Poetry</p>
+ *       </FlexBlock>
+ *     </Flex>
+ *   );
+ * }
+ * ```
+ */
+export const Flex = contextConnect( UnconnectedFlex, 'Flex' );
+
+export default Flex;