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,