From 8c33c42dfa985c31f6c4f8431ce430280b954e37 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Fri, 10 Jan 2025 08:32:32 +0530 Subject: [PATCH 1/4] Block Editor: Add documentation for SpacingSizesControl component --- .../spacing-sizes-control/README.md | 113 ++++++++++++++++++ .../components/spacing-sizes-control/index.js | 39 ++++++ 2 files changed, 152 insertions(+) create mode 100644 packages/block-editor/src/components/spacing-sizes-control/README.md diff --git a/packages/block-editor/src/components/spacing-sizes-control/README.md b/packages/block-editor/src/components/spacing-sizes-control/README.md new file mode 100644 index 00000000000000..942d4b1d32e2af --- /dev/null +++ b/packages/block-editor/src/components/spacing-sizes-control/README.md @@ -0,0 +1,113 @@ +# Spacing Sizes Control + +The SpacingSizesControl component provides a user interface for controlling spacing values in blocks. It supports single, axial, and separated input controls for different spacing configurations. + +## Description + +The SpacingSizesControl component is a flexible control that allows users to modify spacing values for different sides of a block. It supports three viewing modes: + +1. Single: Control one side at a time +2. Axial: Control horizontal and vertical sides together +3. Custom: Control each side separately + +![Spacing Sizes Control](https://i.postimg.cc/3RkzzfL6/Screenshot-2025-01-10-at-8-07-55-AM.png) + +## Usage + +```js +import { + InspectorControls, + __experimentalSpacingSizesControl as SpacingSizesControl, +} from '@wordpress/block-editor'; +import { View } from '@wordpress/primitives'; +import { useCustomUnits } from '@wordpress/components'; + +const DimensionInput = ( { label, onChange, value = '' } ) => { + const availableUnits = [ 'px', 'em', 'rem', 'vw', 'vh' ]; + const units = useCustomUnits( { + availableUnits, + defaultValues: { px: 100, em: 10, rem: 10, vw: 10, vh: 25 }, + } ); + + const handleOnChange = ( unprocessedValue ) => { + onChange( unprocessedValue.all ); + }; + + return ( + + + + ); +}; +``` + +## Props + +### `inputProps` + +- Type: `Object` +- Required: No +- Description: Additional props to pass to the input controls. + +### `label` + +- Type: `String` +- Required: Yes +- Description: Label for the control (e.g., "Height"). + +### `minimumCustomValue` + +- Type: `Number` +- Default: 0 +- Description: Minimum value allowed for custom input. + +### `onChange` + +- Type: `Function` +- Required: Yes +- Description: Callback function called when spacing values change. Receives an object containing the updated values. + +### `onMouseOut` + +- Type: `Function` +- Required: No +- Description: Callback function called when mouse leaves the control. + +### `onMouseOver` + +- Type: `Function` +- Required: No +- Description: Callback function called when mouse enters the control. + +### `showSideInLabel` + +- Type: `Boolean` +- Default: true +- Description: Whether to show the side (top, right, etc.) in the control label. + +### `sides` + +- Type: `Array` +- Default: ALL_SIDES (top, right, bottom, left) +- Description: Array of sides that can be controlled. + +### `useSelect` + +- Type: `Boolean` +- Required: No +- Description: Whether to use a select control for predefined values. + +### `values` + +- Type: `Object` +- Required: No +- Description: Object containing the current spacing values for each side. diff --git a/packages/block-editor/src/components/spacing-sizes-control/index.js b/packages/block-editor/src/components/spacing-sizes-control/index.js index 458b0abee60f2e..81f0e84e32cddb 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/index.js +++ b/packages/block-editor/src/components/spacing-sizes-control/index.js @@ -25,6 +25,45 @@ import { getInitialView, } from './utils'; +/** + * A flexible control for managing spacing values in the block editor. Supports single, axial, + * and separated input controls for different spacing configurations with automatic view selection + * based on current values and available sides. + * + * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/spacing-sizes-control/README.md + * + * @example + * ```jsx + * function SpacerBlock() { + * return ( + * + * + * + * ); + * } + * ``` + * + * @param {Object} props Component props. + * @param {Object} props.inputProps Additional props for input controls. + * @param {string} props.label Label for the control. + * @param {number} props.minimumCustomValue Minimum value for custom input. + * @param {Function} props.onChange Called when spacing values change. + * @param {Function} props.onMouseOut Called when mouse leaves the control. + * @param {Function} props.onMouseOver Called when mouse enters the control. + * @param {boolean} props.showSideInLabel Show side in control label. + * @param {Array} props.sides Available sides for control. + * @param {boolean} props.useSelect Use select control for predefined values. + * @param {Object} props.values Current spacing values. + * @return {Element} Spacing sizes control component. + */ export default function SpacingSizesControl( { inputProps, label: labelProp, From 6eb4513ea8e6f98bc10038966fac928eca2b2435 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Tue, 21 Jan 2025 08:15:45 +0530 Subject: [PATCH 2/4] Refactor `SpacingSizesControl` to use individual side values --- .../src/components/spacing-sizes-control/README.md | 11 ++++++++--- .../src/components/spacing-sizes-control/index.js | 9 +++++++-- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/packages/block-editor/src/components/spacing-sizes-control/README.md b/packages/block-editor/src/components/spacing-sizes-control/README.md index 942d4b1d32e2af..7d63391b499e33 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/README.md +++ b/packages/block-editor/src/components/spacing-sizes-control/README.md @@ -29,14 +29,19 @@ const DimensionInput = ( { label, onChange, value = '' } ) => { defaultValues: { px: 100, em: 10, rem: 10, vw: 10, vh: 25 }, } ); - const handleOnChange = ( unprocessedValue ) => { - onChange( unprocessedValue.all ); + const handleOnChange = ( { top, right, bottom, left } ) => { + onChange( { top, right, bottom, left } ); }; return ( * Date: Mon, 27 Jan 2025 11:53:58 +0530 Subject: [PATCH 3/4] Simplify component example and documentation - Removed unnecessary props and wrappers - Added proper state management with useState hook - Ensured consistent documentation between the component and README - Replaced SpacerBlock with Example component - Added proper imports for SpacingSizesControl and useState - Removed unnecessary View wrapper and optional props - Updated README to match the new implementation --- .../spacing-sizes-control/README.md | 51 ++++++------------- .../components/spacing-sizes-control/index.js | 33 ++++++------ 2 files changed, 32 insertions(+), 52 deletions(-) diff --git a/packages/block-editor/src/components/spacing-sizes-control/README.md b/packages/block-editor/src/components/spacing-sizes-control/README.md index 7d63391b499e33..446b6d46a1e52a 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/README.md +++ b/packages/block-editor/src/components/spacing-sizes-control/README.md @@ -14,45 +14,26 @@ The SpacingSizesControl component is a flexible control that allows users to mod ## Usage -```js -import { - InspectorControls, - __experimentalSpacingSizesControl as SpacingSizesControl, -} from '@wordpress/block-editor'; -import { View } from '@wordpress/primitives'; -import { useCustomUnits } from '@wordpress/components'; - -const DimensionInput = ( { label, onChange, value = '' } ) => { - const availableUnits = [ 'px', 'em', 'rem', 'vw', 'vh' ]; - const units = useCustomUnits( { - availableUnits, - defaultValues: { px: 100, em: 10, rem: 10, vw: 10, vh: 25 }, +```jsx +import { SpacingSizesControl } from '@wordpress/block-editor'; +import { useState } from '@wordpress/element'; + +function Example() { + const [ sides, setSides ] = useState( { + top: '0px', + right: '0px', + bottom: '0px', + left: '0px', } ); - const handleOnChange = ( { top, right, bottom, left } ) => { - onChange( { top, right, bottom, left } ); - }; - return ( - - - + ); -}; +} ``` ## Props diff --git a/packages/block-editor/src/components/spacing-sizes-control/index.js b/packages/block-editor/src/components/spacing-sizes-control/index.js index c346e29f3f7bf2..30f0e305db917d 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/index.js +++ b/packages/block-editor/src/components/spacing-sizes-control/index.js @@ -34,24 +34,23 @@ import { * * @example * ```jsx - * function SpacerBlock() { + * import { SpacingSizesControl } from '@wordpress/block-editor'; + * import { useState } from '@wordpress/element'; + * + * function Example() { + * const [ sides, setSides ] = useState( { + * top: '0px', + * right: '0px', + * bottom: '0px', + * left: '0px', + * } ); + * * return ( - * - * - * + * * ); * } * ``` From 90d058ce56deb49e2442600a1217d93817c80a29 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Tue, 28 Jan 2025 11:16:35 +0530 Subject: [PATCH 4/4] Consolidate README and update import examples - Removed redundant description section in README - Consolidated component description into a single paragraph - Updated import examples to use `__experimentalSpacingSizesControl` alias - Removed screenshot reference - Standardized prop descriptions --- .../components/spacing-sizes-control/README.md | 18 ++++++------------ .../components/spacing-sizes-control/index.js | 2 +- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/packages/block-editor/src/components/spacing-sizes-control/README.md b/packages/block-editor/src/components/spacing-sizes-control/README.md index 446b6d46a1e52a..c8e280c6807120 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/README.md +++ b/packages/block-editor/src/components/spacing-sizes-control/README.md @@ -1,21 +1,15 @@ # Spacing Sizes Control -The SpacingSizesControl component provides a user interface for controlling spacing values in blocks. It supports single, axial, and separated input controls for different spacing configurations. +The SpacingSizesControl component provides a flexible user interface for controlling spacing values in blocks, allowing users to modify values for different sides. It supports three viewing modes: -## Description - -The SpacingSizesControl component is a flexible control that allows users to modify spacing values for different sides of a block. It supports three viewing modes: - -1. Single: Control one side at a time -2. Axial: Control horizontal and vertical sides together -3. Custom: Control each side separately - -![Spacing Sizes Control](https://i.postimg.cc/3RkzzfL6/Screenshot-2025-01-10-at-8-07-55-AM.png) +1. Single: Control one side at a time. +2. Axial: Control horizontal and vertical sides together. +3. Custom: Control each side separately. ## Usage ```jsx -import { SpacingSizesControl } from '@wordpress/block-editor'; +import { __experimentalSpacingSizesControl as SpacingSizesControl } from '@wordpress/block-editor'; import { useState } from '@wordpress/element'; function Example() { @@ -48,7 +42,7 @@ function Example() { - Type: `String` - Required: Yes -- Description: Label for the control (e.g., "Height"). +- Description: Label for the control. ### `minimumCustomValue` diff --git a/packages/block-editor/src/components/spacing-sizes-control/index.js b/packages/block-editor/src/components/spacing-sizes-control/index.js index 30f0e305db917d..5adbe5548556ff 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/index.js +++ b/packages/block-editor/src/components/spacing-sizes-control/index.js @@ -34,7 +34,7 @@ import { * * @example * ```jsx - * import { SpacingSizesControl } from '@wordpress/block-editor'; + * import { __experimentalSpacingSizesControl as SpacingSizesControl } from '@wordpress/block-editor'; * import { useState } from '@wordpress/element'; * * function Example() {