Skip to content
Merged
Changes from 1 commit
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
7e93e07
README: add notes
ciampo Aug 9, 2021
37e1759
README: add link to `CONTRIBUTING.md`
ciampo Aug 9, 2021
cefad1f
CONTRIBUTING: Add initial notes
ciampo Aug 9, 2021
02114ce
More notes into CONTRIBUTING
ciampo Aug 10, 2021
3d665fb
Update CONTRIBUTING
ciampo Aug 11, 2021
0fb4753
Add `enable` to boolean prefixes
ciampo Aug 12, 2021
00e2b35
Remove `View` suffix for styled components
ciampo Aug 12, 2021
17ccabe
Update folder structure: move styles and types into each subfolder
ciampo Aug 12, 2021
1459214
Less strict working about typescript, rename PolymorphicComponent to …
ciampo Aug 24, 2021
c6f6a24
Update packages/components/CONTRIBUTING.md
ciampo Aug 24, 2021
f533857
Refer to the repo testing overview docs in the unit test section
ciampo Sep 1, 2021
4c1c200
Update polyfill info
ciampo Sep 1, 2021
89a89d1
Remove "Components Structure" paragraph
ciampo Sep 1, 2021
5238a88
Reword text in "Folder structure" section, exclude shared utilities
ciampo Sep 1, 2021
7acc925
Folder structure schemes: name parent folders, remove useless sub-com…
ciampo Sep 1, 2021
6621f1e
Expand Storybook section
ciampo Sep 1, 2021
6f6d8de
Add details to soft deprecation strategy
ciampo Sep 1, 2021
9d0ece7
Misc smaller improvements
ciampo Sep 1, 2021
d394f5d
Fix typo
ciampo Sep 1, 2021
3359502
Expand hooks vs components section, move under composition
ciampo Sep 1, 2021
cfc843d
Move sub components naming convention under "APIs consistency" section
ciampo Sep 1, 2021
abf50ad
Add Polymorphic components sub-section, reorganise "Components compos…
ciampo Sep 1, 2021
0021dfc
Add more details about listing props through knobs in storybook
ciampo Sep 2, 2021
15f7023
Remove hyphen from subcomponents
ciampo Sep 2, 2021
4520f7e
Add content to the `Context System` section
ciampo Sep 2, 2021
95de8fb
comment out unfinied sections
ciampo Sep 3, 2021
5393b9a
Apply suggestions from code review
ciampo Sep 8, 2021
6647446
Comment out reference to the "composition section"
ciampo Sep 8, 2021
670ca6c
Rename "Emotion" section to "Styling"
ciampo Sep 8, 2021
e65518d
Updale unit test section to link directly to components snapshot testing
ciampo Sep 8, 2021
b6edc2e
Update the storybook section, adding more details on stories and knobs
ciampo Sep 8, 2021
e8bb18d
Link to the Coding Guidelines in the "Documentation" section
ciampo Sep 8, 2021
08cd356
remove note about relevance of SCSS-related docs in README
ciampo Sep 8, 2021
c34f731
Update context section with example snippets
ciampo Sep 8, 2021
8c494c8
Format internal links to absolute path format
ciampo Sep 8, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update context section with example snippets
  • Loading branch information
ciampo committed Sep 8, 2021
commit c34f73168aafb25ab9412d3f0c4f5ed59c3c1358
72 changes: 71 additions & 1 deletion packages/components/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,77 @@ Components can use this system via a couple of functions:
- they can connect to the Context via `contextConnect`
- they can read the "computed" values from the context via `useContextSystem`

An example of how this is used is the [`Card` component](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/card/card/component.js#L44-L54) — all of its subcomponents (e.g. `CardBody`, `CardHeader`...) will [use, by default, the same value for the `size` as the parent `Card` component](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/card/card-body/hook.js#L23) — which results in all the components having all the correct spacing "auto-magically".
An example of how this is used can be found in the [`Card` component family](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/card). For example, this is how the `Card` component injects the `size` and `isBorderless` props down to its `CardBody` subcomponent — which makes it use the correct spacing and border settings "auto-magically".

```jsx
//=========================================================================
// Simplified snippet from `packages/components/src/card/card/hook.js`
//=========================================================================
import { useContextSystem } from '../../ui/context';

export function useCard( props ) {
// Read any derived registered prop from the Context System in the `Card` namespace
const derivedProps = useContextSystem( props, 'Card' );

// [...]

return computedHookProps;
}

//=========================================================================
// Simplified snippet from `packages/components/src/card/card/component.js`
//=========================================================================
import { contextConnect, ContextSystemProvider } from '../../ui/context';

function Card( props, forwardedRef ) {
const {
size,
isBorderless,
...otherComputedHookProps
} = useCard( props );

// [...]

// Prepare the additional props that should be passed to subcomponents via the Context System.
const contextProviderValue = useMemo( () => {
return {
// Each key in this object should match a component's registered namespace.
CardBody: {
size,
isBorderless,
},
};
}, [ isBorderless, size ] );

return (
{ /* Write additional values to the Context System */ }
<ContextSystemProvider value={ contextProviderValue }>
{ /* [...] */ }
</ContextSystemProvider>
);
}

// Connect to the Context System under the `Card` namespace
const ConnectedCard = contextConnect( Card, 'Card' );
export default ConnectedCard;

//=========================================================================
// Simplified snippet from `packages/components/src/card/card-body/hook.js`
//=========================================================================
import { useContextSystem } from '../../ui/context';

export function useCardBody( props ) {
// Read any derived registered prop from the Context System in the `CardBody` namespace.
// If a `CardBody` component is rendered as a child of a `Card` component, the value of
// the `size` prop will be the one set by the parent `Card` component via the Context
// System (unless the prop gets explicitely set on the `CardBody` component).
const { size = 'medium', ...otherDerivedProps } = useContextSystem( props, 'CardBody' );

// [...]

return computedHookProps;
}
```

#### Unit tests

Expand Down