Skip to content

Commit

Permalink
Update guidelines to use overloaded convention, remove references to …
Browse files Browse the repository at this point in the history
…monolithic components
  • Loading branch information
ciampo committed Jul 31, 2024
1 parent 545e074 commit bdfe95c
Showing 1 changed file with 25 additions and 17 deletions.
42 changes: 25 additions & 17 deletions packages/components/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 }>
Expand All @@ -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 }>
Expand Down Expand Up @@ -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={ /* ... */ }>
Expand All @@ -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.
Expand Down

0 comments on commit bdfe95c

Please sign in to comment.