From b5f267ff7c397379ac51920646ab4685ec23c713 Mon Sep 17 00:00:00 2001
From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Date: Thu, 18 Nov 2021 08:43:26 +1000
Subject: [PATCH] ToolsPanel: Update panel readme and stories (#36557)

* Update ToolsPanel readme illustrating non-panel-item display
* Add ToolsPanel story for non menu item
---
 .../src/tools-panel/stories/index.js          | 54 +++++++++++++++++++
 .../src/tools-panel/tools-panel/README.md     |  9 ++++
 2 files changed, 63 insertions(+)

diff --git a/packages/components/src/tools-panel/stories/index.js b/packages/components/src/tools-panel/stories/index.js
index 9446b3b94d337a..18ea49fd55f7bf 100644
--- a/packages/components/src/tools-panel/stories/index.js
+++ b/packages/components/src/tools-panel/stories/index.js
@@ -81,6 +81,56 @@ export const _default = () => {
 	);
 };
 
+export const WithNonToolsPanelItems = () => {
+	const [ height, setHeight ] = useState();
+	const [ width, setWidth ] = useState();
+
+	const resetAll = () => {
+		setHeight( undefined );
+		setWidth( undefined );
+	};
+
+	return (
+		<PanelWrapperView>
+			<Panel>
+				<ToolsPanel
+					label="ToolsPanel (with non-menu items)"
+					resetAll={ resetAll }
+				>
+					<IntroText>
+						This text illustrates not all items must be wrapped in a
+						ToolsPanelItem and represented in the panel menu.
+					</IntroText>
+					<SingleColumnItem
+						hasValue={ () => !! width }
+						label="Width"
+						onDeselect={ () => setWidth( undefined ) }
+						isShownByDefault={ true }
+					>
+						<UnitControl
+							label="Width"
+							value={ width }
+							onChange={ ( next ) => setWidth( next ) }
+						/>
+					</SingleColumnItem>
+					<SingleColumnItem
+						hasValue={ () => !! height }
+						label="Height"
+						onDeselect={ () => setHeight( undefined ) }
+						isShownByDefault={ true }
+					>
+						<UnitControl
+							label="Height"
+							value={ height }
+							onChange={ ( next ) => setHeight( next ) }
+						/>
+					</SingleColumnItem>
+				</ToolsPanel>
+			</Panel>
+		</PanelWrapperView>
+	);
+};
+
 export const WithOptionalItemsPlusIcon = () => {
 	const [ height, setHeight ] = useState();
 	const [ width, setWidth ] = useState();
@@ -229,3 +279,7 @@ const PanelWrapperView = styled.div`
 const SingleColumnItem = styled( ToolsPanelItem )`
 	grid-column: span 1;
 `;
+
+const IntroText = styled.div`
+	grid-column: span 2;
+`;
diff --git a/packages/components/src/tools-panel/tools-panel/README.md b/packages/components/src/tools-panel/tools-panel/README.md
index f01f2b329fac58..6de380b78ffba2 100644
--- a/packages/components/src/tools-panel/tools-panel/README.md
+++ b/packages/components/src/tools-panel/tools-panel/README.md
@@ -25,6 +25,11 @@ displaying by default through the `isShownByDefault` prop. Determining whether a
 child has a value is done via the `hasValue` function provided through the
 child's props.
 
+Components that are not wrapped within a `ToolsPanelItem` are still rendered
+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.
+
 ## Usage
 
 ```jsx
@@ -51,6 +56,10 @@ export function DimensionPanel( props ) {
 
 	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 ) }