From 73b8e2cbda0e457584e9e1a5c13cd81d9bdc0825 Mon Sep 17 00:00:00 2001 From: Ankit Kumar Shah Date: Wed, 29 Jan 2025 09:15:19 +0530 Subject: [PATCH] Block Editor: Add documentation for SpacingSizesControl component (#68581) * Block Editor: Add documentation for SpacingSizesControl component * Refactor `SpacingSizesControl` to use individual side values * 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 * 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 Co-authored-by: Infinite-Null Co-authored-by: stokesman Co-authored-by: glendaviesnz Co-authored-by: mburridge --- .../spacing-sizes-control/README.md | 93 +++++++++++++++++++ .../components/spacing-sizes-control/index.js | 45 ++++++++- 2 files changed, 137 insertions(+), 1 deletion(-) 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 0000000000000..c8e280c680712 --- /dev/null +++ b/packages/block-editor/src/components/spacing-sizes-control/README.md @@ -0,0 +1,93 @@ +# Spacing Sizes Control + +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: + +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 { __experimentalSpacingSizesControl as 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 ( + + ); +} +``` + +## 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. + +### `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 458b0abee60f2..5adbe5548556f 100644 --- a/packages/block-editor/src/components/spacing-sizes-control/index.js +++ b/packages/block-editor/src/components/spacing-sizes-control/index.js @@ -12,11 +12,11 @@ import { _x, sprintf } from '@wordpress/i18n'; /** * Internal dependencies */ +import useSpacingSizes from './hooks/use-spacing-sizes'; import AxialInputControls from './input-controls/axial'; import SeparatedInputControls from './input-controls/separated'; import SingleInputControl from './input-controls/single'; import LinkedButton from './linked-button'; -import useSpacingSizes from './hooks/use-spacing-sizes'; import { ALL_SIDES, DEFAULT_VALUES, @@ -25,6 +25,49 @@ 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 + * import { __experimentalSpacingSizesControl as 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 ( + * + * ); + * } + * ``` + * + * @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,