Description

This update adds a new <Card /> component to @wordpress/components, as well as a collection of flexible sub-components that can be used to composed various user interfaces. The initial sub-components include:

• <CardBody />
• <CardDivider />
• <CardFooter />
• <CardMedia />

🚀 Deploy Preview

https://deploy-preview-17963--gutenberg-playground.netlify.com/design-system/components/?path=/story/card--default

✨ Visual Design

The <Card /> component's designs are very minimal. The border-radius, border-color, and padding are based on the aesthetics and values found within @wordpress/components and Gutenberg.

🤔 Component API Design

<Card /> drew it's component API (and it's composition) from other frameworks/libraries like Bootstrap and Material UI.

An example for how a <Card /> UI my be composed looks something like this:

import {
	Card,
	CardBody,
	CardDivider,
	CardFooter,
	CardHeader,
	CardMedia
} from '@wordpress/components';

const Example = () => (
	<Card>
		<CardHeader>
			...
		</CardHeader>
		<CardBody>
			...
		<CardBody>
		<CardDivider />
		<CardBody>
			...
		<CardBody>
		<CardMedia>
			<img src="..." />
		</CardMedia>
		<CardHeader>
			...
		</CardHeader>
	</Card>
);

How has this been developed & tested?

📚 Storybook

<Card /> was developed entirely in Storybook. The Knobs add-on was added to make developing and testing easier. I've set up knobs for various props and configurations to see how the various sub-components can fit together.

Knobs was incredibly valuable in the development of <Card />. It helped me improve the iteration cycle/testing of Context (which the component uses internally). The Storybook UI allowed me to catch and fix breaking edge-case CSS issues.

Lastly, Storybook was very helpful in fine-tuning the <CardMedia /> component, which relies more on responsive behaviour:

🧪 Jest / Enzyme

I've written unit tests for all of the various sub-components. I've also added integration tests for sub-components -> <Card />. The naming conventions and testing techniques were drawn from the existing Enzyme based tests I found within @wordpress/components. I didn't add anything new 😄 (as far as architecture, tech, etc... goes)

Test Suites: 6 passed, 6 total
Tests:       34 passed, 34 total
Snapshots:   0 total
Time:        1.572s, estimated 2s
Ran all test suites matching /card/i.

Types of changes

💅 Styled Components

This is new and experimental! For the <Card /> styles (and it's sub-components), I introduced and used styled-components to take care of the CSS.

I've seen a couple of PRs attempting this as well:
#17673
#17614

The benefits of a CSS-in-JS solution are many. Those PRs do a fantastic job at walking through several key benefits - especially for native mobile.

I think it's best feature is... components will be styled and working out-of-the-box. If you build a React component with styled components, you can import the component perfectly styled straight from node_modules. No fussing with Webpack, Grunt, compilers or scripts. It provides for a wonderful developer experience. Not only that, styled components will provide features like theming. This will make it much easier for folks to consume @wordpress/components to build their own interfaces - for their own blocks, plugins, or interfaces outside of Gutenberg.

An incredible example of this experience can be found in the Material UI React library. All of the components come pre-styled and can be themed (Note: They use an alternate CSS-in-JS library, not styled components).

🌲 Preserving standard CSS styling

This is 💯 important. To do this, I added a standard CSS className to the various components (e.g. components-card-header), just like the rest of @wordpress/components. Although these classNames aren't responsible for direct styling, they enable:

• Style overrides via standard CSS selector targeting
• A way better sense of html composition when debugging (e.g. Inspect Element)
• A way to target selectors via Jest/Enzyme

🎨 Color Utils

Since I ventured into CSS-in-JS for the pull request, I needed a way to use the same colour values we have from .scss but for .js code. To do this, I built a color() utility, which lives within the new components/utils directory.

It can be used like this:

color( 'blue.wordpress.700' );
// #00669b

The . notation represents the nested colour values I have stored in the constant color.values.js map (Object).

💪 Testing it all

I (temporarily) updated the block-library/button component with the new <Card /> component - wrapping it's contents. In addition to working with Storybook and Jest, I needed to make sure the code worked with Gutenberg (of course 😂).

In this test, I was able to see that the Styled Components render components worked with the existing components and styles (and the thing didn't explode).

📹 Live Coding

I coded these components via YouTube livestream this past Friday (and a bit this morning):

Here are the videos, in case anyone is interested:

https://www.youtube.com/watch?v=oAPuOB9oYCw
https://www.youtube.com/watch?v=Kf-CtY3wQGM

My thinking for the live coding was to demonstrate and explain my thinking throughout the design process. Also, it was wonderful to engage with folks on chat. There were several points where we collaborated to figuring out specific component API and behaviour. It was lovely 💕.

🤗 Feedback

I would love to know what you folks think! I understand that some of these approaches are new in the context of @wordpress/components and Gutenberg, specifically Stories and Styled Components. I'm more than happy to answer questions!

Thank you so much for your time 🙏

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.

Potentially addresses:
#15921