Add <BoxModelOverlay> component

.eslintrc.js

@@ -26,8 +26,8 @@ const majorMinorRegExp =
  */
 const developmentFiles = [
 	'**/benchmark/**/*.js',
-	'**/@(__mocks__|__tests__|test)/**/*.js',
-	'**/@(storybook|stories)/**/*.js',
+	'**/@(__mocks__|__tests__|test)/**/*.[tj]s?(x)',
+	'**/@(storybook|stories)/**/*.[tj]s?(x)',
 	'packages/babel-preset-default/bin/**/*.js',
 ];
 

docs/manifest.json

@@ -629,6 +629,12 @@
 		"markdown_source": "../packages/components/src/box-control/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "BoxModelOverlay",
+		"slug": "box-model-overlay",
+		"markdown_source": "../packages/components/src/box-model-overlay/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "ButtonGroup",
 		"slug": "button-group",

packages/components/src/box-model-overlay/README.md

@@ -0,0 +1,139 @@
+# BoxModelOverlay
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`<BoxModelOverlay>` component shows a visual overlay of the [box model](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model) (currently only paddings and margins are available) on top of the target element. This is often accompanied by the `<BoxControl>` component to show a preview of the styling changes in the editor.
+
+## Usage
+
+Wrap `<YourComponent>` with `<BoxModelOverlay>` with the `showValues` prop.
+Note that `<YourComponent>` should accept `ref` for `<BoxModelOverlay>` to automatically inject into.
+
+```jsx
+import { __experimentalBoxModelOverlay as BoxModelOverlay } from '@wordpress/components';
+
+// Show all overlays and all sides.
+const showValues = {
+	margin: {
+		top: true,
+		right: true,
+		bottom: true,
+		left: true,
+	},
+	padding: {
+		top: true,
+		right: true,
+		bottom: true,
+		left: true,
+	},
+};
+
+const Example = () => {
+	return (
+		<BoxModelOverlay showValues={ showValues }>
+			<YourComponent />
+		</BoxModelOverlay>
+	);
+};
+```
+
+You can also use the `targetRef` prop to manually pass the ref to `<BoxModelOverlay>` for more advanced usage. This is useful if you need to control where the overlay is rendered or need special handling for the target's `ref`.
+
+```jsx
+const Example = () => {
+	const targetRef = useRef();
+
+	return (
+		<>
+			<YourComponent ref={ targetRef } />
+
+			<BoxModelOverlay
+				showValues={ showValues }
+				targetRef={ targetRef }
+			/>
+		</>
+	);
+};
+```
+
+`<BoxModelOverlay>` internally uses [`Popover`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/components/src/popover/README.md) to position the overlay. This means that you can use `<Popover.Slot>` to alternatively control where the overlay is rendered.
+
+```jsx
+const Example = () => {
+	return (
+		<>
+			<BoxModelOverlay showValues={ showValues }>
+				<YourComponent />
+			</BoxModelOverlay>
+
+			<Popover.Slot />
+		</>
+	);
+};
+```
+
+Here's an example of using it with `<BoxControl>`:
+
+```jsx
+const Example = () => {
+	const [ values, setValues ] = useState( {
+		top: '50px',
+		right: '10%',
+		bottom: '50px',
+		left: '10%',
+	} );
+	const [ showValues, setShowValues ] = useState( {} );
+
+	return (
+		<>
+			<BoxControl
+				label="Padding"
+				values={ values }
+				onChange={ ( nextValues ) => setValues( nextValues ) }
+				onChangeShowVisualizer={ setShowValues }
+			/>
+
+			<BoxModelOverlay showValues={ showValues }>
+				<div
+					style={ {
+						height: 300,
+						width: 300,
+						paddingTop: values.top,
+						paddingRight: values.right,
+						paddingBottom: values.bottom,
+						paddingLeft: values.left,
+					} }
+				/>
+			</BoxModelOverlay>
+		</>
+	);
+};
+```
+
+## Props
+
+Additional props not listed below will be passed to the underlying `Popover` component.
+
+### `showValues`
+
+Controls which overlays and sides are visible. Currently the only properties supported are `margin` and `padding`, each with four sides (`top`, `right`, `bottom`, `left`).
+
+- Type: `Object`
+- Required: Yes
+- Default: `{}`
+
+### `children`
+
+A single React element to rendered as the target. It should implicitly accept `ref` to be passed in.
+
+- Type: `React.ReactElement`
+- Required: Yes if `targetRef` is not passed
+
+### `targetRef`
+
+A ref object for the target element.
+
+- Type: `Ref<HTMLElement>`
+- Required: Yes if `children` is not passed