diff --git a/packages/block-editor/src/components/block-full-height-alignment-control/README.md b/packages/block-editor/src/components/block-full-height-alignment-control/README.md index 7189e59bf05d69..4f98c5a31e96a7 100644 --- a/packages/block-editor/src/components/block-full-height-alignment-control/README.md +++ b/packages/block-editor/src/components/block-full-height-alignment-control/README.md @@ -1,3 +1,55 @@ -# Full Height Toolbar Control +# Block Full Height Alignment Control -Unlike the block alignment options, `Full Height Alignment` can be applied to a block in an independent way. But also, it works very well together with these block alignment options, where the combination empowers the design-layout capability. +The Block Full Height Alignment Control allows users to toggle full height alignment for blocks. Unlike standard block alignment options, this control specifically manages the vertical height behavior of a block, making it span the full height of its container. + +## Development guidelines + +### Usage + +```jsx +import { BlockFullHeightAlignmentControl } from '@wordpress/block-editor'; +import { useState } from '@wordpress/element'; + +function MyBlockEdit() { + const [ isFullHeight, setIsFullHeight ] = useState( false ); + + return ( + + + + ); +} +``` + +### Props + +### `isActive` + +- **Type:** `boolean` +- **Default:** `false` + +Controls whether the full height alignment is currently active. + +### `label` + +- **Type:** `string` +- **Default:** `'Full height'` + +Label for the toolbar button. + +### `onToggle` + +- **Type:** `Function` +- **Default:** `undefined` + +Callback function triggered when the alignment is toggled. + +### `isDisabled` + +- **Type:** `boolean` +- **Default:** `false` + +Whether the control should be disabled. \ No newline at end of file diff --git a/packages/block-editor/src/components/block-full-height-alignment-control/index.js b/packages/block-editor/src/components/block-full-height-alignment-control/index.js index 00d908ce8b7e79..23188a2a4d9333 100644 --- a/packages/block-editor/src/components/block-full-height-alignment-control/index.js +++ b/packages/block-editor/src/components/block-full-height-alignment-control/index.js @@ -5,6 +5,33 @@ import { __ } from '@wordpress/i18n'; import { ToolbarButton } from '@wordpress/components'; import { fullscreen } from '@wordpress/icons'; +/** + * A toolbar control component that allows toggling full height alignment for blocks. + * + * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-full-height-alignment-control/README.md + * + * @example + * ```jsx + * function MyBlockEdit() { + * const [ isFullHeight, setIsFullHeight ] = useState( false ); + * return ( + * + * + * + * ); + * } + * ``` + * + * @param {Object} props Component props. + * @param {boolean} props.isActive Whether full height alignment is currently active. + * @param {string} props.label Label for the toolbar button. Defaults to "Full height". + * @param {Function} props.onToggle Callback function to handle the toggle state. + * @param {boolean} props.isDisabled Whether the control should be disabled. + * @return {Element} The BlockFullHeightAlignmentControl toolbar button. + */ function BlockFullHeightAlignmentControl( { isActive, label = __( 'Full height' ),