Learning about best practices to use @wordpress/components

[ciampo]

Moving this conversation originally started by @gziolo in https://github.com/WordPress/gutenberg/issues/62880#issuecomment-2250015570 to its own separate issue.

---

@ciampo, what is the recommended resource to learn in depth about best practices for composing existing UI components to build accessible interfaces? I had similar dillemas like in this PR when working on the custom block.

I guess there are multiple sources, I'll try to list a few sources / best practices:

I was thinking specifically about @wordpress/components. So far I was using:

• Strorybook - which has great guidelines embedded for how to contribute to the components library
• @wordpress/components package reference is another resource that has the individual components documented

What I couldn't locate was the guide on how to assemble existing components and what to do with these marked as experimental. In general, how to think about the system holistically. I can't find the communication on Make Core related to the vision set in the past, but that article from WP Tavern seems relevant: https://wptavern.com/g2-components-a-from-scratch-reimagining-of-wordpress-components. So, to clarify my question is, if I want to contribute to WordPress core, Gutenberg or extend it, how do I consume these components so I optimize for flexibility and avoid as much as possible writing custom CSS. I'm happy to open an issue, if such resource doesn't exist today, as I needed something like that to accelerate the process of transforming Figma designs into React components.

cc @WordPress/gutenberg-components

[ciampo]

Here are some thoughts:

what to do with these marked as experimental

As of today, "experimental" components that are exported from the package can be assumed as mostly stable, as explained in the docs. We are in the process of slowly removing the "experimental" designation, but it will take a while.

Components exposed as the private APIs, however, should be assumed as private, WIP, and generally not safe to use. We usually leverage private APIs to start testing new apis and components in the editor before making them available via the public APIs. We intend for such private APIs not to stay private indefinitely.

the guide on how to assemble existing components [...] In general, how to think about the system holistically

The best place to start on how to combine existing components together is the components' docs, both in the form of JSDocs and Storybook examples.

We don't currently have generic documentation on this topic, but if there's appetite for it, we should consider it.

The fact that the @wordpress/components package exposes different paradigms doesn't help.

that article from WP Tavern seems relevant: wptavern.com/g2-components-a-from-scratch-reimagining-of-wordpress-components.

I wouldn't rely on that article, as it's likely outdated.

I needed something like that to accelerate the process of transforming Figma designs into React components.

Do you have concrete examples of what components you'd need to work on, or is only an hypothesis ?

[gziolo]

@juanmaguitar, @justintadlock, @ndiego, @ryanwelcher, what was your journey when you started learning how to use @wordpress/components efficiently? How would you educate beginners so they get up to speed quickly on how to build block's UI with them? In particular, the sidebar has a lot of space for expression and applies even more when using Slot/Fill through UI plugins.

[ryandejaegher]

@gziolo Adding my experience here as I found the learning curve to be very steep and resources/tutorials were all over the place. This took place over the last 2-3 years:

1. Third party tutorials/blogs
2. WordPress docs/tutorials (some of these were old but they're more up to date now)
3. Referencing Storybook components
4. Referencing the core blocks in the Gutenberg plugin to see what controls they use

Storybook was probably the most helpful because I could see all the available components and play with them. From there I'd usually see how a core block was implementing a control.

Just recently I referenced the core heading block to see how it setup the heading level control in the toolbar. That's an example where I couldn't find docs or find anything in Storybook.

To your question: How would you educate beginners so they get up to speed quickly on how to build block's UI with them?

I think simple templates for npx @wordpress/create-block. This package was so helpful in getting started and I think it could be taken a step further by having templates for the basic controls:

• npx @wordpress/create-block my-dynamic-block variant=block-with-text-control
• npx @wordpress/create-block my-dynamic-block variant=block-with-select-control
• npx @wordpress/create-block my-dynamic-block variant=block-with-toggle-control
• npx @wordpress/create-block my-dynamic-block variant=block-with-advanced-controls (text, select, and toggle control etc.)

This could be a learning style preference but I find it easier to have a working example from the start and then move backwards to figure out how it works.

One last thing I'd add is considering adding a command for WordPress Playground. In our custom blocks we now have a command in package.json (start:playground) that will start the block build process and spin up WordPress Playground.

TLDR; Beginners need to experience that aha moment and feel the win of "creating their first block"

[juanmaguitar]

How would you educate beginners so they get up to speed quickly on how to build block's UI with them?

I think the Block Development Examples is a great resource for getting up to speed on building blocks' UIs with components. More examples could be added, of course, but here are some excellent examples of blocks using components:

• data-basics-59c8f8 - shows how to create a React app in a WordPress admin page (this example uses A LOT of components)
• plugin-sidebar-9ee4a6 - shows how to add a new item to the Top Toolbar in the Block Editor using the plugin-sidebar slot.
• editable-block-1b8c51 - shows how to create a block that is editable and how core components can be enhanced.
• slotfill-2fb190 - shows how to use components with some Slot and Fills

These examples are a good reference to start working with components as you can install them in your own WP installation and start playing with them (you can also see the code and a demo online among some other things)