Components: promote g2 Popover as Flyout

docs/manifest.json

@@ -875,6 +875,12 @@
 		"markdown_source": "../packages/components/src/flex/flex/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "Flyout",
+		"slug": "flyout",
+		"markdown_source": "../packages/components/src/flyout/flyout/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "FocalPointPicker",
 		"slug": "focal-point-picker",

packages/components/src/flyout/context.js

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * @type {import('react').Context<import('./types').Context>}
+ */
+export const FlyoutContext = createContext( {} );
+export const useFlyoutContext = () => useContext( FlyoutContext );

packages/components/src/flyout/flyout-content/component.js

@@ -0,0 +1,53 @@
+/**
+ * Internal dependencies
+ */
+import { useFlyoutContext } from '../context';
+import { FlyoutContentView, CardView } from '../styles';
+import { contextConnect, useContextSystem } from '../../ui/context';
+
+/**
+ *
+ * @param {import('../../ui/context').PolymorphicComponentProps<import('../types').ContentProps, 'div', false>} props
+ * @param {import('react').Ref<any>}                                                                     forwardedRef
+ */
+function FlyoutContent( props, forwardedRef ) {
+	const {
+		children,
+		elevation,
+		maxWidth,
+		style = {},
+		...otherProps
+	} = useContextSystem( props, 'FlyoutContent' );
+
+	const { label, flyoutState } = useFlyoutContext();
+
+	if ( ! flyoutState ) {
+		throw new Error(
+			'`FlyoutContent` must only be used inside a `Flyout`.'
+		);
+	}
+
+	const showContent = flyoutState.visible || flyoutState.animating;
+
+	return (
+		<FlyoutContentView
+			aria-label={ label }
+			// maxWidth is applied via inline styles in order to avoid the `React does
+			// not recognize the maxWidth prop on a DOM element` error that comes from
+			// passing `maxWidth` as a prop to `FlyoutContentView`
+			style={ { maxWidth, ...style } }
+			{ ...otherProps }
+			{ ...flyoutState }
+		>
+			{ showContent && (
+				<CardView elevation={ elevation } ref={ forwardedRef }>
+					{ children }
+				</CardView>
+			) }
+		</FlyoutContentView>
+	);
+}
+
+const ConnectedFlyoutContent = contextConnect( FlyoutContent, 'FlyoutContent' );
+
+export default ConnectedFlyoutContent;

packages/components/src/flyout/flyout-content/index.js

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

packages/components/src/flyout/flyout/README.md

