From 6347b67c8cf44a567f5cf4b2fb3321b3268d673e Mon Sep 17 00:00:00 2001 From: Andrew Serong <14988353+andrewserong@users.noreply.github.com> Date: Fri, 27 Jan 2023 11:49:47 +1100 Subject: [PATCH 1/3] HeightControl: Stabilise the height control component in the block editor package --- docs/how-to-guides/themes/theme-json.md | 12 +++- .../theme-json-reference/theme-json-living.md | 1 + packages/block-editor/README.md | 19 +++++++ .../src/components/height-control/README.md | 55 +++++++++++++++++++ .../src/components/height-control/index.js | 14 ++++- packages/block-editor/src/components/index.js | 2 +- .../global-styles/dimensions-panel.js | 2 +- schemas/json/theme.json | 2 +- 8 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 packages/block-editor/src/components/height-control/README.md diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index b6b102d9ffbb5..0003404df5d28 100644 --- 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 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": { diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index 913b012a3695f..118327a1f8b0d 100644 --- 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 index 7218886d4f394..b893a6a93e51f 100644 --- a/packages/block-editor/README.md +++ b/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_ + +- + +_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_ diff --git a/packages/block-editor/src/components/height-control/README.md b/packages/block-editor/src/components/height-control/README.md new file mode 100644 index 0000000000000..9f179abec6cbc --- /dev/null +++ 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(); + +); +``` + +### 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 index cc1eea0b4bad8..fe041013d55a0 100644 --- 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 index 3f392fa4ef199..4284f2d8d6f15 100644 --- 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/edit-site/src/components/global-styles/dimensions-panel.js b/packages/edit-site/src/components/global-styles/dimensions-panel.js index ed03c4c288a81..45ca502a70b1c 100644 --- 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 index 467ff5df53534..19a28657fa906 100644 --- 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 } From c308ef35d332545baaccec521e88cae445eaff55 Mon Sep 17 00:00:00 2001 From: Andrew Serong <14988353+andrewserong@users.noreply.github.com> Date: Mon, 30 Jan 2023 14:20:23 +1100 Subject: [PATCH 2/3] Fix typos in readme Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> --- docs/how-to-guides/themes/theme-json.md | 2 +- packages/block-editor/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to-guides/themes/theme-json.md b/docs/how-to-guides/themes/theme-json.md index 0003404df5d28..8e2b60a7693eb 100644 --- a/docs/how-to-guides/themes/theme-json.md +++ b/docs/how-to-guides/themes/theme-json.md @@ -359,7 +359,7 @@ 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)`. diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index b893a6a93e51f..2b6897c3c60df 100644 --- 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 @@ -757,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. From 54f7c118e400e62fa491c97dcd9adfe5ab926e25 Mon Sep 17 00:00:00 2001 From: Andrew Serong <14988353+andrewserong@users.noreply.github.com> Date: Mon, 30 Jan 2023 14:37:20 +1100 Subject: [PATCH 3/3] A couple more typo fixes to please the linter --- packages/block-editor/src/components/font-sizes/fluid-utils.js | 2 +- .../src/components/use-block-display-information/index.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/block-editor/src/components/font-sizes/fluid-utils.js b/packages/block-editor/src/components/font-sizes/fluid-utils.js index f5816e9823d7a..efcf443bb15cc 100644 --- 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/use-block-display-information/index.js b/packages/block-editor/src/components/use-block-display-information/index.js index e9b1e8865a05c..950cb9c905b24 100644 --- 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. *