components: Promote ui/Flex and deprecate isReversed prop (#31297)

* components: Promote ui/Flex and deprecate `isReversed` prop

* Fix various imports

* Update packages/components/CHANGELOG.md

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

* Update packages/components/src/flex/README.md

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

* Reorganize files and add more READMEs

* Use absolute paths to other READMEs

* Update README.md

* Apply suggestions from code review

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

Author: sarayourfriend

docs/manifest.json

@@ -779,10 +779,22 @@
 		"markdown_source": "../packages/components/src/external-link/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "FlexBlock",
+		"slug": "flex-block",
+		"markdown_source": "../packages/components/src/flex/flex-block/README.md",
+		"parent": "components"
+	},
+	{
+		"title": "FlexItem",
+		"slug": "flex-item",
+		"markdown_source": "../packages/components/src/flex/flex-item/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Flex",
 		"slug": "flex",
-		"markdown_source": "../packages/components/src/flex/README.md",
+		"markdown_source": "../packages/components/src/flex/flex/README.md",
 		"parent": "components"
 	},
 	{

packages/components/CHANGELOG.md

@@ -7,6 +7,14 @@
 -   Drop support for Internet Explorer 11 ([#31110](https://github.com/WordPress/gutenberg/pull/31110)). Learn more at https://make.wordpress.org/core/2021/04/22/ie-11-support-phase-out-plan/.
 -   Increase the minimum Node.js version to v12 matching Long Term Support releases ([#31270](https://github.com/WordPress/gutenberg/pull/31270)). Learn more at https://nodejs.org/en/about/releases/.
 
+### Deprecation
+
+-   `isReversed` prop in `Flex` component has been deprecated. Use `direction` instead ([#31297](https://github.com/WordPress/gutenberg/pull/31297)).
+
+### Internal
+
+-   `Flex`, `FlexBlock`, and `FlexItem` components have been re-written from the ground up ([#31297](https://github.com/WordPress/gutenberg/pull/31297)).
+
 ## 13.0.0 (2021-03-17)
 
 ### Breaking Change

packages/components/src/card/styles/card-styles.js

@@ -11,7 +11,7 @@ import { HorizontalRule } from '@wordpress/primitives';
 /**
  * Internal dependencies
  */
-import Flex from '../../flex';
+import { Flex } from '../../flex';
 import { color, space } from '../../utils/style-mixins';
 
 export const styleProps = {

packages/components/src/flex/README.md

@@ -0,0 +1,15 @@
+# FlexBlock (Experimental)
+
+A layout component to contain items of a fixed width within `Flex`.
+
+## Usage
+
+See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for how to use `FlexBlock`.
+
+## Props
+
+### display
+
+**Type**: `[CSSProperties['display']]`
+
+The CSS display property of `FlexBlock`.

packages/components/src/flex/block.js

@@ -1,8 +1,8 @@
 /**
  * Internal dependencies
  */
-import { createComponent } from '../utils';
-import { useFlexBlock } from './use-flex-block';
+import { createComponent } from '../../ui/utils';
+import { useFlexBlock } from './hook';
 
 /**
  * `FlexBlock` is a primitive layout component that adaptively resizes content within layout containers like `Flex`.

packages/components/src/ui/flex/context.ts packages/components/src/flex/context.ts

@@ -1,11 +1,11 @@
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../context';
-import { useFlexItem } from './use-flex-item';
+import { useContextSystem } from '../../ui/context';
+import { useFlexItem } from '../flex-item';
 
 /**
- * @param {import('../context').ViewOwnProps<import('./types').FlexBlockProps, 'div'>} props
+ * @param {import('../../ui/context').ViewOwnProps<import('../types').FlexBlockProps, 'div'>} props
  */
 export function useFlexBlock( props ) {
 	const otherProps = useContextSystem( props, 'FlexBlock' );

packages/components/src/flex/flex-block/README.md

@@ -0,0 +1,2 @@
+export { default } from './component';
+export { useFlexBlock } from './hook';

packages/components/src/ui/flex/flex-block.js packages/components/src/flex/flex-block/component.js

@@ -0,0 +1,21 @@
+# FlexItem (Experimental)
+
+A layout component to contain items of a fixed width within `Flex`.
+
+## Usage
+
+See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for how to use `FlexItem`.
+
+## Props
+
+### display
+
+**Type**: `[CSSProperties['display']]`
+
+The CSS display property of `FlexItem`.
+
+### isBlock
+
+**Type**: `[boolean]`
+
+Determins if `FlexItem` should render as an adaptive full-width block.

packages/components/src/ui/flex/use-flex-block.js packages/components/src/flex/flex-block/hook.js

@@ -1,8 +1,8 @@
 /**
  * Internal dependencies
  */
-import { createComponent } from '../utils';
-import { useFlexItem } from './use-flex-item';
+import { createComponent } from '../../ui/utils';
+import { useFlexItem } from './hook';
 
 /**
  * `FlexItem` is a primitive layout component that aligns content within layout containers like `Flex`.

packages/components/src/flex/flex-block/index.js

@@ -6,12 +6,12 @@ import { css, cx } from 'emotion';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../context';
-import { useFlexContext } from './context';
-import * as styles from './styles';
+import { useContextSystem } from '../../ui/context';
+import { useFlexContext } from '../context';
+import * as styles from '../styles';
 
 /**
- * @param {import('../context').ViewOwnProps<import('./types').FlexItemProps, 'div'>} props
+ * @param {import('../../ui/context').ViewOwnProps<import('../types').FlexItemProps, 'div'>} props
  */
 export function useFlexItem( props ) {
 	const {

packages/components/src/flex/flex-item/README.md

@@ -0,0 +1,2 @@
+export { default } from './component';
+export { useFlexItem } from './hook';

packages/components/src/ui/flex/flex-item.js packages/components/src/flex/flex-item/component.js

@@ -1,4 +1,4 @@
-# Flex
+# Flex (Experimental)
 
 `Flex` is a primitive layout component that adaptively aligns child content horizontally or vertically. `Flex` powers components like `HStack` and `VStack`.
 
@@ -7,7 +7,12 @@
 `Flex` is used with any of it's two sub-components, `FlexItem` and `FlexBlock`.
 
 ```jsx
-import { Flex, FlexItem, FlexBlock, Text } from '@wordpress/components/ui';
+import {
+	__experimentalFlex as Flex,
+	__experimentalFlexBlock as FlexBlock,
+	__experimentalFlexItem as FlexItem,
+	__experimentalText as Text
+} from '@wordpress/components';
 
 function Example() {
 	return (
@@ -27,39 +32,39 @@ function Example() {
 
 ##### align
 
-**Type**: `CSS['alignItems']`
+**Type**: `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`.
 
 In the example below, `flex-start` will align the children content to the top.
 
 ##### direction
 
-**Type**: `FlexDirection`
+**Type**: `[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
 
-**Type**: `boolean`
+**Type**: `[boolean]`
 
 Expands to the maximum available width (if horizontal) or height (if vertical).
 
 ##### gap
 
-**Type**: `number`
+**Type**: `[number | string]`
 
 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
 
-**Type**: `CSS['justifyContent']`
+**Type**: `[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.
 
 ##### wrap
 
-**Type**: `boolean`
+**Type**: `[boolean]`
 
 Determines if children should wrap.

packages/components/src/ui/flex/use-flex-item.js packages/components/src/flex/flex-item/hook.js

@@ -1,13 +1,13 @@
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../context';
-import { useFlex } from './use-flex';
-import { FlexContext } from './context';
-import { View } from '../view';
+import { contextConnect } from '../../ui/context';
+import { useFlex } from './hook';
+import { FlexContext } from './../context';
+import { View } from '../../ui/view';
 
 /**
- * @param {import('../context').ViewOwnProps<import('./types').FlexProps, 'div'>} props
+ * @param {import('../../ui/context').ViewOwnProps<import('../types').FlexProps, 'div'>} props
  * @param {import('react').Ref<any>} forwardedRef
  */
 function Flex( props, forwardedRef ) {