From d59728d1a82cb52dbacddb51bca56c88badb1637 Mon Sep 17 00:00:00 2001
From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Date: Fri, 22 Jul 2022 12:48:18 +1000
Subject: [PATCH 1/2] Add a readme section related to laying out a ToolsPanel

This also includes updating the usage example to better illustrate layout.
---
 .../src/tools-panel/tools-panel/README.md     | 115 ++++++++++++++----
 1 file changed, 94 insertions(+), 21 deletions(-)

diff --git a/packages/components/src/tools-panel/tools-panel/README.md b/packages/components/src/tools-panel/tools-panel/README.md
index 23581f90d7546..9b75f32f6645e 100644
--- a/packages/components/src/tools-panel/tools-panel/README.md
+++ b/packages/components/src/tools-panel/tools-panel/README.md
@@ -30,45 +30,118 @@ however they will not be represented within, or controlled by, the `ToolsPanel`
 menu. An example scenario that benefits from this could be displaying
 introduction or help text within a panel.
 
+### ToolsPanel Layout
+
+The `ToolsPanel` has a two-column grid layout. By default, `ToolsPanelItem`
+components within the panel are styled to span both columns as this fits the
+majority of use-cases. Most non-control elements, such as help text, will be
+rendered as children of the related control's `ToolsPanelItem` and not require
+additional styling.
+
+Suppose an element is related to multiple controls (e.g. a contrast checker), or
+the panel itself (e.g. a panel description). In that case, these will be
+rendered into the panel without a wrapping `ToolsPanelItem`. They'll then only
+span a single column by default. If this is undesirable, those elements will
+likely need a small style tweak, e.g. `grid-column: 1 / -1;`
+
+The usage example below will illustrate a non-`ToolsPanelItem` description
+paragraph, controls that should display in a single row, and others spanning
+both columns.
+
 ## Usage
 
 ```jsx
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+
+/**
+ * WordPress dependencies
+ */
 import {
+	__experimentalBoxControl as BoxControl,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
+	__experimentalUnitControl as UnitControl,
 } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
-import {
-	PaddingEdit,
-	hasPaddingValue,
-	resetPadding,
-	useIsPaddingDisabled,
-} from './padding';
+const PanelDescription = styled.div`
+	grid-column: span 2;
+`;
 
+const SingleColumnItem = styled( ToolsPanelItem )`
+	grid-column: span 1;
+`;
 
-export function DimensionPanel( props ) {
-	const isPaddingDisabled = useIsPaddingDisabled( props );
+export function DimensionPanel() {
+	const [ height, setHeight ] = useState();
+	const [ width, setWidth ] = useState();
+	const [ padding, setPadding ] = useState();
+	const [ margin, setMargin ] = useState();
 
 	const resetAll = () => {
-		// Reset attributes for all block support features in this panel.
+		setHeight( undefined );
+		setWidth( undefined );
+		setPadding( undefined );
+		setMargin( undefined );
 	};
 
 	return (
 		<ToolsPanel label={ __( 'Dimensions' ) } resetAll={ resetAll }>
-			<p>
-				Select dimensions or spacing related settings from the menu for
-				additional controls.
-			</p>
-			{ ! isPaddingDisabled && (
-				<ToolsPanelItem
-					hasValue={ () => hasPaddingValue( props ) }
+			<PanelDescription>
+				Select dimensions or spacing related settings from the
+				menu for additional controls.
+			</PanelDescription>
+			<SingleColumnItem
+				hasValue={ () => !! height }
+				label={ __( 'Height' ) }
+				onDeselect={ () => setHeight( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Height' ) }
+					onChange={ setHeight }
+					value={ height }
+				/>
+			</SingleColumnItem>
+			<SingleColumnItem
+				hasValue={ () => !! width }
+				label={ __( 'Width' ) }
+				onDeselect={ () => setWidth( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Width' ) }
+					onChange={ setWidth }
+					value={ width }
+				/>
+			</SingleColumnItem>
+			<ToolsPanelItem
+				hasValue={ () => !! padding }
+				label={ __( 'Padding' ) }
+				onDeselect={ () => setPadding( undefined ) }
+			>
+				<BoxControl
 					label={ __( 'Padding' ) }
-					onDeselect={ () => resetPadding( props ) }
-				>
-					<PaddingEdit { ...props } />
-				</ToolsPanelItem>
-			) }
+					onChange={ setPadding }
+					values={ padding }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
+			<ToolsPanelItem
+				hasValue={ () => !! margin }
+				label={ __( 'Margin' ) }
+				onDeselect={ () => setMargin( undefined ) }
+			>
+				<BoxControl
+					label={ __( 'Margin' ) }
+					onChange={ setMargin }
+					values={ margin }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
 		</ToolsPanel>
 	);
 }

From e726b47cbb5d320f033cf2c2dfa997c1fc4ea65b Mon Sep 17 00:00:00 2001
From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Date: Fri, 22 Jul 2022 13:03:36 +1000
Subject: [PATCH 2/2] Add changelog

---
 packages/components/CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 05d7bcf42e6d9..66a7bb35654ca 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -19,6 +19,7 @@
 -   `CustomSelectControl`: Add flag to opt in to unconstrained width ([#42460](https://github.com/WordPress/gutenberg/pull/42460/)).
 -   `BorderControl`: Render dropdown as prefix within its `UnitControl` ([#42212](https://github.com/WordPress/gutenberg/pull/42212/))
 -   `UnitControl`: Update prop types to allow ReactNode as prefix ([#42212](https://github.com/WordPress/gutenberg/pull/42212/))
+-   `ToolsPanel`: Updated README with panel layout information and more expansive usage example ([#42615](https://github.com/WordPress/gutenberg/pull/42615)).
 
 ### Internal