From 3703b46a7d31cf772d517e3bd73593c63c2ac8ed Mon Sep 17 00:00:00 2001
From: Haz <hazdiego@gmail.com>
Date: Sat, 11 Sep 2021 13:13:30 +0200
Subject: [PATCH] Add Compound Components section to components CONTRIBUTING.md
 (#34697)

---
 packages/components/CONTRIBUTING.md | 58 +++++++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/packages/components/CONTRIBUTING.md b/packages/components/CONTRIBUTING.md
index 3bed2829216a8..98e4422f853bf 100644
--- a/packages/components/CONTRIBUTING.md
+++ b/packages/components/CONTRIBUTING.md
@@ -35,12 +35,64 @@ function LinkButton( { href, children } ) {
 	return <Button variant="primary" as="a" href={href}>{ children }</Button>;
 }
 ```
+-->
 
-### Composition patterns
+#### Compound components
 
-TBD — E.g. Using `children` vs custom render props vs arbitrary "data" props
+When creating components that render a list of subcomponents, prefer to expose the API using the [Compound Components](https://kentcdodds.com/blog/compound-components-with-react-hooks) technique over array props like `items` or `options`:
 
-### (Semi-)Controlled components
+```jsx
+// ❌ Don't:
+<List
+	items={ [
+		{ value: 'Item 1' },
+		{ value: 'Item 2' },
+		{ value: 'Item 3' },
+	] }
+/>
+```
+```jsx
+// ✅ Do:
+<List>
+	<ListItem value="Item 1" />
+	<ListItem value="Item 2" />
+	<ListItem value="Item 3" />
+</List>
+```
+
+When implementing this pattern, avoid using `React.Children.map` and `React.cloneElement` to map through the children and augment them. Instead, use React Context to provide state to subcomponents and connect them:
+
+```jsx
+// ❌ Don't:
+function List ( props ) {
+	const [ state, setState ] = useState();
+	return (
+		<div { ...props }>
+			{ Children.map( props.children, ( child ) => cloneElement( child, { state } ) ) ) }
+		</div>
+	);
+}
+```
+```jsx
+// ✅ Do:
+const ListContext = createContext();
+
+function List( props ) {
+	const [ state, setState ] = useState();
+	return (
+		<ListContext.Provider value={ state }>
+			<div { ...props } />
+		</ListContext.Provider>
+	);
+}
+
+function ListItem( props ) {
+	const state = useContext( ListContext );
+	...
+}
+```
+
+<!-- ### (Semi-)Controlled components
 
 TBD