Block Editor: Add documentation for SpacingSizesControl component (#6…

…8581)

* 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 <[email protected]>
Co-authored-by: stokesman <[email protected]>
Co-authored-by: glendaviesnz <[email protected]>
Co-authored-by: mburridge <[email protected]>

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 (
+		<SpacingSizesControl
+			values={ sides }
+			onChange={ setSides }
+			label="Sides"
+		/>
+	);
+}
+```
+
+## 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.

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 (
+ *     <SpacingSizesControl
+ *       values={ sides }
+ *       onChange={ setSides }
+ *       label="Sides"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @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,