From bdfe95c441888d7536ac39e177ee1753ada83e4d Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Wed, 31 Jul 2024 17:04:49 +0200
Subject: [PATCH] Update guidelines to use overloaded convention, remove
 references to monolithic components

---
 packages/components/CONTRIBUTING.md | 42 +++++++++++++++++------------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/packages/components/CONTRIBUTING.md b/packages/components/CONTRIBUTING.md
index 916915be3de5c..b276a897ba6a3 100644
--- a/packages/components/CONTRIBUTING.md
+++ b/packages/components/CONTRIBUTING.md
@@ -127,18 +127,18 @@ When creating components that render a list of subcomponents, prefer to expose t
 
 ```jsx
 // ✅ Do:
-<List.Root>
+<List>
 	<List.Item value="Item 1" />
 	<List.Item value="Item 2" />
 	<List.Item value="Item 3" />
-</List.Root>
+</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 ListRoot ( props ) {
+function List ( props ) {
 	const [ state, setState ] = useState();
 	return (
 		<div { ...props }>
@@ -152,7 +152,7 @@ function ListRoot ( props ) {
 // ✅ Do:
 const ListContext = createContext();
 
-function ListRoot( props ) {
+function List( props ) {
 	const [ state, setState ] = useState();
 	return (
 		<ListContext.Provider value={ state }>
@@ -234,28 +234,38 @@ TDB -->
 
 ## Naming Conventions
 
-It is recommended for compound components to use dot notation to separate the namespace from the individual component names. The top-level compound component should be called `Root`.
+It is recommended for compound components to use dot notation to separate the namespace from the individual component names. The top-level compound component should be called as the namespace (no dot notation).
 
-In comparison to compound components, it is recommended for monolithic components not to use dot-notation or namespacing in their export names.
-
-Dedicated React context should be also using the dot notation, while hooks should not
+Dedicated React context should also use the dot notation, while hooks should not.
 
 ```tsx
+// Component.tsx
+//=======================
+/** The top-level component's JSDoc. */
+export const Component = Object.assign( TopLevelComponent, {
+	/** The sub-component's JSDoc. */
+	SubComponent,
+	/** The sub-component's JSDoc. */
+	Content,
+} );
+
+export function useComponent() {
+	/* ... */
+}
+
+// App.tsx
+//=======================
 import { Component, useComponent } from '@wordpress/components';
 import { useContext } from '@wordpress/element';
 
-function CompoundExample() {
+function CompoundComponentExample() {
 	return (
-		<Component.Root>
+		<Component>
 			<Component.SubComponent />
-		</Component.Root>
+		</Component>
 	);
 }
 
-function MonolithExample() {
-	return <Component />;
-}
-
 function ContextProviderExample() {
 	return (
 		<Component.Context.Provider value={ /* ... */ }>
@@ -277,8 +287,6 @@ function HookExample() {
 }
 ```
 
-The suggested naming conventions can help consumers of the package to distinguish between monolithic a compound components, and allows components to expose at the same time a monolithic and a compound version if needed.
-
 ## TypeScript
 
 We strongly encourage using TypeScript for all new components.