HeightControl: Stabilise the height control component in the block editor package

docs/how-to-guides/themes/theme-json.md

@@ -257,6 +257,9 @@ The settings section has the following structure:
 			"text": true
 		},
 		"custom": {},
+		"dimensions": {
+			"minHeight": false,
+		},
 		"layout": {
 			"contentSize": "800px",
 			"wideSize": "1000px"
@@ -317,6 +320,7 @@ There's one special setting property, `appearanceTools`, which is a boolean and
 
 - border: color, radius, style, width
 - color: link
+- dimensions: minHeight
 - spacing: blockGap, margin, padding
 - typography: lineHeight
 
@@ -355,10 +359,10 @@ The following presets can be defined via `theme.json`:
     - `steps`: the number of steps to generate in the spacing scale. The default is 7. To prevent the generation of the spacing presets, and to disable the related UI, this can be set to `0`.
     - `mediumStep`: the steps in the scale are generated descending and ascending from a medium step, so this should be the size value of the medium space, without the unit. The default medium step is `1.5rem` so the mediumStep value is `1.5`.
     - `unit`: the unit the scale uses, eg. `px, rem, em, %`. The default is `rem`.
-- `spacing.spacingSizes`: themes can choose to include a static `spacing.spacingSizes` array of spacing preset sizes if they have a sequence of sizes that can't be generated via an increment or mulitplier. 
+- `spacing.spacingSizes`: themes can choose to include a static `spacing.spacingSizes` array of spacing preset sizes if they have a sequence of sizes that can't be generated via an increment or mulitplier.
     - `name`: a human readable name for the size, eg. `Small, Medium, Large`.
     - `slug`: the machine readable name. In order to provide the best cross site/theme compatibility the slugs should be in the format, "10","20","30","40","50","60", with "50" representing the `Medium` size value.
-    - `size`: the size, including the unit, eg. `1.5rem`. It is possible to include fluid values like `clamp(2rem, 10vw, 20rem)`. 
+    - `size`: the size, including the unit, eg. `1.5rem`. It is possible to include fluid values like `clamp(2rem, 10vw, 20rem)`.
 - `typography.fontSizes`: generates a single class and custom property per preset value.
 - `typography.fontFamilies`: generates a single custom property per preset value.
 
@@ -792,6 +796,9 @@ Each block declares which style properties it exposes via the [block supports me
 			"gradient": "value",
 			"text": "value"
 		},
+		"dimensions": {
+			"minHeight": "value"
+		},
 		"filter": {
 			"duotone": "value"
 		},
@@ -841,6 +848,7 @@ Each block declares which style properties it exposes via the [block supports me
 			"core/group": {
 				"border": {},
 				"color": {},
+				"dimensions": {},
 				"spacing": {},
 				"typography": {},
 				"elements": {

docs/reference-guides/theme-json-reference/theme-json-living.md

@@ -22,6 +22,7 @@ Setting that enables the following UI tools:
 
 - border: color, radius, style, width
 - color: link
+- dimensions: minHeight
 - spacing: blockGap, margin, padding
 - typography: lineHeight
 

packages/block-editor/README.md

@@ -531,6 +531,25 @@ _Returns_
 
 -   `Object`: Typography block support derived CSS classes & styles.
 
+### HeightControl
+
+HeightControl renders a linked unit control and range control for adjusting the height of a block.
+
+_Related_
+
+-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/height-control/README.md>
+
+_Parameters_
+
+-   _props_ `Object`:
+-   _props.label_ `?string`: A label for the control.
+-   _props.onChange_ `( value: string ) => void`: Called when the height changes.
+-   _props.value_ `string`: The current height value.
+
+_Returns_
+
+-   `WPComponent`: The component to be rendered.
+
 ### InnerBlocks
 
 _Related_

packages/block-editor/src/components/height-control/README.md

@@ -0,0 +1,55 @@
+# Height Control
+
+The `HeightControl` component adds a linked unit control and slider component for controlling the height of a block within the block editor. It supports passing a label, and is used for controlling the minimum height dimensions of Group blocks.
+
+_Note:_ It is worth noting that the minimum height option is an opt-in feature. Themes need to declare support for it before it'll be available, and a convenient way to do that is via opting in to the [appearanceTools](/docs/how-to-guides/themes/theme-json/#opt-in-into-ui-controls) UI controls.
+
+## Table of contents
+
+1. [Development guidelines](#development-guidelines)
+2. [Related components](#related-components)
+
+## Development guidelines
+
+### Usage
+
+Renders the markup for height control component, to be used in the block inspector.
+
+```jsx
+import { HeightControl } from '@wordpress/block-editor';
+import { useState } from '@wordpress/element';
+
+const MyLineHeightControl = () => (
+	const [ value, setValue ] = useState();
+	<HeightControl
+		label={ 'My Height Control' }
+		onChange={ setValue }
+		value={ value }
+	/>
+);
+```
+
+### Props
+
+#### `value`
+
+-   **Type:** `String` or `Number` or `Undefined`
+
+The value of the current height.
+
+#### `onChange`
+
+-   **Type:** `Function`
+
+A callback function that handles the application of the height value.
+
+#### `label`
+
+-   **Type:** `String`
+-   **Default:** `'Height'`
+
+A label for the height control. This is useful when using the height control for a feature that is controlled in the same way as height, but requires a different label. For example, "Min. height".
+
+## Related components
+
+Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [`BlockEditorProvider`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree.

packages/block-editor/src/components/height-control/index.js

@@ -28,9 +28,21 @@ const RANGE_CONTROL_CUSTOM_SETTINGS = {
 	rem: { max: 50, step: 0.1 },
 };
 
+/**
+ * HeightControl renders a linked unit control and range control for adjusting the height of a block.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/height-control/README.md
+ *
+ * @param {Object}                     props
+ * @param {?string}                    props.label    A label for the control.
+ * @param {( value: string ) => void } props.onChange Called when the height changes.
+ * @param {string}                     props.value    The current height value.
+ *
+ * @return {WPComponent} The component to be rendered.
+ */
 export default function HeightControl( {
-	onChange,
 	label = __( 'Height' ),
+	onChange,
 	value,
 } ) {
 	const customRangeValue = parseFloat( value );

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

@@ -53,7 +53,7 @@ export { default as __experimentalColorGradientControl } from './colors-gradient
 export { default as __experimentalColorGradientSettingsDropdown } from './colors-gradients/dropdown';
 export { default as __experimentalPanelColorGradientSettings } from './colors-gradients/panel-color-gradient-settings';
 export { default as __experimentalUseMultipleOriginColorsAndGradients } from './colors-gradients/use-multiple-origin-colors-and-gradients';
-export { default as __experimentalHeightControl } from './height-control';
+export { default as HeightControl } from './height-control';
 export { default as __experimentalImageEditor } from './image-editor';
 export { default as __experimentalImageSizeControl } from './image-size-control';
 export { default as InnerBlocks, useInnerBlocksProps } from './inner-blocks';

packages/edit-site/src/components/global-styles/dimensions-panel.js

@@ -18,7 +18,7 @@ import {
 } from '@wordpress/components';
 import {
 	__experimentalUseCustomSides as useCustomSides,
-	__experimentalHeightControl as HeightControl,
+	HeightControl,
 	__experimentalSpacingSizesControl as SpacingSizesControl,
 	experiments as blockEditorExperiments,
 } from '@wordpress/block-editor';

schemas/json/theme.json

@@ -20,7 +20,7 @@
 			"type": "object",
 			"properties": {
 				"appearanceTools": {
-					"description": "Setting that enables the following UI tools:\n\n- border: color, radius, style, width\n- color: link\n- spacing: blockGap, margin, padding\n- typography: lineHeight",
+					"description": "Setting that enables the following UI tools:\n\n- border: color, radius, style, width\n- color: link\n- dimensions: minHeight\n- spacing: blockGap, margin, padding\n- typography: lineHeight",
 					"type": "boolean",
 					"default": false
 				}