HeightControl: Stabilise the height control component in the block ed…

…itor package (#47475) * HeightControl: Stabilise the height control component in the block editor package * Fix typos in readme Co-authored-by: Aaron Robertshaw <[email protected]> * A couple more typo fixes to please the linter --------- Co-authored-by: Aaron Robertshaw <[email protected]>
WordPress · Jan 31, 2023 · 79dfbe7 · 79dfbe7 · github-actions · Jan 31, 2023
1 parent 46a5545
commit 79dfbe7
Show file tree

Hide file tree

Showing 10 changed files with 105 additions and 10 deletions.
diff --git a/docs/how-to-guides/themes/theme-json.md b/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 multiplier.
     - `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": {

diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/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
 

diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md
@@ -401,7 +401,7 @@ _Returns_
 
 ### getComputedFluidTypographyValue
 
-Computes a fluid font-size value that uses clamp(). A minimum and maxinmum
+Computes a fluid font-size value that uses clamp(). A minimum and maximum
 font size OR a single font size can be specified.
 
 If a single font size is specified, it is scaled up and down by
@@ -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_
@@ -738,7 +757,7 @@ to try to find a match we need to things:
 1\. Block's client id to extract it's current attributes.
 2\. A block variation should have set `isActive` prop to a proper function.
 
-If for any reason a block variaton match cannot be found,
+If for any reason a block variation match cannot be found,
 the returned information come from the Block Type.
 If no blockType is found with the provided clientId, returns null.
 

diff --git a/packages/block-editor/src/components/font-sizes/fluid-utils.js b/packages/block-editor/src/components/font-sizes/fluid-utils.js
@@ -12,7 +12,7 @@ const DEFAULT_MINIMUM_FONT_SIZE_FACTOR = 0.75;
 const DEFAULT_MINIMUM_FONT_SIZE_LIMIT = '14px';
 
 /**
- * Computes a fluid font-size value that uses clamp(). A minimum and maxinmum
+ * Computes a fluid font-size value that uses clamp(). A minimum and maximum
  * font size OR a single font size can be specified.
  *
  * If a single font size is specified, it is scaled up and down by

diff --git a/packages/block-editor/src/components/height-control/README.md b/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.
diff --git a/packages/block-editor/src/components/height-control/index.js b/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 );

diff --git a/packages/block-editor/src/components/index.js b/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';

diff --git a/packages/block-editor/src/components/use-block-display-information/index.js b/packages/block-editor/src/components/use-block-display-information/index.js
@@ -34,7 +34,7 @@ import { store as blockEditorStore } from '../../store';
  * 1. Block's client id to extract it's current attributes.
  * 2. A block variation should have set `isActive` prop to a proper function.
  *
- * If for any reason a block variaton match cannot be found,
+ * If for any reason a block variation match cannot be found,
  * the returned information come from the Block Type.
  * If no blockType is found with the provided clientId, returns null.
  *

diff --git a/packages/edit-site/src/components/global-styles/dimensions-panel.js b/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';

diff --git a/schemas/json/theme.json b/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
 				}