Feature: Rapid UI component scaffolding

[willhowat]

Description of the Change

Added a micro-generator framework plop to rapidly scaffold UI components within the theme in an effort to:

• Shave off the time this takes, whether from scratch or copy/paste/re-factor
• Avoid incremental deviations from intended patterns and copy/paste errors
• Provide a source of truth for intended patterns in the context of the longer term project lifecycle
• Support the wider adoption of style guide component examples

One aspect I'm trying to address here by keeping this within the theme is the ability to start with common patterns, with the freedom to adapt them based on per-project needs.

From the theme root npm run new
Follow the guided menu to generate component files in a consistent manner:

• component partial
• styleguide example(s) of the partial
• component CSS
• component JS

All files are optional so can be as granular as required.
Including generated files needs to be done manually in the respective index files and/or styleguide template.
This was done to avoid accidental bloat.

Plop uses handlebars template files, these can be altered in [theme]/plop-templates.
Config files lives at [theme]/plopfile.js.

Closes #88

CC: @brentvr @joesnellpdx @rdimascio @ian-pvd

Alternate Designs

Alternatives were investigated to Plop, but this seems the simplest to configure and adopt across experience levels.
One strong contender was Hygen however, Plop does provide a super useful menu to select a generator allowing for a single npm script and contextual menu, whereas Hygen relies on directly running individual generators.

The templates follow some opinions in their patterns.
These have had real world testing in recent projects and have proven beneficial. They can be easily reconfigured through the plop templates if required.

Possible Drawbacks

The use of handlebars templates may not be ideal should this be extended to include rapid block scaffolding. To this end the npm script new has been added rather than anything more plop specific to allow a more natural swap of tooling if required.

Faker has been included as a composer dependency to support component style guide examples through stubbing of data. This package is stable, but no longer in active development. An alternative would be nice, but I was unable to source anything appropriate. The project has been taken up as FakerJS, but this is FE and Node focussed and does not provide the PHP integration we would need.

Verification Process

• ran npm run new for various configurations of UI component
• verified all files output as expected
• verified all files can be included and components render as expected
• verified NPM builds complete as expected

Checklist:

• I have read the CONTRIBUTING document.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my change.
• All new and existing tests passed.

Changelog Entry

Added

• plop.js as theme npm dependency
• ./plopfile.js for configuration of component generation
• ./plop-templates/ containing component generation templates
• fzaninotto/faker as composer dependency for styleguide example data
• example-ui-component (partial, style guide partial examples, CSS, JS)
• commented includes for example-ui-component files (style guide partial examples, CSS, JS)

Updated

• styleguide.css with styling for sub-headers
• Readme

[nicholasio]

I like this, but I'm not sure if the scaffold itself is the best to place to put the templates and all of the logic behind template generation.

I feel like 10up-toolkit would be a better place to put this in by exposing a new command: 10up-toolkit scaffold fe:component, which could be expanded in the future to include things like blocks etc... There's some previous work that never got merged: 10up/10up-toolkit#29

[ian-pvd]

This looks great. Tested the script and its outputting components like I'd expect.
I'm looking forward to testing this with my own custom component templates.

[joesnellpdx]

I like this, but I'm not sure if the scaffold itself is the best to place to put the templates and all of the logic behind template generation.

I feel like 10up-toolkit would be a better place to put this in by exposing a new command: 10up-toolkit scaffold fe:component, which could be expanded in the future to include things like blocks etc... There's some previous work that never got merged: 10up/10up-toolkit#29

@willhowat What are your thoughts per @nicholasio 's suggestion moving to 10up-toolkit?

[willhowat]

I like this, but I'm not sure if the scaffold itself is the best to place to put the templates and all of the logic behind template generation.
I feel like 10up-toolkit would be a better place to put this in by exposing a new command: 10up-toolkit scaffold fe:component, which could be expanded in the future to include things like blocks etc... There's some previous work that never got merged: 10up/10up-toolkit#29

@willhowat What are your thoughts per @nicholasio 's suggestion moving to 10up-toolkit?

@joesnellpdx @nicholasio I've been thinking about this a lot and I can see value in that approach as well.
This tools is intended to provide rapid scaffolding of elements within the context of wp-scaffold.
The structure of files generated is by nature aligned with the structure of wp-scaffold and other aspects such as the styleguide, which live within wp-scaffold.
If this were to move to 10up-toolkit I think we would have to carefully consider how we allow configuration in a standalone world to ensure there isn't an assumed dependency.

