Adding Storybook to document components and improve frontend developer flow

[juliacanzani]

Following a discussion with @nicolas-jaussaud today I've decided to explore adding Storybook to the framework to act as documentation and frontend development environment.

Here's WP's Storybook to give you an idea of what it could look like: https://wordpress.github.io/gutenberg/?path=/

I've installed it and done some (very) initial setup in this branch: tool/storybook

I will need help, if we decide this is a good idea, setting up a deploy pipeline to Cloudflare pages. Mark has set this up once already with Bitbucket pipelines (see private repo qbt-storybook).

Give it a go and see if you like it, run command can be found in the readme, and let me know of any strong feelings for/against or alternative suggestions that would meet this need for documentation and better ease-of-use for frontend team members. @eliot-akira I heard from Nico that there had been discussion of inline documentation with Docusaurus. I feel this could be a good alternative, but do let me know your thoughts.

[eliot-akira]

Looks great, I read through the summary of changes.

• main...tool/storybook

If you'd like, you can create a pull request from the above link. In the PR page, there's a way to review and discuss specific lines of code, suggest changes (and click to apply), to collaboratively prepare the feature.

I'll check out the branch locally to see how it works. This sounds useful to have a consolidated definition and overview of all available components and their properties.

---

there had been discussion of inline documentation with Docusaurus. I feel this could be a good alternative

Maybe a documentation site (or section in Blocks docs) for the Fields module, with link(s) to the Storybook as interactive reference. It can complement other types of docs, like guides/tutorials/explanations.

..setting up a deploy pipeline to Cloudflare pages. Mark (@Mark-hub-work) has set this up once already with Bitbucket pipelines (see private repo qbt-storybook).

I want to learn how to do this too. It'd be nice to document the steps as a how-to guide. I'll create an issue for it, to be solved after this Storybook setup is ready.

• Automated workflow to deploy static site from GitHub repo to Cloudflare Pages

Ideally the workflow can be adapted to support any type of static site, built with Storybook, Docusaurus, TypeDoc, Vite, etc. Something like:

• Set up GitHub Pages with Cloudflare and a Custom Domain

---

improve frontend developer flow

A playground, dev site, or living documentation is nice, with hot module replacement (fast refresh with no page reload) during development. The immediate feedback loop reduces the friction between thinking and its actualization, closer to a design tool or sculpting material by hand.

Playgrounds provide a testing ground that renders developer code in real time. They have the capability of evaluating and displaying the results of single expressions as they are coded (in line or on a side bar), providing rapid feedback to the programmer. This type of development environment, known as a read-eval-print loop (or REPL) is useful for learning, experimenting and fast prototyping.

• https://en.wikipedia.org/wiki/Xcode#Playgrounds

In addition to Storybook for the Fields module, it'd be great to have similar dev experience for other modules and plugins, including for users of Blocks and the Template System. In this direction:

Programming involves editing code while also running it in our head. To augment this mental simulation, live programming provides a closer loop between the programmer and a program that is executing while it is being edited.

Live programming gives immediate feedback on the behavior of a program as it is edited, replacing the edit/compile/debug cycle with a more fluid programming experience.

• Embodiment and Living System
• Explorable Explanations
• Learnable Programming
• Malleable Systems

[eliot-akira]

OK, pull request #10 has been merged. This will be a good start, we can gradually document all field components.

• Storybook: Document all field components #11

And set up automated deploy of the built Storybook site.

• Storybook: Publish to GitHub Pages or Cloudflare Pages #12