@wordpress/components 19.15.0 → 20.0.0

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

@@ -38,12 +38,22 @@ function UnforwardedExternalLink(
 		),
 	].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;

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * WordPress dependencies
@@ -12,18 +12,18 @@ import deprecated from '@wordpress/deprecated';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import { useResponsiveValue } from '../../ui/utils/use-responsive-value';
 import { space } from '../../ui/utils/space';
 import * as styles from '../styles';
 import { useCx, rtl } from '../../utils';
+import type { FlexProps } from '../types';
+
+function useDeprecatedProps(
+	props: WordPressComponentProps< FlexProps, 'div' >
+): WordPressComponentProps< FlexProps, 'div' > {
+	const { isReversed, ...otherProps } = props;
 
-/**
- *
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} props
- * @return {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} Props with the deprecated props removed.
- */
-function useDeprecatedProps( { isReversed, ...otherProps } ) {
 	if ( typeof isReversed !== 'undefined' ) {
 		deprecated( 'Flex isReversed', {
 			alternative: 'Flex direction="row-reverse" or "column-reverse"',
@@ -38,10 +38,7 @@ function useDeprecatedProps( { isReversed, ...otherProps } ) {
 	return otherProps;
 }
 
-/**
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} props
- */
-export function useFlex( props ) {
+export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 	const {
 		align = 'center',
 		className,
@@ -67,7 +64,11 @@ export function useFlex( props ) {
 	const rtlWatchResult = rtl.watch();
 
 	const classes = useMemo( () => {
-		const sx = {};
+		const sx: {
+			Base?: SerializedStyles;
+			Items?: SerializedStyles;
+			WrapItems?: SerializedStyles;
+		} = {};
 
 		sx.Base = css( {
 			alignItems: isColumn ? 'normal' : align,

package/src/flex/flex-block/README.md

@@ -1,9 +1,5 @@
 # FlexBlock
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 A layout component to contain items of a fixed width within `Flex`.
 
 ## Usage
@@ -12,8 +8,8 @@ See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for
 
 ## Props
 
-### display
-
-**Type**: `[CSSProperties['display']]`
+### `display`: `CSSProperties['display']`
 
 The CSS display property of `FlexBlock`.
+
+-   Required: No

package/src/flex/flex-block/component.tsx

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import type { FlexBlockProps } from '../types';
+import { useFlexBlock } from './hook';
+
+function UnconnectedFlexBlock(
+	props: WordPressComponentProps< FlexBlockProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const flexBlockProps = useFlexBlock( props );
+
+	return <View { ...flexBlockProps } ref={ forwardedRef } />;
+}
+
+/**
+ * `FlexBlock` is a primitive layout component that adaptively resizes content
+ * within layout containers like `Flex`.
+ *
+ * ```jsx
+ * import { Flex, FlexBlock } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Flex>
+ *       <FlexBlock>...</FlexBlock>
+ *     </Flex>
+ *   );
+ * }
+ * ```
+ */
+export const FlexBlock = contextConnect( UnconnectedFlexBlock, 'FlexBlock' );
+
+export default FlexBlock;

package/src/flex/flex-block/{hook.js → hook.ts}

@@ -1,13 +1,13 @@
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import { useFlexItem } from '../flex-item';
+import type { FlexBlockProps } from '../types';
 
-/**
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexBlockProps, 'div'>} props
- */
-export function useFlexBlock( props ) {
+export function useFlexBlock(
+	props: WordPressComponentProps< FlexBlockProps, 'div' >
+) {
 	const otherProps = useContextSystem( props, 'FlexBlock' );
 	const flexItemProps = useFlexItem( { isBlock: true, ...otherProps } );
 

package/src/flex/flex-item/README.md

@@ -1,9 +1,5 @@
 # FlexItem
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 A layout component to contain items of a fixed width within `Flex`.
 
 ## Usage
@@ -12,14 +8,15 @@ See [`flex/README.md#usage`](/packages/components/src/flex/flex/README.md#usage)
 
 ## Props
 
-### display
-
-**Type**: `[CSSProperties['display']]`
+### `display`: `CSSProperties['display']`
 
 The CSS display property of `FlexItem`.
 
-### isBlock
+-   Required: No
 
-**Type**: `[boolean]`
+### `isBlock`: `boolean`
 
 Determins if `FlexItem` should render as an adaptive full-width block.
+
+-   Required: No
+-   Default: `false`

package/src/flex/flex-item/component.tsx

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useFlexItem } from './hook';
+import type { FlexItemProps } from '../types';
+
+function UnconnectedFlexItem(
+	props: WordPressComponentProps< FlexItemProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const flexItemProps = useFlexItem( props );
+
+	return <View { ...flexItemProps } ref={ forwardedRef } />;
+}
+
+/**
+ * `FlexItem` is a primitive layout component that aligns content within layout
+ * containers like `Flex`.
+ *
+ * ```jsx
+ * import { Flex, FlexItem } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Flex>
+ *       <FlexItem>...</FlexItem>
+ *     </Flex>
+ *   );
+ * }
+ * ```
+ */
+export const FlexItem = contextConnect( UnconnectedFlexItem, 'FlexItem' );
+
+export default FlexItem;

package/src/flex/flex-item/{hook.js → hook.ts}

@@ -1,27 +1,30 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import { useFlexContext } from '../context';
 import * as styles from '../styles';
 import { useCx } from '../../utils/hooks/use-cx';
+import type { FlexItemProps } from '../types';
 
-/**
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexItemProps, 'div'>} props
- */
-export function useFlexItem( props ) {
+export function useFlexItem(
+	props: WordPressComponentProps< FlexItemProps, 'div' >
+) {
 	const {
 		className,
 		display: displayProp,
 		isBlock = false,
 		...otherProps
 	} = useContextSystem( props, 'FlexItem' );
-	const sx = {};
+
+	const sx: {
+		Base?: SerializedStyles;
+	} = {};
 
 	const contextDisplay = useFlexContext().flexItemDisplay;
 

package/src/flex/stories/index.tsx

@@ -0,0 +1,81 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Flex, FlexItem, FlexBlock } from '../';
+import { View } from '../../view';
+
+const meta: ComponentMeta< typeof Flex > = {
+	component: Flex,
+	title: 'Components/Flex',
+	subcomponents: { FlexBlock, FlexItem },
+	argTypes: {
+		align: { control: { type: 'text' } },
+		as: { control: { type: 'text' } },
+		children: { control: { type: null } },
+		gap: { control: { type: 'text' } },
+		justify: { control: { type: 'text' } },
+		// Disabled isReversed because it's deprecated.
+		isReversed: {
+			table: {
+				disable: true,
+			},
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const GrayBox = ( { children }: { children: string } ) => (
+	<View style={ { backgroundColor: '#eee', padding: 10 } }>{ children }</View>
+);
+
+export const Default: ComponentStory< typeof Flex > = ( { ...args } ) => {
+	return (
+		<Flex { ...args }>
+			<FlexItem>
+				<GrayBox>Item 1</GrayBox>
+			</FlexItem>
+			<FlexItem>
+				<GrayBox>Item 2</GrayBox>
+			</FlexItem>
+			<FlexItem>
+				<GrayBox>Item 3</GrayBox>
+			</FlexItem>
+		</Flex>
+	);
+};
+Default.args = {};
+
+export const ResponsiveDirection: ComponentStory< typeof Flex > = ( {
+	...args
+} ) => {
+	return (
+		<Flex { ...args }>
+			<FlexItem>
+				<GrayBox>Item 1</GrayBox>
+			</FlexItem>
+			<FlexBlock>
+				<GrayBox>Item 2</GrayBox>
+			</FlexBlock>
+			<FlexItem>
+				<GrayBox>Item 3</GrayBox>
+			</FlexItem>
+			<FlexItem>
+				<GrayBox>Item 4</GrayBox>
+			</FlexItem>
+		</Flex>
+	);
+};
+ResponsiveDirection.args = {
+	direction: [ 'column', 'row' ],
+};

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

@@ -5,21 +5,30 @@ Snapshot Diff:
 - First value
 + Second value
 
-@@ -7,14 +7,10 @@
+@@ -1,22 +1,18 @@
+  <div
+    class="components-flex css-1giw1wa-View-Flex-sx-Base-sx-Items-ItemsRow em57xhy0"
+-   data-testid="flex"
++   data-testid="base-flex"
+    data-wp-c16t="true"
+    data-wp-component="Flex"
+  >
+    <div
       class="components-flex-item css-mw3lhz-View-Item-sx-Base em57xhy0"
       data-wp-c16t="true"
       data-wp-component="FlexItem"
-    />
-    <div
+    >
+      Item
+    </div>
+-   <div
 -     class="css-1mm2cvy-View em57xhy0"
 -   />
 -   <div />
--   <div
+    <div
       class="components-flex-item components-flex-block css-14wzr73-View-Item-sx-Base-block em57xhy0"
       data-wp-c16t="true"
       data-wp-component="FlexBlock"
-    />
-  </div>
+    >
 `;
 
 exports[`props should render align 1`] = `
@@ -97,6 +106,7 @@ exports[`props should render correctly 1`] = `
 
 <div
   class="components-flex emotion-0 emotion-1"
+  data-testid="base-flex"
   data-wp-c16t="true"
   data-wp-component="Flex"
 >
@@ -104,12 +114,16 @@ exports[`props should render correctly 1`] = `
     class="components-flex-item emotion-2 emotion-1"
     data-wp-c16t="true"
     data-wp-component="FlexItem"
-  />
+  >
+    Item
+  </div>
   <div
     class="components-flex-item components-flex-block emotion-4 emotion-1"
     data-wp-c16t="true"
     data-wp-component="FlexBlock"
-  />
+  >
+    Item
+  </div>
 </div>
 `;
 
@@ -142,5 +156,31 @@ Snapshot Diff:
 
 exports[`props should render spacing 1`] = `
 Snapshot Diff:
-Compared values have no visual difference.
+- Received styles
++ Base styles
+
+  Array [
+    Object {
+-     "margin-left": "calc(4px * 2)",
+-   },
+-   Object {
+-     "min-width": "0",
+-   },
+-   Object {
+      "-ms-flex": "1",
+      "-webkit-flex": "1",
+      "display": "block",
+      "flex": "1",
+      "max-height": "100%",
+      "max-width": "100%",
+      "min-height": "0",
++     "min-width": "0",
++   },
++   Object {
++     "margin-left": "calc(4px * 5)",
++   },
++   Object {
+      "min-width": "0",
+    },
+  ]
 `;