@@ -0,0 +1,98 @@
+# Flyout
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`Flyout` is a component to render a floating content modal. It is similar in purpose to a tooltip, but renders content of any sort, not only simple text.
+
+## Usage
+
+```jsx
+import { Button, __experimentalFlyout as Flyout, __experimentalText as } from '@wordpress/components';
+
+function Example() {
+	return (
+		<Flyout trigger={ <Button>Show/Hide content</Button> }>
+			<Text>Code is Poetry</Text>
+		</Flyout>
+	);
+}
+```
+
+## Props
+
+### `state`: `PopoverStateReturn`
+
+- Required: No
+
+### `label`: `string`
+
+- Required: No
+
+### `animated`: `boolean`
+
+Determines if `Flyout` has animations.
+
+- Required: No
+- Default: `true`
+
+### `animationDuration`: `boolean`
+
+The duration of `Flyout` animations.
+
+- Required: No
+- Default: `160`
+
+### `baseId`: `string`
+
+ID that will serve as a base for all the items IDs. See https://reakit.io/docs/popover/#usepopoverstate
+
+- Required: No
+- Default: `160`
+
+### `elevation`: `number`
+
+Size of the elevation shadow. For more information, check out [`Card`](/packages/components/src/card/card/README.md#props).
+
+- Required: No
+- Default: `5`
+
+### `maxWidth`: `CSSProperties[ 'maxWidth' ]`
+
+Max-width for the `Flyout` element.
+
+- Required: No
+- Default: `360`
+
+### `onVisibleChange`: `( ...args: any ) => void`
+
+Callback for when the `visible` state changes.
+
+- Required: No
+
+### `trigger`: `FunctionComponentElement< any >`
+
+Element that triggers the `visible` state of `Flyout` when clicked.
+
+```jsx
+<Flyout trigger={<Button>Greet</Button>}>
+	<Text>Hi! I'm Olaf!</Text>
+</Flyout>
+```
+
+- Required: Yes
+
+### `visible`: `boolean`
+
+Whether `Flyout` is visible. See [the `Reakit` docs](https://reakit.io/docs/popover/#usepopoverstate) for more information.
+
+- Required: No
+- Default: `false`
+
+### `placement`: `PopperPlacement`
+
+Position of the popover element. See [the `popper` docs](https://popper.js.org/docs/v1/#popperplacements--codeenumcode) for more information.
+
+- Required: No
+- Default: `auto`

packages/components/src/flyout/flyout/component.js

@@ -0,0 +1,111 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import { PopoverDisclosure, Portal } from 'reakit';
+
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useMemo, cloneElement } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect } from '../../ui/context';
+import { FlyoutContext } from '../context';
+import { useFlyoutResizeUpdater } from '../utils';
+import FlyoutContent from '../flyout-content';
+import { useUpdateEffect } from '../../utils/hooks';
+import { useFlyout } from './hook';
+
+/**
+ *
+ * @param {import('../../ui/context').PolymorphicComponentProps<import('../types').Props, 'div', false>} props
+ * @param {import('react').Ref<any>}                                                                     forwardedRef
+ */
+function Flyout( props, forwardedRef ) {
+	const {
+		children,
+		elevation,
+		label,
+		maxWidth,
+		onVisibleChange,
+		trigger,
+		flyoutState,
+		...otherProps
+	} = useFlyout( props );
+
+	const resizeListener = useFlyoutResizeUpdater( {
+		onResize: flyoutState.unstable_update,
+	} );
+
+	const uniqueId = `flyout-${ flyoutState.baseId }`;
+	const labelId = label || uniqueId;
+
+	const contextProps = useMemo(
+		() => ( {
+			label: labelId,
+			flyoutState,
+		} ),
+		[ labelId, flyoutState ]
+	);
+
+	const triggerContent = useCallback(
+		( triggerProps ) => {
+			return cloneElement( trigger, triggerProps );
+		},
+		[ trigger ]
+	);
+
+	useUpdateEffect( () => {
+		onVisibleChange?.( flyoutState.visible );
+	}, [ flyoutState.visible ] );
+
+	return (
+		<FlyoutContext.Provider value={ contextProps }>
+			{ trigger && (
+				<PopoverDisclosure
+					{ ...flyoutState }
+					ref={ trigger.ref }
+					{ ...trigger.props }
+				>
+					{ triggerContent }
+				</PopoverDisclosure>
+			) }
+			<Portal>
+				<FlyoutContent
+					ref={ forwardedRef }
+					{ ...otherProps }
+					elevation={ elevation }
+					maxWidth={ maxWidth }
+				>
+					{ resizeListener }
+					{ children }
+				</FlyoutContent>
+			</Portal>
+		</FlyoutContext.Provider>
+	);
+}
+
+/**
+ * `Flyout` is a component to render a floating content modal.
+ * It is similar in purpose to a tooltip, but renders content of any sort,
+ * not only simple text.
+ *
+ * @example
+ * ```jsx
+ * import { Button, __experimentalFlyout as Flyout, __experimentalText as } from '@wordpress/components';
+ *
+ * function Example() {
+ * 	return (
+ * 		<Flyout trigger={ <Button>Show/Hide content</Button> }>
+ *			<Text>Code is Poetry</Text>
+ * 		</Flyout>
+ * 	);
+ * }
+ * ```
+ */
+const ConnectedFlyout = contextConnect( Flyout, 'Flyout' );
+
+export default ConnectedFlyout;

packages/components/src/flyout/flyout/hook.js

@@ -0,0 +1,45 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import { usePopoverState } from 'reakit';
+
+/**
+ * Internal dependencies
+ */
+import { useContextSystem } from '../../ui/context';
+
+/**
+ * @param {import('../../ui/context').PolymorphicComponentProps<import('../types').Props, 'div', false>} props
+ */
+export function useFlyout( props ) {
+	const {
+		animated = true,
+		animationDuration = 160,
+		baseId,
+		elevation = 5,
+		id,
+		maxWidth = 360,
+		placement,
+		state,
+		visible,
+		...otherProps
+	} = useContextSystem( props, 'Flyout' );
+
+	const _flyoutState = usePopoverState( {
+		animated: animated ? animationDuration : undefined,
+		baseId: baseId || id,
+		placement,
+		visible,
+		...otherProps,
+	} );
+
+	const flyoutState = state || _flyoutState;
+
+	return {
+		...otherProps,
+		elevation,
+		maxWidth,
+		flyoutState,
+	};
+}

packages/components/src/flyout/flyout/index.js

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

packages/components/src/flyout/index.js

@@ -0,0 +1 @@
+export { default as Flyout } from './flyout';

packages/components/src/ui/popover/stories/index.js → packages/components/src/flyout/stories/index.js

@@ -1,24 +1,24 @@
 /**
  * Internal dependencies
  */
-import { CardBody, CardHeader } from '../../../card';
-import Button from '../../../button';
-import { Popover } from '..';
+import { CardBody, CardHeader } from '../../card';
+import Button from '../../button';
+import { Flyout } from '..';
 
 export default {
-	component: Popover,
-	title: 'G2 Components (Experimental)/Popover',
+	component: Flyout,
+	title: 'Components (Experimental)/Flyout',
 };
 
 export const _default = () => {
 	return (
-		<Popover
+		<Flyout
 			trigger={ <Button>Click</Button> }
 			visible
 			placement="bottom-start"
 		>
 			<CardHeader>Go</CardHeader>
 			<CardBody>Stuff</CardBody>
-		</Popover>
+		</Flyout>
 	);
 };