My preference at this time would be to move forward in wp-scaffold.
In that way provide an immediate benefit and open this up for feedback.
We can then if suitable take those learnings and look at how to build something that could be within 10up-toolkit or other.

[nicholasio]

I like this, but I'm not sure if the scaffold itself is the best to place to put the templates and all of the logic behind template generation.
I feel like 10up-toolkit would be a better place to put this in by exposing a new command: 10up-toolkit scaffold fe:component, which could be expanded in the future to include things like blocks etc... There's some previous work that never got merged: 10up/10up-toolkit#29

@willhowat What are your thoughts per @nicholasio 's suggestion moving to 10up-toolkit?

@joesnellpdx @nicholasio I've been thinking about this a lot and I can see value in that approach as well. This tools is intended to provide rapid scaffolding of elements within the context of wp-scaffold. The structure of files generated is by nature aligned with the structure of wp-scaffold and other aspects such as the styleguide, which live within wp-scaffold. If this were to move to 10up-toolkit I think we would have to carefully consider how we allow configuration in a standalone world to ensure there isn't an assumed dependency.

My preference at this time would be to move forward in wp-scaffold. In that way provide an immediate benefit and open this up for feedback. We can then if suitable take those learnings and look at how to build something that could be within 10up-toolkit or other.

I think we could have a default opinionated template focused in wp-scaffold while letting projects specify their own template at the project level, at that point toolkit would be a abstraction around plop. npx 10up-toolkit scaffold template-name

[willhowat]

I like this, but I'm not sure if the scaffold itself is the best to place to put the templates and all of the logic behind template generation.
I feel like 10up-toolkit would be a better place to put this in by exposing a new command: 10up-toolkit scaffold fe:component, which could be expanded in the future to include things like blocks etc... There's some previous work that never got merged: 10up/10up-toolkit#29

@willhowat What are your thoughts per @nicholasio 's suggestion moving to 10up-toolkit?

@joesnellpdx @nicholasio I've been thinking about this a lot and I can see value in that approach as well. This tools is intended to provide rapid scaffolding of elements within the context of wp-scaffold. The structure of files generated is by nature aligned with the structure of wp-scaffold and other aspects such as the styleguide, which live within wp-scaffold. If this were to move to 10up-toolkit I think we would have to carefully consider how we allow configuration in a standalone world to ensure there isn't an assumed dependency.
My preference at this time would be to move forward in wp-scaffold. In that way provide an immediate benefit and open this up for feedback. We can then if suitable take those learnings and look at how to build something that could be within 10up-toolkit or other.

I think we could have a default opinionated template focused in wp-scaffold while letting projects specify their own template at the project level, at that point toolkit would be a abstraction around plop. npx 10up-toolkit scaffold template-name

I do think there's a lot of value in adding this into toolkit.

@nicholasio I'd be happy to see how I can help in that respect however, if you are able to provide some guidance around how best to manage the integration that would be really appreciated.

@joesnellpdx for now would it be acceptable to add this in to scaffold as is? On the basis we can update the 'new' script to wire into toolkit once it lands there

[joesnellpdx]

@fabiankaegy adding you to the conversation.

@willhowat has done some great work here, and I know there is something in the works from Core as well - so the two of you should connect.

[darylldoyle]

I love this idea, but I'd also love to explore if there's a more generic way to handle it so that we can generate things outside of FE components and the theme.

For example, I've also wondered if we could do something like this to generate code for the mu-plugin, or to spin up a new block. I'd love to see something similar to how Laravel Artisan handles it:

php artisan make:controller PostsController

I've had thoughts of something similar for the scaffold:

$ php 10up make:cpt Event --mu-plugin=10up-plugin 
$ php 10up make:block MyCustomBlock --theme=10up-theme
$ php 10up make:component Carousel --theme=10up-theme --type=atom

We'd then have a directory of stub files within the project that each project could customise to their needs. Whilst it looks like PlopJS could do this, my concern would be that plopfile.js would get unwieldy. I would like to explore if this could be a better experience for engineers if this happened via PHP, where we could define a distinct class per feature.

Again, I'm not at all against this, and I think it's a great idea; I just want to ensure that we're not diving into adopting a system that will stop us from expanding it to other parts of the scaffold in the future.