Add DimensionControl component

docs/manifest-devhub.json

@@ -641,6 +641,12 @@
 		"markdown_source": "../packages/components/src/date-time/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "DimensionControl",
+		"slug": "dimension-control",
+		"markdown_source": "../packages/components/src/dimension-control/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Disabled",
 		"slug": "disabled",

packages/components/src/dimension-control/README.md

@@ -0,0 +1,120 @@
+DimensionControl
+=============================
+
+`DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
+
+## Usage
+
+In a block's `edit` implementation, render a `<DimensionControl />` component. 
+
+
+```jsx
+import { registerBlockType } from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+import {
+	DimensionControl,
+} from '@wordpress/block-editor';
+
+registerBlockType( 'my-plugin/my-block', {
+	// ...
+
+	attributes: {
+		// other attributes here
+		// ...
+
+		paddingSize: {
+			type: 'string',
+		},
+	},
+
+	edit( { attributes, setAttributes, clientId } ) {
+
+		const { paddingSize } = attributes;
+
+
+		const updateSpacing = ( dimension, size, device = '' ) => {
+			setAttributes( {
+				[ `${ dimension }${ device }` ]: size,
+			} );
+		};
+
+		return (
+			<DimensionControl
+				label={ __( 'Padding' ) }
+				icon={ 'desktop' }
+				onChange={ partialRight( updateSpacing, 'paddingSize' ) }
+				value={ paddingSize }
+			/>
+		);
+	}
+} );
+```
+
+_Note:_ it is recommended to partially apply the value of the Block attribute to be updated (eg: `paddingSize`, `marginSize`...etc) to your callback functions. This avoids the need to unnecessarily couple the component to the Block attribute schema.
+
+_Note:_ by default, if you do not provide an initial `value` prop for the current dimension value, then no value will be selected (ie: there is no default dimension set). 
+
+## Props
+
+### `label`
+* **Type:** `String`
+* **Default:** `undefined`
+* **Required:** Yes
+
+The human readable label for the control. 
+
+### `value`
+* **Type:** `String`
+* **Default:** `''`
+* **Required:** No
+
+The current value of the dimension UI control. If provided the UI with automatically select the value.
+
+### `sizes`
+* **Type:** `Array`
+* **Default:** See `packages/block-editor/src/components/dimension-control/sizes.js`
+* **Required:** No
+
+An optional array of size objects in the following shape:
+
+```
+[
+	{
+		name: __( 'Small' ),
+		slug: 'small',
+	},
+		{
+		name: __( 'Medium' ),
+		slug: 'small',
+	},
+	// ...etc
+]
+```
+
+By default a set of relative sizes (`small`, `medium`...etc) are provided. See `packages/block-editor/src/components/dimension-control/sizes.js`.
+
+### `icon`
+* **Type:** `String`
+* **Default:** `undefined`
+* **Required:** No
+
+An optional dashicon to display before to the control label.
+
+### `onChange`
+* **Type:** `Function`
+* **Default:** `undefined`
+* **Required:** No
+* **Arguments:**:
+  - `size` - a string representing the selected size (eg: `medium`)
+
+A callback which is triggered when a spacing size value changes (is selected/clicked).
+
+
+### `className`
+* **Type:** `String`
+* **Default:** `''`
+* **Required:** No
+
+A string of classes to be added to the control component.
+
+

packages/components/src/dimension-control/index.js

@@ -0,0 +1,76 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import { isFunction } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+/**
+ * Internal dependencies
+ */
+import {
+	Icon,
+	SelectControl,
+} from '../';
+import { __ } from '@wordpress/i18n';
+
+import {
+	Fragment,
+} from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import sizesTable, { findSizeBySlug } from './sizes';
+
+export function DimensionControl( props ) {
+	const { label, value, sizes = sizesTable, icon, onChange, className = '' } = props;
+
+	const onChangeSpacingSize = ( val ) => {
+		const theSize = findSizeBySlug( sizes, val );
+
+		if ( ! theSize || value === theSize.slug ) {
+			onChange( undefined );
+		} else if ( isFunction( onChange ) ) {
+			onChange( theSize.slug );
+		}
+	};
+
+	const formatSizesAsOptions = ( theSizes ) => {
+		const options = theSizes.map( ( { name, slug } ) => ( {
+			label: name,
+			value: slug,
+		} ) );
+
+		return [ {
+			label: __( 'Default' ),
+			value: '',
+		} ].concat( options );
+	};
+
+	const selectLabel = (
+		<Fragment>
+			{ icon && (
+				<Icon
+					icon={ icon }
+				/>
+			) }
+			{ label }
+		</Fragment>
+	);
+
+	return (
+		<SelectControl
+			className={ classnames( className, 'block-editor-dimension-control' ) }
+			label={ selectLabel }
+			hideLabelFromVision={ false }
+			value={ value }
+			onChange={ onChangeSpacingSize }
+			options={ formatSizesAsOptions( sizes ) }
+		/>
+	);
+}
+
+export default DimensionControl;

packages/components/src/dimension-control/sizes.js

@@ -0,0 +1,45 @@
+/**
+ * Sizes
+ *
+ * defines the sizes used in dimension controls
+ * all hardcoded `size` values are based on the value of
+ * the Sass variable `$block-padding` from
+ * `packages/block-editor/src/components/dimension-control/sizes.js`.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Finds the correct size object from the provided sizes
+ * table by size slug (eg: `medium`)
+ *
+ * @param  {Array}  sizes containing objects for each size definition
+ * @param  {string} slug  a string representation of the size (eg: `medium`)
+ * @return {Object}       the matching size definition
+ */
+export const findSizeBySlug = ( sizes, slug ) => sizes.find( ( size ) => slug === size.slug );
+
+export default [
+	{
+		name: __( 'None' ),
+		slug: 'none',
+	},
+	{
+		name: __( 'Small' ),
+		slug: 'small',
+	},
+	{
+		name: __( 'Medium' ),
+		slug: 'medium',
+	},
+	{
+		name: __( 'Large' ),
+		slug: 'large',
+	}, {
+		name: __( 'Extra Large' ),
+		slug: 'xlarge',
+	},
+];

packages/components/src/dimension-control/style.scss

@@ -0,0 +1,22 @@
+.block-editor-dimension-control {
+
+	.components-base-control__field {
+		display: flex;
+		align-items: center;
+	}
+
+	.components-base-control__label {
+		display: flex;
+		align-items: center;
+		margin-right: 1em;
+		margin-bottom: 0;
+
+		.dashicon {
+			margin-right: 0.5em;
+		}
+	}
+
+	&.is-manual .components-base-control__label {
+		width: 10em;
+	}
+}