Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/how-to-guides/themes/theme-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,9 @@ The settings section has the following structure:
"text": true
},
"custom": {},
"dimensions": {
"minHeight": false,
},
"layout": {
"contentSize": "800px",
"wideSize": "1000px"
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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"
},
Expand Down Expand Up @@ -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": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
23 changes: 21 additions & 2 deletions packages/block-editor/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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_
Expand Down Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 55 additions & 0 deletions packages/block-editor/src/components/height-control/README.md
Original file line number Diff line number Diff line change
@@ -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.
14 changes: 13 additions & 1 deletion packages/block-editor/src/components/height-control/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down
2 changes: 1 addition & 1 deletion packages/block-editor/src/components/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
2 changes: 1 addition & 1 deletion schemas/json/theme.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down